Wallet State Attestation: Signed Booleans about On-Chain State

Introduction

Motivation Existing access-control primitives --- OAuth 2.0 , OIDC , SAML, and the broader credential-presentation family --- answer the question "who is this user?" by accepting a presented artifact (token, assertion, credential) from a holder. Wallet State Attestation answers a different question: "does this wallet currently satisfy a specified condition over on-chain state?" The holder presents nothing. An issuer reads canonical on-chain state for a specified wallet address, evaluates the operator-defined condition, and returns a signed boolean. Verifiers check the signature offline using a published JWKS endpoint. This is a distinct primitive from identity verification, credential issuance, or holder-presentation flows. It belongs in a parallel category --- what this document terms wallet-state-attestation --- alongside, not within, the existing credential-presentation stack.

Position Relative to Identity Primitives OAuth and OIDC prove who a subject is. Wallet State Attestation proves what a wallet currently holds, owns, or has been attested to in on-chain state. These are complementary, not competing. A system may use OAuth to authenticate a human or service principal, then call a wallet-state attestation issuer to verify that a wallet associated with that principal satisfies an on-chain condition. The two primitives operate on different subjects (identity vs. wallet state) and answer different questions.

Position Relative to Credentials Wallet State Attestation is not a Verifiable Credential (W3C VC) , an mDoc / ISO/IEC 18013-5 mobile document, an eIDAS attestation, a SAML assertion, or an OIDC ID token. These are credential-presentation primitives: an authority issues a credential, the holder presents it, the verifier checks the issuer's signature over the holder's presented bytes. Wallet State Attestation does not involve credential presentation. The holder does not present anything. The issuer pulls public on-chain state directly, evaluates a condition, and signs the result. The signed payload is an observation about external state, not a credential about the holder's identity. This document treats the credential / VC / eIDAS / SAML stack as adjacent prior art for explicit non-conflation purposes. See ("What This Is Not") for the full enumeration.

Position Relative to Other Documents Wallet State Attestation is referenced or adopted in the following public artifacts (all informative; see References):

Knowledge Context Protocol (KCP) RFC-0004 --- defines an attestation_url / attestation_jwks mechanism in KCP YAML manifests for verifying agent eligibility before access. The pattern is mechanism-agnostic; wallet state attestation is one valid implementation shape.
Verifiable Intent (VI) environment.* constraint family --- defines an environmental constraint family for autonomous-mode (L3) execution in agent commerce, establishing family-wide vocabulary (attestation_url, max_attestation_age), composition rules, and IANA registry mechanics for individual constraint types. The wallet-state-attestation primitive is the reference implementation shape used by VI's environment.wallet_state constraint type.
Agent Governance Vocabulary --- defines wallet_state as a foundation-layer signal type with named production issuers.
Open Agent Trust Registry (OATR) --- third-party trust registry of attestation issuers, including wallet-state-attestation issuers.
Draft ERC-8210 Agent Assurance Protocol --- proposed IRiskHook verification taxonomy identifies wallet state attestation as the representative shape for pre-commitment eligibility verification (one of three categories in the verification framework, alongside post-hoc resolution evidence and behavioral reputation).
Universal Commerce Protocol (UCP) identity-linking --- wallet attestation acknowledged as a reserved extensibility point for future non-OAuth identity-mechanism types.

Wallet state attestation is not dependent on or normatively related to any of these documents. They are listed as evidence of adoption and as informative context for readers seeking to understand where the primitive is in use.

Use Cases Common deployments of wallet state attestation include:

Condition-based access --- gating API access, content access, or commerce flows on whether a specified wallet holds a specified token, NFT, or attested status at request time, without exposing actual balance or transaction history.
Agent-to-agent trust verification --- autonomous agents verifying counterparty wallet state (holdings, attested compliance status, etc.) before transaction execution.
Compliance gating --- verifying on-chain compliance attestations (KYC status from external attestors, country attestations, sanctions clearance) against a wallet without the verifier receiving any identity attribute beyond the boolean it asked for ().
Pre-commitment eligibility --- agent commerce protocols verifying that an agent wallet satisfies pre-conditions (sufficient stake, sufficient balance, attested status) before contract commitment.

The primitive is read-only and does not interact with chain state beyond observation. Implementations issue attestations on demand; attestations are short-lived and expire (typically thirty minutes; see ).

Terminology 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 BCP 14 when, and only when, they appear in all capitals, as shown here. The following terms are used throughout this document: Issuer --- The party that reads on-chain state, evaluates conditions, and signs the resulting attestation. The issuer is the sole signer of attestations within its declared scope (see ). Holder --- The wallet whose on-chain state is observed. The holder does not present anything in this primitive; the issuer reads chain state directly. The holder need not be aware of any individual attestation. Verifier --- The party that consumes the attestation, checks the signature against the issuer's published JWKS, and acts on the result. Condition --- An operator-defined predicate over wallet state. Examples include: "balance of token T at address A is greater than or equal to value V", "wallet A owns NFT N", "wallet A has a valid on-chain attestation of type T from attestor X". Attestation --- The signed payload returned by the issuer in response to a request. Distinguish explicitly from a credential (which is presented by a holder), from a JWT claim in the credential sense (which carries identity information), and from a VC (which is issued by an authority over a holder's presented identity). An attestation in this document's sense is an issuer-signed observation about public on-chain state. Fact profile --- A multi-condition, multi-dimension attestation payload consisting of a structured collection of condition results, organized by dimension and covered by a single issuer signature. A fact profile is signed as one object under the algorithms of this document; its detailed format is not specified here. Used for richer wallet-state queries where a single boolean is insufficient. Distinguish explicitly from a "trust score" or "reputation rating" --- a fact profile contains observed evidence organized by dimension, not an opinion or aggregate. Block reference --- Chain-specific freshness evidence included in every attestation. EVM chains MUST include block number and block timestamp. XRPL MUST include ledger index and, where available, ledger hash. Solana MUST include slot. Bitcoin MUST include block height and block hash (chain-tip evidence; see for Bitcoin-specific considerations). Any other chain family MUST include the reference the issuer documents for it. Condition hash --- A SHA-256 hash of the JSON serialization of the evaluated condition, with member names sorted as sorts them and no insignificant whitespace, represented as a 0x-prefixed lowercase hexadecimal string, included in the response for tamper-evidence over the condition itself.

