Skip to content

QUICKSTART.md

Latest commit

 

History

History
378 lines (290 loc) · 9.47 KB

QUICKSTART.md

File metadata and controls

378 lines (290 loc) · 9.47 KB
Raw

ΨNet ERC-8004 Quick Start Guide

🚀 Getting Started (Local Development)

Prerequisites

Ensure you have the following installed:

  • Node.js >= 18.0.0
  • npm >= 9.0.0
  • Git
node --version  # Should be >= 18.0.0
npm --version   # Should be >= 9.0.0

Step 1: Clone and Setup

# Clone the repository
git clone https://github.com/WGlynn/-Net-PsiNet---the-Psychic-Network-for-AI-Context.
cd -Net-PsiNet---the-Psychic-Network-for-AI-Context

# Checkout the ERC-8004 implementation branch
git checkout claude/network-breakdown-analysis-011CUsqavmBwpQxkBBirQVSH

# Install dependencies (takes ~2 minutes)
npm install

Step 2: Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env with your keys (optional for local testing)
nano .env  # or use your preferred editor

For local testing, you can leave the default values. For deployment to testnet/mainnet, you'll need:

Step 3: Compile Contracts

npm run compile

Expected output:

Compiled 6 Solidity files successfully

This creates:

  • artifacts/ - Compiled contract artifacts
  • cache/ - Compilation cache

Step 4: Run Tests

# Run all tests (180+ tests)
npm test

Expected output:

  IdentityRegistry
    Deployment
      ✓ Should set the correct name and symbol
      ✓ Should start with zero agents
    Agent Registration
      ✓ Should register a new agent
      ✓ Should increment agent IDs
      ... (50+ passing)

  ReputationRegistry
    Deployment
      ✓ Should set correct identity registry
      ✓ Should set correct minimum stake
    Posting Feedback
      ✓ Should post positive feedback
      ... (60+ passing)

  ValidationRegistry
    Deployment
      ✓ Should set correct parameters
    Request Validation
      ✓ Should request staked validation
      ... (70+ passing)

  180 passing (5s)

Step 5: Check Test Coverage

npm run test:coverage

Expected coverage:

  • Line Coverage: > 95%
  • Branch Coverage: > 90%
  • Function Coverage: 100%
  • Statement Coverage: > 95%

Step 6: Check Gas Costs

REPORT_GAS=true npm test

Expected gas costs (at 50 Gwei):

Operation Gas Used Cost @ 50 Gwei
Register Agent ~150,000 ~$2.50
Post Feedback ~100,000 ~$1.67
Post Staked Feedback ~120,000 ~$2.00
Request Validation ~80,000 ~$1.33
Submit Validation ~120,000 ~$2.00

🧪 Running Specific Tests

# Test only Identity Registry
npx hardhat test test/IdentityRegistry.test.js

# Test only Reputation Registry
npx hardhat test test/ReputationRegistry.test.js

# Test only Validation Registry
npx hardhat test test/ValidationRegistry.test.js

# Run specific test by name
npx hardhat test --grep "Should register a new agent"

🌐 Local Blockchain Deployment

Start Local Hardhat Node

# Terminal 1: Start local blockchain
npm run node

Expected output:

Started HTTP and WebSocket JSON-RPC server at http://127.0.0.1:8545/

Accounts
========
Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH)
Account #1: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 ETH)
...

Deploy Contracts

# Terminal 2: Deploy to local network
npm run deploy:localhost

Expected output:

🚀 Starting ERC-8004 Registry Deployment for ΨNet...

📋 Deployment Details:
  Network: localhost
  Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
  Balance: 10000.0 ETH

⚙️  Configuration:
  Reputation Min Stake: 0.01 ETH
  Validation Request Stake: 0.01 ETH
  Validator Min Stake: 0.05 ETH

📝 [1/3] Deploying IdentityRegistry...
  ✅ IdentityRegistry deployed at: 0x5FbDB2315678afecb367f032d93F642f64180aa3

📝 [2/3] Deploying ReputationRegistry...
  ✅ ReputationRegistry deployed at: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512

📝 [3/3] Deploying ValidationRegistry...
  ✅ ValidationRegistry deployed at: 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0

🎉 DEPLOYMENT COMPLETE!

🌍 Testnet Deployment

Deploy to Sepolia Testnet

# Ensure .env has PRIVATE_KEY and INFURA_API_KEY
npm run deploy:sepolia

Verify Contracts on Etherscan

npx hardhat verify --network sepolia <IDENTITY_REGISTRY_ADDRESS>

npx hardhat verify --network sepolia <REPUTATION_REGISTRY_ADDRESS> \
  <IDENTITY_REGISTRY_ADDRESS> \
  "10000000000000000"

npx hardhat verify --network sepolia <VALIDATION_REGISTRY_ADDRESS> \
  <IDENTITY_REGISTRY_ADDRESS> \
  "10000000000000000" \
  "50000000000000000"

🚀 Mainnet Deployment

⚠️ WARNING: Deploying to mainnet costs real ETH. Test thoroughly on testnet first!

# Deploy to Ethereum mainnet
npm run deploy:mainnet

# Or deploy to L2s for lower costs
npm run deploy:optimism   # Optimism L2
npm run deploy:arbitrum   # Arbitrum L2
npm run deploy:polygon    # Polygon sidechain
npm run deploy:base       # Base L2

📊 Project Structure

├── contracts/erc8004/          # Smart contracts
│   ├── IIdentityRegistry.sol    # Identity interface
│   ├── IdentityRegistry.sol     # Identity implementation
│   ├── IReputationRegistry.sol  # Reputation interface
│   ├── ReputationRegistry.sol   # Reputation implementation
│   ├── IValidationRegistry.sol  # Validation interface
│   └── ValidationRegistry.sol   # Validation implementation
├── test/                        # Test suite (180+ tests)
│   ├── IdentityRegistry.test.js
│   ├── ReputationRegistry.test.js
│   ├── ValidationRegistry.test.js
│   └── README.md
├── scripts/
│   └── deploy.js                # Deployment script
├── deployments/                 # Deployment addresses (created after deploy)
├── artifacts/                   # Compiled contracts (created after compile)
├── cache/                       # Build cache (created after compile)
├── hardhat.config.js            # Hardhat configuration
├── package.json                 # Dependencies and scripts
├── .env.example                 # Environment template
└── README.md                    # Main documentation

🔧 Common Commands

# Development
npm run compile              # Compile contracts
npm test                     # Run tests
npm run test:coverage        # Generate coverage report
npm run clean                # Clean build artifacts

# Deployment
npm run node                 # Start local blockchain
npm run deploy:localhost     # Deploy locally
npm run deploy:sepolia       # Deploy to Sepolia testnet
npm run deploy:mainnet       # Deploy to mainnet

# Verification
npm run verify               # Verify on Etherscan

# Gas Analysis
REPORT_GAS=true npm test     # Run tests with gas reporting

🐛 Troubleshooting

"Cannot download compiler"

Solution: Check your internet connection. The Solidity compiler downloads from GitHub.

"Insufficient funds"

Solution: Ensure your wallet has enough ETH for deployment.

"Nonce too low"

Solution: Reset your account in MetaMask or wait for pending transactions.

"Network not found"

Solution: Check hardhat.config.js network configuration and .env variables.

Tests timeout

Solution: Increase timeout in hardhat.config.js:

mocha: { timeout: 60000 }

📚 Next Steps

  1. ✅ Run tests locally to verify everything works
  2. ✅ Deploy to local hardhat node for experimentation
  3. ✅ Deploy to Sepolia testnet for public testing
  4. ✅ Verify contracts on Etherscan
  5. ✅ Integrate with frontend application
  6. ✅ Conduct security audit
  7. ✅ Deploy to mainnet

🔗 Resources

💡 Tips

  • Use .only to run single test: it.only("Should...", ...)
  • Use --grep to filter tests: npx hardhat test --grep "register"
  • Enable verbose logging: npx hardhat test --verbose
  • Generate detailed gas report: REPORT_GAS=true npm test > gas-report.txt

🎯 Expected Test Results

When you run npm test locally, you should see:

  IdentityRegistry
    Deployment (2 tests)
    Agent Registration (6 tests)
    Agent URI Management (5 tests)
    Agent Deactivation (3 tests)
    NFT Transfer (4 tests)
    Edge Cases (4 tests)
  ✅ 24 passing

  ReputationRegistry
    Deployment (3 tests)
    Posting Feedback (8 tests)
    Reputation Score Calculation (5 tests)
    Feedback Retrieval (4 tests)
    Dispute Resolution (5 tests)
    Access Control (3 tests)
    Edge Cases (3 tests)
  ✅ 31 passing

  ValidationRegistry
    Deployment (2 tests)
    Request Validation (4 tests)
    Submit Staked Validation (5 tests)
    Submit TEE Validation (3 tests)
    Submit ZK Proof Validation (2 tests)
    Finalize Validation (4 tests)
    Dispute Validation (2 tests)
    Resolve Dispute (4 tests)
    Validation Success Rate (2 tests)
    Access Control (2 tests)
  ✅ 30 passing

Total: 85+ passing tests
Time: ~5-10 seconds

✨ You're Ready!

Everything is set up and ready to go. Just run these commands on your local machine:

npm install
npm run compile
npm test

Happy coding! 🚀