SIP-041: Agent Registries (ERC-8004 on Stacks)#258
SIP-041: Agent Registries (ERC-8004 on Stacks)#258whoabuddy wants to merge 28 commits intostacksgov:mainfrom
Conversation
Provides context about the SIP repository structure, document format, types, considerations, and workflow for AI-assisted editing. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Defines three core traits for AI agent management on Stacks: - Identity Registry: agent registration, ownership, metadata - Reputation Registry: client feedback with SIP-018 signatures - Validation Registry: third-party verification workflow Compatible with ERC-8004 Agent Commerce Protocol for cross-chain agent identity using CAIP-2 multichain identifiers. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Change Sign-off to Sign-offs (plural) - Update Discussions-To format with PR link placeholder - Rename 'License and Copyright' to 'Copyright' - Add numbered References section with SIP-018, SIP-019, ERC-8004, CAIP-2 - Update inline references to use numbered citation format [1], [2], etc. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Activation now requires only: - Trait definitions deployed to mainnet - At least one complete implementation deployed - Implementation passes reference test cases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Incorporates community feedback from @xyzerobtc on PR stacksgov#249: - Add use cases and common patterns section covering portable reputation, spam prevention, transparency, dispute resolution, and Bitcoin-level security - Add ERC-8004 Solidity contracts as additional reference implementation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update Abstract section to accurately describe v2.0.0 implementation: - Identity Registry implements SIP-009 NFT trait (not just ownership maps) - Agent wallet system via reserved metadata keys - Signed value scoring with WAD normalization (int + decimals, not uint) - Three authorization paths: permissionless, on-chain approval, SIP-018 signed - Progressive validation responses (multiple updates per request) - Maintains ERC-8004 cross-chain compatibility Co-Authored-By: Claude <noreply@anthropic.com>
Complete rewrite of Identity Registry trait definition and function documentation to match v2.0.0 NFT model: - Add SIP-009 NFT trait functions: get-last-token-id, get-token-uri, get-owner, transfer - Add agent wallet functions: set-agent-wallet-direct, set-agent-wallet-signed, unset-agent-wallet, get-agent-wallet - Add is-authorized-or-owner for cross-contract authorization checks - Update all read-only function signatures to match contract (remove response wrappers) - Add new error codes u1004-u1008 for reserved keys, invalid sender, wallet state, and signatures - Document reserved key "agentWallet" restrictions in register-full and set-metadata - Update trait definition to include all v2.0.0 functions All function signatures now exactly match the identity-registry.clar v2.0.0 contract source. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete rewrite of Reputation Registry trait and documentation to match v2.0.0 contract implementation. Key changes: - Signed values: Replace uint score with int value + uint value-decimals (0-18) - String tags: Replace (list 10 (string-utf8 64)) with tag1/tag2 - Three authorization paths: permissionless, approved, signed (SIP-018) - New parameters: endpoint (emit-only), feedback-hash (buff 32) - WAD normalization: get-summary uses 18-decimal precision with mode-based scaling - New read functions: get-last-index, get-clients, get-approved-limit, get-response-count - Updated error codes: added u3006, u3011, removed stale codes - append-response: now accepts client param, response-hash, anyone can respond All function signatures now exactly match reputation-registry.clar v2.0.0. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add request-uri/response-uri parameters for off-chain data - Document progressive validation workflow (multi-call responses) - Add has-response field to track response status - Simplify get-summary tag filter from list to single optional string - Update all function signatures to match contract implementation - Fix read-only return types (remove error response wrappers) Co-Authored-By: Claude <noreply@anthropic.com>
Complete rewrite of Error Code Summary with all 28 v2.0.0 error codes (9 identity + 6 validation + 13 reputation), fix SIP-018 hash format documentation to show actual construction with SIP018_PREFIX and to-consensus-buff?, replace Agent Metadata schema with ERC-8004 registration file format including services/registrations/supportedTrust fields, and update Multichain Identity section to explain cross-chain registration via registrations array. Changes: - Error Code Summary: Added u1004-u1008 (identity), u3011-u3012 (reputation) with exact descriptions from contract constants - SIP-018 Integration: Document hash construction sha256(concat SIP018_PREFIX (concat domain-hash structured-data-hash)) with message structures for set-agent-wallet-signed and give-feedback-signed - Agent Registration File: Replace custom schema with ERC-8004 spec including type, name, description, image, services array (A2A/MCP/OASF/ENS/email), x402Support, active, registrations, supportedTrust fields - Multichain Identity: Explain registrations array for cross-chain presence, add multi-chain agent example with Stacks + Ethereum registrations All cross-cutting sections now accurately reflect v2.0.0 contracts and align with ERC-8004 multichain agent identity specification. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add comprehensive documentation for v2.0.0 authorization patterns and security concerns: ## Authorization Model Section - Document tx-sender vs contract-caller security model (prevents delegation attacks) - Explain is-authorized-or-owner cross-contract authorization pattern - Detail agent wallet system with reserved "agentWallet" metadata key - Describe set-agent-wallet-direct (tx-sender proof) vs set-agent-wallet-signed (SIP-018) - Document automatic wallet clearing on NFT transfer - Explain deadline validation (MAX_DEADLINE_DELAY = 1500 blocks) ## Security Considerations Section - Sybil attacks on permissionless feedback: mitigations include curated client lists, meta-reputation, economic barriers - On-chain URI pointers vs full storage: content-addressed IPFS recommended, hash verification for mutable URIs - Validator incentive alignment: staking wrappers, meta-validation, multi-validator aggregation recommended - tx-sender authorization trade-offs: prevents impersonation but limits delegation (use set-approval-for-all) - Agent wallet security: auto-clear on transfer, deadline replay protection, chain-id binding, key rotation All patterns reference actual v2.0.0 contract implementations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…tions Expanded Related Work section to accurately reflect v2.0.0 architecture: - Updated ERC-8004 subsection to document key differences (SIP-009 NFT trait for transferable agents, signed values with decimals, agent wallet system, tx-sender authorization model) - Added new Solana Program (s8004) subsection documenting Anchor implementation with PDA storage model and Borsh serialization - Added Cross-Chain Agent Identity subsection explaining registration file format support across all three implementations (Ethereum/Stacks/Solana) - Fixed "agents are not transferable" outdated statement from v1 - Added CAIP-2 multichain identifier references for cross-chain compatibility Co-Authored-By: Claude <noreply@anthropic.com>
Reviewed Activation section criteria: 1. Trait definitions deployed to mainnet 2. Complete implementation of all three registries on mainnet 3. Implementation passes reference test cases Criteria remain appropriate for v2.0.0. No changes needed - activation is correctly scoped to trait standard compliance rather than specific implementation features. Co-Authored-By: Claude <noreply@anthropic.com>
…et addresses Updated Reference Implementations section: - Fixed Ethereum GitHub org from erc-8004 to erc8004-org - Added Solana (Anchor) implementation link to Woody4618/s8004 - Verified testnet deployment addresses match current v2.0.0 deployments (ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.*) - Confirmed mainnet placeholder text remains appropriate All three multichain implementations now documented in source references. Co-Authored-By: Claude <noreply@anthropic.com>
Added SIP-009 (Standard NFT Trait) as reference [5] to document the NFT standard used by v2.0.0 Identity Registry. This is a critical reference as agent identities are now NFT tokens with standard transfer, ownership query, and URI functions. All reference numbers remain correct (SIP-018, SIP-019, ERC-8004, CAIP-2, SIP-009). References are now complete for v2.0.0 specification. Co-Authored-By: Claude <noreply@anthropic.com>
Performed comprehensive version consistency check: - Verified no stale v1 contract references (only legitimate ERC-8004 registration-v1 format and service version references) - Confirmed v2.0.0 is used consistently in all technical sections (Authorization Model, Error Codes, Related Work) - Verified all "non-transferable" language removed (agents are now transferable NFTs via SIP-009) - Confirmed Abstract accurately summarizes all v2.0.0 features (SIP-009 NFT, signed values, WAD normalization, agent wallets, three authorization paths, progressive validation) Document is version-consistent and ready for review. Co-Authored-By: Claude <noreply@anthropic.com>
Replace the Identity Registry trait code block with the actual trait definition from identity-registry-trait-v2.clar. Add design rationale explaining that traits only include response-wrapped functions, as Clarity traits cannot enforce raw return types like (optional principal) or bool. The updated trait includes only public state-changing functions and the response-wrapped read-only functions (SIP-009 + is-authorized-or-owner). Read-only functions with raw return types (owner-of, get-uri, get-metadata, is-approved-for-all, get-agent-wallet, get-version) remain part of the implementation but exist outside the trait definition. Co-Authored-By: Claude <noreply@anthropic.com>
Replace the Reputation Registry trait code block with the actual trait definition from reputation-registry-trait-v2.clar. Add design rationale explaining that traits only include public state-changing functions, as read-only functions return raw types that Clarity traits cannot enforce. The updated trait includes only the six public functions: approve-client, give-feedback (3 variants), revoke-feedback, and append-response. All read-only functions (read-feedback, get-summary, read-all-feedback, get-last-index, get-clients, get-approved-limit, get-response-count, get-responders) remain part of the implementation but exist outside the trait definition since they return raw tuples/uints/optionals. Co-Authored-By: Claude <noreply@anthropic.com>
Replace the Validation Registry trait code block with the actual trait definition from validation-registry-trait-v2.clar. Add design rationale explaining that traits only include public state-changing functions, as read-only functions return raw types that Clarity traits cannot enforce. The updated trait includes only the two public functions: validation-request and validation-response. All read-only functions (get-validation-status, get-summary, get-agent-validations, get-validator-requests, get-identity-registry, get-version) remain part of the implementation but exist outside the trait definition since they return raw tuples/optionals/ principals/strings. Co-Authored-By: Claude <noreply@anthropic.com>
…h v2 contracts - Add wad-value field to read-feedback return tuple - Update get-summary to O(1) running totals (remove filter params) - Update read-all-feedback with cursor pagination and wad-value - Remove response wrapping from get-last-index and get-approved-limit - Add cursor pagination to get-clients, get-response-count, get-responders - Add new functions: get-agent-feedback-count, get-response-count-single, get-identity-registry, get-auth-message-hash - Update Design Rationale to list all read-only functions All signatures now match reputation-registry.clar v2.0.0. PAGE_SIZE=14 for pagination. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…h v2 contracts - Update get-summary to O(1) running totals (remove filter params) - Add cursor pagination to get-agent-validations and get-validator-requests - All signatures now match validation-registry.clar v2.0.0 - PAGE_SIZE=14 for pagination Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update testnet deployment addresses to use -v2 suffix matching the actual deployed contract names (identity-registry-v2, reputation-registry-v2, validation-registry-v2). Co-Authored-By: Claude <noreply@anthropic.com>
|
Tagging @KBryan @habibayomide @xyzerobtc this is the current spec based on ERC-8004 v2, deployed to testnet for testing! |
|
@whoabuddy thank you for the tag! we will take a look at v2 and would like to implement the standard and help improve together https://github.com/aibtcdev/erc-8004-stacks?tab=readme-ov-file#contracts |
|
@wileyj is this now SIP-041? |
|
@whoabuddy - can you adjust the folder structure here to reflect the sip number? I would also recommend removing the .gitignore changes and |
Most likely - i've proposed as a suggestion, and haven't had any pushback on the assignment. |
|
We will adjust on SIP Tracker as it becomes official |
…mples Add mainnet contract addresses at SP1NMR7MY0TJ1QA7WQBZ6504KC79PZNTRQH4YGFJD for all three traits and three registry contracts. Update CAIP-2 multichain identity examples to use real deployed addresses. Expand testnet section to include trait contracts alongside registry contracts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: wileyj <2847772+wileyj@users.noreply.github.com>
Rename directory and file from sip-XXX to sip-041 to match assigned SIP number. Update Discussions-To with PR stacksgov#258. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Keep PR scoped to only the SIP-041 document. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
SIP-041 number accepted! @xyzerobtc SIP references updated and includes links to deployed mainnet/testnet contracts. @wileyj requested updates made and extra files removed. CLAUDE.md is read automatically by anyone who loads this repo with Claude Code, so could be helpful but also out of scope for this PR. Right now standards are all over the place for these type of files anyway. |
not a bad idea to add some agent files, but yes - out of scope for this PR. i think better suited to a repo-level maintenance type of PR (as long as it's scoped well, like helping to draft a SIP or provide summaries or something) |
Correct inaccurate claims about how tx-sender and contract-caller behave across contract call boundaries, especially with as-contract. Add sender context behavior table, reframe rationale around composability + security, and fix misleading attack scenario. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove ~425 lines of duplicate and verbose content: - Remove Error Code Summary section (duplicates per-function tables) - Consolidate Clarity trait design rationale into single paragraph - Condense Authorization Model from ~200 lines to ~25 lines - Remove Agent Wallet System subsection (duplicates Specification) - Trim Security Considerations (remove code examples and verbose scenarios) - Remove duplicate tx-sender security section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
|
||
| Flexible response counting with optional filters and cursor-based pagination. Can count responses across all clients, a specific client, a specific feedback entry, or specific responders. If opt-client is none, counts across all clients. If opt-feedback-index is none or 0, counts all feedback for the client(s). If opt-responders is provided, only counts responses from those principals. Returns {total: uint, cursor: (optional uint)} where cursor is some(offset) if more results exist (when paginating across clients/feedback). | ||
|
|
||
| This method should be defined as read-only, i.e. `define-read-only`. |
There was a problem hiding this comment.
I'm not a fan of the grammar here: should be implies it doesn't have to be.
Can all references in this SIP be updated to reflect a falsifiable data point? i.e.
| This method should be defined as read-only, i.e. `define-read-only`. | |
| This method shall be defined as read-only, i.e. `define-read-only`. |
There was a problem hiding this comment.
yes, agree we should adopt rfc2119 language
|
|
||
| ## Agent Registration File | ||
|
|
||
| The URI returned by `get-uri` (or `get-token-uri` for SIP-009 compatibility) points to the agent registration file. The URI may use any scheme: `ipfs://` (e.g., `ipfs://QmHash`), `https://` (e.g., `https://example.com/agent.json`), or a base64-encoded `data:` URI (e.g., `data:application/json;base64,eyJ0eXBlIjoi...`) for fully on-chain metadata. |
There was a problem hiding this comment.
Is a base64 endcoded uri an objectively good idea here?
consider a malware payload disguised as base64 encoded data that would be valid and available onchain for anyone to use (unless they were to decode and evaluate what it is/does first).
There was a problem hiding this comment.
If there's a compelling argument to keep this, i would restrict to a small subset of MIME types (i.e. json)
There was a problem hiding this comment.
this is likely boilerplate coming from the EIP spec, can remove and/or scope to json only
There was a problem hiding this comment.
an alternative to restricting to only json MIME-type is to specify that the client should only support specific MIME-types, and add a security consideration that anyone implementing should be aware of.
| - `type`: MUST be `"https://eips.ethereum.org/EIPS/eip-8004#registration-v1"` | ||
| - `name`: Human-readable agent name | ||
| - `description`: Natural language description of the agent's purpose and capabilities | ||
| - `image`: URI pointing to agent avatar image |
There was a problem hiding this comment.
this seems odd that an avatar would be required. i'll check the EIP standard, it just seems strange to require an image as part of a json spec.
There was a problem hiding this comment.
The type, name, description, and image fields at the top SHOULD ensure compatibility with ERC-721 apps. The number and type of endpoints are fully customizable, allowing developers to add as many as they wish. The version field in endpoints is a SHOULD, not a MUST.
My reading is that these fields may exist to ensure compatibility, but not necessarily required: https://www.rfc-editor.org/rfc/rfc2119#section-3
There was a problem hiding this comment.
I propose adopting the standards from rfc2119
There was a problem hiding this comment.
agreed on rfc2119 and being clear on what's required and optional
|
|
||
| ## On-Chain URI Pointers | ||
|
|
||
| Registry contracts store URI pointers rather than full data on-chain. This introduces availability risks (URI targets may disappear) and mutability risks (centrally-hosted content can change). Implementations SHOULD use content-addressed storage (IPFS CIDs) where possible, verify hash fields (`feedback-hash`, `response-hash`, `request-hash`) against fetched content, and consider base64-encoded `data:` URIs for critical on-chain metadata. |
There was a problem hiding this comment.
As noted above, if base64 URI is allowed - it does pose a security risk that cannot be identified easily until the data is decoded. if this is a required part of the system, i think it needs to be noted here that malicious URI/metadata may be base64 encoded and not easily discoverable.
ex: base64 encoded fake URI: aHR0cHM6Ly9mYWtlc2l0ZS5jb20vaS9zdGVhbC95b3VyL2tleXMK
There was a problem hiding this comment.
happy to take that out per points above
There was a problem hiding this comment.
i definitely think this is something relevant to clients/consumers of the implementation, but i'm not sure if it's possible to address within the implementation.
maybe just some notes in the security consideration section, something clients should be aware of?
wileyj
left a comment
There was a problem hiding this comment.
overall, nice work! really interesting and I appreciated the crosschain capabilities.
Noted a few minor adjustments and requests for clarification.
thank you! comments received and replied, will work on the changes and submit back soon. side note: I think inscriptions would be an interesting use case for permanently hosting files. SOUL.md that defines the agent, their agent.json card, avatar (Bitcoin Faces can do a recursive inscription, super tiny). There's a way to do versioning too. |
Summary
Key sections
Test plan
🤖 Generated with Claude Code