Scripts Reference¶

All scripts are defined in package.json and run from the agentenregister/ directory.

cd agentenregister
npm run <script-name>

Services¶

Scripts for starting the Agent Registry services.

Script	Command	Description
`npm start`	`concurrently "npm run api" "npm run relayer"`	Start API + Relayer together
`npm run api`	`node api/server.js`	Start REST API server (port 3000)
`npm run relayer`	`node relayer/relayer.js`	Start gasless relayer (port 3001)
`npm run dashboard`	`cd dashboard && npm run dev`	Start web dashboard (port 3002)
`npm run dashboard:build`	`cd dashboard && npm run build`	Build dashboard for production

Running all three services

# Terminal 1: API + Relayer
npm start

# Terminal 2: Dashboard
npm run dashboard

Smart Contracts¶

Scripts for compiling, deploying, and verifying smart contracts.

Script	Command	Description
`npm run compile`	`npx hardhat compile`	Compile Solidity contracts
`npm run verify`	`npx hardhat run scripts/verify-contracts.js --network baseSepolia`	Verify contracts on Basescan

Deployment Scripts¶

Script	Command	Target
`npm run deploy:local`	`npx hardhat run scripts/deploy.js --network hardhat`	Local Hardhat network
`npm run deploy:sepolia`	`npx hardhat run scripts/deploy.js --network sepolia`	Ethereum Sepolia
`npm run deploy:base-testnet`	`npx hardhat run scripts/deploy.js --network baseSepolia`	Base Sepolia
`npm run deploy:arbitrum-testnet`	`npx hardhat run scripts/deploy.js --network arbitrumSepolia`	Arbitrum Sepolia
`npm run deploy:base`	`npx hardhat run scripts/deploy.js --network base`	Base Mainnet
`npm run deploy:arbitrum`	`npx hardhat run scripts/deploy.js --network arbitrumOne`	Arbitrum Mainnet

Testing¶

Scripts for running the test suite.

Script	Command	Description
`npm test`	`npx hardhat test`	Run the full test suite (68 tests)
`npm run test:coverage`	`npx hardhat coverage`	Run tests with code coverage report
`npm run test:live`	`node scripts/run-tests-live.js`	Run live integration tests on Base Sepolia
`npm run scientific`	`node scripts/scientific-harness.js`	Run scientific experiment (100 agents)

Test Suite Details¶

Suite	Tests	What It Covers
Registration	12	Agent registration, duplicate prevention, field validation
Compliance	8	Attestation, grace period, lapse detection
Revenue	6	Revenue reporting, history, aggregation
Lineage	8	Parent-child registration, generation depth cap
Regulatory	10	Suspend, revoke, reactivate, regulator management
Gasless (ERC-2771)	8	Meta-transactions, forwarder verification, nonce tracking
Access Control	10	Authorization boundaries, modifier enforcement
Edge Cases	6	Overflow, zero values, boundary conditions

Running tests

# Run all tests
npm test

# Run with verbose output
npx hardhat test --verbose

# Run a specific test file
npx hardhat test test/Agentenregister.test.js

Live Tests¶

The live test script (npm run test:live) runs 13 integration tests against the deployed contracts on Base Sepolia:

Test	What It Verifies
Register 5 agents	Gasless registration via relayer
Compliance attestation	Attestation updates on-chain timestamp
Revenue reporting	Revenue records stored correctly
Parent-child lineage	Child and grandchild registration (gen 0 -> 1 -> 2)
Regulatory actions	Suspend, reactivate via regulator role
KYA endpoint	API returns correct registration/compliance status

Scientific Experiment¶

The scientific harness (npm run scientific) registers 100 agents with varied configurations and measures:

Registration success rate and latency (avg, median, P95)
Gas consumption per operation type
Compliance attestation patterns
Revenue reporting distribution
Lineage tree depth and width

Results are written to docs/SCIENTIFIC_RESULTS.md.

Setup & Configuration¶

Scripts for initial project setup.

Script	Command	Description
`npm run setup:keys`	`node scripts/setup.js --generate-keys`	Generate deployer + relayer wallets
`npm run setup:deploy`	`node scripts/setup.js --deploy --network baseSepolia`	Deploy contracts to Base Sepolia
`npm run local`	`node scripts/deploy-local.js`	Full local dev setup (Hardhat node + deploy)
`npm run local:deploy`	`node scripts/deploy-local.js --only-deploy`	Deploy to running Hardhat node

First-time setup

# 1. Generate wallets
npm run setup:keys

# 2. Fund wallets (Base Sepolia faucet)
npm run claim

# 3. Deploy contracts
npm run setup:deploy

# 4. Start services
npm start

Utilities¶

Script	Command	Description
`npm run addresses`	(inline node script)	Print deployer + relayer wallet addresses
`npm run claim`	`node scripts/claim-faucet.mjs`	Claim testnet ETH from Coinbase CDP faucet
`npm run claim:relayer`	`node scripts/claim-faucet.mjs --relayer-only --claims 200`	Claim testnet ETH to relayer wallet only
`npm run node`	`npx hardhat node`	Start a local Hardhat node

SDK¶

Script	Command	Description
`npm run sdk:build`	`cd sdk/typescript && npm run build`	Build the TypeScript SDK

Environment Variables¶

All scripts read configuration from a .env file in the agentenregister/ directory. See Environment Variables for the full reference.

Critical variables:

Variable	Required By	Description
`DEPLOYER_KEY`	deploy, verify, setup	Private key for contract deployment
`RELAYER_KEY`	relayer, test:live, scientific	Private key for the gasless relayer
`REGISTRY_ADDRESS`	api, relayer, test:live	Deployed Agent Registry contract address
`FORWARDER_ADDRESS`	relayer, test:live	Deployed MinimalForwarder contract address
`RPC_URL`	api, relayer	RPC endpoint (default: `https://sepolia.base.org`)

Quick Reference¶

# Development workflow
npm run compile          # Compile contracts after changes
npm test                 # Run tests
npm run test:coverage    # Check coverage

# Local development
npm run local            # Start Hardhat node + deploy

# Testnet
npm run claim            # Get testnet ETH
npm run setup:deploy     # Deploy to Base Sepolia
npm start                # Start API + Relayer
npm run dashboard        # Start dashboard

# Verification & experiments
npm run verify           # Verify on Basescan
npm run test:live        # Integration tests
npm run scientific       # Full experiment (100 agents)