Deployment Guide

This guide covers deploying the ERC-8004 contracts (IdentityRegistry, ReputationRegistry, ValidationRegistry) to Starknet networks.

Prerequisites

Before deploying, ensure you have:

Scarb 2.12.1 - Cairo package manager
snforge 0.51.2 - Starknet Foundry testing framework
sncast - Starknet Foundry deployment tool (comes with snforge)
A funded Starknet account - For paying deployment gas fees

Recommended: Install via asdf

The recommended way to install Scarb and Starknet Foundry is through asdf, which makes version management easy:

# Add plugins
asdf plugin add scarb
asdf plugin add starknet-foundry

# Install and set versions
asdf install scarb 2.12.1
asdf install starknet-foundry 0.51.2
asdf set --home scarb 2.12.1
asdf set --home starknet-foundry 0.51.2

See the Scarb asdf guide and Starknet Foundry asdf guide for more details.

Install Starknet Foundry

curl -L https://raw.githubusercontent.com/foundry-rs/starknet-foundry/master/scripts/install.sh | sh
snfoundryup

Verify installation:

scarb --version  # Should show 2.12.1
snforge --version  # Should show 0.51.2

Build Contracts

Navigate to the contracts directory and build:

cd packages/starknet-identity/erc8004-cairo
scarb build

This generates Sierra artifacts in target/dev/:

erc8004_cairo_IdentityRegistry.contract_class.json
erc8004_cairo_ReputationRegistry.contract_class.json
erc8004_cairo_ValidationRegistry.contract_class.json

Sepolia Testnet Deployment

1. Configure Account

Set up your deployer account with sncast:

sncast account import \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --name sepolia_deployer \
  --address YOUR_ACCOUNT_ADDRESS \
  --private-key YOUR_PRIVATE_KEY \
  --type open_zeppelin \
  --add-profile sepolia_deployer

Fund Your Account

Ensure your account has STRK or ETH for gas fees. Get testnet tokens from the Starknet Faucet.

2. Deploy IdentityRegistry

The IdentityRegistry has no constructor arguments:

# Declare the contract class
sncast --profile sepolia_deployer declare \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --contract-name IdentityRegistry

# Deploy an instance
sncast --profile sepolia_deployer deploy \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --class-hash 0x<CLASS_HASH_FROM_DECLARE>

Save the deployed contract address - you'll need it for the next steps.

3. Deploy ReputationRegistry

The ReputationRegistry requires the IdentityRegistry address as a constructor argument:

# Declare
sncast --profile sepolia_deployer declare \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --contract-name ReputationRegistry

# Deploy with IdentityRegistry address
sncast --profile sepolia_deployer deploy \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --class-hash 0x<CLASS_HASH_FROM_DECLARE> \
  --constructor-calldata 0x<IDENTITY_REGISTRY_ADDRESS>

4. Deploy ValidationRegistry

The ValidationRegistry also requires the IdentityRegistry address:

# Declare
sncast --profile sepolia_deployer declare \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --contract-name ValidationRegistry

# Deploy with IdentityRegistry address
sncast --profile sepolia_deployer deploy \
  --url "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --class-hash 0x<CLASS_HASH_FROM_DECLARE> \
  --constructor-calldata 0x<IDENTITY_REGISTRY_ADDRESS>

Automated Deployment Script

For convenience, use the provided deployment script:

cd packages/starknet-identity/erc8004-cairo
bash scripts/deploy_sepolia.sh

This script:

Builds contracts
Declares all three contract classes
Deploys IdentityRegistry
Deploys ReputationRegistry (linked to IdentityRegistry)
Deploys ValidationRegistry (linked to IdentityRegistry)
Saves addresses to deployed_addresses_sepolia.json

Mainnet Deployment

Production Deployment

Mainnet deployment requires careful review. Ensure contracts have been thoroughly tested on Sepolia first.

1. Configure Mainnet Account

sncast account import \
  --url "https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --name mainnet_deployer \
  --address YOUR_MAINNET_ACCOUNT \
  --private-key YOUR_MAINNET_PRIVATE_KEY \
  --type open_zeppelin \
  --add-profile mainnet_deployer

2. Deploy to Mainnet

Follow the same steps as Sepolia, but use the mainnet profile and RPC URL:

# Declare and deploy IdentityRegistry
sncast --profile mainnet_deployer declare \
  --url "https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --contract-name IdentityRegistry

sncast --profile mainnet_deployer deploy \
  --url "https://starknet-mainnet.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY" \
  --class-hash 0x<CLASS_HASH>

# Continue with ReputationRegistry and ValidationRegistry...

Mainnet Checklist

Before mainnet deployment, verify:

All unit tests pass (snforge test)
E2E tests pass on Sepolia
Contract code has been audited (if handling significant value)
Deployer account has sufficient mainnet funds
Backup of all addresses and class hashes saved
Team review of deployment plan completed

Post-Deployment Verification

Verify on Block Explorer

Check your contracts on Voyager:

Sepolia: https://sepolia.voyager.online/contract/<ADDRESS>
Mainnet: https://voyager.online/contract/<ADDRESS>

Run E2E Tests

After deployment, run end-to-end tests against your deployed contracts:

cd packages/starknet-identity/erc8004-cairo/e2e-tests

# Create .env file with your deployment
cat > .env << EOF
STARKNET_RPC_URL=https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_9/YOUR_KEY
ACCOUNT_ADDRESS=0x<YOUR_ACCOUNT>
PRIVATE_KEY=0x<YOUR_PRIVATE_KEY>
IDENTITY_REGISTRY=0x<DEPLOYED_ADDRESS>
REPUTATION_REGISTRY=0x<DEPLOYED_ADDRESS>
VALIDATION_REGISTRY=0x<DEPLOYED_ADDRESS>
EOF

pnpm install
pnpm test

Contract Addresses

Official Deployments

Testnet Contracts

These are the official Starknet Agentic ERC-8004 deployments. For your own deployment, follow the steps above.

Sepolia Testnet:

Contract	Address
IdentityRegistry	`0x...` (TBD)
ReputationRegistry	`0x...` (TBD)
ValidationRegistry	`0x...` (TBD)

Mainnet:

Contract	Address
IdentityRegistry	Not yet deployed
ReputationRegistry	Not yet deployed
ValidationRegistry	Not yet deployed

Upgradeability

Non-Upgradeable

The current ERC-8004 contracts are not upgradeable. Once deployed, the contract logic cannot be changed. This is intentional for trust minimization.

If you need upgradeability, consider:

Proxy pattern - Deploy behind an OpenZeppelin proxy
Registry migration - Deploy new versions and migrate data
Versioned registries - Run multiple registry versions in parallel

Troubleshooting

Common Issues

Issue	Solution
`Class hash already declared`	The contract class exists on-chain. Use the existing class hash for deployment.
`Insufficient balance`	Fund your account with STRK or ETH for gas.
`Invalid signature`	Check your private key and account address match.
`Contract not found`	Verify the class hash and wait for network confirmation.
`Build fails`	Ensure Scarb 2.12.1 is installed. Check `Scarb.toml` dependencies.

Getting Help

Next Steps

After deployment:

Register test agents - Use the Identity Skill to register agents
Integrate with your app - Connect via MCP Tools
Build reputation - Start collecting feedback with the Reputation Registry