Architecture Overview The primitive operates as a three-step pipeline: read -> evaluate -> sign.

The issuer receives a request specifying a wallet address, a chain identifier, and one or more conditions.
The issuer reads canonical on-chain state for the specified wallet at or near the current chain tip. The issuer selects the block and reports it in the block reference.
The issuer evaluates each condition against the observed state.
The issuer signs the result and returns the attestation.

The evaluation is deterministic: the same condition evaluated against the same chain state at the same block produces the same per-condition result. A verifier can independently re-derive each result by reading the same chain state and applying the same condition logic, exactly where the block reference names the state that was read (an EVM block, an XRPL ledger) and to within the anchor where the reference is a tip marker or a floor, as the issuer documents per chain family. The attestation identifier, the attestedAt timestamp, and the signature value differ from one issuance to the next. The primitive is read-only: the issuer does not modify chain state, does not request a wallet signature from the holder, and does not custody any assets. The issuer is a passive reader of public chain state. For each chain referenced in the request, the issuer captures a block reference (block number and block timestamp for EVM chains; ledger index and, where available, ledger hash for XRPL; slot for Solana; block height and block hash for Bitcoin; for any other chain family, the reference the issuer documents) at attestation time. The block reference is carried inside each per-condition result and is therefore covered by the issuer's signature. If a required chain observation cannot be acquired, the issuer MUST NOT sign the attestation; see . This document does not specify how the issuer reads chain state (RPC routing, indexer choice, archive node selection), how it manages signing keys (HSM, software, federated), or how it handles chain-specific edge cases (reorgs, finality, data availability). These are implementation concerns, deliberately left out of scope.

Request Shape A request is a JSON object with the following structure: ", "conditions": [ { "type": "", "chainId": "", "...": "" } ], "format": "jwt", "proof": "merkle" } ]]> wallet --- A chain-specific address string. EVM addresses use the standard 0x-prefixed hexadecimal form. Solana addresses use base58. XRPL addresses use the r-address format. Bitcoin addresses MAY use any standard format (P2PKH, P2SH, bech32 / SegWit, bech32m / Taproot). Because one request can span several chains, an implementation MAY reserve wallet for one address family and carry the others in chain-specific members (e.g., solanaWallet, xrplWallet, bitcoinWallet). chainId --- A chain identifier, carried by each condition whose type is not bound to a single chain, so that one request can span several chains. EVM chains use the numeric EIP-155 chain identifier (the reference part of a CAIP-2 identifier ), expressible as integer (e.g., 1 for Ethereum mainnet) or string. Non-EVM chains use a string identifier naming the chain (for example solana, xrpl, bitcoin). conditions --- A list of one or more condition objects. Each has a type field discriminating the condition category, and type-specific fields specifying the parameters of that category. This document does not enumerate all possible condition types. Common categories include token balance evaluation, NFT ownership evaluation, on-chain attestation reference (e.g., reference to an Ethereum Attestation Service entry), and identity-registry membership evaluation. Implementations MAY define additional condition types. format --- OPTIONAL. When "jwt", the response additionally carries the attestation as an RFC 7519 JWT (). When omitted, the response is the JSON format of alone. proof --- OPTIONAL. Requests a cryptographic proof layer. When omitted, no proof is requested. Value: "merkle" (where supported by the underlying chain; returns Merkle storage proofs anchored to the block header).

