Proposal: WalletStateCredential — verifiable claims about on-chain wallet state

[douglasborthwick-crypto]

Context

ACK-ID currently supports did:pkh for identifying blockchain wallets and CAIP-19 for identifying on-chain assets. ControllerCredential establishes who controls a wallet — but there's no credential type for making verifiable claims about what a wallet holds.

The ACK-ID future directions doc explicitly calls out "agent reputation, reliability metrics, and ethical compliance attestations" as areas where the VC framework should extend. The overall roadmap references "advanced privacy-preserving techniques" and "agent reputation systems based on cryptographically verifiable interaction history." A wallet-state credential fits squarely in this gap.

Proposal: WalletStateCredential

A new W3C VC type that attests to on-chain conditions — token balances, NFT ownership, EAS attestations — without exposing raw balances or requiring the verifier to query the chain.

Credential structure

Following the existing createCredential() pattern in @agentcommercekit/vc:

import { createCredential } from "@agentcommercekit/vc"

const credential = createCredential({
  type: "WalletStateCredential",
  issuer: "did:web:insumermodel.com",
  subject: "did:pkh:eip155:1:0xabc...def",
  attestation: {
    pass: true,
    results: [
      {
        type: "token_balance",
        chainId: 1,
        met: true,
        evaluatedCondition: {
          type: "token_balance",
          contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          chainId: 1,
          threshold: 1000,
          decimals: 6
        },
        conditionHash: "0x3a7f...",
        blockNumber: "0x12f4a80",
        blockTimestamp: "2026-03-04T12:00:00Z",
        label: "USDC >= 1000"
      },
      {
        type: "nft_ownership",
        chainId: 1,
        met: true,
        evaluatedCondition: {
          type: "nft_ownership",
          contractAddress: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
          chainId: 1
        },
        conditionHash: "0x8b2e...",
        blockNumber: "0x12f4a80",
        blockTimestamp: "2026-03-04T12:00:00Z",
        label: "BAYC holder"
      }
    ]
  },
  expirationDate: new Date(Date.now() + 1800_000)  // 30 min TTL
})

Key design choices:

• Privacy-preserving: results return met: true/false per condition, never raw balances. The verifier learns "wallet holds >= 1000 USDC" without learning the actual balance.
• Tamper-evident: each result includes a conditionHash (SHA-256 of the canonical JSON of evaluatedCondition), so verifiers can confirm exactly what was checked.
• Block-anchored: blockNumber and blockTimestamp pin each result to a specific chain state. For XRPL conditions, ledgerIndex serves the same role.
• CAIP-compatible: wallet subjects use did:pkh with CAIP-2 chain IDs (eip155:1, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Asset identification can use CAIP-19 (eip155:1/erc20:0xA0b8...eB48), though the reference implementation uses flat contractAddress + chainId fields.
• Short-lived: on-chain state changes, so these credentials have short TTLs (30 minutes in the reference implementation).

ClaimVerifier

Following the getControllerClaimVerifier() pattern:

import type { ClaimVerifier, CredentialSubject } from "@agentcommercekit/vc"

function isWalletStateClaim(subject: CredentialSubject): boolean {
  return (
    "pass" in subject &&
    "results" in subject &&
    Array.isArray(subject.results) &&
    subject.results.every((r: any) => "met" in r && "conditionHash" in r)
  )
}

export function getWalletStateClaimVerifier(): ClaimVerifier {
  return {
    accepts: (type: string[]) => type.includes("WalletStateCredential"),
    verify: async (credentialSubject: CredentialSubject) => {
      if (!isWalletStateClaim(credentialSubject)) {
        throw new Error("Invalid wallet state claim")
      }
      // Verification: resolve issuer's JWKS, verify VC signature,
      // check expiration (on-chain state is time-sensitive),
      // optionally recompute conditionHash from evaluatedCondition
      // to confirm condition integrity
    }
  }
}

The verifier validates the VC signature against the issuer's JWKS endpoint and checks expiration. It does NOT re-query the chain — the point is that the credential is a portable, offline-verifiable proof of on-chain state at a specific block height.

Use cases in ACK

1. Solvency checks before payment: an ACK-Pay server can require a WalletStateCredential proving the agent's wallet holds sufficient funds before issuing a payment request. Prevents failed transactions.
2. Trust-gated access: a server can require proof of token holdings (governance tokens, staked assets) before granting access to premium services — without the agent revealing its full portfolio.
3. Compliance credentials: wallet-level KYC attestations (e.g., EAS-based Coinbase Verified Account on Base) can be expressed as conditions, giving ACK agents a path to on-chain compliance proof.
4. Credential chaining: ControllerCredential + WalletStateCredential together prove "this agent is controlled by entity X, and entity X's wallet meets conditions Y" — a complete identity + authorization chain.

Reference implementation

InsumerAPI already issues wallet-state attestations in this shape — POST /v1/attest with format: "jwt" returns an ES256-signed JWT containing pass, results (with per-condition met, evaluatedCondition, conditionHash, blockNumber, blockTimestamp), and standard claims (iss, sub, jti, iat, exp). The signing key is published at a JWKS endpoint (kid: insumer-attest-v1, ES256/P-256). This could serve as a reference issuer for a WalletStateCredential implementation.

Wrapping the existing attestation response into createCredential() format would be straightforward — the claim shape maps directly.

Open questions

1. Condition type registry: should condition types (token_balance, nft_ownership, eas_attestation, farcaster_id) be an open enum, or defined in a schema?
2. Multi-chain representation: CAIP-19 handles EVM assets well, but some chains (XRPL trust lines) don't map cleanly to asset_namespace:asset_reference. Worth defining a CAIP-19 extension or keeping chain-specific fields?
3. Issuer trust: who decides which issuers are trusted for wallet-state claims? This is the same trust model question as any VC issuer — probably left to the verifier's policy.
4. Revocation: BitstringStatusList (already in @agentcommercekit/vc) could work, but short TTLs may make explicit revocation unnecessary for most wallet-state claims.

Happy to contribute a PR with the credential type, schema, and claim verifier if there's interest.