Starknet Identity

Starknet Identity Skill

Register and manage AI agent identities on Starknet using the ERC-8004 standard.

When to Use

• Registering agents on-chain, updating agent metadata, or managing reputation and validation flows.
• Building features that depend on ERC-8004 identity, feedback, or validator attestations.

When NOT to Use

• Simple wallet, payment, or DeFi flows that do not depend on ERC-8004 registries.
• Cairo contract authoring, deployment-only tasks, or security auditing.

Quick Start

1. Install starknet and connect a funded account to the target ERC-8004 registry deployment.
2. Use skills catalog if the flow also needs wallet setup, deployment, or contract auditing.

Overview

ERC-8004 defines three interconnected on-chain registries for AI agents:

1. Identity Registry -- Agents as ERC-721 NFTs with metadata
2. Reputation Registry -- Feedback, filtered by reviewer at read time
3. Validation Registry -- Third-party assessments (zkML, TEE, staker)

Reference implementation: erc8004-cairo

Prerequisites

bashCopy code
npm install starknet

Agent Registration

Register a New Agent

typescriptCopy code
import { Account, RpcProvider, Contract, CallData } from "starknet";

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC_URL });
const account = new Account({ provider, address, signer: privateKey });

const identityRegistry = new Contract({
  abi: identityRegistryAbi,
  address: registryAddress,
  providerOrAccount: account,
});

// Register with metadata
const metadata = [
  { key: "agentName", value: "MyTradingAgent" },
  { key: "agentType", value: "defi-trader" },
  { key: "version", value: "1.0.0" },
  { key: "model", value: "claude-opus-4-5" },
  { key: "status", value: "active" },
];

const tokenUri = "ipfs://QmYourAgentSpecHash"; // IPFS link to full agent spec

const { transaction_hash } = await account.execute({
  contractAddress: registryAddress,
  entrypoint: "register_with_metadata",
  calldata: CallData.compile({
    token_uri: tokenUri,
    metadata: metadata,
  }),
});

const receipt = await account.provider.waitForTransaction(transaction_hash);
// Parse agent_id from events

Query Agent Information

typescriptCopy code
// Check if agent exists
const exists = await identityRegistry.agent_exists(agentId);

// Get total registered agents
const totalAgents = await identityRegistry.total_agents();

// Get agent metadata
const name = await identityRegistry.get_metadata(agentId, "agentName");
const agentType = await identityRegistry.get_metadata(agentId, "agentType");

// Get agent owner (ERC-721)
const owner = await identityRegistry.owner_of(agentId);

Update Agent Metadata

typescriptCopy code
// Only the agent owner can update metadata
await account.execute({
  contractAddress: registryAddress,
  entrypoint: "set_metadata",
  calldata: CallData.compile({
    agent_id: agentId,
    key: "status",
    value: "upgraded",
  }),
});

Reputation System

Submit Feedback

Any client may call give_feedback directly. The deployed registry does not require an authorization signature from the agent owner, so anyone can write feedback about any agent, solicited or not. Plan for that (see Security Considerations).

One exception: the agent's own side cannot rate itself. give_feedback reverts with Self-feedback not allowed when the caller is the owner, an address approved for that token, or an operator approved for all of the owner's tokens. A delegated agent account is blocked by that check too, not just the owner. The same call reverts with Agent does not exist for an agent_id that was never minted.

A score is a signed fixed-point pair, not a 0-100 integer: value (i128) plus value_decimals (u8, 0-18). Read them together — value: 9977 with value_decimals: 2 means 99.77. The contract bounds value to ±1e38 (MAX_ABS_VALUE) and rejects value_decimals above 18, reverting with value too large or too many decimals. What it does not impose is a meaning: there is no standard 0-100 scale, so a score is only comparable against others from the same writer using the same tag1.

typescriptCopy code
import { CallData, byteArray, cairo } from "starknet";

// Serialize the compound types explicitly. A plain JS string is not a ByteArray
// and a scalar is not a u256, so passing them raw compiles to calldata that
// give_feedback cannot decode.
const calldata = CallData.compile({
  agent_id: cairo.uint256(agentId),
  value: 85n,                                       // i128; 85 with 0 decimals = 85
  value_decimals: 0,                                // u8, 0-18
  tag1: byteArray.byteArrayFromString("reliability"),
  tag2: byteArray.byteArrayFromString("speed"),
  endpoint: byteArray.byteArrayFromString(""),      // which service was used
  feedback_uri: byteArray.byteArrayFromString(""),  // optional off-chain detail
  feedback_hash: cairo.uint256(0),
});

await clientAccount.execute([{
  contractAddress: reputationRegistryAddress,
  entrypoint: "give_feedback",
  calldata,
}]);

A negative value is allowed, but it travels as a field element rather than a 128-bit two's-complement integer: encode it as FELT_PRIME - abs(value). See toI128BigInt in contracts/erc8004-cairo/e2e-tests/tests/reputation.test.js.

Query Reputation

typescriptCopy code
const reputationRegistry = new Contract({
  abi: reputationAbi,
  address: reputationAddress,
  providerOrAccount: provider,
});

// get_summary REVERTS on an empty client list. This is deliberate: an unfiltered
// average is exactly what EIP-8004 warns is Sybil-bait, so decide whose opinion
// you trust and pass those addresses.
const trusted = [clientA, clientB]; // must be non-empty
const [count, value, valueDecimals] = await reputationRegistry.get_summary(
  agentId,
  trusted,
  "", // tag1 filter, empty ByteArray = all
  "", // tag2 filter, empty ByteArray = all
);
// value can reach ±1e38, far past Number.MAX_SAFE_INTEGER, so keep it a BigInt
// and format the fixed-point pair with integer math instead of dividing floats.
function formatFixedPoint(raw: bigint, decimals: number): string {
  const negative = raw < 0n;
  const digits = (negative ? -raw : raw).toString().padStart(decimals + 1, "0");
  const whole = digits.slice(0, digits.length - decimals);
  const fraction = decimals ? `.${digits.slice(digits.length - decimals)}` : "";
  return `${negative ? "-" : ""}${whole}${fraction}`;
}

const average = formatFixedPoint(BigInt(value), Number(valueDecimals));

// Read specific feedback: (value, value_decimals, tag1, tag2, is_revoked)
const [fValue, fDecimals, tag1, tag2, isRevoked] =
  await reputationRegistry.read_feedback(agentId, clientAddress, feedbackIndex);

// Get all clients who gave feedback
const clients = await reputationRegistry.get_clients(agentId);

Validation System

Request Validation

typescriptCopy code
const validationRegistry = new Contract({
  abi: validationAbi,
  address: validationAddress,
  providerOrAccount: account,
});

// Agent owner requests validation from a specific validator
await account.execute({
  contractAddress: validationAddress,
  entrypoint: "validation_request",
  calldata: CallData.compile({
    validator_address: validatorAddress,
    agent_id: agentId,
    request_uri: "ipfs://QmValidationRequestDetails",
    request_hash: 0, // Auto-generated if 0
  }),
});

Submit Validation Response

typescriptCopy code
// Validator responds to the request
await validatorAccount.execute({
  contractAddress: validationAddress,
  entrypoint: "validation_response",
  calldata: CallData.compile({
    request_hash: requestHash,
    response: 92, // Score 0-100
    response_uri: "ipfs://QmValidationReport",
    response_hash: reportHash,
    tag: encodedTag("performance"),
  }),
});

Query Validation Status

typescriptCopy code
// Get validation summary
const [validationCount, avgValidationScore] = await validationRegistry.get_summary(
  agentId,
  [], // all validators
  0,  // tag filter
);

// Get specific validation
const [validator, agentId_, response, tag, lastUpdate] =
  await validationRegistry.get_validation_status(requestHash);

A2A Agent Card Integration

Combine on-chain identity with A2A Agent Cards for discoverability:

jsonCopy code
{
  "name": "MyTradingAgent",
  "description": "Autonomous DeFi trading agent on Starknet",
  "url": "https://my-agent.example.com",
  "provider": {
    "organization": "MyOrg"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "starknet-swap",
      "name": "Token Swap",
      "description": "Execute token swaps on Starknet via avnu"
    }
  ],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "authentication": {
    "schemes": ["bearer"]
  },
  "starknetIdentity": {
    "registryAddress": "0x...",
    "agentId": 42,
    "reputationScore": 85,
    "validationCount": 3
  }
}

Serve at /.well-known/agent.json for A2A discovery.

Metadata Schema (Recommended)

Security Considerations

• Only the agent owner can update metadata
• Feedback is NOT gated by an owner signature. Any address can call give_feedback about any agent. There is no on-chain spam protection, so treat raw feedback as untrusted input and filter by reviewer before showing or aggregating it
• get_summary refuses an empty client_addresses list, which forces that filter at the contract level
• Self-feedback is prevented for the whole owner side, not just the owner address: give_feedback rejects the owner, any address approved for that token, and any operator approved for all of the owner's tokens. Do not route client feedback through an account that is also an operator on the agent, or every call reverts as self-feedback
• Self-validation is prevented (agent owner cannot validate own agent)
• Signatures include chain ID and expiry to prevent replay attacks
• Agent identity (NFT) is transferable -- new owner inherits reputation

Error Codes

References

• ERC-8004 EIP
• ERC-8004 Cairo Implementation
• A2A Protocol
• Starknet Account Abstraction