Response Shape A response contains a signed attestation object together with the signature and key identifier. The signed attestation object has the following structure: ", "pass": true, "results": [ { "condition": 0, "label": "", "type": "", "chainId": "", "met": true, "evaluatedCondition": { /* condition object */ }, "conditionHash": "0x", "blockNumber": "", "blockTimestamp": "" } ], "attestedAt": "" } ]]> The signature is computed over signed bytes derived from this object under the signing scheme that the transmitted kid selects (). The signature, the key identifier (kid), expiry timestamp (expiresAt), and any deployment-specific wrappers are transmitted alongside the signed object but are NOT part of the signed bytes. Nor is any member of the transmitted attestation object other than id, pass, results, and attestedAt: an issuer MAY add informational members there (for example, counts of met and unmet conditions), and they are unsigned. Note that the signed object does not in general name the wallet: the requester knows which wallet it asked about, but a party that receives a JSON-format attestation second-hand cannot bind it to a wallet from the signed bytes alone (some condition types carry the address inside evaluatedCondition). The JWT format names the wallet in its sub claim (). A typical wire response carries the signed object plus these adjacent fields: " }, "sig": "", "kid": "", "pqSig": "", "pqKid": "" } ]]> Field semantics (signed object): id --- An opaque attestation identifier. Implementation-specific format. Useful for correlation, logging, and replay detection. It is covered by the signature. pass --- The aggregate result. Default semantics: logical AND of all per-condition met values. Operators MAY specify alternate combination logic in extensions. results --- An array of per-condition result objects. Each MUST include the per-condition met boolean, the condition type, the verbatim evaluatedCondition (as it was evaluated, after any normalization), and the conditionHash (SHA-256 of the UTF-8 JSON serialization of evaluatedCondition with member names sorted as sorts them (by UTF-16 code units) and no insignificant whitespace, as a 0x-prefixed lowercase hexadecimal string). The evaluatedCondition object is flat: its member values are strings, numbers, booleans, or null, never objects or arrays, so that sorting its member names fully determines the serialization; strings and numbers are serialized as in the bare scheme of . A verifier MUST recompute conditionHash from the transmitted evaluatedCondition and MUST reject the result as altered if the two differ. Each result MUST include chain-specific freshness evidence: blockNumber and blockTimestamp for EVM chains; ledgerIndex and (where available) ledgerHash for XRPL; slot for Solana; blockHeight and blockHash for Bitcoin; for any other chain family, the reference the issuer documents for it. All such freshness fields are inside the signed results array and are therefore covered by the issuer's signature. Implementations MAY include additional informational fields (condition index, label, etc.) echoed from the request. attestedAt --- ISO 8601 timestamp of when the attestation was signed. Field semantics (adjacent, unsigned): expiresAt --- ISO 8601 timestamp of when the attestation expires. Verifiers SHOULD check expiry (step 6 of ). Recommended default: thirty minutes after attestedAt. Implementations MAY use shorter expiries; longer expiries SHOULD be justified by the use case. expiresAt is transmitted with the attestation but is not part of the signed payload; verifiers concerned with tamper-evidence over the expiry SHOULD use the JWT format (), where exp is a signed claim. kid --- Key identifier (RFC 7517) for the public key used to sign this attestation. Verifiers use this to look up the appropriate public key in the issuer's JWKS. kid is transmitted alongside the signed payload but is not part of the signed bytes. The kid selects both the verification key and the signing scheme (); verifiers resolve it against the issuer's published JWKS as described in . The JWT format embeds kid in the protected header where it is covered by the JWT signature. sig --- The signature. Default: ECDSA P-256 signature over the signed bytes defined in , in P1363 (raw R || S) format, base64-encoded with the standard alphabet and padding (Section 4 of ). pqSig, pqKid --- OPTIONAL. A companion signature under a second algorithm and the identifier of the key that produced it (). When present they are additive: sig and kid are unchanged by their presence, and a verifier that does not implement companion verification ignores them. The signature scope includes the evaluatedCondition and conditionHash fields nested inside results, ensuring the signature is tamper-evident over both the result and the condition that produced it.

Signing Algorithm The default signing algorithm is ECDSA with P-256 curve and SHA-256 (ES256) per . The signed bytes are produced under one of the signing schemes in . An issuer MAY additionally attach a companion signature under a second algorithm ().

Signing Schemes This document defines two signing schemes. The type of message a verifier holds is evident from its shape (an attestation of carries pass and results; a fact profile does not); the kid transmitted with it selects both the verification key and the signing scheme. The issuer's documentation states, for each kid it publishes, which scheme that kid selects and, for the domain-separated scheme, the domain tag. Verifiers MUST determine the scheme from the kid, MUST NOT assume that an issuer uses a single scheme, and MUST NOT verify an attestation under any scheme other than the one its kid selects. A single public key MAY be published under more than one kid, so that one key serves more than one scheme. An issuer that signs more than one type of message under the domain-separated scheme MUST use a distinct domain tag for each type, and a verifier MUST NOT accept an attestation under a kid that the issuer documents for a different type of message. Signing schemes apply to the JSON format of . In the JWT format () the signed bytes are the JWS Signing Input of the JWT , whatever scheme the kid would select in the JSON format; there the kid selects the verification key (and, through its JWKS entry, the algorithm) but no scheme. Bare scheme. The signed bytes are the JSON serialization of an object carrying exactly the four members of the signed object, in the order id, pass, results, attestedAt, with no insignificant whitespace, encoded as UTF-8. Inside results, every member of every result object, including the members of evaluatedCondition, is serialized in the order in which it was transmitted, and array element order is preserved. Nothing inside the signed bytes of this scheme is re-sorted: the sorting of member names described in applies only to the computation of conditionHash. Strings and numbers are serialized as the ECMAScript JSON.stringify function serializes them, which for well-formed Unicode strings and finite numbers is also the serialization of primitive values specified by . The signed bytes are not transmitted as such; a verifier reconstructs them from the transmitted response. Under the bare scheme a verifier therefore MUST use a JSON parser that preserves the order of object members, and MUST omit from the reconstruction every member of the transmitted attestation object other than the four named above. Domain-separated scheme. The signed bytes are the concatenation of (1) a domain tag, (2) a single line feed character (U+000A), and (3) the canonical serialization of a JSON object carrying the member v (the scheme version, the integer 2 for the scheme defined here) together with the four members of the signed object (id, pass, results, attestedAt). The canonical serialization is the JSON Canonicalization Scheme : member names sorted at every level of nesting, array element order preserved, no insignificant whitespace, and strings and numbers serialized as that document specifies. (RFC 8785 requires well-formed Unicode strings; an issuer MUST NOT sign a string that is not.) Because the member names are sorted, a verifier needs no order-preserving parser under this scheme. The domain tag is an ASCII string, fixed by the issuer, that identifies the message type and the scheme version. It binds a signature to its message type, so that a signature produced over one type of message cannot be presented as a signature over another. An issuer using this scheme SHOULD carry numeric quantities inside the signed object (thresholds, amounts, ratios) as decimal strings and SHOULD confine JSON numbers to small integers, so that the signed bytes do not depend on any implementation's floating-point number formatting and can be reproduced exactly in any language. The signed bytes are encoded as UTF-8. Signed bytes are stable per kid. An issuer introducing a new scheme MUST do so under a new kid and MUST NOT change the signed bytes produced under a kid it has already published. Attestations signed under an earlier scheme therefore remain verifiable, unchanged, by verifiers deployed before the new scheme existed.

Signature Encoding and Additional Algorithms The signature output is the raw P1363 (R || S) representation of the ECDSA signature, base64-encoded (88 characters for P-256). Implementations producing DER-encoded ECDSA signatures MUST convert to P1363 before transmission. Implementations MAY support additional algorithms (ES384, EdDSA / Ed25519). Algorithm selection is encoded in the JWKS entry indexed by kid. Verifiers MUST NOT verify a signature under an algorithm other than the one the selected JWKS entry implies (its alg, and the key type and curve it carries).

Companion Signatures An issuer MAY attach to an attestation a companion signature produced under a second algorithm, for example a post-quantum signature algorithm. A companion signature is additive: it changes neither the signed object, nor the signed bytes defined in , nor the values of sig and kid. A verifier that does not implement companion verification ignores the companion fields and is otherwise unaffected. In the JSON format the companion is carried in two adjacent fields: pqSig, the companion signature, base64-encoded with the standard alphabet and padding (Section 4 of ), and pqKid, the key identifier of the companion key in the issuer's JWKS. The companion signature is computed over the concatenation of (1) a companion domain tag, (2) a single line feed character (U+000A), and (3) the exact signed bytes that the attestation's kid selects under , encoded as UTF-8. A verifier therefore reuses the bytes it has already reconstructed for the primary signature. The companion domain tag is distinct from any domain tag used by a signing scheme and is documented by the issuer for each pqKid it publishes. The companion algorithm defined by this document is ML-DSA-65 . Signatures are produced as in Algorithm 2 of (ML-DSA.Sign, not the pre-hash variant) with an empty context string; these are the parameters that specifies for JOSE. The companion key is published in the issuer's JWKS ( of this document) as an AKP key, the key type defined by . In the JWT format () the companion is a sibling token, pqJwt, returned beside the ES256 JWT: a JWS in compact serialization whose protected header carries alg ML-DSA-65 and the companion kid, and whose claims are the same as those of the ES256 JWT. No companion domain tag is used in the JWT format: pqJwt is verified over its own JWS signing input. A verifier that checks pqJwt MUST also confirm that its payload and the ES256 JWT's payload carry the identical claim set: the same member names and, for every member, a deeply equal JSON value (objects compared without regard to member order, arrays in order, numbers by value). Any difference, whether a changed value, a missing member, or an extra member on either side, makes the companion refuted. Byte-identical payload segments satisfy this trivially, but a verifier MUST NOT require byte-for-byte equality, since two serializers may order members differently. The companion then vouches for every claim a relying party reads from the ES256 JWT, and cannot be transplanted from another attestation. A verifier that implements companion verification MUST report the companion result as a verdict separate from the primary signature result, with one of four values: verified (transmitted, and verifies under the key that pqKid selects; in the JWT format, also carrying the same claim set as the ES256 JWT); refuted (transmitted, and either fails verification under that key or, in the JWT format, carries a different claim set); absent (no companion was transmitted, that is, no pqSig in the JSON format and no pqJwt in the JWT format); or unverifiable (transmitted, but the verifier could not check it). Unverifiable records a gap in the verifier's knowledge; refuted records positive evidence of alteration. A verifier determines the verdict by the first of these that applies:

No companion was transmitted: absent.
The attestation's own kid is missing, or is one the verifier has never met, so the signed bytes the companion covers cannot be reconstructed: unverifiable. A verifier MUST NOT substitute the signed bytes of another scheme for a kid it does not know, since that could only produce a false refutation.
pqKid resolves to no JWKS entry, resolves to a key of the wrong type, or names a companion key the issuer documents for a different type of message; or pqSig is transmitted without pqKid; or the verifier has no implementation of the algorithm: unverifiable. A verifier applies no companion domain tag other than the one pqKid names, so a pqKid of the wrong type leaves it nothing it is entitled to check.
Otherwise the companion signature is checked, and in the JWT format the claim sets are compared: verified or refuted. An attestation whose own kid the verifier knows but the issuer documents for a different type of message reaches this step with well-defined signed bytes, and its companion is checked against them; a relabelled artifact is therefore never unverifiable.

Item 2, and the relabelling case of item 4, concern the signed bytes of the JSON format. In the JWT format the companion is a JWS over its own signing input and is bound to the ES256 JWT by its claim set, so it is evaluated whether or not the JWT's kid selects a key; a genuine pqJwt beside a JWT whose kid the verifier cannot place is reported verified while the JWT's own signature verdict is unverifiable. In the JWT format, a pqJwt that does not parse as a compact JWS, or whose protected header lacks either the companion algorithm or a kid, is malformed and is refuted, since the header is covered by the companion signature and the issuer always emits both; this rule is applied before item 3 of the list. A refuted companion MUST cause the attestation to be rejected. An unverifiable companion MUST NOT be treated as verified. Whether an absent or unverifiable companion causes rejection is a matter of verifier policy: a verifier MAY require a verified companion from a date of its own choosing, and it MUST judge that date by its own clock at the time of verification, never by a timestamp carried in the attestation. A verifier reading an attestation after the fact, as a record rather than for a live decision, MUST NOT refuse it for lacking a companion; it reports the absence.

JWKS Discovery The issuer publishes its public key set at a discoverable HTTPS endpoint following . A commonly used path is /.well-known/jwks.json, under the well-known URI prefix of ; this document does not register that path. Each JWKS entry MUST include kid, kty, and alg, together with the public key parameters that its key type requires: crv, x, and y for an elliptic curve key (kty EC, ); pub for an Algorithm Key Pair key (kty AKP, ); and correspondingly for any other key type. A JWKS MAY therefore hold keys of more than one key type, and verifiers MUST NOT require the parameters of one key type on an entry of another. Issuers MAY publish multiple active keys simultaneously, to support key rotation, more than one signing scheme (), or companion signatures (). An issuer adding entries of a new key type to an existing JWKS SHOULD append them after the existing entries, so that the position of every existing entry is unchanged for deployed verifiers. Key selection: verifiers MUST select the verification key by the transmitted kid, never by position in the JWKS and never by default. If the kid is missing, or resolves to no entry in the JWKS available to the verifier, the verifier MUST NOT accept the attestation and MUST NOT substitute any other key, including the first entry in the JWKS or a key built into the verifier. Such an attestation is unverifiable, which is distinct from refuted: a refuted attestation carries a signature that fails under the key its kid selects, whereas nothing has been shown about the signature of an unverifiable one. Verifiers SHOULD report the two outcomes distinctly. Neither outcome is a successful verification. Key rotation: when the issuer rotates signing keys, the new public key MUST be published in JWKS before the issuer signs any attestation with the corresponding private key. Retired public keys SHOULD remain published in JWKS for a duration at least equal to the longest possible outstanding attestation expiry (typically the default thirty-minute window). An issuer MAY instead retain every key it has ever published, under its original kid, so that an attestation kept as a record remains checkable for as long as anyone holds it; retention does not extend an attestation's validity, which its expiry still governs. Relying parties that keep attestations as records SHOULD keep a copy of the JWKS with them. Because JWKS documents are cached, by verifiers and by intermediaries, different verifiers can hold different versions of an issuer's JWKS for up to the cache lifetime after it changes. During that interval a verifier holding the earlier version will find that a newly introduced kid resolves to no entry; the attestation is then unverifiable, not refuted, as described above. A verifier that meets an unknown kid MAY refresh its copy of the JWKS and retry. Verifiers SHOULD cache the JWKS according to the HTTP cache headers the issuer publishes, and MAY be supplied with a copy of the JWKS out of band instead of fetching it. The cache lifetime an issuer sets bounds how quickly a newly published kid becomes visible to verifiers; an issuer SHOULD document it.

JWT Format When format is "jwt", the response additionally carries the attestation as an RFC 7519 JWT, in a jwt member beside the members of the JSON format (). Protected header: {"alg": "ES256", "typ": "JWT", "kid": "<key id>"} per . The kid in the protected header is covered by the JWT signature. Standard claims:

iss --- issuer identifier (e.g., the issuer's base URL)
sub --- the wallet address a condition in the request evaluated. When the conditions span several address families, the issuer documents which family's wallet sub names; a wallet the request supplied but no condition evaluated is not named.
jti --- JWT identifier (typically the attestation id)
iat --- issuance timestamp (Unix seconds)
exp --- expiry timestamp (Unix seconds)

Custom claims carrying the attestation payload:

pass --- aggregate result
results --- per-condition result array
conditionHash --- array of per-condition conditionHash values, in results order
blockNumber --- chain block reference (typically the first result's blockNumber, where chain-homogeneous)
blockTimestamp --- chain block timestamp (typically the first result's blockTimestamp)

The JWT signature is computed by the issuer using the corresponding private key. Verifiers verify using any standard JWT library that supports ES256 and JWKS discovery. When the issuer attaches a companion signature, the JWT format carries it as the sibling token pqJwt (); the ES256 JWT is unchanged by its presence. The JWT format provides signed coverage of exp and kid (via standard claim and protected header, respectively); deployments requiring tamper-evident expiry or signed key-identifier binding SHOULD use the JWT format rather than the JSON format described in . A response in the JWT format carries the token beside the JSON-format members, so a verifier may hold both. A relying party that reads claims from the JWT MUST have verified the JWT itself; verifying the JSON-format attestation beside it is not a substitute, because the two are separately signed. A verifier handed both SHOULD verify the JWT as well as the attestation, and report the JWT's outcome as its own verdict: its signature under the same kid as the response, its results under step 4 of , its companion under , and that it is the token of this attestation (its kid equals the response's kid, jti equals id, and pass, results, and exp equal the attestation's pass, results, and expiresAt truncated to whole seconds). A transmitted JWT that fails any of these rejects the response: a relying party cannot tell which of the two it will be shown. The correspondence check does not cover sub, which the JSON-format attestation does not carry; the wallet named in sub is vouched for by the JWT's own signature alone. A JWT MAY also be presented on its own; it is then a complete attestation, verified as describes for the JWT format, without the correspondence check.

Optional Merkle Proofs When proof is "merkle" and the underlying chain supports Merkle storage proofs (typically EVM chains for storage-slot-mappable conditions), the response MAY include Merkle storage proofs anchored to the block header for each per-condition result. Merkle proofs permit trustless verification: a verifier can independently check the Merkle proof against the block reference without trusting the issuer's evaluation. When a Merkle proof is included (proof.available is true in the per-result proof object), the proof object MUST include the block reference and the proof nodes needed to check the proven value against that block's state root (for a storage-slot proof, including the storage slot path). Not all conditions or chains support Merkle proofs. Implementations MUST indicate proof availability per result and MAY return proof.available: false with a reason field when proof generation is unsupported for the condition or chain (e.g., NFT ownership conditions, non-storage-slot-mappable conditions, non-EVM chains). Privacy trade-off: Merkle proofs reveal raw on-chain values (e.g., the actual token balance). When no proof is requested, the wallet's balance is not returned. Operators MUST consider whether the trustlessness benefit of Merkle proofs is worth the privacy cost in each deployment. Bitcoin, XRPL, and Solana have different state-proof models and may not support Merkle proofs in the sense. Implementations targeting those chains MAY define chain-appropriate proof shapes or MAY return proof.available: false. For Bitcoin specifically: the UTXO model does not permit reproducible balance-at-block queries. Bitcoin implementations anchor the attestation to the chain tip (block height + block hash) at observation time as the cryptographically-bound freshness evidence appropriate to the UTXO model. The blockHeight and blockHash are covered by the issuer's signature inside the result and bind the observation to a recent chain tip rather than to a specific block's historical state. Issuers MUST refuse to sign Bitcoin attestations when the chain-tip lookup fails; see .

Security Considerations

Single-Issuer Architecture This document describes a single-issuer attestation primitive. The issuer is the sole signer of attestations within its declared scope. This is a deliberate design choice for several reasons:

Deterministic signature surface. Verifiers can independently re-derive an attestation's results from chain state without resolving issuer trust hierarchies, federation policies, or multi-party signing logic.
No re-signing or wrapping. This document defines no re-signing, aggregation under a wrapper signature, or repackaging of attestations by any party other than the issuer; a wrapper or aggregate signature confers no authority, and a verifier accepts no signature other than the issuer's own (its primary signature, and any companion or JWT signature the issuer itself produced, and ). The original observation's signature is the authoritative artifact end-to-end.
Unambiguous attribution. For audit, dispute resolution, and accountability, the issuer is unambiguously identified by the JWKS endpoint and signing key.

Multi-issuer federation, key delegation, cross-issuer attestation aggregation, and threshold signing are explicitly out of scope for this document. Future Internet-Drafts MAY define such mechanisms as separate primitives, but they are distinct from the single-issuer wallet-state attestation defined here.

Freshness Anchors and Replay Considerations The cryptographically-bound freshness anchors are the block reference inside each per-condition result and the attestedAt timestamp in the outer signed payload (the iat claim in the JWT format). Both are covered by the issuer's signature. Verifiers requiring strict tamper-evident freshness derive their policy from these signed anchors (e.g., "reject if attestedAt is older than thirty minutes", or "reject if blockTimestamp is older than sixty seconds"). The expiresAt field is an issuer-provided TTL hint, transmitted alongside the attestation but outside the signed payload in the JSON format described in . Because expiresAt is unsigned in the JSON format, a verifier that relies on it SHOULD confirm that it is no later than the signed attestedAt plus the issuer's documented validity window, and SHOULD reject the attestation as altered otherwise. Deployments requiring tamper-evident expiry SHOULD use the JWT format described in , where exp is a signed claim. For replay-sensitive deployments, implementations MAY include a nonce binding or audience binding in custom JWT claims (when the JWT format is used). This document does not normatively specify these extensions; deployments requiring replay protection beyond freshness checking SHOULD define them explicitly in their integration profile.

Refuse-on-Observation-Failure Issuers MUST refuse to sign an attestation when any required observation fails: chain-tip lookup, balance query, on-chain attestation registry lookup, or any other data source the condition depends on. A successfully signed attestation therefore implies that all underlying observations were acquired against a current chain reference at attestation time. Partial or degraded observations MUST NOT be signed. Verifiers MAY cross-check the included block reference against an independent chain source if the deployment requires it.

What This Primitive Does Not Protect Against

Chain-level reorganizations after attestation. If a chain reorgs after an attestation has been signed, the historical state observed in the attestation may no longer be canonical. Operators handling this concern SHOULD use chains with strong finality, SHOULD use sufficiently old block references, or SHOULD include reorg-handling logic in their verification flow.
Off-chain state changes. This primitive observes on-chain state only. It does not attest to off-chain identity, off-chain agreements, or off-chain commitments.
Malicious issuer. A compromised or malicious issuer could sign false attestations. This is mitigated by: (a) JWKS publication of signing keys, (b) optional Merkle proofs for trustless verification (where supported), (c) condition hashes for tamper-evidence over the evaluated logic, and (d) deterministic re-derivation by independent verifiers.

Algorithm Agility The default ES256 algorithm is widely supported and provides 128-bit security. Implementations supporting additional algorithms MUST include the algorithm in the JWKS entry indexed by kid. Verifiers MUST check the algorithm before verifying. Algorithm migration: when the cryptographic landscape changes (e.g., post-quantum migration), this document provides two paths, and an issuer can use either or both. Rotation: the issuer publishes a key for the new algorithm in JWKS under a new kid and begins signing with it; verifiers that do not support the new algorithm can no longer verify new attestations. Composition: the issuer continues to sign with the existing algorithm and attaches a companion signature under the new algorithm (). Composition leaves the existing signature, its signed bytes, and its key unchanged, so deployed verifiers that ignore unrecognized members keep working, and each verifier adopts the new algorithm on its own schedule by choosing the date from which it requires a verified companion. Composition is an application of post-quantum/traditional hybrid signing, for which gives terminology. In the JSON format a companion signature covers the same signed bytes as the primary signature, so an attacker must defeat both algorithms to forge an attestation that is accepted by a relying party requiring both signatures to verify. In the JWT format the two tokens are signed separately, and the same property holds when the verifier requires their claim sets to be identical, as requires: an attacker who defeats only the primary algorithm then cannot alter any claim without the companion refuting it. Under either path the protocol surface remains stable.

Privacy Considerations

Boolean by Default The default response mode returns the result of condition evaluation, not the wallet's balance. A verifier learns whether a wallet satisfies a condition (e.g., "holds at least 100 USDC") without being told the balance itself. An issuer MAY return public reference values that the evaluation used (for example, a token's total supply); it SHOULD NOT return a value from which the wallet's balance can be derived unless the caller requested proof mode. This is the privacy-preserving default and SHOULD be used unless specific deployment requirements justify a less-private mode.

Merkle Mode Trade-Off When proof is "merkle", raw on-chain values are revealed for trustless verification. Operators MUST consider the privacy implications of revealing actual balances or asset holdings in each deployment.

No Identity Attributes The primitive handles no identity attributes: no name, document, contact, or account data is collected, signed, or transmitted. The one identifier it handles is the wallet address (), which is public on the chain but persistent, and so may be personal data where it can be linked to a natural person. The signed output is a boolean about a condition; where the condition itself concerns a person (for example, a KYC or jurisdiction attestation issued by a third party), the boolean relates to that person even though no attribute is disclosed, and deployers should handle it as information about that person. The results echo operator-provided text (label, and the condition parameters in evaluatedCondition); operators SHOULD NOT place identity attributes in them.

Wallet Address Handling The wallet address is the subject of the query but is public information on the underlying chain. Issuers SHOULD NOT log or retain wallet addresses beyond what is required for service delivery, abuse prevention, and operational integrity. Implementations targeting privacy-conscious deployments SHOULD document their address-handling policy.

Awareness of Observation This primitive observes public chain state without holder participation. The holder is not required to consent to nor be aware of any individual attestation, consistent with the public nature of blockchain state. Deployers operating in regulated or consumer-facing contexts SHOULD consider whether their deployment context requires additional transparency mechanisms; such mechanisms are out of scope for this document.

Verification Procedure This section collects the checks of the preceding sections into one procedure for the JSON format, naming the verdict at each branch. Steps 1 to 4 are REQUIRED; steps 5 and 6 are RECOMMENDED; step 7 is OPTIONAL. A verifier SHOULD report each step's outcome separately rather than as one boolean, so that a relying party can apply its own policy to the recommended and optional steps.

Select the key and scheme. Read the transmitted kid. If it is absent, or resolves to no entry in the JWKS available to the verifier, stop: the signature verdict is unverifiable (). Do not substitute any other key. If the kid resolves but the issuer documents it for a different type of message, stop: the artifact is relabelled, and the signature verdict is refuted. Otherwise the kid selects the key, the algorithm (the JWKS entry's alg and key type), and the signing scheme with its domain tag ().
Reconstruct the signed bytes from the transmitted attestation object under the selected scheme: under the bare scheme, exactly the members id, pass, results, and attestedAt in that order, every nested member in transmitted order, no whitespace, UTF-8; under the domain-separated scheme, the domain tag, a line feed, and the RFC 8785 serialization of the object {v, id, pass, results, attestedAt} with v equal to the scheme version. Members of the transmitted object other than the four named are not part of the signed bytes.
Verify the primary signature: decode sig (standard base64, P1363), and verify it under the selected algorithm over the signed bytes. Failure is refuted; the attestation is rejected.
Recompute each condition hash: for every result, serialize evaluatedCondition with member names sorted and no whitespace (), hash it, and compare with the transmitted conditionHash. A mismatch marks the result as altered; the attestation is rejected.
Check freshness against the signed anchors (attestedAt and each result's block reference) under the verifier's own policy (), and reject identifiers already seen if replay protection is required.
Check expiry: reject if the current time is past expiresAt, and, because expiresAt is unsigned in this format, reject as altered an expiresAt later than the signed attestedAt plus the issuer's documented validity window (). A verifier MAY allow a small clock skew.
Check the companion, if one is transmitted, in the order given in , and report one of verified, refuted, absent, or unverifiable as its own verdict. Refuted rejects the attestation; absent and unverifiable are subject to the verifier's own policy.

After a stop at step 1, the verifier reports the signature verdict it reached and the companion verdict of ; steps 4 to 6 need no key: step 4 MUST, and steps 5 and 6 SHOULD, still be performed and reported; a step the verifier did not perform is reported as not performed, never as passed; a verifier whose report has no separate state for an unperformed step reports it as failed with a reason that says it was not performed. The attestation is rejected whenever the signature verdict is not verified. In the JWT format, steps 1 to 3 are performed by a JWS library over the token's own signing input, with the library pinned to the algorithm the selected JWKS entry implies rather than to the token's own alg header (the kid still selects the key, and step 1's rules for a missing, unknown, or wrong-type kid still apply), step 4 applies to the results claim, expiry is the signed exp claim, and the companion is pqJwt bound by the full claim set (). A verifier holding both formats of the same attestation also verifies the token beside the attestation as describes. Issuers SHOULD publish test vectors covering, at least: a genuine attestation under each scheme they use; a tampered condition, a tampered signature, and a tampered condition hash; a missing and an unknown kid; and, where companions are used, a genuine, a tampered, and a mislabelled companion. A verifier that reproduces the published verdicts on such a set has evidence of interoperability that reading this document alone cannot give.

What This Is Not This section explicitly enumerates adjacent primitives that wallet state attestation is not, to prevent conflation:

Not a Verifiable Credential (W3C VC) . VCs are issued by an authority, presented by a holder, and verified against the holder's presented bytes. Wallet state attestations are pulled by the issuer from public chain state without holder presentation.
Not an mDoc or eIDAS attestation. mDocs (ISO/IEC 18013-5) are pre-issued, batched, and stored by the holder for later presentation. Wallet state attestations are issued on demand, are short-lived, and are not stored by the holder.
Not a SAML assertion or OIDC ID token. These primitives carry identity claims about a user. Wallet state attestations carry observations about wallet state, with no identity attribute ().
Not a reputation score, trust score, or credit rating. A wallet state attestation contains observed facts (boolean results, optionally with structured fact profiles). It does not contain opinions, scores, ratings, or aggregated judgments. A separate primitive built on top of wallet state attestations might produce a score; this primitive does not.
Not a settlement attestation, delivery attestation, or transaction proof. Wallet state attestation is read-only state observation at observation time. It does not attest to action confirmation, transaction completion, or delivery of goods or services.
Not an oracle in the price-feed sense. This primitive observes specific wallet state on demand for a specific request; it does not publish continuous data streams or aggregate market data.

These distinctions are essential to keeping wallet state attestation as a distinct primitive in the agent-commerce, condition-based-access, and verification ecosystems.

IANA Considerations This document has no IANA actions.

References Normative References The Base16, Base32, and Base64 Data Encodings JSON Web Signature (JWS) JSON Canonicalization Scheme (JCS) Cryptographic operations like hashing and signing need the data to be expressed in an invariant format so that the operations are reliably repeatable. One way to address this is to create a canonical representation of the data. Canonicalization also permits data to be exchanged in its original form on the "wire" while cryptographic operations performed on the canonicalized counterpart of the data in the producer and consumer endpoints generate consistent results. This document describes the JSON Canonicalization Scheme (JCS). This specification defines how to create a canonical representation of JSON data by building on the strict serialization methods for JSON primitives defined by ECMAScript, constraining JSON data to the Internet JSON (I-JSON) subset, and by using deterministic property sorting. Module-Lattice-Based Digital Signature Standard National Institute of Standards and Technology ML-DSA for JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE) Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. JSON Web Key (JWK) A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. JSON Web Algorithms (JWA) This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers. JSON Web Token (JWT) JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References Well-Known Uniform Resource Identifiers (URIs) Terminology for Post-Quantum Traditional Hybrid Schemes The OAuth 2.0 Authorization Framework The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] Chain Agnostic Improvement Proposal 2: Blockchain ID Specification n.d. Ethereum Improvement Proposal 1186: RPC-Method to get Merkle Proofs n.d. OpenID Connect Core 1.0 n.d. Verifiable Credentials Data Model n.d. Knowledge Context Protocol RFC-0004: Trust, Provenance, and Compliance n.d. Verifiable Intent --- environment.* Constraint Family Agent Governance Vocabulary n.d. Open Agent Trust Registry n.d. Draft Ethereum Improvement Proposal 8210: Agent Assurance Protocol n.d. Universal Commerce Protocol: Identity Linking n.d.

Changes from -00 This revision extends the format in two ways, restates the request shape, and states the existing format more precisely. Nothing an issuer signs changes: the signature over every attestation issued under -00 verifies under this revision exactly as before. Where a verifier built from this revision behaves differently from one built from -00, the difference is listed in the last two items or, for the added scheme and the correspondence check, in the item that introduces it.

now has subsections and defines two signing schemes selected by kid: the bare scheme and a domain-separated scheme based on . It states that signed bytes are stable per kid, that one key may be published under several kid values, that the schemes apply to the JSON format, that the signed bytes are reconstructed from the transmitted object under the bare scheme with every member in transmitted order, and that sorting of member names applies to conditionHash alone.
New defines optional companion signatures under a second algorithm (ML-DSA-65), carried as pqSig and pqKid in the JSON format and as pqJwt in the JWT format, bound in the JWT format by the full claim set, with four reported verdicts and the order in which they are determined. describes composition alongside rotation as a path for algorithm migration.
New collects the checks into one numbered procedure, names the verdict at each branch, states what is reported after a stop, maps the procedure onto the JWT format, and recommends that issuers publish test vectors.
states the required JWK members per key type, so that a JWKS can hold elliptic curve and AKP keys together; the key selection rule (by kid, never by position or default; a missing or unknown kid is unverifiable, reported distinctly from refuted); that an issuer may retain published keys permanently; guidance on cached JWKS documents, including that a verifier MAY hold a copy of the JWKS supplied out of band and MAY refresh and retry on an unknown kid; and that new key types are appended after existing entries. Caching is stated in terms of the issuer's published headers, without a figure.
states that members of the transmitted attestation object other than the four signed members are unsigned, that the signed object does not in general name the wallet, that evaluatedCondition is flat, the base64 alphabet, and the serialization used for conditionHash. : chainId is carried by each condition; format and proof are top-level members; the chain-family lists are open-ended. : the JWT is carried beside the JSON format; sub is the wallet a condition evaluated; a relying party that reads claims from the JWT verifies the JWT itself; a correspondence check between the two formats is given.
Statements made more precise: a fact profile is covered by a single signature; the XRPL ledger hash is included where available; the evaluation, rather than the attestation, is deterministic, and re-derivation is exact where the block reference names the state read; the issuer selects the anchored block; the contents of a proof object are stated for proofs that are not storage-slot proofs; id is signed and usable for replay detection; iat is the JWT counterpart of attestedAt; format and proof are omitted rather than set to "json" or "none"; checking expiry is RECOMMENDED, consistent with . The Abstract states that verification needs no contact with the issuer beyond a copy of its published key set and documentation. states that the default mode does not return the balance and may return public reference values the evaluation used. names the one identifier the primitive handles, the wallet address, and how a boolean about a person is to be treated; is aligned with it. states that a wrapper signature confers no authority.
References: added , , , , and ; is normative; takes the place of RFC 5785; one informative URL is updated.
Verifier behaviour that differs from a verifier built from -00: a missing or unknown kid is not accepted and no other key is substituted; a kid documented for a different type of message is not accepted; conditionHash is recomputed, and a mismatch causes rejection; a refuted companion causes rejection; a transmitted JWT that fails verification or does not correspond to the attestation beside it rejects the response; a verifier relying on the unsigned expiresAt checks it against the signed attestedAt. In each case the verifier accepts less.
Requirements stated more loosely than in -00: checking expiry is RECOMMENDED rather than required (, consistent with ); verifier caching of the JWKS is a SHOULD rather than a MUST, and the -00 recommendation of a one-hour maximum cache lifetime is not carried forward (); an XRPL ledger hash is included where available rather than always (). The issuer selects the anchored block; the -00 option of a caller-specified block is not carried forward (). A verifier built from this revision also verifies attestations under the domain-separated scheme and accepts a JWKS that holds more than one key type, neither of which a verifier built from -00 does.

Acknowledgments The author thanks the IETF community for ongoing discussion of attestation primitives in the agentic and wallet-state space.