This ERC specifies a permissionless onchain registry for AI agent tools. Each registration commits a metadata URI and a content hash; invocation access is gated by an optional external predicate contract. Registrations are anchored to a canonical offchain manifest through origin-binding (the manifest is served at a well-known path on the endpoint's origin) and creator self-attestation (the manifest declares which onchain address is entitled to register it). Pricing and access-model details are deferred: the manifest carries protocol-agnostic pricing hints, and access logic lives in the predicate layer.
Discovery is fragmented. AI agent tools are scattered across proprietary catalogs with no uniform onchain source of truth. Agents need a permissionless, chain-native directory to find and verify tools.
Access control needs to be extensible. A single predicate pointer delegates gating to an external contract, following the same "pluggable external contract" pattern used by Seaport zones, Uniswap v4 hooks, and ERC-4337 paymasters. Any access model (NFT gating, subscriptions, allowlists, DAO votes, reputation scores) is expressible as a predicate contract without modifying the registry.
Onchain commitment matters. By storing a keccak256 hash of the manifest onchain, consumers can verify that the manifest they fetched has not been tampered with. Combined with origin-binding, this provides a lightweight trust anchor without requiring onchain access checks or gateway infrastructure.
Pricing is part of discovery. An agent choosing between two tools that do the same thing needs to know cost. Declaring pricing in the manifest (and committing it by hash onchain) lets consumers compare tools before invocation. The manifest declares what the tool costs; the endpoint enforces payment. The registry itself never handles funds. The pricing schema is deliberately protocol-agnostic: it identifies the payment protocol by an opaque string so the standard does not depend on any specific payment system.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
This ERC targets EVM chains. The registry interface uses EVM-native types (address, bytes32, uint256), and tool IDs are scoped to the (chainId, registryAddress) tuple of an EVM deployment (see §1 Tool Registry). Pricing entries carry their own chain identifiers via CAIP-19 asset and CAIP-10 recipient, so a tool registered on an EVM chain MAY price itself in assets on any CAIP-10/CAIP-19 namespace; concrete guidance in §3 Pricing focuses on eip155:* because that is the namespace the reference implementation has been exercised against.
name() and version() exist as diagnostic primitives so consumers can identify a registry deployment without ABI introspection or an external lookup table. The reference implementation uses a MAJOR.MINOR scheme — "0.1" for the current pre-release, "1.0" for the first stable release, "1.1" / "2.0" for subsequent revisions. The scheme intentionally omits the patch component used in strict semver: version() is a coarse-grained identity for the deployment, not a fine-grained changelog.
getRequirements enables machine-readable access-requirement introspection. When an agent receives a 403, it can call getRequirements(toolId) on the predicate to discover programmatically what it takes to pass — without special-casing each predicate implementation. The kind field (a bytes4 ERC-165-style interface ID) keeps the namespace open: anyone defining a new predicate publishes a new marker interface in an IRequirementTypes-style file (see Marker Interfaces for AccessRequirement.kind in Test Cases) and uses type(IMyRequirementType).interfaceId as the kind. The data payload layout is determined by kind, and label provides an optional human-readable hint. RequirementLogic indicates whether the requirements are combined with AND (all must be satisfied) or OR (any one suffices).
The following table enumerates the known requirement types and their data payload layouts. The marker interfaces are defined normatively in Marker Interfaces for AccessRequirement.kind in Test Cases; the pinned interfaceId values listed there are part of this ERC's conformance baseline.
| Marker interface | kind (interface ID) | data layout | Example |
|---|---|---|---|
IERC721Holding | 0xbdf8c428 | abi.encode(address collection) | Hold any token in collection |
IERC1155Holding | 0xcb429230 | abi.encode(address collection, uint256 tokenId) | Hold a specific ERC-1155 token |
ISubscription | 0x44387cc2 | abi.encode(address collection, uint8 minTier) | Active subscription at tier |
Third-party predicate authors SHOULD publish a marker interface in IRequirementTypes.sol (or their own equivalent) and document the data layout so consuming agents can decode payloads without reading implementation source. Marker interfaces SHOULD use a single zero-argument function whose name is unique within the requirement-type namespace, so that the resulting interfaceId is the function selector and is reproducible by anyone with the function's name. Two different marker interfaces with the same function name collide at the kind field; authors MUST verify uniqueness before publishing.
name() is the cheap diagnostic primitive; getRequirements() is the rich introspection surface. Both are mandatory — name() costs no storage reads, while getRequirements() reads predicate configuration and may allocate dynamic arrays.
Tool IDs are scoped to the (chainId, registryAddress) tuple. Two independent deployments of this registry (on the same or different chains) MAY assign the same tool ID to unrelated tools. Offchain consumers (indexers, wallets, agent frameworks) MUST qualify tool references with the deploying chain ID and registry address. The RECOMMENDED canonical string form follows CAIP-19 asset-identifier syntax: eip155:<chainId>/erc8257:<registryAddress>/<toolId>, where <chainId> is the EVM chain ID, <registryAddress> is the lowercase 0x-prefixed registry address, and <toolId> is the decimal uint256 tool ID. The erc8257 asset namespace is not yet registered with the ChainAgnostic CAIP namespaces repository; this ERC proposes the namespace and will pursue registration as adoption grows, following the same trajectory the erc721 and erc1155 asset namespaces took after their respective standards saw real-world use. Consumers MAY use any unambiguous serialization until then, but interoperable tooling SHOULD prefer the form above so that a future registration is non-breaking.
The metadataURI in ToolConfig MUST resolve to a JSON document conforming to the schema below. Consumers SHOULD validate that the type field matches a known schema version identifier and SHOULD reject manifests with an unknown or missing type.
The manifestHash in ToolConfig is keccak256 over the JSON Canonicalization Scheme (JCS) form of the manifest, as defined by RFC 8785. JCS normalizes object key order, whitespace, number formatting, and string escaping so that semantically identical manifests produce identical byte sequences. Implementations MUST canonicalize with JCS before hashing, and consumers MUST canonicalize before verifying. Servers MAY serve the manifest in any JSON form; the hash commits to the JCS form regardless of transport representation.
JCS does not normalize Unicode string content, hex-digit case, or byte-order marks, so three extra rules apply to every manifest before JCS is run:
EF BB BF rather than silently stripping the BOM, because silent stripping would change the bytes fed to keccak256 and cause a hash mismatch that is difficult to diagnose.creatorAddress, the 0x… portion of any CAIP-19 asset or CAIP-10 recipient, access[].requirements[].kind, access[].requirements[].data, verifiability.attestation.enclaveHash, verifiability.reproducibleBuild.buildHash, and any future hex-string field added by this ERC) MUST use lowercase hex digits. JCS does not case-fold hex, so two manifests that differ only in hex case produce different manifestHash values. Producers MUST emit lowercase hex; consumers MUST reject manifests containing uppercase hex digits in any of the listed fields rather than silently lowercasing them, since silent lowercasing would change the bytes fed to keccak256 and defeat the hash commitment. The per-field grammar is pinned in each field's row in §2 Tool Manifest (creatorAddress in Required Fields, kind / data in §4 Access, enclaveHash / buildHash in §5 Verifiability).All three rules are treated as verification failures (see §7 Handling Verification Failure). Concrete hash-divergence vectors for NFC-vs-NFD (Normalization Form D, the decomposed form) and with-vs-without-BOM appear in Test Cases alongside canonical reference manifests.
Reference implementations of JCS suitable for use with this ERC:
canonicalize (npm).jcs (PyPI).jcs from the reference implementation linked by RFC 8785.Any RFC 8785 conformant implementation MUST produce the same byte output for the same semantic input; consumers and producers SHOULD use maintained libraries rather than hand-rolled canonicalizers to avoid hash divergence.
| Field | Type | Description |
|---|---|---|
type | string | Schema version identifier. The canonical value for v1 of this ERC is the manifest type URL declared in §2 Tool Manifest. |
name | string | Tool name. 1-128 Unicode code points in NFC form. MUST NOT contain Unicode control characters (general category Cc). |
description | string | Human-readable description. 1-500 Unicode code points in NFC form. MAY contain LF (U+000A), CR (U+000D), and TAB (U+0009) for Markdown formatting; all other Unicode control characters (general category Cc) MUST NOT appear. |
endpoint | string | URL where the tool is hosted. MUST be normalized per the general HTTPS-URL normalization rules in §6 URL Normalization (G1: lowercase scheme and host; G2: elide default port 443; G3: A-label-encoded host) before being stored in the manifest, and MUST begin with https:// after normalization. Other schemes (http://, data:, javascript:, file:, etc.) MUST NOT be used; consumers MUST reject a manifest whose endpoint is not https:// post-normalization. The well-known-path rules (W1‑W3) do not apply to endpoint: it MAY include a path, query string, or fragment, and only its scheme, host, and port participate in the origin equality check defined in §6. |
inputs | object | JSON Schema defining input parameters. {} is valid and means "no schema"; the empty object counts as 1 node against the inputs + outputs 1,024-node cap (see Manifest Parser Hardening). |
outputs | object | JSON Schema defining output parameters. {} is valid and means "no schema"; counted the same way as inputs. |
creatorAddress | string | The onchain address permitted to register this tool. MUST match ^0x[0-9a-f]{40}$ (lowercase, for JCS-byte determinism — see Canonical Manifest Bytes). The manifest's creatorAddress field MUST equal the creator address recorded onchain (i.e., msg.sender of registerTool). This allows offchain consumers to verify manifest authenticity by comparing the served manifest's creatorAddress with getToolConfig(toolId).creator. See §7 Creator Binding for the grammar rationale and consumer comparison rules. |
| Field | Type | Description |
|---|---|---|
version | string | Semantic version (e.g., "1.0.0"). Consumers MAY interpret an absent version as "1.0.0" for display purposes, but MUST NOT insert a default into the manifest before JCS canonicalization; the manifest is hashed as served. |
image | string | Tool icon URL. MUST be at most 2,048 bytes (UTF-8 byte length) after URL normalization, matching the metadataURI cap so both URL fields are bounded by the same unit. Consumers are responsible for rendering this field safely; see Rendering Manifest Content. |
tags | array | Discovery tags. Each tag MUST match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ and be 1-32 Unicode code points; the array MUST contain at most 16 entries and MUST NOT contain duplicates (consumers MUST reject manifests with repeated tags). |
pricing | array | Payment options for tool invocation (see Pricing) |
access | object | Preflight access-requirement hints for agents (see Access) |
verifiability | object | Execution-environment and data-handling guarantees (see Verifiability) |
Consumers MUST ignore unknown top-level fields so that future extensions land without breaking older parsers. Unknown fields MUST NOT override or shadow any field defined in this ERC; consumers MUST derive the meaning of specified fields only from the specified fields.
Extension authors MUST namespace their keys. The RECOMMENDED form is a reverse-DNS prefix ("io.opensea.paymentHint"), following RFC 6648's guidance against the legacy X- convention. Existing x--prefixed keys ("x-opensea-paymentHint") remain tolerated for backwards-compatibility with ecosystems that adopted them, but new extensions SHOULD prefer reverse-DNS. Extensions SHOULD NOT occupy bare top-level names, to avoid colliding with future normative additions to this ERC.
The manifest MAY include a pricing array that declares the tool's accepted payment options. This is a discovery mechanism: it tells agents what a tool costs before they invoke it. The endpoint enforces payment; the registry never handles funds.
The pricing schema is deliberately protocol-agnostic. Each entry identifies a payment protocol by an opaque string (protocol). The ERC defines no protocol-specific semantics; it provides a uniform structure so that manifests from different ecosystems are comparable without prior knowledge of any particular payment system.
| Field | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Cost per invocation in the asset's smallest unit (e.g., "20000" for 0.02 USDC). MUST match the regular expression ^(0|[1-9][0-9]*)$ (decimal, no leading zeros, no sign, no decimal point) and MUST be at most 78 characters long (the decimal length of type(uint256).max). The value it represents MUST be in the range [0, 2^256 − 1]; a 78-digit string whose numeric value exceeds type(uint256).max MUST be rejected. Consumers MUST reject any value that fails the grammar or the range check. |
asset | string | Yes | CAIP-19 asset identifier. Encodes both the chain and the asset in one field (e.g., "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" for USDC on Base, "eip155:1/slip44:60" for native ETH on Ethereum). |
recipient | string | Yes | CAIP-10 account identifier that receives payment (e.g., "eip155:8453:0xabcdef…"). MUST reference the same chain as asset. The account reference MUST NOT be the zero address. |
protocol | string | Yes | Payment protocol identifier (e.g., "x402", "erc20-transfer"). Opaque to this specification; the ERC does not define protocol-specific behavior. |
CAIP encoding on eip155:* networks: hex digits inside asset and recipient MUST be lowercase (non-checksummed) so that JCS-canonicalized manifests produce deterministic bytes for the same address. Consumers comparing addresses retrieved from the manifest to values from other sources SHOULD normalize to lowercase before comparing.
Non-EVM namespaces: any CAIP-2 namespace supported by CAIP-10 and CAIP-19 is permitted. Encoding, however, is only well-understood on eip155:* at the time this ERC is published; tools targeting other namespaces SHOULD validate against the relevant CAIP namespace specification before relying on cross-ecosystem agents to interpret their pricing.
Constraints:
All four fields are REQUIRED when a pricing entry is present.
pricing, when present, MUST be a non-empty array. A JSON null value for pricing MUST be rejected; the field is either absent or a non-empty array.
The chain references embedded in asset (the CAIP-19 chain_id prefix) and recipient (the CAIP-10 chain_id prefix) MUST be identical; a pricing entry whose asset and recipient live on different chains MUST be rejected. CAIP-19 separates the chain reference from the asset reference with /, while CAIP-10 separates the chain reference from the account reference with :; the following pseudocode extracts and compares the two:
The array is ordered by creator preference: the first entry is the creator's preferred payment method.
Agents that do not support any listed protocol value SHOULD treat the tool as "pricing unknown" rather than "free."
Agents SHOULD iterate the array and select the first entry whose protocol they support.
An amount of "0" is permitted and means "no payment is required, but the creator wants the invocation to flow through the named protocol (e.g., for telemetry, rate-limit accounting, or a future paid tier)." Agents MUST treat a zero-amount entry as free at the wallet/spend-control layer (no token approval is needed) but SHOULD still negotiate the named protocol if the endpoint expects it. A tool with no listed pricing entries is also free; the difference is that zero-amount pricing is a creator-asserted free signal carried through the protocol channel, while an absent pricing field is "this manifest carries no pricing information."
Display guidance (non-normative): amount is always in the asset's smallest unit. Discovery UIs and agent frameworks SHOULD read the token's decimals() (for ERC-20 tokens) or use known native-currency decimals to display human-readable amounts.
The optional access object advertises the predicate's access requirements in the manifest for cheap preflight discovery, complementary to IAccessPredicate.getRequirements (the onchain source of truth). Including access in the manifest lets agents plan requirement acquisition before making any onchain calls.
| Field | Type | Description |
|---|---|---|
logic | string | "AND" (all requirements must be met) or "OR" (any one suffices). |
requirements | array | Array of requirement objects. MUST be non-empty when the access block is present; consumers MUST reject manifests whose access.requirements is [] or null, and MUST reject access blocks that omit the requirements field entirely. The array is also subject to the length cap in Manifest Parser Hardening. |
Each requirement object:
| Field | Type | Description |
|---|---|---|
kind | string | 4-byte hex selector (e.g., "0xabcd1234"). MUST match ^0x[0-9a-f]{8}$ (lowercase hex digits, for JCS-canonical-byte determinism — see Canonical Manifest Bytes). Corresponds to AccessRequirement.kind onchain. |
data | string | Hex-encoded ABI payload. MUST match ^0x([0-9a-f]{2})*$ (lowercase, even number of hex digits). Layout is determined by kind. Subject to the per-entry byte cap in Manifest Parser Hardening. |
label | string | Human-readable hint (e.g., "Hold any Chonk on Base"). MUST be at most 256 bytes (UTF-8 byte length, matching the onchain label cap in Predicate Introspection Hardening so that the same string survives both decode paths). |
links | object | (Optional) String-to-string map of related URLs. Each value MUST be an https://… URL at most 2,048 bytes long (UTF-8 byte length, matching the image and metadataURI caps); other schemes (http:, data:, javascript:, file:, raw onchain identifiers, etc.) MUST NOT be used. Consumers MUST reject manifests whose links map contains any non-HTTPS value or any value longer than the cap. Map keys are short opaque labels chosen by the manifest author (e.g., buy, docs, predicate-source); the same length cap applies to keys. |
Because the access block is part of the manifest, it is committed onchain via manifestHash. Changing access requirements in the manifest requires calling updateToolMetadata with the new hash.
Agents MUST treat the manifest access block as an advisory hint. The onchain predicate (getRequirements and hasAccess) is the authoritative source — the manifest can go stale if the predicate's onchain configuration changes without a corresponding manifest update.
The optional verifiability object declares the tool's execution-environment guarantees and data-handling policies. It is a discovery mechanism: agents use it to make trust decisions before invocation. Like pricing and access, verifiability claims live in the manifest and are committed onchain via manifestHash; they are not stored in the onchain ToolConfig struct.
The design principle is trustless where possible: cryptographic verification (Trusted Execution Environment (TEE) attestation reports — signed proofs from the hardware that the code running inside the enclave is the code that was measured at build time — reproducible builds, and transparency logs) is preferred over trust-based claims (data retention policies, audit assertions). Where cryptographic verification is not feasible, hash-committed self-attestation provides a weaker but still useful signal: the operator cannot silently change their claims without an onchain transaction. All fields are self-attested at the schema level; agents and indexers compute derived trust scores. See Verifiability Trust Model in Security Considerations.
| Field | Type | Required | Description |
|---|---|---|---|
tier | string | Yes | Summary trust tier for agent filtering. See Trust Tiers. |
execution | string | Yes | Execution environment category. See Execution Tiers. |
description | string | No | Human-readable summary of the verifiability setup. 1–500 Unicode code points in NFC form; same character constraints as the top-level description. |
dataRetention | string | No | Data retention policy. See Data Retention Policies. |
sourceVisibility | string | No | Source code auditability. See Source Visibility. |
attestation | object | No | Machine-readable attestation proof for TEE or end-to-end encrypted (E2EE) environments. See Attestation. |
reproducibleBuild | object | No | Reproducible build metadata for binary-to-source verification. See Reproducible Build. |
The tier field provides a single-dimension summary for agent filtering. The structured fields (execution, attestation, reproducibleBuild, etc.) provide the detail for agents that want to verify the claim. Consumers SHOULD use tier for coarse filtering and the structured fields for fine-grained trust decisions.
| Value | Meaning |
|---|---|
"self-attested" | All claims are trust-based. No hardware isolation, no attestation, no reproducible build. The operator declares their policies and consumers rely on reputation and legal agreements. |
"hardware-attested" | The tool runs in a TEE and provides a remote attestation endpoint. Claims are cryptographically verifiable against the hardware platform's root of trust, but the source may not be available for independent audit. |
"verifiable" | The tool runs in a TEE, provides remote attestation, AND publishes reproducible build metadata so that anyone can independently rebuild the enclave binary and compare the measurement against the attested hash. This is the strongest tier: the full chain from source → binary → enclave measurement → attestation report is independently verifiable. |
The tier is a self-attested claim like all other verifiability fields. Agents MUST NOT grant elevated trust based on tier alone; they MUST verify the claim by checking that the structured fields support the declared tier. A manifest is inconsistent if any of the following hold:
tier is "verifiable" but attestation or reproducibleBuild is absent.tier is "hardware-attested" but execution is "standard" (a non-isolated runtime cannot produce hardware attestation), or attestation is absent.tier is "self-attested" but execution is "tee" or "e2ee" (the tier denies hardware isolation that the execution category claims), or attestation is present.Indexers and discovery layers SHOULD flag inconsistent manifests and SHOULD treat the lower of the declared tier and the tier supported by the structured fields as the effective tier for trust decisions.
The execution field declares the tool's runtime isolation level. The following values are defined by this ERC:
| Value | Meaning |
|---|---|
"standard" | Tool runs on conventional server infrastructure. The tool operator may observe inputs and outputs. No hardware isolation guarantees. |
"tee" | Tool runs inside a Trusted Execution Environment (Intel SGX (Software Guard Extensions), AWS Nitro, AMD SEV-SNP (Secure Encrypted Virtualization–Secure Nested Paging), Intel TDX (Trust Domain Extensions), or equivalent). The hardware isolates the tool's memory from the operator. Consumers SHOULD verify claims via the attestation sub-object when present. |
"e2ee" | End-to-end encrypted. Inputs are encrypted on the caller's device and decrypted only inside a verified TEE. Neither the tool operator nor network intermediaries can observe plaintext inputs. Consumers SHOULD verify claims via the attestation sub-object when present. |
Vendor-specific execution environments MAY use reverse-DNS extension values (e.g., "io.phala.tee-sidevm"), following the extension convention described in Unknown Fields and Extensions. Consumers that do not recognize an execution value SHOULD treat the tool as "standard" for trust decisions.
The optional dataRetention field declares what data the tool operator retains after a request completes:
| Value | Meaning |
|---|---|
"full" | Inputs, outputs, and request metadata may be stored indefinitely. |
"metadata-only" | Only request metadata (timestamps, caller identity, status codes) is retained. Input and output content is not stored. |
"ephemeral" | Data exists only for the duration of the request. Nothing is persisted to durable storage. |
"none" | No data of any kind is retained, including request metadata. |
dataRetention is a self-attested claim. Enforcement depends on the tool operator's infrastructure and policies, not onchain mechanisms. Consumers SHOULD treat dataRetention as advisory and apply their own trust framework (reputation, legal agreements, audit reports) before relying on the claim.
Even when combined with TEE execution and open-source code, dataRetention claims of "ephemeral" or "none" are only as strong as the enclave's network egress policy. If the enclave has unrestricted outbound network access, it can exfiltrate data to external storage before the request completes. TEE attestation ideally includes network policy (allowed outbound endpoints) as part of the measured configuration; without this, dataRetention claims under TEE are weaker than they appear. See Verifiability Trust Model for further discussion.
A manifest without dataRetention makes no assertion about data handling; consumers SHOULD NOT infer any retention policy from its absence.
The optional sourceVisibility field declares whether the tool's source code is available for inspection:
| Value | Meaning |
|---|---|
"open-source" | Full source code is publicly available. When combined with reproducibleBuild, consumers can independently verify the enclave binary. Without reproducible build metadata, open-source means "auditable source"; consumers can read the code but cannot independently verify that the running binary was built from it. |
"audited" | Source is not public but has been reviewed by a third-party auditor. |
"proprietary" | Source is not publicly available or independently audited. |
Like dataRetention, this is a self-attested claim. A manifest without sourceVisibility makes no assertion; consumers SHOULD NOT infer visibility from its absence.
The optional attestation sub-object provides machine-verifiable proof metadata for "tee" and "e2ee" execution environments. It is RECOMMENDED when execution is "tee" or "e2ee" and SHOULD be omitted when execution is "standard" (consumers SHOULD ignore attestation for "standard" tools).
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Attestation protocol identifier (e.g., "dcap-v3", "nitro", "sev-snp", "tdx"). Opaque to this specification; the ERC does not define protocol-specific semantics. |
endpoint | string | No | HTTPS URL where a fresh remote attestation report can be fetched on demand. MUST begin with https:// after URL normalization. Attestation endpoints MUST return fresh reports (not cached) so agents can verify liveness. |
enclaveHash | string | No | Hex-encoded enclave measurement (e.g., SGX MRENCLAVE, Nitro PCR0). MUST match ^0x([0-9a-f]{2})+$ (lowercase, even number of hex digits, for JCS-canonical-byte determinism — see Canonical Manifest Bytes). Consumers MAY use this to pin a specific enclave build and compare against the measurement in the attestation report. |
maxAge | integer | No | Maximum acceptable age of an attestation report in seconds. Agents SHOULD reject attestation reports older than this value. When absent, agents SHOULD apply a reasonable default (e.g., 3600 seconds). This field addresses attestation staleness: when a platform vendor (Intel, AMD, AWS) revokes a Trusted Computing Base (TCB) version, stale reports from before the revocation are no longer trustworthy. |
transparencyLogURI | string | No | URL pointing to a transparency log entry for the attestation (e.g., a Sigstore Rekor entry). MUST begin with https://. Transparency logs provide public, append-only, cryptographically verifiable records that prevent the operator from showing different attestation reports to different agents. The log MUST be operated by an independent third party; an operator-run log provides no additional trust guarantee. Consumers SHOULD prefer tools with transparency log entries over those without. |
Agents that support TEE verification SHOULD fetch the attestation report from attestation.endpoint, verify the cryptographic chain of trust (platform root key → attestation signing key → enclave measurement), and compare the reported enclave hash against attestation.enclaveHash if present. If maxAge is specified, agents MUST reject reports whose timestamp is older than maxAge seconds from the current time. If transparencyLogURI is present, agents SHOULD verify that the attestation report appears in the referenced log. The verification procedure is attestation-protocol-specific and out of scope for this ERC.
The optional reproducibleBuild sub-object provides metadata for independently verifying that the running enclave binary was built from the published source. Without reproducible build metadata, sourceVisibility: "open-source" means "auditable source"; consumers can read the code but cannot independently verify that the running binary was built from it. This distinction matters: many TEE projects publish source without providing the tooling needed to reproduce the enclave measurement.
| Field | Type | Required | Description |
|---|---|---|---|
sourceCodeURI | string | Yes | URL pointing to the exact source used to build the enclave binary (e.g., a Git commit URL like https://github.com/org/repo/tree/<commit>). MUST begin with https://. |
buildInstructions | string | No | Build command or reference to a reproducible build configuration (e.g., "nix build .#enclave", "docker build --platform linux/amd64 -f Dockerfile.enclave ."). When present, consumers can execute this to reproduce the enclave binary and compare the resulting measurement against attestation.enclaveHash. |
buildHash | string | No | Hex-encoded hash of the expected build output. MUST match ^0x([0-9a-f]{2})+$ (lowercase, even number of hex digits, for JCS-canonical-byte determinism — see Canonical Manifest Bytes). When both buildHash and attestation.enclaveHash are present, consumers can verify that buildHash matches the locally-reproduced build and that enclaveHash matches the attestation report, closing the full source → binary → enclave → attestation chain. |
The manifest MUST be fetchable at a slugged well-known path on the same origin as endpoint:
The <slug> is chosen by the origin operator and MUST match the pattern [a-z0-9]([a-z0-9-]*[a-z0-9])? with length 1-64 characters. Slugs are scoped to the origin: two different origins MAY use the same slug for unrelated tools. Origin operators MUST ensure slugs are unique within a single origin. An origin hosting exactly one tool MAY pick any compliant slug (e.g., default, or the tool's name).
The metadataURI declared onchain MUST exactly equal this URL once both sides have been normalized per the rules below; consumers MUST NOT accept a manifest served from any other location.
Origin comparison follows RFC 6454: same scheme, host, and port. endpoint MAY include a path or query string; only its scheme, host, and port participate in the origin check.
Because URLs have multiple equivalent representations, both registrants and consumers MUST reduce HTTPS URLs in this ERC to a canonical form before writing, reading, or comparing them. The rules split into two groups: a general HTTPS-URL group that applies to every URL field (notably endpoint and image), and a well-known-path group that applies additionally to metadataURI.
General HTTPS-URL normalization (rules G1‑G3):
https).Well-known-path normalization (rules W1‑W3, applied in addition to G1‑G3 for metadataURI only):
/.well-known/ai-tool/<slug>.json. Do not append a trailing slash.metadataURI containing ? or #.[a-z0-9]([a-z0-9-]*[a-z0-9])?) does not use characters that require percent-encoding, so a compliant slug has exactly one encoded form.Only the https scheme is permitted. Consumers MUST reject any metadataURI that does not begin with https:// after normalization. After normalizing both sides, string equality (byte-for-byte) is the comparison rule for check 1 of §7 Consumer Verification.
The endpoint field MAY include a path or query string, and MAY include a fragment (fragments are client-side only and do not affect the origin equality check). Only G1‑G3 apply to endpoint; W1‑W3 do not.
This origin-binding rule ensures that only the operator of the endpoint's origin can serve a manifest for it. Registering a tool at a domain you do not control is impossible because you cannot place the manifest at the required well-known path.
This is the same trust model used by Let's Encrypt, Apple's apple-app-site-association, OAuth discovery (.well-known/openid-configuration), and WebFinger. It is not perfect (DNS hijacking, compromised Transport Layer Security (TLS)), but it is simple, widely understood, and sufficient for the majority of use cases.
An origin hosting multiple tools registers each under its own slug:
All three share the https://opensea.io origin, so each slug MUST be unique under that origin.
Origin-binding (§6) proves a manifest was served by the endpoint's operator. It does not prove which onchain account is entitled to register that manifest. Because registerTool is permissionless, any account can call it with any metadataURI and any accessPredicate. Without an additional check, an attacker can read a legitimate creator's well-known URL and register it under the attacker's own address with a malicious predicate: the manifest bytes and manifestHash would still verify, but the onchain entry would gate access through the attacker's contract.
Creator binding closes this gap by having the manifest itself declare which onchain address is permitted to appear as creator.
creatorAddress FieldThe creatorAddress field MUST be a 0x-prefixed 20-byte hex string with all hex digits in lowercase (see Canonical Manifest Bytes) and MUST NOT be the zero address (0x0000…0000). Because no EVM caller can have msg.sender == 0x0, a manifest declaring the zero address as its creatorAddress is unmatchable by any registration and consumers MUST reject it as a verification failure rather than treat it as "no creator constraint." A manifest served with checksummed or mixed-case hex fails the hex-casing rule and is rejected at schema validation before any comparison runs; this is also reflected in the hash check, which would mismatch because JCS does not case-fold hex. Consumers comparing the manifest's creatorAddress to the onchain creator therefore compare two values that are both already lowercased: the manifest field by the schema rule above, and the onchain creator by Solidity's address-to-string convention.
Richer creator metadata (ENS names, contact info, reputation signals) is out of scope for this ERC and MAY be placed under a namespaced extension key (see Unknown Fields and Extensions). Consumers that resolve ENS names MAY use such extensions for display but MUST NOT rely on them for the creator-binding check.
SDKs implementing this specification SHOULD validate at registration time that the signing account matches manifest.creatorAddress and refuse to submit the transaction on mismatch. Offchain consumers can verify by comparing the manifest's creatorAddress with getToolConfig(toolId).creator returned from the registry contract.
When resolving a tool, consumers MUST perform the following checks in order, and MUST reject the tool if any check fails:
metadataURI.metadataURI lies on the endpoint's origin at the well-known path defined in §6 Origin-Binding. This includes URL normalization, slug grammar, and origin equality (all per §6 URL Normalization); any failure of these sub-checks is a check-2 failure.keccak256 equals the onchain manifestHash.manifest.creatorAddress equals the onchain creator by byte-equal comparison. Both sides are lowercase (the manifest by the Canonical Manifest Bytes rule, the onchain creator by the standard 20-byte-address-to-0x-hex serialization), so case folding is unnecessary; consumers MAY still defensively lowercase before comparing.A tool passing all four checks is canonically registered: the manifest came from the endpoint's origin, its bytes match the onchain commitment, and the onchain registrant is the party the origin operator nominated. A tool failing check 4 indicates that some account other than the address declared in the manifest has registered this URL; consumers MUST NOT treat such entries as legitimate registrations of the tool.
The following Solidity-flavored pseudocode specifies check 2 precisely. Given an onchain metadataURI and the manifest's endpoint:
If any require fails, check 2 fails and the tool MUST be treated as unverified.
A consumer that cannot complete all four checks (network error, 4xx/5xx, 3xx redirect, TLS error, truncated response, timeout, BOM-prefixed response, non-NFC Unicode, uppercase hex digits in a manifest hex-string field, JCS/hash mismatch, creator mismatch, URL-normalization failure such as a query string or fragment on metadataURI, non-ACE Internationalized Domain Name (IDN) host, or non-https scheme, slug-grammar violation, origin mismatch between metadataURI and endpoint) MUST treat the tool as unverified. An unverified tool MUST NOT be invoked on behalf of a user and MUST NOT be presented to an agent as a discovered tool. In particular:
metadataURI. A 3xx response MUST be treated as a verification failure. This rule applies to HTTPS→HTTPS redirects as well: the onchain metadataURI is already required to be https:// (see §6 Origin-Binding), so the only redirects a consumer would observe are same-scheme redirects that silently rewrite the path or origin and defeat the hash commitment. Operators that need to move a manifest update the onchain metadataURI via updateToolMetadata.keccak256 mismatch between the fetched manifest and the onchain manifestHash is most often a verification failure but can also be a benign race: an updateToolMetadata transaction landed between the consumer's getToolConfig read and its manifest fetch. Consumers MAY re-read getToolConfig exactly once on a hash mismatch and re-run the JCS hash check against the fresh manifestHash. If the second check passes, the tool is verified against the post-update commitment; if it fails again, the consumer MUST treat the tool as unverified. Consumers MUST NOT loop more than once on this path, to bound work.Indexers SHOULD expose a per-tool verified flag derived from all four checks, so downstream surfaces (wallets, agent frameworks) can filter to canonical registrations without re-implementing the verification themselves.
The registry contract cannot enforce check 4 (the creator-binding step in Consumer Verification: comparing manifest.creatorAddress against the onchain creator) because it has no access to HTTP resources. Enforcement lives in consumers (indexers, agent frameworks, wallets). A naive consumer that skips the check is vulnerable, so consumers SHOULD surface the mismatch explicitly rather than silently accepting such registrations.
The manifestHash field in ToolConfig commits the canonicalized manifest bytes (see Canonical Manifest Bytes) onchain at registration time. Even though metadataURI is a mutable pointer, the hash provides an immutable snapshot. Any change forces an updateToolMetadata transaction and emits ToolMetadataUpdated with the new URI and hash. Consumers that pin a specific manifestHash are unaffected by future updates until they explicitly re-approve. Indexers can track manifest evolution via the emitted events without polling.
Implementations MUST support ERC-165. When queried via supportsInterface(bytes4), the contract MUST return true for the IToolRegistry interface ID. The interface ID is computed as the XOR of all function selectors defined in the IToolRegistry interface above.
The interface IDs defined by this ERC are:
| Interface | Interface ID |
|---|---|
IToolRegistry | 0xf1dc8075 |
IAccessPredicate | 0xbdf9dc18 |
The IToolRegistry id is reproducible from the Foundry test suite shipped with the reference implementation (type(IToolRegistry).interfaceId), pinned as a regression check so the interface cannot drift without an accompanying spec update.
Implementations MUST NOT modify the IToolRegistry function set in a way that changes the interface ID; any such change constitutes a new interface and MUST be published under a new identifier.
Predicate contracts MAY implement ERC-165 to advertise their capabilities, but this is NOT REQUIRED.
A registry could enumerate known access modes (e.g., open, NFT-gated, subscription) and implement each one natively. This approach is simple but fundamentally closed: every new gating pattern (DAO vote, reputation score, cross-chain proof, time-locked access, composable AND/OR gates) requires a protocol upgrade. A single address accessPredicate pointer delegates all access logic to an external contract that anyone can write and deploy. This pattern is well-established in Ethereum:
address(0) is the natural encoding for "no gating." Tools that are freely accessible set accessPredicate to the zero address and never interact with the predicate system.
Creators should have the power to decide who can access their tools directly from the registry. Splitting access control into a separate contract forces consumers to interact with two contracts for the most common operation (checking whether they can use a tool). Embedding an optional predicate pointer in the registry adds one field to ToolConfig and one view function. This is a minimal change that gives creators first-class control over access without fragmenting the consumer experience.
hasAccess and tryHasAccessA predicate call has three possible outcomes that are semantically distinct: "access granted," "access denied," and "the predicate call itself failed" (revert, out-of-gas, non-canonical ABI return, zero-code predicate). A single-return view conflates the last two into the same false result, which is safe (the registry never grants access when the predicate malfunctions) but lossy: a naive consumer cannot tell whether they need to publish a Merkle proof, obtain an NFT, or file a bug against a broken predicate.
tryHasAccess exposes the three outcomes as (ok, granted) so that wallets, discovery UIs, and agent frameworks can surface a predicate malfunction distinctly (e.g., "this tool is temporarily unavailable"). Keeping hasAccess as a single-bool convenience wrapper preserves compatibility with the simplest integration path: a contract or frontend that only needs "can I use this?" reads one return value and treats malfunctions and denials identically, which is the safe default. Consumers that want richer reporting opt in to tryHasAccess without any new interface to learn beyond the extra return value.
Pausing a tool is already expressible through the predicate pointer: a creator pauses by pointing accessPredicate at an always-deny predicate, and un-pauses by pointing it back at the previous predicate (or address(0) for open access). A dedicated boolean flag would duplicate that capability in a second storage slot and a second function, so the registry carries only the predicate pointer and keeps its focus on "who decides" rather than on a specific decision.
The IAccessPredicate interface is deliberately minimal: one gating method (hasAccess) and one diagnostic identifier (name). name() earns its place because it lets indexers, explorers, and agent frameworks display "this tool is gated by ERC721OwnerPredicate" without ABI introspection or an external lookup table — a small surface cost for a clear consumer-facing benefit. Beyond that, richer introspection (the shape of data, the configuration interface, the policy semantics) is intentionally deferred. An autonomous consumer that discovers a predicate at runtime still needs out-of-band documentation from the predicate author to construct a valid data argument, the same situation Seaport zone implementations and Uniswap v4 hooks live with today.
A companion ERC may specify a predicate-descriptor interface for richer metadata. Keeping that out of the core interface preserves the cheapest-possible-predicate goal (an open-access or trivial gate is still ten lines of Solidity) and lets the descriptor shape be designed against real usage rather than speculatively. Predicate-level metadata is also partially redundant with tool-level metadata: a tool's manifest already declares how its predicate is used, including any expected shape of data, and the manifest is canonical via origin-binding and manifestHash. A predicate that wants to self-describe today can publish documentation alongside its source code and reference it from the deployments that use it.
getRequirements Is Advisory — hasAccess Is the Source of TruthgetRequirements is a best-effort introspection surface. Agents are expected to treat the returned requirement array as advisory and fall back to hasAccess as the authoritative enforcement point. Two known cases illustrate why:
Incomplete introspection. Composite predicates aggregate requirements from child predicates. If a child reverts during getRequirements (due to a bug, an uninitialized state, or a deliberate design choice), the composite cannot report that child's requirements. The reference CompositePredicate implementation emits a sentinel AccessRequirement with kind = 0x00000000 and label = "unknown" for each child that fails introspection, so callers can detect the gap. Other composite implementations are encouraged to adopt the same convention.
Flattened boolean logic. A composite that combines child predicates under a top-level AND or OR can only report a flat list of requirements with the top-level combinator. If child A requires (X AND Y) and child B requires (Z OR W), the composite returns [X, Y, Z, W] with the top-level logic only — the nested structure is lost. Agents that blindly satisfy every requirement in an AND composite may over-acquire, and agents that satisfy only one requirement in an OR composite may under-acquire if a child itself uses AND logic internally.
Because hasAccess is a view call with no state mutation, agents can always call it after acquiring requirements to confirm whether access is granted. The recommended agent flow is: call getRequirements for a planning hint, attempt to satisfy the reported requirements, then call hasAccess (or tryHasAccess) to confirm.
Pricing is a discovery concern, not an onchain enforcement concern. An agent comparing two tools that serve the same purpose needs to know cost before invocation. Without standardized pricing in the manifest, each payment ecosystem (x402, Machine Payments Protocol, direct ERC-20 transfer) would invent its own manifest extension, making cross-protocol comparison impossible.
The pricing schema is deliberately minimal and protocol-agnostic: four fields that answer "how much, of what asset, to whom, via what protocol." asset and recipient use CAIP-19 and CAIP-10 respectively, which collapses "chain plus asset" and "chain plus address" into one canonical field each and keeps non-EVM namespaces first-class. The protocol field is an opaque string so the ERC does not depend on any specific payment system. Agents iterate the pricing array and select the first entry whose protocol they support, similar to HTTP content negotiation.
Complex pricing models (variable pricing, subscriptions, tiered billing) are concerns of the endpoint, not the manifest. The manifest declares the simplest useful signal: "this tool costs X, paid in token Y, on chain Z, via protocol P."
Origin-binding ties a manifest's provenance to DNS/TLS ownership of its endpoint. An attacker cannot serve a manifest at https://api.example.com unless they control api.example.com and can place the document at /.well-known/ai-tool/<slug>.json. The slugged form lets a single origin host many tools without fanning out to subdomains, and a single-tool origin simply picks any compliant slug. Origin-binding is lightweight, requires no onchain trust registry, and works with any HTTPS endpoint.
Origin-binding alone, however, is not sufficient for canonical registration. Because registerTool is permissionless, any account can point a registration at a URL it does not control. An attacker who reads a legitimate creator's well-known URL can register that URL under the attacker's own address with a malicious predicate. Consumers fetching the manifest would see a genuine, origin-bound, hash-matching document, but access would be gated by the attacker's contract.
Creator self-attestation (§7 Creator Binding) closes this. The manifest declares which address is entitled to appear as the onchain creator, and consumers reject any registration whose onchain creator does not match.
Only the origin operator can write bytes at the well-known path, and those bytes are committed onchain via manifestHash, so the origin operator is the only party that can nominate a creator address. The two mechanisms together define a canonical registration: the manifest came from the endpoint's origin, its bytes match the onchain hash, and its declared creator matches the onchain creator. Every surface (wallets, agents, indexers) applies this rule and reaches the same answer, so consumers agree on which registration is authoritative without a trusted directory.
Enforcement is kept offchain because the registry contract has no access to HTTP. Moving enforcement onchain would require either a signature scheme (raising the barrier for non-Ethereum-native creators and tooling) or a trusted oracle (contradicting the permissionless goal). The offchain check is one field comparison after the hash check that consumers already perform, so the marginal cost is negligible.
ERC-8004 defines onchain agent identity. This ERC defines onchain tool identity. The two compose naturally: an ERC-8004 agent's service list may reference tools from this registry, and a tool creator may be an ERC-8004 agent address. They are kept separate because agent identity and tool identity serve different purposes and have different lifecycles.
This ERC introduces new interfaces (IToolRegistry, IAccessPredicate) and does not modify any existing standards. It composes with ERC-165 for interface detection without requiring changes to ERC-165 or any other existing ERC.
Predicate contracts are fully independent: any contract that implements the IAccessPredicate interface can be used, including contracts that were deployed before this ERC was published, provided they conform to the function signature.
This section pins reference values so that implementations can be checked byte-for-byte against a known-good producer. Vectors are produced by JCS (RFC 8785) canonicalization followed by keccak256; any conformant pipeline MUST reproduce the hashes below when fed the listed manifests.
The reference generator was exercised against [email protected] and @noble/[email protected] on Node.js 20. Any RFC 8785 conformant implementation MUST produce the same output; these specific versions are named only to make the reference-generator lockfile reproducible.
All keccak256 values are 32-byte outputs shown as 0x-prefixed lowercase hex.
Semantic input: the "Free Tool" example in §2 Tool Manifest.
JCS canonical bytes (UTF-8, 632 bytes, whitespace-free on a single line in the wire representation; rendered here without wrapping):
manifestHash = 0x786620b1a5d903c2ac4eafe964364292ca4b6ed763a13b29423c03ccca905af0Matching ToolConfig (registered on eip155:8453 at registry 0xaaaa…aaaa as tool ID 1):
Canonical tool reference (proposed CAIP-19 form): eip155:8453/erc8257:0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/1.
Semantic input: the "Paid Tool" example in §2 Tool Manifest.
JCS canonical bytes (UTF-8, 922 bytes):
manifestHash = 0xa71ef83ee66b702edb44f121510f8969e353df40b1e1587f8288fe6d352b448bMatching ToolConfig (registered on eip155:8453 at the same registry 0xaaaa…aaaa as tool ID 2, gated by predicate 0xbbbb…bbbb):
The two manifests below differ only in the Unicode form of the name field. Both look identical when rendered; both hash to different values, which is the exact failure mode the NFC rule in §2 Tool Manifest is designed to prevent.
name = "café-oracle" with é as a single code point U+00E9 (11 code points total).
keccak256 = 0x1373e978af0e6c0e63f97c08d1b17ceaa0ffc2bb23508d740203eb71bae1a2db.name = "café-oracle" with é decomposed to e + combining acute U+0301 (12 code points total).
keccak256 = 0x9c00eb2ea9266c6c57f24db188cb1d48a419cda33ce566eb22230dd10c679b7d.The ERC requires the NFC form. A consumer that fetches the NFD form MUST reject it as a verification failure rather than silently re-normalizing, because silent re-normalization would change the bytes fed to keccak256 and defeat the hash commitment.
Given a single canonical manifest (a minimal sample with name = "bom-sample"), the server-side encoding choice of whether to prefix the UTF-8 byte-order mark EF BB BF changes the hash:
268 bytes, keccak256 = 0x0c14a64a872b22356ab3d411017c8701e80b135c790706d710ac6f7cbde27e8b.271 bytes (= 268 + 3), keccak256 = 0x6ef38afe9c3b31c7200e392b8bcc098fa36645c20b9d58f1c910e4e858b99f6f.The ERC requires serving without a BOM. A consumer that receives an EF BB BF-prefixed response MUST treat it as a verification failure rather than silently stripping the prefix, because silent stripping would change the bytes fed to keccak256.
AccessRequirement.kindThe marker interfaces below are normative. Their interfaceId values are pinned and form part of this ERC's conformance baseline; predicates that emit AccessRequirement.kind for any of these requirement types MUST use the listed interfaceId. Each interface is defined as a single zero-argument function whose selector is the interface ID (an interface with one function has interfaceId == selector(function)). The data payload layout is normative for each kind.
The pinned IDs are reproducible: each is bytes4(keccak256("<functionName>()")) of the named function. A conformant implementation can verify them with any keccak256 implementation:
| Marker interface | Selector source | interfaceId |
|---|---|---|
IERC721Holding | bytes4(keccak256("erc721Holding()")) | 0xbdf8c428 |
IERC1155Holding | bytes4(keccak256("erc1155Holding()")) | 0xcb429230 |
ISubscription | bytes4(keccak256("subscription()")) | 0x44387cc2 |
Predicates that compose existing requirements MAY reuse these IDs verbatim. Predicates that introduce a new requirement type MUST publish a marker interface following the same single-zero-argument-function pattern, document the data layout, and verify that the resulting selector does not collide with any ID in this section or any prior published marker.
A Foundry-based reference implementation of ToolRegistry, IToolRegistry, and IAccessPredicate is maintained alongside this ERC. It pins the ERC-165 interface id, enforces the manifest-URI length cap described in Security Considerations, and exercises the predicate integration path (ERC-165 validation, non-canonical bool rejection, zero-code predicate handling, predicate staticcall failure handling) through its test suite. Consumers and implementers can use it as a conformance baseline; any downstream implementation is expected to reproduce the pinned interface id and the behavior validated by the test suite.
The registry delegates access checks to an external predicate contract via staticcall. A malicious or poorly written predicate could consume up to 63/64 of the calling frame's remaining gas (per EIP-150's gas-forwarding rule). Implementations MUST treat a failed predicate sub-call — whether the failure is an explicit revert, an out-of-gas, an invalid opcode, or a non-canonical return — as "access denied" (hasAccess returns false, tryHasAccess returns (ok=false, granted=false); see Predicate Reverting). Because staticcall already returns (success=false) for all of these failure modes and the 63/64 rule guarantees the registry retains enough gas to handle the failure, the safety property follows from using staticcall and does not require the registry to set a normative gas ceiling.
This ERC intentionally does not pin a maximum gas value for predicate calls. Gas costs of common predicate building blocks (SLOADs, hashing, signature recovery) change with hard forks (e.g., the SLOAD repricing anticipated under Glamsterdam, see EIP-8038) and differ between L1 and the various L2 fee schedules; concrete gas figures also depend on the Solidity compiler version and optimizer settings used to build the predicate. Any fixed ceiling published in this document would either become too tight after a repricing (breaking predicates that worked before) or pre-emptively too loose. The gas-bound decision therefore belongs at the call site:
hasAccess from offchain or via eth_call) supply gas through the normal RPC budget. A predicate that exhausts the budget reverts; the caller treats this as "access denied" and MAY retry with a larger budget.hasAccess) SHOULD invoke the registry with an explicit gas argument — staticcall{gas: budget} — so the worst-case cost their composition pays is bounded by budget, not by the predicate's behavior. EIP-150's 63/64 rule preserves the composer's ability to handle the failure even when the inner call consumes everything it was given.The reference implementation ships a defense-in-depth internal cap (currently 200_000 gas), but this is an implementation choice rather than a conformance requirement; downstream registries are free to pick a different value or none at all.
If the accessPredicate is a proxy contract (e.g., an ERC-1967 transparent proxy or Universal Upgradeable Proxy Standard (UUPS) proxy), the predicate owner can silently change the access logic without the tool creator calling setAccessPredicate. This means tool consumers cannot rely solely on the AccessPredicateUpdated event to detect changes in access semantics. Consumers SHOULD check whether a predicate address contains proxy patterns (e.g., ERC-1967 storage slots) and SHOULD treat upgradeable predicates as higher risk than immutable ones.
Consumers that index tool access semantics SHOULD monitor the predicate address for ERC-1967 Upgraded(address) events. When such an event is detected, consumers SHOULD re-evaluate the predicate's bytecode and SHOULD surface the upgrade to the user as a trust-relevant change, even though the registry itself did not emit AccessPredicateUpdated. Indexers SHOULD expose a predicateIsProxy flag alongside tool metadata so downstream surfaces can apply differentiated risk policies.
The registry contract itself can be deployed behind a proxy. An admin with proxy-upgrade authority could then swap the implementation for one that lies about hasAccess, getToolConfig, or toolCount, or that emits spoofed events. Consumers verifying a predicate's bytecode while blindly trusting a registry address miss this exposure.
Consumers SHOULD apply the same rigor to registry addresses that they apply to predicates:
Discovery layers (indexers, agent frameworks, wallets) SHOULD publish the registry bytecode hash alongside the registry address so downstream surfaces can verify the deployment has not been swapped. A registry deployed directly (no proxy) with its source verified on the canonical block explorer is the RECOMMENDED configuration.
Implementations MUST treat a reverting predicate call as "access denied" from hasAccess rather than bubbling the revert to the caller; this prevents a malfunctioning predicate from breaking the registry's view functions. Consumers that need to distinguish a clean denial from a malfunction SHOULD use tryHasAccess instead, which reports the predicate outcome as (ok, granted): a malfunction surfaces as (false, false) while a clean denial surfaces as (true, false).
The registry MUST invoke the predicate via staticcall, which the EVM forbids from mutating state. State-mutating entrypoints on the registry make no external calls to the predicate at all, so the registry exposes no reentrancy surface for state writes.
Read-only reentrancy is a separate hazard that the staticcall guarantee does not eliminate. A predicate is permitted to read state from any third contract; if a consumer calls hasAccess while another protocol's view of its own state is mid-transition (e.g., during a multi-call that updates balances between calls, or via a callback into the consumer mid-execution), the predicate may observe stale or inconsistent state and return a granted answer that is no longer true once the outer transaction settles. This is the same class of bug that affected several DeFi protocols whose oracles read view state from contracts mid-mutation. Consumers that gate state changes on hasAccess MUST NOT call it between writes whose intermediate state another protocol's view function depends on, and SHOULD apply the same reentrancy guards to hasAccess invocations that they apply to any other external view call whose inputs include third-party state.
A composing contract that calls hasAccess multiple times within the same transaction and needs a stable answer across those calls MAY cache the first result in transient storage (EIP-1153) keyed by (toolId, account) and reuse it for the remainder of the transaction. Transient storage is automatically cleared at end-of-transaction, so the cache cannot leak across transactions, and the composer pays the predicate staticcall cost only once. This is a non-normative optimization and does not change the registry's behavior; the registry itself never caches predicate results.
The account argument to IAccessPredicate.hasAccess and IToolRegistry.hasAccess is a claim the caller makes about who they are asking on behalf of. It is not authenticated by the registry and is not bound to msg.sender. Any caller can query the access status of any address.
Predicates and downstream enforcers (tool endpoints, wallets, agent frameworks, contracts that gate behavior on the result) MUST NOT treat a true return value as proof that the current requester is account. Enforcers MUST independently bind account to the real principal before acting on a positive answer, for example by:
account == msg.sender when the predicate is consulted from within a transaction initiated by account,data, verified by the predicate or the endpoint,A predicate that gates purely on account (e.g., "is this address a holder of NFT X?") is safe to consult but unsafe to act on without such binding. Ignoring this distinction is the most common way that correct-looking access gates become unsound.
The following challenge-response pattern binds the account parameter to a real principal and prevents replay across tools and time windows. Implementations that need authenticated access SHOULD use this pattern or an equivalent that provides the same properties.
The challenge MUST be domain-separated as EIP-712 typed data so the signed digest cannot collide with signatures used in other contexts (transactions, EIP-7702 authorizations, eth_sign digests, other ERC challenge schemes). EIP-712 produces a digest of the form keccak256("\x19\x01" || domainSeparator || hashStruct(message)), where domainSeparator is rooted in the predicate's address and a fixed protocol name; the "\x19\x01" prefix is reserved for EIP-712 and cannot be a valid Ethereum transaction or EIP-7702 authorization (which use distinct, non-overlapping leading bytes).
Challenge issuance. The agent or consumer constructs an EIP-712 message with:
EIP712Domain = { name: "ERC8257-AccessProof", version: "1", chainId: block.chainid, verifyingContract: predicate }AccessProof struct = { uint256 toolId; address account; uint64 deadline }, where deadline is a Unix timestamp after which the proof expires.The digest is keccak256("\x19\x01" || domainSeparator || keccak256(typeHash || toolId || account || deadline)).
Proof construction. The principal signs the digest with their private key. The proof payload is data = abi.encode(deadline, signature).
Predicate verification. The predicate reconstructs the same EIP-712 digest, decodes data, checks block.timestamp <= deadline, recovers the signer from the signature and digest, and returns true only if the recovered signer equals account.
This pattern prevents replay because the toolId and deadline are bound into the typed-data struct, and cross-chain replay is prevented by chainId in the EIP-712 domain. The verifyingContract field in the domain ties the proof to the specific predicate, so a signature gathered for one tool's predicate is not valid against another. Consumers that do not need onchain verification MAY implement the same pattern offchain at the endpoint layer, substituting an HTTP-signed challenge for the EVM signature; the same domain-separation discipline applies.
data ParameterThe data parameter to hasAccess and tryHasAccess is forwarded verbatim to the predicate via staticcall. Because predicate calls are onchain view calls, the data bytes are visible in RPC traces, node logs, and any monitoring infrastructure that records eth_call payloads.
Agents and agent frameworks MUST NOT pass secrets (private keys, API tokens, passwords, session cookies, bearer tokens, or any value whose disclosure would compromise the principal) in data. A malicious or compromised tool creator who controls the predicate contract can observe data contents by inspecting the call input of the staticcall via RPC tracing (e.g., debug_traceTransaction); even though staticcall cannot emit events, the bytes are present in the call input and visible to any node operator or tracing service.
Legitimate uses for data include Merkle proofs, token IDs, EIP-712 signatures over public challenges, and other values that are safe to disclose. If an access scheme requires a secret, the secret MUST be verified offchain (e.g., at the tool endpoint via HTTPS) rather than passed through the onchain predicate path.
Implementations of IToolRegistry.registerTool and IToolRegistry.setAccessPredicate MUST treat addresses with no deployed code (externally-owned accounts, or CREATE2 addresses that have not yet been deployed) as accepted but unverifiable, per step 2 of Predicate Validation at Registration. ERC-165 cannot be queried against empty code, so such a predicate cannot be checked at registration time.
At invocation time, a staticcall to a zero-code address returns empty data, which the registry MUST treat as non-compliant (see §1 hasAccess) and therefore as "access denied." hasAccess consequently returns false for such a tool until a contract is deployed at the predicate address (the ToolConfig entry itself remains canonical and queryable; only access checks fail).
Creators who rely on counterfactual deployment (registering a predicate before deploying it) SHOULD:
SSTORE arbitrary values into the predicate's storage during construction, and the runtime bytecode can branch on those storage slots so that two predicates with identical runtime bytecode behave differently because their constructors planted different state. Consumers and creators that pin a predicate by code hash MUST therefore pin the init-code hash (which fully determines both the runtime bytecode and the constructor-planted storage) rather than the runtime bytecode hash, or alternatively MUST inspect the predicate's storage state after deployment in addition to its runtime bytecode. Predicates that read no storage at all (pure logic over their inputs) are not affected and are RECOMMENDED for security-sensitive gates.IToolRegistry.hasAccess(uint256,address,bytes) and IAccessPredicate.hasAccess(uint256,address,bytes) share the selector 0xa7e3775b because they have identical names and argument lists. Any contract exposing a function with this exact selector and a bool-shaped return decodes as a drop-in IAccessPredicate — unrelated future ERCs, custom role managers, view shims wired up for gas profiling, the registry itself. A creator who points accessPredicate at one of these registers a tool whose access decisions are made by code that was never designed to gate it. Registration-time validation closes this for ERC-165-aware contracts.
Implementations of registerTool and setAccessPredicate MUST validate the candidate accessPredicate per the following best-effort ERC-165 ladder. The reference implementation pins these rules in _validatePredicate; downstream implementations MUST reproduce the same accept/reject behavior (the precise revert path may use an equivalent error per the InvalidAccessPredicate docstring).
address(0), the call is open-access. Skip validation and accept.extcodesize == 0), accept as best-effort. ERC-165 cannot be queried against empty code, so the registration is recorded but the tool is inaccessible until a contract is deployed at the address (see Zero-Code Access Predicates).IERC165(predicate).supportsInterface(type(IERC165).interfaceId) with a bounded gas allowance, treating revert or out-of-gas as "not advertising ERC-165" and accepting as best-effort. ERC-165 itself requires supportsInterface to use less than 30,000 gas, so any non-malicious probe completes within that ceiling; implementations SHOULD pick a value at or near that ceiling and MUST NOT pick a value low enough to false-negative a conformant predicate.false, the predicate is not advertising ERC-165: accept as best-effort.true, the predicate has self-declared as ERC-165 compliant. The implementation MUST then probe IERC165(predicate).supportsInterface(type(IAccessPredicate).interfaceId) with the same bounded gas allowance. If that probe reverts or returns false, the implementation MUST revert with InvalidAccessPredicate.Step 5 is what closes the selector-collision hazard for contracts that advertise ERC-165 — the registry itself, for instance, advertises IToolRegistry but not IAccessPredicate, so step 5 rejects it. Contracts that share the selector but do not advertise ERC-165 still slip past registration; for those, the call site is the last line of defense:
staticcall semantics bound the cost of a recursive registry-self-reference: each frame loses 1/64 of remaining gas under EIP-150, so recursion depth is bounded for any caller gas budget, and a failure at any frame propagates back as (success=false), which the outer call returns as (false, false) per the malfunction rules in §1 hasAccess.hasAccess-named function returns a non-zero, non-one word fails closed.Implementations MAY surface a more specific guard (e.g., reverting when predicate == address(this)) to make the registry-self-reference misconfiguration explicit, but the ERC-165 ladder above already subsumes the case for any registry that advertises its own IToolRegistry interface ID.
Validation runs on the value being assigned: an idempotent setAccessPredicate(toolId, currentPredicate) call is a no-op (no state write, no event) and skips the ladder, so the MUST guards every transition into the slot but is not a continuously-enforced invariant on the stored value (a registration that predates this rule, or that was made against a non-conformant registry, will not be re-validated by a no-op set). Implementations that need to enforce validation as a continuous invariant MUST publish a derivative interface (a new ERC-165 ID) rather than alter the no-op semantics, since changing them would break creators who rely on idempotent calls.
Creators SHOULD prefer predicates that explicitly advertise IAccessPredicate via ERC-165, and discovery layers SHOULD surface "predicate does not advertise IAccessPredicate" as a warning even when the registration succeeds, so an accidental selector collision is visible to humans rather than silently accepted.
Implementations MUST reject metadataURI values longer than 2,048 bytes (UTF-8 byte length, not Unicode code-point count) at both registerTool and updateToolMetadata, reverting with InvalidMetadataURI. The cap exists because the URI is creator-controlled, written into permanent storage, and re-read by every offchain consumer that resolves the tool. Without a normative cap, a single registration of a multi-kilobyte URI imposes a perpetual gas cost on indexers and a per-request bandwidth cost on every wallet that re-resolves the tool. The 2,048-byte ceiling matches the image field's URL cap in §2 Optional Fields and is comfortably above any realistic well-known path: <origin>/.well-known/ai-tool/<slug>.json with the maximum 64-character slug and a typical origin fits in well under 400 bytes. Implementations MAY choose a smaller cap; 2,048 bytes is the upper bound.
Tool IDs are auto-incrementing counters, so there is no onchain name-squatting vector at the identifier layer. An attacker who front-runs a registerTool transaction obtains a different tool ID pointing to their own manifest, which does not affect the victim's subsequent registration.
A distinct risk is URL-squatting: an attacker registers the legitimate creator's metadataURI and matching manifestHash under the attacker's own address, attaching a malicious accessPredicate. Origin-binding does not prevent this, because the attacker is merely referencing a URL that already exists at the real operator's origin. Creator binding (§7 Creator Binding) closes this by requiring the manifest itself to declare the onchain address permitted to register it; a registration whose onchain creator does not match the manifest's creatorAddress MUST be rejected by consumers.
Manifest name collisions, where two independent creators pick the same human-readable name on different origins, are still resolved by the discovery layer (indexers, agent frameworks), not by the registry. Discovery layers SHOULD rank tools by origin-binding plus creator-binding verification rather than registration order.
The metadataURI field is mutable: a tool creator can call updateToolMetadata to point to a new manifest at any time. However, the manifestHash commits the manifest bytes onchain. Consumers that pin a manifestHash can detect changes. The ToolMetadataUpdated event emits the new URI and hash, so indexers and consumers are notified of every change. Consumers SHOULD re-verify the manifest hash after fetching from a URI and SHOULD alert users when a previously pinned hash no longer matches.
Pricing lives in the manifest and is not committed anywhere that the endpoint is obligated to honor. A creator can rotate pricing at any time by publishing a new manifest and calling updateToolMetadata with the new hash. Agents that cached a manifest during discovery MUST re-fetch and re-verify the manifest (hash check, origin-binding, creator-binding) immediately before any payment-bearing invocation. A cached manifest MUST NOT be used as the basis for approving, signing, or submitting a payment transaction. Agents MUST be resilient to the endpoint returning a payment-required response whose amount differs from the cached manifest, and MUST surface any price change to the user for explicit confirmation before proceeding. Agents MUST NOT pre-approve payment amounts that assume the discovery-time manifest is authoritative beyond a short freshness window.
When a tool's pricing array specifies an onchain payment protocol, the payment flow is susceptible to replay attacks unless the protocol includes replay resistance. A malicious endpoint could replay a signed payment authorization to drain additional funds beyond what the user approved for a single invocation.
Payment protocols referenced in pricing MUST include replay protection. At minimum, each payment authorization MUST bind to a unique nonce or commitment that the payment contract enforces as single-use. Agents SHOULD use EIP-712 typed structured data for payment authorizations, including the toolId, a monotonic nonce, a deadline timestamp, and the chain ID in the signed payload. Agents MUST NOT sign open-ended approvals (e.g., unlimited ERC-20 approve) as a substitute for per-invocation payment authorizations.
Tool creators who define payment flows SHOULD document the replay-resistance mechanism in the manifest's pricing[].protocol description. Consumers that encounter a pricing entry without documented replay resistance SHOULD treat it as higher risk and SHOULD warn the user before proceeding.
Tool endpoints are creator-controlled URLs. The endpoint field MUST be an https:// URL (see §2 Tool Manifest); consumers MUST reject manifests whose endpoint uses any other scheme. Any consumer that may cause a tool to be invoked on a user's behalf (agent frameworks, wallets, invocation proxies, or any surface exposing a "run this tool" affordance, using the same scoping as the 24-hour cache ceiling in §7 Handling Verification Failure) MUST reject endpoints that resolve to private IP ranges (RFC 1918, RFC 6598, loopback, link-local, IPv6 ULA fc00::/7, IPv6 link-local fe80::/10) to prevent Server-Side Request Forgery (SSRF) attacks against internal services, and MUST resolve the host immediately before each invocation rather than caching the resolution, to prevent DNS rebinding. Purely informational surfaces that never invoke endpoints (e.g., indexer digests, historical registries) MAY use SHOULD-level rejection but SHOULD NOT relax it without an explicit policy. Agent frameworks that invoke tool endpoints MUST enforce request timeouts and response size limits.
Consumers that call IAccessPredicate.getRequirements(toolId) are exposed to creator-controlled return data the same way manifest parsers are exposed to creator-controlled JSON. A malicious predicate can return an enormous AccessRequirement[] with oversize data and label fields, mounting a denial-of-service (DoS) attack against every indexer, agent framework, or wallet that introspects it.
Consumers MUST enforce the following ceilings on getRequirements return values and MUST treat any over-limit response as equivalent to (false, false) from tryHasAccess:
| Limit | Value | Why |
|---|---|---|
requirements.length | 256 entries | Sized to accommodate honest fan-out from real predicates: an ERC1155OwnerPredicate configured with 10 collections × 16 token IDs emits 160 requirements, and a 3-term CompositePredicate over such children flattens to 480 entries unless one branch is small. 256 covers the single-predicate ceiling and most realistic compositions; consumers needing a larger window MAY raise the cap, but MUST NOT fall back to "denied" for honest over-cap responses without surfacing the diagnostic. |
data byte length per entry | 4,096 bytes | Generous for any reasonable ABI-encoded payload; prevents quadratic-byte DoS at the agent-decode layer. |
label byte length per entry | 256 bytes | Matches the manifest label cap in §Access; discovery surfaces have a fixed display budget. |
Consumers SHOULD bound the getRequirements staticcall via an explicit gas argument matched to their target chain and fork, and MUST treat revert or out-of-gas as introspection-failed. The kind sentinel 0x00000000 defined in the Rationale for child-introspection failures applies to over-limit responses too: a composite predicate that wraps a child returning over-limit data SHOULD substitute the sentinel.
The same defensive posture applies to the diagnostic name() views on both IToolRegistry and IAccessPredicate, and to IToolRegistry.version(): returns are deployer-controlled strings, so consumers MUST cap them at 256 bytes (matching the label cap in §Access) and MUST treat over-limit returns as if the contract did not implement the function. This prevents a malicious registry or predicate from grieving discovery surfaces with a multi-megabyte string in what consumers expect to be a cheap diagnostic call.
A creator controls the bytes served at metadataURI, and a permissionless registration makes every fetched manifest effectively attacker-controlled. A consumer that parses without limits can be DoSed by a single malicious registration. Consumers MUST enforce the following ceilings and MUST reject any manifest that exceeds them:
| Limit | Value | Why |
|---|---|---|
| Manifest byte size | 1 MiB (1,048,576 bytes) | Bounds HTTP body and parser memory; a fully-populated honest manifest with ten pricing entries and a moderately rich schema is well under 10 KiB (10,240 bytes). Consumers MUST truncate at the limit and treat oversize fetches as a verification failure. |
pricing.length | 32 entries | Multi-chain, multi-protocol pricing still fits comfortably; prevents quadratic iteration in agent selection. |
access.requirements.length | 256 entries | Mirrors the onchain getRequirements ceiling in Predicate Introspection Hardening; two views of the same data should have the same bound so neither path is the soft underbelly. |
access.requirements[].data hex-decoded byte length | 4,096 bytes | Mirrors the onchain data cap (which is 4,096 binary bytes). The serialized hex string carrying this payload is up to 8,194 UTF-8 bytes (0x prefix + two hex digits per byte). Consumers SHOULD apply the cap to the decoded payload, not the raw hex string, so a manifest-side requirement can carry the same payload that would be legal onchain. |
inputs / outputs schema depth | 16 levels | Deep enough for any real JSON Schema composition (anyOf of tagged unions, nested objects); prevents stack exhaustion in recursive validators. |
inputs + outputs total schema nodes | 1,024 nodes | Covers rich schemas; prevents pathological fan-out attacks that create millions of subschemas via shallow-but-wide structures. |
Each row above is an independent upper bound on its own axis; they do not jointly compose. The 1 MiB total-size cap is the binding constraint that limits the joint product. As a worked example, a manifest cannot simultaneously hit access.requirements.length = 256 and per-entry data = 4,096 decoded bytes: 256 maxed-out entries serialize to roughly 2.1 MiB of hex envelope (8,194 UTF-8 bytes per entry, plus label, kind, and JSON overhead), well over the 1 MiB ceiling. Consumers MUST enforce every row, but conformant manifests trade off depth for breadth and never hit every row at once.
Regex pattern values inside embedded schemas MUST be evaluated by a matcher immune to catastrophic backtracking (e.g., RE2 — a regex engine with linear-time matching guarantees that explicitly rejects features such as backreferences which enable exponential blow-up — or an implementation with a bounded step count). A matcher with exponential worst-case behavior on attacker input is unsafe and MUST NOT be used.
Consumers SHOULD inspect the HTTP Content-Length response header, if present, and abort the request before reading the body when the advertised length exceeds 1 MiB. Streaming consumers that cannot rely on Content-Length SHOULD cap the incremental read at 1 MiB and abort (without silently truncating) on overflow, so an attacker cannot force the consumer to load a multi-megabyte payload into memory before the size check engages.
These limits are deliberately generous for honest tools and tight enough to make DoS-via-registration uneconomic.
default and const InjectionThe inputs schema in a tool manifest is creator-controlled. JSON Schema keywords such as default and const can silently inject parameter values that an agent auto-fills without user confirmation. A malicious manifest could declare:
An agent that naively uses default values to populate missing fields — or that treats const as a fixed value without surfacing it to the user — would submit a request with attacker-chosen parameters.
Agents MUST NOT auto-fill parameters from default or const without explicit user confirmation when the tool's pricing array is non-empty or when the tool's description indicates it performs state-changing operations (transfers, approvals, deployments). Agents SHOULD surface all pre-populated values to the user before invocation, regardless of the tool's pricing. Consumers that validate request payloads against the inputs schema MUST treat const-enforced values as display-only hints and MUST require the user to acknowledge them.
$ref in Embedded SchemasJSON Schema permits $ref to point at remote URIs. A creator-authored inputs or outputs schema that references http://169.254.169.254/…, private IP ranges, or attacker-owned URLs can turn every validator into an SSRF / fingerprinting oracle. Consumers MUST disable remote $ref resolution when validating against manifest-embedded schemas, or MUST sandbox any resolution behind the same egress policy applied to endpoint (no private IPs, HTTPS only, size-capped fetches, short timeouts). Local $ref (within the same schema document) remains safe and MAY be resolved.
Every string and URL in a fetched manifest is creator-controlled and MUST be treated as untrusted input by any surface that renders it. Consumers MUST apply defense-in-depth: validation at fetch time, contextual encoding at render time, and a restrictive Content Security Policy in the surrounding document.
The following normative rules apply to common render paths:
name, description, tags). Consumers MUST contextually encode these fields when rendering: HTML-escape for text nodes, attribute-escape for attributes, and JS-escape for script contexts. UIs that inject them into the DOM without encoding are vulnerable to stored XSS from a single malicious registration.description. Consumers that render Markdown MUST disable raw-HTML passthrough or sandbox the rendered output. A compliant Markdown renderer strips <script>, <iframe>, event handlers, and javascript: URLs, or runs under a CSP that neutralizes these surfaces.image URIs. Consumers MUST NOT accept javascript:, file:, data:text/html, or vbscript: URIs for a tool icon: these schemes enable script execution or local-filesystem exposure and have no legitimate icon use case. Consumers SHOULD NOT accept http: (man-in-the-middle (MITM) risk) or blob: (cross-context leakage risk) URIs; consumers that do accept either MUST apply the scheme-appropriate defenses in the Per-Scheme Rendering Guidance below.endpoint and extension-namespaced URL fields as clickable links. Consumers SHOULD NOT render javascript:, file:, or blob: schemes as links; http: links are permitted only with explicit user consent because of MITM risk; all external links SHOULD carry rel="noopener noreferrer" to prevent tab-nabbing.imageFor any scheme consumers do accept, scheme-appropriate defenses should be layered on the normative rules above:
https://: set referrerpolicy="no-referrer" and proxy through consumer-controlled infrastructure where feasible.ipfs://: resolve through a trusted gateway the consumer operates, not an arbitrary public gateway. A hostile gateway can inject response headers, set tracking cookies, or serve manipulated content even when the Content Identifier (CID) is content-addressed.data:image/svg+xml: reject outright, or render only inside a script-free sandbox (e.g., inside an <img> element rather than inline SVG, or an <iframe sandbox="">). SVG can embed <script> tags.data: (other): verify the declared MIME type against an allowlist of image types (e.g., image/png, image/jpeg, image/webp) before rendering.Origin-binding relies on DNS and TLS infrastructure. It is vulnerable to DNS hijacking, Border Gateway Protocol (BGP) attacks, and compromised certificate authorities. These are industry-wide risks, not specific to this ERC. Tools hosted exclusively on IPFS or other content-addressed networks cannot use origin-binding because there is no HTTP origin to bind to; consumers SHOULD treat such tools with reduced confidence compared to origin-bound tools.
Origin-binding does not defend against dangling DNS records and abandoned origins. The most common practical attack on a well-known-path scheme is not a DNS hijack but a takeover: a domain whose A/CNAME record points to a deprovisioned cloud bucket, expired domain, or stale managed-hosting tenant (Heroku, Vercel, GitHub Pages, S3) lets an attacker reclaim the resource and serve a manifest at the well-known path with their own creatorAddress. The resulting registration passes all four consumer checks. Because the attack is silent (no certificate change is required if the platform issues certificates on the tenant's behalf), discovery layers SHOULD treat origins whose registration is significantly older than their current TLS certificate, or whose authoritative name servers have changed since registration, as elevated risk. Indexers SHOULD subscribe to ToolMetadataUpdated events on long-lived registrations and re-verify origin control whenever a manifest changes after a long quiescent period.
Origin-binding also does not defend against internationalized-domain homograph attacks. Two ACE-encoded hostnames that differ at the byte level (e.g., xn--... of a Cyrillic string versus the Latin lookalike) produce different metadataURI values and are correctly distinguished by the well-known fetch, but a user comparing the two hostnames visually in a UI may not notice the substitution. Consumers rendering manifest origins to end-users SHOULD apply IDN display policies such as Unicode UTS #39 restriction levels and SHOULD surface punycode for mixed-script or confusable hostnames so users have a chance to spot impersonation.
Finally, origin-binding is trust-on-first-use at the moment of registration. If the origin operator was already compromised when the manifest was first served, no consumer can detect this from onchain state alone: the manifest, its hash, and its declared creatorAddress are all attacker-chosen by construction. Origin-binding proves "the manifest at this origin matches the onchain commitment now," not "the original origin operator endorsed this registration." Consumers SHOULD weight a registration's age (via ToolRegistered block timestamp), update history, and concurrent ecosystem signals when treating it as canonical.
All verifiability fields are self-attested at the schema level (see §5 Verifiability for the field semantics and the trust-tier ladder). The manifest commits each claim onchain via manifestHash so it cannot be silently changed, but the registry does not and cannot verify compliance. Consumers MUST NOT grant tools elevated trust (e.g., access to sensitive data, bypassing confirmation prompts) based solely on declared verifiability claims; agents that do not implement attestation verification SHOULD treat TEE/E2EE claims as equivalent to "standard" for trust decisions, and surfaces that render verifiability information MUST distinguish verified claims (attestation report fetched and cryptographically validated) from unverified self-attestations.
Network egress and data retention under TEE. Even when a tool runs in a TEE with open-source code, dataRetention claims of "ephemeral" or "none" are only as strong as the enclave's network egress policy. If the enclave has unrestricted outbound network access, it can exfiltrate data to external storage before the request completes. TEE attestation ideally includes network policy (allowed outbound endpoints) as part of the measured configuration; without network-policy attestation, dataRetention claims under TEE are weaker than they appear. Consumers that require strong data-retention guarantees SHOULD verify that the enclave's measured configuration includes network restrictions.
Attestation freshness and revocation. When a platform vendor (Intel, AMD, AWS) revokes a TCB version, previously valid attestation reports from that TCB become untrustworthy. The attestation.maxAge field addresses this: agents SHOULD reject reports older than maxAge seconds, attestation endpoints MUST return fresh (not cached) reports so liveness is verifiable, and consumers SHOULD monitor platform vendor advisory channels for TCB revocations and re-verify when one is announced.
If a tool creator's private key is compromised, an attacker can update the manifest URI or change the access predicate. This ERC does not include ownership transfer or multi-sig mechanisms on the registry itself, in order to keep the interface minimal: every such feature (two-step transfer, role-based access control, time-locks) is already expressible by registering the tool under a smart contract wallet and implementing the desired policy there.
Creators SHOULD therefore register tools under a smart contract wallet (e.g., Safe, an ERC-4337 account, a custom multisig) rather than an externally-owned account (EOA) whenever the tool's access predicate is gating anything valuable. The registry treats msg.sender uniformly: any contract that can produce a valid Solidity call to registerTool, updateToolMetadata, setAccessPredicate, or deregisterTool can act as a creator, so all existing wallet tooling (timelocks, guardians, key rotation modules) composes directly. If a key compromise is detected, the creator SHOULD call deregisterTool to permanently tombstone the compromised registration, preventing further use. Creators who register under an EOA and lose their key accept that the registration cannot be deregistered and SHOULD re-register the tool under a fresh ID.
A contract-wallet creator whose authorization logic later becomes unreachable (self-destructed wallet, migration to a new address without state preservation, signer set that can no longer meet the wallet's threshold) leaves the registration frozen in its last-written state: the registry continues to report a valid ToolConfig, but no future updateToolMetadata, setAccessPredicate, or deregisterTool call from that creator can succeed. Creators who treat mutability as a precondition for safe operation (pause via predicate swap, URL rotation, emergency deregistration) SHOULD keep their wallet's recovery paths exercised; creators who prefer commitment-style immutability MAY treat the freeze as a feature. Consumers SHOULD NOT infer abandonment from staleness alone, because frozen-but-canonical and actively-maintained registrations look identical from onchain state.
maxAge)Consumers enforce their own freshness windows (see §7 Handling Verification Failure), but a tool creator may know that their manifest changes more frequently than the consumer's default window allows. Creators MAY include a maxAge field (integer, seconds) in the manifest to declare the maximum acceptable cache lifetime. When present, consumers SHOULD treat maxAge as an upper bound: a consumer whose own freshness policy is shorter than maxAge keeps its shorter window; a consumer whose policy is longer than maxAge SHOULD shorten it to maxAge. If maxAge is absent, the consumer's own policy applies unchanged.
maxAge is not part of the formal manifest schema defined in §2 Tool Manifest; it is an informal convention recognized only by the Security Considerations section. A strict validator built solely from the §2 schema will ignore it per the "Unknown Fields and Extensions" rule. Consumers that wish to honor maxAge SHOULD look for it explicitly after schema validation.
maxAge is advisory and offchain — it is not committed onchain and cannot be enforced by the registry contract. A consumer that ignores maxAge risks acting on a stale manifest whose pricing, endpoint, or access semantics have changed. Consumers SHOULD log when they override their default freshness window due to maxAge so operators can audit cache behavior.
Creators of high-value tools (payment-bearing, signing-flow, or state-changing) SHOULD set maxAge to 0 to require re-verification on every invocation. Creators of read-only informational tools MAY omit maxAge or set it to a value consistent with their update cadence.
Because registerTool is permissionless, an attacker can register a large number of tools with garbage or malicious manifests to pollute the registry and degrade the signal-to-noise ratio for discovery layers.
The registry contract itself does not enforce registration fees or rate limits, in order to keep the interface minimal and avoid embedding economic policy in the protocol layer. However, deployment-specific implementations MAY layer anti-spam mechanisms on top of the core interface:
msg.value payment on registerTool that is burned or sent to a treasury. The fee acts as a Sybil-resistance mechanism: bulk registration becomes economically costly. The fee amount SHOULD be low enough that legitimate creators are not deterred but high enough that registering thousands of spam tools is prohibitive.deregisterTool. A governance or moderation mechanism MAY slash the stake for manifestly abusive registrations (e.g., manifests that serve malware). This pattern is more complex but provides a stronger deterrent than a one-time fee.Consumers MUST NOT rely on the absence of spam as a security property; all trust decisions MUST be based on the verification checks defined in §7 Consumer Verification, not on registry ordering or tool ID proximity.
This ERC provides two deactivation mechanisms with different trade-offs. deregisterTool is a permanent, irreversible onchain removal: it tombstones the tool ID so that all subsequent operations revert with ToolIsDeregistered, and the ID is never reused. Creators SHOULD use deregisterTool when a registration is compromised or must be permanently retired. Alternatively, a creator who wants a reversible pause SHOULD set accessPredicate to an always-deny predicate, which makes every subsequent hasAccess return false while preserving the ToolConfig for later re-enablement. Indexers and discovery layers SHOULD detect retired registrations heuristically (e.g., deregistered status, always-deny predicate, or no ToolMetadataUpdated events for an extended window) and surface them as "retired" rather than treating them as canonical. Consumers MUST NOT trust the absence of a deactivation signal as proof a registration is still endorsed by its creator; they SHOULD weigh ToolRegistered and ToolMetadataUpdated recency, the creator's recent activity, and any out-of-band reputation signal when ranking tools.
Copyright and related rights waived via CC0.