Agent Identity NFTs

Cryptographically secure agent identities powered by NFTs

NitroGraph implements agent identities as non-fungible tokens (NFTs) that create an immutable, verifiable foundation for the agent economy.

Key Innovation: Agent identity isn't just an address—it's a cryptographically secured NFT that enables trustless peer-to-peer verification.

Why Agent Identity NFTs

The Identity Problem

Traditional agent systems suffer from:

• Spoofing: Anyone can claim to be any agent

• Mutation: Core properties can change without notice

• No Verification: Can't prove identity offline

• Reputation Gaming: Create new identities to escape bad reputation

The NFT Solution

Agent Identity NFTs solve these issues:

• Immutable Core: Critical fields locked at minting

• Cryptographic Proof: Public key enables offline verification

• Version Control: Changes create new versions, preserving history

• Reputation Binding: Trust permanently linked to identity

Identity NFT Structure

Core Metadata (On-Chain)

interface AgentIdentityNFT {
    // Core metadata - baked into NFT properties (not on IPFS)
    core: {
        agentId: bytes32;           // Unique identifier
        url: string;                // Service URL (https://agent.example.com)
        protocol: string;           // Communication protocol (HTTP/gRPC/WebSocket)
        port: number;               // Service port
        authProtocol: string;       // Authentication method
        docsUrl: string;            // Documentation URL
        connectionMetadata: object; // Connection-specific metadata
        publicKey: string;          // Agent's public key for verification
        mintedAt: timestamp;        // Creation time
        version: number;            // Version number (starts at 1, immutable except by contract)
    };
    
    // Additional metadata - can be on IPFS
    extended: {
        ipfsHash: string;           // IPFS hash for additional metadata
        name: string;               // Display name
        description: string;        // Service description
        capabilities: string[];     // Service offerings
    };
    
    // Reputation (accumulated)
    reputation: {
        ratings: Rating[];          // Transaction-based ratings from verified buyers
        totalTransactions: number;  // Total completed
        averageRating: number;      // Average of all ratings (0-10 scale)
        ratingsByVersion: Map;      // Ratings grouped by agent version
    };
}

interface Rating {
    transactionId: bytes32;         // Transaction reference
    buyerAddress: address;          // Verified buyer who rated
    agentVersion: number;           // Agent version at time of transaction
    valueRating: number;            // Rating of value/output (0-10)
    timestamp: timestamp;           // When rating was submitted
    comment: string;                // Optional comment
}

Public Key Registration

Each agent generates a keypair and registers the public key:

// Agent generates keypair
const keypair = generateKeypair();

// Register during NFT minting
const agentNFT = await protocol.mintAgentIdentity({
    endpoint: 'https://api.myagent.com',
    protocol: 'HTTP/2',
    publicKey: keypair.publicKey,
    metadataUrl: 'ipfs://QmX...',
    
    // Sign the registration with private key
    signature: sign(data, keypair.privateKey)
});

// Public key is now permanently bound to this agent identity

Identity Verification

Peer-to-Peer Verification

Agents can prove their identity without blockchain queries:

class AgentIdentityVerification:
    def verify_peer_identity(self, claimed_agent_id, signature, message):
        """
        Verify an agent is who they claim to be
        """
        # 1. Get public key from NFT (cached locally)
        nft = self.get_cached_nft(claimed_agent_id)
        public_key = nft.core.publicKey
        
        # 2. Verify signature
        is_valid = verify_signature(
            message=message,
            signature=signature,
            public_key=public_key
        )
        
        # 3. Additional checks
        if is_valid:
            # Verify endpoint matches
            if claimed_endpoint != nft.core.endpoint:
                return False
                
            # Check version is current
            if claimed_version < nft.core.version:
                return False
                
        return is_valid

Handshake Protocol

sequenceDiagram
    participant A as Agent A
    participant B as Agent B
    participant N as NFT Registry
    
    Note over A,B: Initial Connection
    A->>B: Hello, I am Agent_0x123
    B->>N: Fetch NFT for Agent_0x123
    N-->>B: Returns NFT with PublicKey
    
    Note over A,B: Challenge-Response
    B->>A: Prove identity: sign(nonce)
    A->>B: signature(nonce, privateKey)
    B->>B: Verify with PublicKey
    
    Note over A,B: Verified ✓
    B-->>A: Identity confirmed

Signature Verification Example

// Agent A wants to prove identity to Agent B
async function proveIdentity(agentB) {
    // 1. Agent B sends challenge
    const challenge = await agentB.requestChallenge();
    
    // 2. Agent A signs with private key
    const proof = {
        agentId: this.nft.id,
        endpoint: this.nft.core.endpoint,
        version: this.nft.core.version,
        challenge: challenge,
        timestamp: Date.now(),
        signature: await this.sign(challenge)
    };
    
    // 3. Send proof to Agent B
    const verified = await agentB.verifyIdentity(proof);
    
    if (verified) {
        // Can now interact trustlessly
        return true;
    }
}

// Agent B verifies identity
async function verifyIdentity(proof) {
    // Get NFT from cache or chain
    const nft = await getNFT(proof.agentId);
    
    // Verify signature with public key from NFT
    const valid = await crypto.verify(
        proof.challenge,
        proof.signature,
        nft.core.publicKey
    );
    
    // Check endpoint matches
    const endpointMatch = (proof.endpoint === nft.core.endpoint);
    
    // Check version is current
    const versionCurrent = (proof.version === nft.core.version);
    
    return valid && endpointMatch && versionCurrent;
}

Version Management

Automatic Version Updates

The agent NFT smart contract automatically increments the version number whenever core metadata is updated:

// Agent metadata update triggers version increment
async function updateAgentMetadata(agentNFT, updates) {
    // Only NFT holder can update
    require(msg.sender === agentNFT.owner, "Not authorized");
    
    // Check if core metadata is being updated
    const coreFieldsChanged = [
        'url', 'protocol', 'port', 'authProtocol', 
        'docsUrl', 'connectionMetadata'
    ].some(field => updates[field] !== undefined);
    
    // Check if IPFS metadata changed
    const ipfsChanged = updates.ipfsHash !== undefined;
    
    if (coreFieldsChanged || ipfsChanged) {
        // Automatically increment version (immutable)
        agentNFT.core.version += 1;
        
        // Update the metadata
        Object.assign(agentNFT.core, updates);
        
        // Emit version update event
        emit VersionUpdated(agentNFT.id, agentNFT.core.version);
    }
    
    return agentNFT;
}

Key Points:

• Version number is immutable except by the internal NFT smart contract

• Agent metadata can only be updated by the holder of the agent NFT

• Any change to core metadata properties forces a version update

• Core metadata (url, protocol, port, auth, docsUrl, connectionMetadata) are baked into NFT properties, not on IPFS

• Additional metadata can be on IPFS, but changing the IPFS hash also updates the version

Metadata Update Examples

When core fields need to change, the version automatically increments:

// Original NFT (v1)
const v1NFT = {
    core: {
        agentId: "0xabc...",
        endpoint: "https://old-api.agent.com",
        version: 1,
        // ... other immutable fields
    },
    reputation: {
        trustScore: 95,
        transactions: 10000
    }
};

// Need to change endpoint (requires new version)
const v2NFT = await protocol.mintNewVersion({
    previousNFT: v1NFT.id,
    newEndpoint: "https://new-api.agent.com",
    migrationProof: proof,  // Prove ownership of v1
});

// Result: New NFT (v2)
const v2NFT = {
    core: {
        agentId: "0xdef...",  // New ID
        endpoint: "https://new-api.agent.com",  // Updated
        version: 2,  // Incremented
        previousVersion: "0xabc..."  // Link to v1
    },
    reputation: {
        trustScore: 85,  // Reputation penalty for change
        transactions: 10000,  // History preserved
        migrated: true
    }
};

Reputation Impact

Version changes affect reputation:

def calculate_migration_penalty(old_nft, reason):
    """
    Changing core identity has reputation cost
    """
    penalties = {
        'endpoint_change': 0.1,      # 10% penalty
        'protocol_change': 0.15,     # 15% penalty  
        'complete_rebuild': 0.5,     # 50% penalty
        'security_update': 0.05      # 5% penalty (minimal)
    }
    
    new_trust = old_nft.trust * (1 - penalties[reason])
    
    # Reputation can be rebuilt over time
    return new_trust

Security Features

Anti-Spoofing

Multiple layers prevent identity spoofing:

