Skip to content

demo: wallet-state attestations (InsumerAPI) in ACK#112

Open
douglasborthwick-crypto wants to merge 2 commits into
agentcommercekit:mainfrom
douglasborthwick-crypto:demo/insumer-wallet-state
Open

demo: wallet-state attestations (InsumerAPI) in ACK#112
douglasborthwick-crypto wants to merge 2 commits into
agentcommercekit:mainfrom
douglasborthwick-crypto:demo/insumer-wallet-state

Conversation

@douglasborthwick-crypto

@douglasborthwick-crypto douglasborthwick-crypto commented Jun 15, 2026

Copy link
Copy Markdown

What

Adds demos/insumer-wallet-state, mirroring demos/skyfire-kya: a worked example of consuming an InsumerAPI wallet-state attestation inside ACK.

Why

ACK-ID attests who an agent is, and ACK-Pay confirms a payment cleared — but nothing checks the paying wallet's on-chain state before settlement: no balance, holdings, or compliance condition on the payer. InsumerAPI fills that gap: read a wallet against a condition (token balance / NFT / EAS) across 37 chains, return an ES256-signed boolean, verifiable offline against a public JWKS — the same envelope shape the skyfire-kya token rides.

What it shows

  • Verifies the attestation with the public JWKS (no secret) via the insumer-verify SDK — signature, condition-hash binding, expiry.
  • Maps it into an ACK WalletStateCredential (W3C VC) with the original ES256 signature preserved as a detached JWS.
  • Gates on the boolean, with InsumerAPI named in trustedIssuers. No re-signing, no fork.
  • Runs against the live API (pnpm demo; a free key is one curl — see the README). In production today gating settlement for a Circle Alliance member building payments for the agentic economy.

The README documents a native path (publishing a did:web issuer + emitting VC-shaped output so it flows through verifyParsedCredential) as a follow-on, and is explicit about the bearer / presenter-binding boundary.

AI usage disclosure

Built with AI assistance (Claude Code); reviewed and verified end-to-end against the live API, and type-checked in-tree.

Summary by CodeRabbit

  • New Features
    • Added a new insumer-wallet-state demo for consuming InsumerAPI wallet-state attestations to drive access-control gating.
    • Supports verifying attestations, handling expiry, and converting results into W3C Verifiable Credentials for ACK-style claim checking.
  • Documentation
    • Added a README with two integration approaches, what the granted value means, and end-to-end run/mint/verify steps.
  • Tests / Tooling
    • Added demo package setup (scripts/config) plus Vitest configuration and a sample JWT attestation for offline verification.

Adds demos/insumer-wallet-state, mirroring demos/skyfire-kya: consume an
InsumerAPI wallet-state attestation (a signed boolean over on-chain
conditions) and gate access on it. Verifies against the public JWKS via
insumer-verify; maps into an ACK Verifiable Credential with the original
ES256 signature preserved. No re-signing, no fork.
@coderabbitai

coderabbitai Bot commented Jun 15, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ecf2f42a-cb15-4393-800d-2d72314c3725

📥 Commits

Reviewing files that changed from the base of the PR and between 0738c7a and 2a47a92.

📒 Files selected for processing (3)
  • demos/insumer-wallet-state/sample-attestation.json
  • demos/insumer-wallet-state/src/index.ts
  • demos/insumer-wallet-state/src/insumer-ack-id.ts
✅ Files skipped from review due to trivial changes (1)
  • demos/insumer-wallet-state/sample-attestation.json
🚧 Files skipped from review as they are similar to previous changes (2)
  • demos/insumer-wallet-state/src/index.ts
  • demos/insumer-wallet-state/src/insumer-ack-id.ts

Walkthrough

Adds a new demos/insumer-wallet-state package that verifies an InsumerAPI wallet-state attestation JWT as an ACK-ID gate claim. The core library (insumer-ack-id.ts) exports verification functions and a W3C VC converter; the demo entrypoint mints or loads a sample attestation and logs the result.

Changes

Insumer Wallet-State Demo

Layer / File(s) Summary
Package scaffolding
demos/insumer-wallet-state/package.json, demos/insumer-wallet-state/tsconfig.json, demos/insumer-wallet-state/vitest.config.ts
Bootstraps the private ESM demo package with scripts (demo, check:types, test, clean), workspace dependencies (agentcommercekit, insumer-verify@1.5.1), TypeScript path alias (@/*./src/*), and Vitest config with passWithNoTests.
Core Insumer–ACK integration library
demos/insumer-wallet-state/src/insumer-ack-id.ts
Defines INSUMER_ISSUER/INSUMER_ISSUER_DID constants, InsumerVerifyOptions, WalletStateCredentialSubject, and WalletStateGateResult interfaces. Exports verifyInsumerAttestation (delegates to insumer-verify), verifyInsumerAttestationAsAckId (enforces issuer/DID allowlist, derives subject DID from results[0].chainId, maps payload to gate result with expiresAt ISO timestamp), convertInsumerAttestationToVerifiableCredential (builds W3C VC with JsonWebSignature2020 detached proof), and getWalletStateClaimVerifier (accepts WalletStateCredential type, throws if pass !== true).
Demo entrypoint
demos/insumer-wallet-state/src/index.ts
Implements getAttestationJwt() to POST /v1/attest using INSUMER_API_KEY or fall back to sample-attestation.json. main() calls verifyInsumerAttestationAsAckId, logs gate result, converts granted tokens to W3C VC, and branches on denied/expired states. Top-level error handler exits with code 1.
Sample fixture and README
demos/insumer-wallet-state/sample-attestation.json, demos/insumer-wallet-state/README.md
Provides a precomputed JWT in sample-attestation.json for offline runs. README documents the attestation flow, what granted proves, adapter-based vs. native-verifier integration options, and run/mint/verify commands.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely identifies the main addition: a new demo showing how to consume InsumerAPI wallet-state attestations within ACK, which is the primary objective of the changeset.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@demos/insumer-wallet-state/sample-attestation.json`:
- Around line 2-4: The sample JWT in the fixture has an expiration timestamp
(exp=1781559981) set to June 15, 2026 in the future, which contradicts the _note
field claiming the attestation "will read as expired." To make the fixture
deterministically expired regardless of when the demo runs, either replace the
jwt value with one containing a past expiration timestamp (update the exp claim
to a timestamp before the current time), or update the _note field to accurately
document the exact expiry time (June 15, 2026, 21:46:21 UTC) instead of implying
it is already expired.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2d2eabb6-2c01-4157-a175-04382978959b

📥 Commits

Reviewing files that changed from the base of the PR and between 60eec23 and 0738c7a.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (7)
  • demos/insumer-wallet-state/README.md
  • demos/insumer-wallet-state/package.json
  • demos/insumer-wallet-state/sample-attestation.json
  • demos/insumer-wallet-state/src/index.ts
  • demos/insumer-wallet-state/src/insumer-ack-id.ts
  • demos/insumer-wallet-state/tsconfig.json
  • demos/insumer-wallet-state/vitest.config.ts

Comment thread demos/insumer-wallet-state/sample-attestation.json Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant