Wallet State Attestation: Signed Booleans about On-Chain State

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 14 November 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

2. 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 [RFC2119] [RFC8174] 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 Section 10.1).¶

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 independently-signed condition results. 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 ledger hash. Solana MUST include slot. Bitcoin MUST include block height and block hash (chain-tip evidence; see Section 9 for Bitcoin-specific considerations).¶

Condition hash --- A SHA-256 hash of the JSON serialization of the evaluated condition, with top-level keys sorted in lexical order, represented as a 0x-prefixed lowercase hexadecimal string, included in the response for tamper-evidence over the condition itself.¶

3. Architecture Overview

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

1. The issuer receives a request specifying a wallet address, a chain identifier, and one or more conditions.¶

2. The issuer reads canonical on-chain state for the specified wallet at the current chain tip (or, where supported, at a specified block).¶

3. The issuer evaluates each condition against the observed state.¶

4. The issuer signs the result and returns the attestation.¶

The attestation is deterministic: the same inputs evaluated against the same chain state at the same block produce the same output. A verifier can independently re-derive the attestation by reading the same chain state and applying the same condition logic.¶

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 chain-tip 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) at attestation time. The chain-tip 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 Section 10.3.¶

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

4. Request Shape

A request is a JSON object with the following structure:¶

{
  "wallet": "<address>",
  "chainId": "<chain identifier>",
  "conditions": [
    {
      "type": "<condition type>",
      "...": "<condition-specific parameters>"
    }
  ],
  "options": {
    "format": "json",
    "proof": "none"
  }
}

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). Implementations MAY accept the wallet in a chain-specific field (e.g., solanaWallet, xrplWallet, bitcoinWallet) when the address format is ambiguous.¶

chainId --- A chain identifier. EVM chains use a numeric chain identifier consistent with CAIP-2 [CAIP-2], expressible as integer (e.g., 1 for Ethereum mainnet) or string. Non-EVM chains use a string identifier (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.¶

options.format --- Selects the response envelope. Values: "json" (default; raw JSON object) or "jwt" (RFC 7519 JWT token).¶

options.proof --- Requests an optional cryptographic proof layer. Values: "none" (default) or "merkle" (where supported by the underlying chain; returns [EIP-1186] Merkle storage proofs anchored to the block header).¶

5. Response Shape

A response contains a signed attestation object together with the signature and key identifier. The signed attestation object has the following structure:¶

{
  "id": "<opaque attestation identifier>",
  "pass": true,
  "results": [
    {
      "condition": 0,
      "label": "<operator-provided label>",
      "type": "<condition type>",
      "chainId": "<chain identifier>",
      "met": true,
      "evaluatedCondition": { /* condition object */ },
      "conditionHash": "0x<sha256 of evaluatedCondition>",
      "blockNumber": "<chain-specific block reference>",
      "blockTimestamp": "<ISO 8601 timestamp>"
    }
  ],
  "attestedAt": "<ISO 8601 timestamp>"
}

The signature is computed over a JSON serialization of this object with field order id, pass, results, attestedAt. 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. A typical wire response carries the signed object plus these adjacent fields:¶

{
  "attestation": {
    /* signed object above */
    "expiresAt": "<ISO 8601 timestamp>"
  },
  "sig": "<base64 P1363 ECDSA signature>",
  "kid": "<key identifier for JWKS lookup>"
}

Field semantics (signed object):¶

id --- An opaque attestation identifier. Implementation-specific format. Useful for correlation and logging; not used for verification.¶

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 JSON serialization of evaluatedCondition with top-level keys sorted lexically). 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. 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 MUST check expiry. 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 (Section 8), 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; verifiers identify the verification key by trying the issuer's published JWKS entries indexed by the transmitted kid. 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 JSON serialization of the signed object, in base64-encoded P1363 (raw R || S) format. See Section 6.¶

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

6. Signing Algorithm

The default signing algorithm is ECDSA with P-256 curve and SHA-256 (ES256) per [RFC7518].¶

The signed bytes are the JSON serialization of the signed object (id, pass, results, attestedAt) using deterministic field-order serialization in that order. Verifiers MUST verify the signature against the exact bytes the issuer produced; verifiers reconstructing the preimage from a parsed JSON object MUST preserve the original field order. Issuers and verifiers SHOULD treat the signed bytes as opaque transport-layer material, not a re-serializable JSON object. For nested objects whose key order is not externally meaningful (notably the evaluatedCondition object hashed into conditionHash), keys are sorted in lexical order before serialization. See [RFC8785] for a general canonical-JSON scheme; this document does not require RFC 8785 conformance for the outer signed payload, because the outer field set is fixed and ordered by this specification.¶

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 consult the JWKS entry to determine the algorithm before verifying.¶

7. JWKS Discovery

The issuer publishes its public key set at a discoverable HTTPS endpoint following [RFC7517]. The recommended path is /.well-known/jwks.json per [RFC5785].¶

Each JWKS entry MUST include kid, kty, crv, alg, x, and y fields appropriate for the curve and algorithm. Issuers MAY publish multiple active keys simultaneously to support key rotation.¶

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

Verifiers MUST cache the JWKS appropriately (HTTP cache headers as published by the issuer; the issuer SHOULD set Cache-Control: max-age=3600 or shorter).¶

8. JWT Format

When options.format is "jwt", the response is wrapped in an RFC 7519 JWT.¶

Protected header: {"alg": "ES256", "typ": "JWT", "kid": "<key id>"} per [RFC7519]. 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 --- wallet address (the subject of the attestation)¶

• 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.¶

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 Section 5.¶

9. Optional Merkle Proofs

When options.proof is "merkle" and the underlying chain supports Merkle storage proofs (typically EVM chains for storage-slot-mappable conditions), the response MAY include [EIP-1186] 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 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). The default "none" mode preserves privacy by returning only the boolean result. 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 [EIP-1186] 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 Section 10.3.¶

10. Security Considerations

11. Privacy Considerations

12. 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) [VC-DATA-MODEL]. 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 component.¶

• 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.¶

13. IANA Considerations

This document has no IANA actions.¶

14. References

Acknowledgments

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

Author's Address