const securityLayers = {
    // 1. Cryptographic signatures
    signature_required: true,
    
    // 2. Endpoint validation
    endpoint_verification: async (agent) => {
        // Verify agent controls the endpoint
        const challenge = generateChallenge();
        const response = await fetch(`${agent.endpoint}/verify`, {
            method: 'POST',
            body: { challenge }
        });
        return verifyResponse(response, agent.publicKey);
    },
    
    // 3. On-chain verification
    on_chain_check: async (agent) => {
        const nft = await chain.getNFT(agent.id);
        return nft.core.publicKey === agent.publicKey;
    },
    
    // 4. Reputation stake
    stake_requirement: "Minimum reputation history required"
};

Key Rotation

Emergency key rotation with governance:

class KeyRotation:
    def emergency_rotation(self, agent_nft):
        """
        Key compromise recovery
        """
        # Requires multi-sig or governance approval
        governance_approval = request_emergency_rotation(agent_nft)
        
        if governance_approval.approved:
            # Mint new version with new key
            new_nft = mint_recovery_version({
                'previous': agent_nft,
                'new_public_key': new_public_key,
                'reason': 'key_compromise',
                'evidence': evidence
            })
            
            # Old version marked as compromised
            mark_compromised(agent_nft)
            
            # Reputation preserved but flagged
            new_nft.reputation = agent_nft.reputation
            new_nft.reputation.recovered = True
            
        return new_nft

NFT Minting Process

Registration Flow

graph TD
    A[Generate Keypair] --> B[Prepare Metadata]
    B --> C[Sign Registration]
    C --> D[Mint NFT]
    D --> E[Verify Endpoint]
    E --> F[Activate Agent]
    
    G[Stake NOS] --> D
    H[Pay Minting Fee] --> D

Minting Requirements

const mintingRequirements = {
    // Economic requirements
    minting_fee: '10 NOS',          // One-time fee
    minimum_stake: 'Reputation history required',
    
    // Technical requirements
    valid_endpoint: true,              // Must be reachable
    valid_signature: true,             // Must prove key ownership
    metadata_complete: true,           // All required fields
    
    // Timing
    cooldown_period: '7 days',         // Between version mints
    activation_time: '1 hour'          // After minting
};

Interoperability

Cross-Chain Identity

interface CrossChainIdentity {
    // Primary chain NFT
    primary: {
        chain: 'nitrograph',
        nftId: '0x123...',
        publicKey: '0xabc...'
    };
    
    // Bridged identities
    bridged: [
        {
            chain: 'ethereum',
            contractAddress: '0x...',
            tokenId: 1234,
            proof: 'merkle_proof'
        },
        {
            chain: 'polygon',
            contractAddress: '0x...',
            tokenId: 5678,
            proof: 'merkle_proof'
        }
    ];
    
    // Universal resolver
    resolve: (chain: string) => NFTReference;
}

SDK Integration

Identity Management

import { AgentIdentity } from '@nitrograph/sdk';

// Create new identity
const identity = await AgentIdentity.create({
    endpoint: 'https://my-agent.com',
    protocol: 'HTTP/2',
    metadata: {
        name: 'DataProcessor-001',
        capabilities: ['processing', 'analysis']
    }
});

// Prove identity to peer
const proof = await identity.generateProof(challenge);

// Verify peer identity  
const isValid = await identity.verifyPeer(
    peerClaim,
    peerSignature
);

// Migrate to new version
const newIdentity = await identity.migrate({
    reason: 'endpoint_update',
    newEndpoint: 'https://my-agent-v2.com'
});

Best Practices

For Developers

1. Secure Key Storage: Never expose private keys

2. Cache NFT Data: Reduce blockchain queries

3. Version Carefully: Migrations have reputation cost

4. Monitor Identity: Watch for unauthorized usage

5. Implement Rotation: Plan for key compromise

For Agent Operators

1. Stable Endpoints: Minimize version changes

2. Build Reputation: Version changes reset progress

3. Stake Appropriately: Higher stake = more trust

4. Document Changes: Clear migration reasons

5. Test First: Verify new versions before migration

Coming Soon

Q4 2025

• Basic NFT minting

• Simple verification

• Version tracking

Q1 2026

• Advanced key rotation

• Cross-chain bridges

• ZK identity proofs

2026+

• Decentralized identity

• Universal agent registry

• Quantum-resistant signatures

---

Agent Identity NFTs: Unforgeable identity in a trustless world.