Skip to content

SIP-041: Agent Registries (ERC-8004 on Stacks)#258

Open
whoabuddy wants to merge 28 commits intostacksgov:mainfrom
aibtcdev:feat/sip-erc-8004-agent-registration
Open

SIP-041: Agent Registries (ERC-8004 on Stacks)#258
whoabuddy wants to merge 28 commits intostacksgov:mainfrom
aibtcdev:feat/sip-erc-8004-agent-registration

Conversation

@whoabuddy
Copy link
Contributor

Summary

  • Adds a new SIP defining standard trait interfaces for on-chain AI agent registries on Stacks
  • Defines three registries: Identity (SIP-009 NFT-based agent registration), Reputation (feedback and scoring), and Validation (task-based verification)
  • Specifies trait definitions, read-only query functions, error codes, authorization models (permissionless, on-chain approval, SIP-018 signed), and activation criteria
  • All specifications verified against v2.0.0 contract implementations deployed on testnet

Key sections

  • Trait Definitions: Identity (13 functions), Reputation (6 functions), Validation (2 functions) — traits enforce only public/response-wrapped signatures per Clarity constraints
  • Read-Only Functions: O(1) summary lookups, cursor-based pagination (PAGE_SIZE=14), raw return types
  • Authorization: Three paths — permissionless, on-chain approval, SIP-018 structured data signing
  • Security Considerations: Sybil resistance, feedback integrity, validation collusion prevention
  • Reference Implementation: Links to deployed v2 testnet contracts

Test plan

  • Cross-reviewed all trait definitions against v2 trait files
  • Verified all 46 function signatures match contract code
  • Confirmed all 24 error codes match
  • Validated testnet addresses use -v2 suffix
  • Checked PAGE_SIZE, MAX_DEADLINE_DELAY constants
  • Manual review of prose for clarity and completeness

🤖 Generated with Claude Code

whoabuddy and others added 22 commits February 5, 2026 21:47
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>
@whoabuddy whoabuddy changed the title Add SIP-XXX: Standard Trait Definition for Agent Registries SIP-XXX Agent Registries (ERC-8004 on Stacks) Feb 7, 2026
@whoabuddy
Copy link
Contributor Author

whoabuddy commented Feb 7, 2026

Tagging @KBryan @habibayomide @xyzerobtc this is the current spec based on ERC-8004 v2, deployed to testnet for testing!

@xyzerobtc
Copy link

@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 wileyj changed the title SIP-XXX Agent Registries (ERC-8004 on Stacks) SIP-041: Agent Registries (ERC-8004 on Stacks) Feb 11, 2026
@xyzerobtc
Copy link

@wileyj is this now SIP-041?

@wileyj
Copy link
Contributor

wileyj commented Feb 11, 2026

@whoabuddy - can you adjust the folder structure here to reflect the sip number?
./sips/sip-clarity5/sip-clarity5.md -> ./sips/sip-041/sip-clarity5.md

I would also recommend removing the .gitignore changes and CLAUDE.md (i didin't see a reference to it in the SIP, included by mistake?)

@wileyj
Copy link
Contributor

wileyj commented Feb 11, 2026

@wileyj is this now SIP-041?

Most likely - i've proposed as a suggestion, and haven't had any pushback on the assignment.

@xyzerobtc
Copy link

We will adjust on SIP Tracker as it becomes official

whoabuddy and others added 4 commits February 11, 2026 16:13
…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>
@whoabuddy
Copy link
Contributor Author

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.

@wileyj
Copy link
Contributor

wileyj commented Feb 12, 2026

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)

whoabuddy and others added 2 commits February 11, 2026 19:47
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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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`.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there's a compelling argument to keep this, i would restrict to a small subset of MIME types (i.e. json)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is likely boilerplate coming from the EIP spec, can remove and/or scope to json only

Copy link
Contributor

@wileyj wileyj Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I propose adopting the standards from rfc2119

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

happy to take that out per points above

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

@wileyj wileyj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

overall, nice work! really interesting and I appreciated the crosschain capabilities.

Noted a few minor adjustments and requests for clarification.

@wileyj wileyj requested a review from a team February 17, 2026 20:40
@whoabuddy
Copy link
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants