agentic-wallet-mcp 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to `agentic-wallet-mcp` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> Entries for 0.5.0 and earlier were reconstructed from commit history when this file was
+> introduced in 0.6.0, so they summarise each release rather than being exhaustive.
+
+## [0.6.0] — 2026-07-28
+
+This release is about the wallet never misstating what a call cost. Four reporting defects were
+found during live use, in each case the wallet told the caller something untrue about money.
+
+### Changed — BREAKING
+
+- **`amountPaid` is now `undefined` on a cache hit.** Previously a cache hit replayed the original
+  issuance's `txHash`/`paidAsset`/`amountPaid` at the top level, so a **free** call was
+  indistinguishable from a fresh charge and anything summing `amountPaid` across calls
+  double-counted. Those values now appear under `originalPayment: { txHash, asset, amount }`
+  instead, and are omitted entirely when the cached credential was issued free. Any consumer
+  reading top-level `amountPaid` to track spend needs updating.
+
+### Added
+
+- **`get_template_schema` tool** — a free read of a credential template's declared attribute
+  schema (`{ required, optional }`), taking a `did:zid:...` id or a known template name. No
+  payment, no signing, no issuer call. Previously the only way to ask what a template required was
+  `subscribe_and_issue` with `dryRun` — a tool whose name reads as "this charges money" — so an
+  agent had no obvious reason to reach for it and would discover a newly-required attribute by
+  failing an issuance first. A template that cannot be read returns `{ error }` rather than an
+  empty schema, so "needs nothing" is never confused with "could not look it up".
+- **`staleAttributes` on a cache hit** — `{ missing, dropped }` when a held credential no longer
+  matches the template it came from. Validity checks only ever asked whether a credential had
+  expired, never whether its fields still fit the template, so an issuer changing a template left
+  holders with a credential that looked valid and wasn't. The cached credential is still returned;
+  this reports, it does not re-issue or charge.
+- **`decimals` on `wallet_status({ token })`** — the raw base-unit balance stays canonical (it is
+  the unit x402 quotes `maxAmountRequired` in, so cap checks and comparisons remain integer-only),
+  but callers no longer need a second contract call to know whether `"473999900"` means 474 or
+  474 million.
+- **`paymentAttempted: { asset, amount, paymentId }`** on any failure occurring after the x402
+  payment has settled on chain. The issuer's error body carries neither the amount nor a
+  transaction reference, so such a debit was previously invisible in the response and discoverable
+  only by comparing `balanceOf` before and after. `paymentId` is the handle the issuer's idempotent
+  recovery endpoint takes.
+- **Indeterminate-settlement recovery.** The issuer distinguishes a definitive facilitator
+  rejection from an outcome that is *unknown* — where the payment may well have landed and the
+  record is deliberately left recoverable. On the indeterminate code the wallet now polls the
+  issuer's status endpoint (bounded) and reports `recovery: { status, txHash?, vcId?, polls }`,
+  rather than discarding a credential already paid for. `status: "ISSUED"` means it exists after
+  all; note the status endpoint returns only its id, not the credential body.
+- **`MbiError.mbiStatus`** — the issuer's own numeric status code, parsed from the error body.
+  Previously only the HTTP status and an opaque message string were available, so the two
+  post-payment failures could be told apart only by substring-matching or by trusting an HTTP 502
+  that any gateway can emit.
+- **Explicit HTTP deadline** on the issuer client (90s, overridable), above the issuer's own 60s
+  facilitator timeout. Previously the runtime default applied, which happened to be longer but was
+  not a deliberate choice — a deadline at or below the issuer's would abort a settlement still
+  legitimately in progress.
+
+### Fixed
+
+- **Failed balance lookups no longer report a fabricated zero.** Any failure — non-zero
+  `errorCode`, missing field, malformed payload — previously collapsed to `{ balance: '0' }`,
+  making an unreachable node indistinguishable from an empty wallet. Worse, because the
+  underlying helpers returned *normally*, a caller's `try`/`catch` never fired. Now surfaced as
+  `{ error: 'query_failed' }`. Both the ZTP20 and the native ZTX path had the same defect; both
+  are fixed.
+- `originalPayment` is omitted for a cached credential that was issued free, rather than reported
+  as `{ asset: 'none', amount: '0' }` — matching the documented behaviour.
+
+### Documentation
+
+- `query_contract` documented for the first time. It shipped in 0.5.0 but was never added to the
+  tool list. The documentation now also states plainly that it is a pass-through with no ABI or
+  method list — the contract decides what it understands, and an unknown method returns the same
+  shape as a typo.
+- The `subscribe_and_issue` description previously claimed `schema` is returned on *every*
+  response; the cache path returns before the chain lookup, so it never did. Corrected, and the
+  cache path now performs the lookup so the claim holds.
+
+## [0.5.0] — 2026-07-27
+
+### Added
+
+- Wallet BE account-activation checking: `activated`/`activationTxHash` fields,
+  `checkActivationStatus`, a bounded `waitForActivation` polling helper, and polling wired into
+  both first-run account creation and `create_holder_account`.
+- x402 payment readiness — `pay_and_fetch` and `subscribe_and_issue` surface an insufficient-funds
+  shortfall as a structured result instead of throwing.
+- Per-network JMYR token registry (`resolveTokenAddress`) and token-balance lookup on
+  `wallet_status`.
+- `query_contract` — general-purpose read-only contract/account query, exposed as an agent tool.
+- Template attribute validation and derivation, with the full declared schema surfaced.
+
+### Fixed
+
+- A `resolveHolder` polling failure degrades instead of crashing startup.
+- The `hsmPassword` is persisted alongside address/DID on account override, not dropped.
+
+## [0.4.0] — 2026-07-24
+
+### Added
+
+- Local cache of issued credentials, keyed by template, so `subscribe_and_issue` does not pay and
+  re-issue for a credential already held.
+- Named-template alias resolution (e.g. `"AI Birthcert"`), and an `agentDid` auto-fill gated on the
+  template's declared schema.
+
+### Fixed
+
+- `revealAttributes` ordering to match the credential's signed field order, which was breaking BBS+
+  presentation verification.
+- Free-template synchronous issuance handled in the issuer's phase 1.
+
+## [0.3.0] — 0.3.1
+
+### Added
+
+- Live x401 proof integration: OID4VP submit authentication, DCQL reveal mapping, and an issuer-key
+  override for when the resolver is unreachable.
+- Integration guide, presentation-submission fix, and the switch to the published
+  `x401-zetrix-client` package.
+
+## [0.2.0]
+
+### Added
+
+- Optional `ZETRIX_ADDRESS`/`HOLDER_DID` onboarding, with `HSM_PASSWORD` guaranteed present.
+- x402 asset symbol resolved from a ZTP20 contract's `contractInfo`.
+
+## [0.1.0]
+
+Initial release — the five agent-facing tools (`wallet_status`, `prove_identity`, `pay_and_fetch`,
+`subscribe_and_issue`, `create_holder_account`) over x401, x402, and issuer-side credential
+issuance, with all signing through Wallet BE's HSM.

package/README.md

@@ -13,18 +13,20 @@ through Wallet BE's HSM.
 - **holder key custody + signing** → Wallet BE softHSM (`/wallet/hsm/*`)
 - **VC issuance** → MBI RS (`/v1/vc/pay/*`)
 
-[`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md) has a full end-to-end prompt script (onboarding →
+[`docs/USAGE_FLOW.md`](https://github.com/Zetrix-Chain/zetrix-agentic-wallet/blob/main/docs/USAGE_FLOW.md) has a full end-to-end prompt script (onboarding →
 VC issuance → identity proof → pay-per-use).
 
 ## Tools
 
 | Tool | Does | Input | Output (shape) |
 |---|---|---|---|
-| `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache) | `{ heldCredentials? }` | `{ holderDid, zetrixAddress, network, credentials }` |
+| `wallet_status` | Report holder DID/address/network + held VCs (client-supplied, or the local cache); optionally a token balance | `{ heldCredentials?, token? }` | `{ holderDid, zetrixAddress, network, credentials, tokenBalance? }` |
 | `prove_identity` | Answer an x401 `PROOF-REQUEST` → return the `PROOF-RESPONSE` header to replay | `{ proofRequest, vc?, revealAttribute?, issuerKeys? }` | `{ proofResponseHeader, verified, presentationId }` |
 | `pay_and_fetch` | Fetch a URL, auto-pay with x402 (self-pay via Wallet BE) on `402` | `{ url, method?, headers?, body? }` | `{ status, body, paymentMade, amountPaid, amountPaidHuman, asset }` |
-| `subscribe_and_issue` | Reuse a cached VC if still valid, else pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate?, dryRun?, forceReissue? }` | `{ issued, vcId, vc, txHash, fromCache? }` |
+| `subscribe_and_issue` | Reuse a cached VC if still valid, else pay x402 → MBI issues → return the VC | `{ templateId, attributes, expirationDate?, dryRun?, forceReissue? }` | `{ issued, vcId, vc, txHash, fromCache?, schema?, originalPayment?, paymentAttempted?, recovery? }` |
 | `create_holder_account` | Onboarding: mint an HSM account (the MCP already auto-creates one at startup if `ZETRIX_ADDRESS` is omitted — see Environment below). Always checks for an existing account first — if one is active for this session, returns `{ alreadyExists: true, existing }` without creating anything; pass `confirmNew: true` (after asking the user) to mint a new one anyway | `{ password, label?, purpose?, confirmNew? }` | `{ created, alreadyExists, existing?, zetrixAddress?, holderDid?, publicKeyHex?, message }` |
+| `get_template_schema` | **Free** read of a VC template's declared attribute schema. Call before `subscribe_and_issue` to learn which attributes it requires | `{ templateId }` | `{ templateId, schema: { required, optional } }` or `{ templateId, error }` |
+| `query_contract` | Read-only query against any Zetrix contract — call an arbitrary method and return its raw result. No signing, no state change | `{ contractAddress, method, params? }` | `{ ok: true, result }` or `{ ok: false, error }` |
 
 > **VCs are cached locally**, keyed by `templateId`, under `~/.agentic-wallet-mcp/vc-cache/`
 > (scoped per network + holder — different identities or networks never share a cache).
@@ -38,6 +40,40 @@ VC issuance → identity proof → pay-per-use).
 > back to the `expirationDate` requested at issuance; a VC with neither is cached indefinitely.
 > All Ed25519 signing still goes through Wallet BE HSM; no plaintext private keys.
 
+> `subscribe_and_issue` also returns `schema: { required, optional }` — the template's full
+> declared attribute list, read from chain — on every outcome that reaches the chain (issued,
+> dry-run quote, or a missing-attribute error), so you always see the complete field list rather
+> than only what went wrong — **including on a cache hit**, so a caller holding a credential can
+> still see what the template currently asks for.
+> Attributes the wallet auto-fills for you (e.g. `agentDid`, or a template-declared derived
+> key like the `AI Birthcert` template's `id` ← `agentUsername`) are omitted from `schema` since
+> you never need to supply them. Some templates also declare format validators for optional
+> attributes (e.g. `AI Birthcert`'s `dob` must be `YYYY-MM-DD`, `countryOfOrigin` must be a valid
+> ISO 3166 code or name) — an invalid value is rejected locally before any payment or MBI call.
+
+> **A held credential can go stale without expiring.** `isVcValid` only asks whether a VC is past
+> its `validUntil` — a VC whose *fields* no longer match the template it came from still reads as
+> valid. When an issuer changes a template (adds a required attribute, drops one), a cache hit now
+> reports the delta:
+>
+> ```jsonc
+> { "fromCache": true, "staleAttributes": { "missing": ["agentUsername"], "dropped": ["agentName"] } }
+> ```
+>
+> `missing` is what a reissue would need you to supply; `dropped` is what the held VC carries that
+> the template no longer declares. Absent when the held VC still satisfies the template. **The
+> cached VC is still returned** — this reports, it does not re-issue or charge. Reported from live
+> testing: without it, an agent reusing the attributes from a previously-issued credential only
+> discovered a newly-required field by attempting an issuance and being rejected.
+
+> **`get_template_schema` is the free way to ask what a template needs**, and is what an agent
+> should reach for before building an issuance request. It takes a `did:zid:...` id *or* a known
+> template name (e.g. `"AI Birthcert"`), performs no payment/signing/MBI call, and hides the
+> attributes the wallet fills in itself. A template it cannot read returns `{ error }` rather than
+> an empty schema, so *"needs nothing"* is never confused with *"couldn't look it up"*.
+> (`subscribe_and_issue` with `dryRun: true` also returns the schema, alongside the price — use
+> that when you want both.)
+
 > `create_holder_account` mints a **brand-new** keypair — Wallet BE's `/account/create` has no
 > way to provision a pre-chosen address. It always checks first whether an account is already
 > active for this session; if so, it returns `{ alreadyExists: true, existing }` and creates
@@ -49,6 +85,49 @@ VC issuance → identity proof → pay-per-use).
 > in your MCP config always overrides the saved account (see Environment below); the tool never
 > writes the MCP host's own config file or restarts the server for you.
 
+> **What a call cost is reported precisely.** `paidAsset`/`amountPaid` are set **only when this
+> call paid**. A cache hit reports the earlier charge under `originalPayment: { txHash, asset,
+> amount }` — never as `amountPaid` — so summing spend across calls cannot double-count a free
+> hit (omitted entirely when the cached VC was issued free). If issuance fails **after** the x402
+> payment has already settled on chain (MBI phase 2), the response carries
+> `paymentAttempted: { asset, amount, paymentId }`. MBI's own error body reports none of these, so
+> this is the only in-band signal that you were charged — and `paymentId` is the handle MBI's
+> recovery endpoint takes. It is never set for a phase-1 failure, which happens before anything is
+> paid. **Never retry a post-payment failure: the funds may already be gone, and each attempt costs
+> the full amount again — look the `paymentId` up instead.**
+
+> **Two post-payment failures exist and they mean different things:**
+> `4006` is a *definitive* facilitator rejection, while `4012` (HTTP 502) means the settle outcome
+> is **indeterminate** — MBI stopped listening but the payment may well have landed, so it
+> deliberately leaves the record recoverable rather than marking it failed. On `4012` the wallet
+> polls `GET /v1/vc/pay/status/{paymentId}` for you and reports
+> `recovery: { status, txHash?, vcId?, polls }`:
+>
+> | `recovery.status` | Means |
+> |---|---|
+> | `ISSUED` | The payment landed and the credential exists after all. `/status` returns only its `vcId`, **not** the VC body — so `vc` stays unset and you fetch it separately. |
+> | `FAILED` | MBI's terminal verdict on the payment. |
+> | `REQUIRED` / `SETTLED` | Still unresolved when the poll budget ran out — check again later with the `paymentId`. |
+> | `UNKNOWN` | `/status` itself was unreachable. The charge still stands; retry the lookup, not the payment. |
+
+> `wallet_status({ token })` returns `tokenBalance: { token, balance, decimals }` for `ZTX` or any
+> registered ZTP20 symbol (e.g. `JMYR`). `balance` is in the asset's **raw base units** — the same
+> unit x402 quotes `maxAmountRequired` in, so cap checks and quote comparisons stay integer-only.
+> Divide by `10^decimals` to display it: `"473999900"` with `decimals: 6` is `473.9999 JMYR`.
+> `decimals` is `null` if the token's `contractInfo` can't be read (the balance is still returned).
+> A failed lookup reports `{ token, error: "query_failed" }` and an unregistered symbol
+> `{ token, error: "unknown_token" }` — **never a zero balance**, so "0" always means you really
+> hold nothing rather than that the node was unreachable.
+
+> `query_contract` is a **pass-through**: whatever you put in `method` is sent to the contract
+> as-is. It performs no validation and holds no ABI or method list — the contract decides what it
+> understands, and an unknown method comes back as `{ ok: false, error: "query_contract: no result
+> value returned" }`, the same shape as a typo. To discover what a token supports, start with
+> `contractInfo` (returns `symbol`, `decimals`, `protocol`, `supply`, …); a `protocol: "ztp20"`
+> contract implements at least `balanceOf({ address })`, `totalSupply()` and
+> `allowance({ owner, spender })`. Read-only only (`optType: 2`) — state-changing methods like
+> `transfer`/`approve` need signing and are not reachable through this tool.
+
 > `revealAttribute` on `prove_identity` is optional and usually should stay that way. Omitted,
 > it's derived automatically from the challenge's DCQL `credential_requirements` — each claim path
 > is resolved against the presented VC's `credentialSubject` (e.g. a DCQL leaf name `agentName`
@@ -196,16 +275,19 @@ the `<...>` placeholders (don't commit a filled copy; `mcp.local.json` is gitign
 ## Example prompts
 
 - *"Check my wallet status."* → `wallet_status`
+- *"What's my JMYR balance?"* → `wallet_status({ token: "JMYR" })` (divide `balance` by `10^decimals` to display it)
 - *"I got a 401 with this PROOF-REQUEST header — prove my identity and give me the PROOF-RESPONSE to replay."* → `prove_identity`
 - *"Fetch `https://api.example/data` and pay automatically if it asks."* → `pay_and_fetch`
+- *"What fields does the AI Birthcert template need?"* → `get_template_schema` (free — do this before issuing)
 - *"Apply for the agent-identity credential with these attributes and pay for it."* → `subscribe_and_issue`
 - *"My wallet_status call is failing — I don't have a holder account yet. Set one up."* → `create_holder_account` (asks you for a password; if an account already exists it reports that instead of creating — confirm with the user, then re-call with `confirmNew: true` to replace it)
+- *"What's the total supply of this token contract?"* → `query_contract({ contractAddress, method: "totalSupply" })`
 
-For the full ordered script (onboarding → check → issue → prove → pay), see [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md).
+For the full ordered script (onboarding → check → issue → prove → pay), see [`docs/USAGE_FLOW.md`](https://github.com/Zetrix-Chain/zetrix-agentic-wallet/blob/main/docs/USAGE_FLOW.md).
 
 ## End-to-end usage flow
 
-Full narrative version with example prompts: [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md).
+Full narrative version with example prompts: [`docs/USAGE_FLOW.md`](https://github.com/Zetrix-Chain/zetrix-agentic-wallet/blob/main/docs/USAGE_FLOW.md).
 
 **Step 0 — onboarding (once).** Only if `ZETRIX_ADDRESS` isn't set yet: the MCP creates an HSM
 account automatically at startup from `HSM_PASSWORD` alone (see "Onboarding" under Environment
@@ -232,7 +314,7 @@ via MBI (`/vp/ext/create` + `/vp/ext/submit`, `includeVp: true`) → resolve the
 verification keys via the ZID resolver → submit to the verifier with wallet-auth headers →
 package the signed result as a `PROOF-RESPONSE`. Replaying that header back to the original
 resource server happens outside this MCP, in whatever drove the conversation. See "The
-`PROOF-REQUEST` header" section in [`docs/USAGE_FLOW.md`](docs/USAGE_FLOW.md) for the exact wire
+`PROOF-REQUEST` header" section in [`docs/USAGE_FLOW.md`](https://github.com/Zetrix-Chain/zetrix-agentic-wallet/blob/main/docs/USAGE_FLOW.md) for the exact wire
 structure and field semantics.
 
 **Phase 4 — `pay_and_fetch` — pay-per-use.**