agentic-wallet-mcp 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# 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.1] — 2026-07-29
+
+**Upgrade if you use testnet.** The testnet Wallet BE and MBI endpoints have moved to the Zetrix
+sandbox hosts. No API, tool or config surface changed — this is an endpoint migration only.
+
+### Changed
+
+- **Testnet default endpoints moved to the Zetrix sandbox hosts.** `ZETRIX_NETWORK=zetrix:testnet`
+  now derives `https://wallet-api-sandbox.zetrix.com/server` (was
+  `https://wallet-api.myegdev.com/server`) and `https://mbi-vc-sandbox.zetrix.com` (was
+  `https://mbi-vc.myegdev.com`). Anyone on testnet relying on the built-in defaults should upgrade
+  to follow the platform; mainnet defaults are unchanged, and an explicit `WALLET_BE_URL` /
+  `MBI_BASE_URL` still wins over the network default, so anyone pinning those is unaffected.
+  Note the Wallet BE base keeps its `/server` path suffix — verified against the new host, which
+  returns nginx `404` without it.
+
+## [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?, schema? }` |
+| `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).
@@ -39,14 +41,39 @@ VC issuance → identity proof → pay-per-use).
 > 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 (issued, dry-run quote, or a
-> missing-attribute error), so you always see the complete field list rather than only what went
-> wrong. Attributes the wallet auto-fills for you (e.g. `agentDid`, or a template-declared derived
+> 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
@@ -58,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`
@@ -146,11 +216,11 @@ network:
 
 | Network | `WALLET_BE_URL` default | `MBI_BASE_URL` default | `OID4VP_BASE_URL` default | `ZID_RESOLVER_BASE_URL` default |
 |---|---|---|---|---|
-| `zetrix:testnet` | `https://wallet-api.myegdev.com/server` | `https://mbi-vc.myegdev.com` | `https://zid-oid4vp-sandbox.zetrix.com/api` | `https://zid-resolver-sandbox.zetrix.com` |
+| `zetrix:testnet` | `https://wallet-api-sandbox.zetrix.com/server` | `https://mbi-vc-sandbox.zetrix.com` | `https://zid-oid4vp-sandbox.zetrix.com/api` | `https://zid-resolver-sandbox.zetrix.com` |
 | `zetrix:mainnet` | `https://wallet-api.zetrix.com/server` | `https://mbi-vc.zetrix.com` | `https://zid-oid4vp.zetrix.com/api` | `https://zid-resolver.zetrix.com` |
 
 Only set any of the four explicitly if you run your own instance of that service instead of the
-default one — an explicit value always wins over the network default. The `*.myegdev.com`
+default one — an explicit value always wins over the network default. The `*-sandbox.zetrix.com`
 (testnet) hosts are public endpoints — no VPN needed; if you're on a corporate VPN and one of
 them times out, disconnecting it is more likely to fix that than connecting it. See "Network
 reachability & troubleshooting" below.
@@ -205,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
@@ -241,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.**
@@ -250,17 +323,25 @@ Independent of Phases 2/3 — no VC or identity proof involved, just a fresh pay
 
 ## Network reachability & troubleshooting
 
-The `*.myegdev.com` testnet endpoints are public — no VPN needed to reach them. One dependency
-sits behind a CDN edge (see the ZID resolver row below). When something that worked before
-suddenly times out or 403s, check this table before assuming a code regression.
+The `*-sandbox.zetrix.com` testnet endpoints are public — no VPN needed to reach them. Reachability
+differs per host, and this is the first thing to check when something that worked before suddenly
+times out or 403s, before assuming a code regression.
+
+- **`wallet-api-sandbox.zetrix.com` / `mbi-vc-sandbox.zetrix.com`** — direct origin IPs
+  (`124.243.148.237` / `111.119.237.222` as of 2026-07-29), **not** CDN-fronted, unlike the ZID
+  hosts and the mainnet endpoints. Being off-CDN is why the **corporate VPN blocks them
+  specifically** while `test-node.zetrix.com` and the mainnet hosts keep working over the same
+  VPN — so a failure here looks like a total outage while everything else looks healthy.
+  Disconnect the VPN. Verified reachable over a plain internet path on 2026-07-29.
+- **ZID resolver** sits behind a CDN edge with a managed challenge — see its row below.
 
 | Symptom | Cause | Fix / status |
 |---|---|---|
-| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc.myegdev.com`) | Transient network issue, or (if you're on a corporate VPN) the VPN routing away from the public internet | If you're on a VPN, try disconnecting it and retrying. Verify reachability directly: `curl -I https://wallet-api.myegdev.com/server` |
+| `Wallet BE /wallet/hsm/sign-blob request failed <- fetch failed <- UND_ERR_CONNECT_TIMEOUT` (or same for `mbi-vc-sandbox.zetrix.com`) | Corporate VPN routing away from the public internet — it blocks these two direct-origin hosts specifically (observed 2026-07-29), or a transient network issue | **Disconnect the VPN and retry.** Verify reachability directly: `curl -sS -o /dev/null -w '%{http_code}\n' "https://wallet-api-sandbox.zetrix.com/server/wallet/hsm/account/activate/status?address=<yourAddress>"` — `200` (with an `errorCode: 0` body) is healthy; `000` means the TCP connect never completed, so it's a network path problem, not a code problem |
 | `VP derivation failed <- ZID resolver HTTP 403 ... cf-mitigated: challenge` | ZID resolver (`zid-resolver-sandbox.zetrix.com`) sitting behind a Cloudflare **managed challenge** that blocks plain server-to-server `fetch` | Server-to-server access to the resolver must be allowlisted so it returns `200` directly. If the challenge is active, `prove_identity`'s `issuerKeys` input is the fallback — fetch the DID document via a real browser (it clears the JS challenge) and pass its `verificationMethod` entries' `publicKeyMultibase` (BBS+) / `publicKeyHex` (Ed25519) directly. |
 | `OID4VP backend returned a malformed presentation definition` | Historical SDK bug: the live sandbox's `GET /v1/presentation/{id}` response has no `expires_at` field, but the SDK guard required one | **Fixed** in `x401-zetrix-client` — `expiresAt` is now optional on `PresentationDefinition`. If you see this, you're on a stale cached `npx` install — clear it (`npx clear-npx-cache` or bump the version) to pick up the current published `agentic-wallet-mcp`. |
 | `SUBMIT_FAILED: OID4VP backend returned 401 ... Missing X-Wallet-Public-Key header` | Historical SDK gap: `POST /v1/presentation/submit` requires wallet-auth headers (`X-Wallet-Public-Key` / `X-Wallet-Signed-Data`, holder signs their own address) that the SDK didn't send | **Fixed** — `X401Wallet` now accepts an injected `submitAuth` provider and the wallet wires it automatically; nothing to configure. |
-| `MBI /vp/ext/submit did not return vp` | MBI's `includeVp` opt-in not deployed on the target instance | Deployed on the sandbox (`mbi-vc.myegdev.com`). If you see this against a different MBI instance, that instance needs the same rollout. |
+| `MBI /vp/ext/submit did not return vp` | MBI's `includeVp` opt-in not deployed on the target instance | Deployed on the sandbox (`mbi-vc-sandbox.zetrix.com`). If you see this against a different MBI instance, that instance needs the same rollout. |
 
 ## Security notes
 

package/dist/server-bundle.cjs

@@ -12547,9 +12547,17 @@ var import_node_path3 = require("node:path");
 // package.json
 var package_default = {
   name: "agentic-wallet-mcp",
-  version: "0.5.0",
+  version: "0.6.1",
   description: "Agent-facing MCP wallet for Zetrix \u2014 orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
-  keywords: ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
+  keywords: [
+    "mcp",
+    "model-context-protocol",
+    "zetrix",
+    "wallet",
+    "x401",
+    "x402",
+    "blockchain"
+  ],
   license: "MIT",
   author: "MyEG Services Berhad",
   homepage: "https://github.com/Zetrix-Chain/zetrix-agentic-wallet",
@@ -12570,6 +12578,7 @@ var package_default = {
   files: [
     "dist/server-bundle.cjs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   scripts: {
@@ -21539,10 +21548,10 @@ function deriveZidResolverBaseUrl(network) {
   return network.includes("testnet") ? "https://zid-resolver-sandbox.zetrix.com" : "https://zid-resolver.zetrix.com";
 }
 function deriveWalletBeUrl(network) {
-  return network.includes("testnet") ? "https://wallet-api.myegdev.com/server" : "https://wallet-api.zetrix.com/server";
+  return network.includes("testnet") ? "https://wallet-api-sandbox.zetrix.com/server" : "https://wallet-api.zetrix.com/server";
 }
 function deriveMbiBaseUrl(network) {
-  return network.includes("testnet") ? "https://mbi-vc.myegdev.com" : "https://mbi-vc.zetrix.com";
+  return network.includes("testnet") ? "https://mbi-vc-sandbox.zetrix.com" : "https://mbi-vc.zetrix.com";
 }
 function deriveTemplateRegistryAddress(network) {
   return network.includes("testnet") ? "ZTX3JszqPgRUx743SAp7q7zURfjvkWuH2FMEz" : "ZTX3GqJM1U6ifMPonwD4fGvrgoTKJua7b2cKX";
@@ -21643,6 +21652,49 @@ async function queryContract(input, query) {
   }
 }
 
+// src/clients/token-balance-client.ts
+var ZTX_DECIMALS = 6;
+async function fetchZTP20BalanceStrict(contractAddress, address, query) {
+  const result = await query({
+    contractAddress,
+    input: JSON.stringify({ method: "balanceOf", params: { address } }),
+    optType: 2
+  });
+  if (result?.errorCode !== 0) {
+    throw new Error(`balanceOf failed with errorCode ${result?.errorCode}`);
+  }
+  const raw = result.result?.query_rets?.[0]?.result?.value;
+  if (raw === void 0 || raw === null || raw === "") {
+    throw new Error("balanceOf returned no value");
+  }
+  const parsed = JSON.parse(raw);
+  const balance = parsed?.balance;
+  if (typeof balance !== "string") {
+    throw new Error("balanceOf returned no balance field");
+  }
+  return balance;
+}
+async function queryTokenBalance(deps, token) {
+  const symbol = token.toUpperCase();
+  if (symbol === "ZTX") {
+    try {
+      return { token: symbol, balance: await deps.fetchNativeBalance(deps.address), decimals: ZTX_DECIMALS };
+    } catch {
+      return { token: symbol, error: "query_failed" };
+    }
+  }
+  const contractAddress = deps.resolveTokenAddress(symbol);
+  if (!contractAddress) return { token: symbol, error: "unknown_token" };
+  let balance;
+  try {
+    balance = await fetchZTP20BalanceStrict(contractAddress, deps.address, deps.query);
+  } catch {
+    return { token: symbol, error: "query_failed" };
+  }
+  const info = await fetchTokenInfo(contractAddress, deps.query);
+  return { token: symbol, balance, decimals: info?.decimals ?? null };
+}
+
 // src/clients/template-info-client.ts
 async function fetchTemplateFields(templateId, registryAddress, nodeBaseUrl, query) {
   const key = `template__${templateId}`;
@@ -21860,16 +21912,35 @@ var MbiVpAdapter = class {
 // src/clients/mbi-client.ts
 var MbiError = class extends Error {
   httpStatus;
-  constructor(message, httpStatus) {
+  /**
+   * MBI's own numeric code from the ResponseWrapper body — finer-grained than the HTTP status
+   * and the only reliable way to tell a *definitive* post-payment failure from an indeterminate
+   * one. Undefined when the body carries no numeric `status`.
+   */
+  mbiStatus;
+  constructor(message, httpStatus, mbiStatus) {
     super(message);
     this.name = "MbiError";
     this.httpStatus = httpStatus;
+    this.mbiStatus = mbiStatus;
   }
 };
+var MBI_SETTLEMENT_INDETERMINATE = 4012;
 var MbiClient = class _MbiClient {
   baseUrl;
-  constructor(baseUrl) {
+  /** Per-request deadline in ms. See {@link MbiClient.DEFAULT_TIMEOUT_MS}. */
+  timeoutMs;
+  /**
+   * MBI's own facilitator read timeout is 60s, and `/settle` submits
+   * a transaction on chain. A client deadline at or below that would abort a settle MBI is
+   * still legitimately waiting on — manufacturing exactly the indeterminate outcome that MR
+   * exists to prevent, except on our side where nothing records it. Sits above 60s so MBI
+   * always gets to answer first; raise it in step if MBI's own timeout is ever raised.
+   */
+  static DEFAULT_TIMEOUT_MS = 9e4;
+  constructor(baseUrl, opts) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = opts?.timeoutMs ?? _MbiClient.DEFAULT_TIMEOUT_MS;
   }
   /**
    * Phase 1 — POST /v1/vc/pay/apply without X-PAYMENT; expects the 402 challenge.
@@ -21919,6 +21990,7 @@ var MbiClient = class _MbiClient {
     return fetch(`${this.baseUrl}${path}`, {
       method,
       headers,
+      signal: AbortSignal.timeout(this.timeoutMs),
       ...body !== void 0 ? { body: JSON.stringify(body) } : {}
     }).catch((e) => {
       throw new MbiError(`MBI ${path} request failed: ${e.message}`);
@@ -21933,13 +22005,15 @@ var MbiClient = class _MbiClient {
   async error(res, context) {
     const text = await res.text().catch(() => "");
     let msg = text;
+    let mbiStatus;
     try {
       const j = JSON.parse(text);
+      if (typeof j.status === "number") mbiStatus = j.status;
       const truncated = text.length > _MbiClient.ERROR_BODY_MAX_LEN ? `${text.slice(0, _MbiClient.ERROR_BODY_MAX_LEN)}\u2026 (truncated, ${text.length} bytes total)` : text;
       msg = `${j.message ?? j.error ?? text} | full body: ${truncated}`;
     } catch {
     }
-    return new MbiError(`MBI ${context} \u2014 HTTP ${res.status}: ${msg}`, res.status);
+    return new MbiError(`MBI ${context} \u2014 HTTP ${res.status}: ${msg}`, res.status, mbiStatus);
   }
 };
 
@@ -22084,6 +22158,19 @@ function isVcValid(entry, now = /* @__PURE__ */ new Date()) {
   if (Number.isNaN(expiry.getTime())) return false;
   return expiry.getTime() > now.getTime();
 }
+function extractAttributeKeys(vc) {
+  if (typeof vc !== "object" || vc === null) return [];
+  const subject = vc.credentialSubject;
+  if (typeof subject !== "object" || subject === null) return [];
+  const keys = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(subject)) {
+    if (key === "id") continue;
+    if (typeof value === "object" && value !== null) {
+      for (const inner of Object.keys(value)) keys.add(inner);
+    }
+  }
+  return [...keys];
+}
 function extractValidUntil(vc, fallback) {
   if (typeof vc === "object" && vc !== null && "validUntil" in vc) {
     const v = vc.validUntil;
@@ -22123,29 +22210,60 @@ async function payWithReadinessCheck(requestedAsset, rawPay) {
 }
 
 // src/orchestrator/subscribe.ts
+function diffAgainstTemplate(vc, fields) {
+  const held = new Set(extractAttributeKeys(vc));
+  const missing = fields.required.filter((k) => !held.has(k));
+  const dropped = [...held].filter((k) => !fields.allKeys.includes(k));
+  return missing.length > 0 || dropped.length > 0 ? { missing, dropped } : void 0;
+}
+var TERMINAL_SETTLEMENT_STATUSES = /* @__PURE__ */ new Set(["ISSUED", "FAILED"]);
+var RECOVERY_MAX_POLLS = 5;
+var RECOVERY_POLL_DELAY_MS = 2e3;
+async function pollSettlementOutcome(deps, paymentId) {
+  if (!deps.mbi.getStatus) return void 0;
+  const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let last;
+  for (let polls = 1; polls <= RECOVERY_MAX_POLLS; polls++) {
+    let status;
+    try {
+      status = await deps.mbi.getStatus(paymentId);
+    } catch {
+      return { status: "UNKNOWN", ...last ? { txHash: last.txHash, vcId: last.vcId } : {}, polls };
+    }
+    last = { status: status.status, txHash: status.txHash, vcId: status.vcId };
+    if (TERMINAL_SETTLEMENT_STATUSES.has(status.status)) {
+      return { status: status.status, txHash: status.txHash, vcId: status.vcId, polls };
+    }
+    if (polls < RECOVERY_MAX_POLLS) await sleep(RECOVERY_POLL_DELAY_MS);
+  }
+  return { ...last, polls: RECOVERY_MAX_POLLS };
+}
 async function subscribeAndIssue(deps, opts) {
   if (!/^did:zid:/.test(opts.templateId)) {
     return { issued: false, reason: `templateId must be a did:zid:... credential-definition id, got "${opts.templateId}"` };
   }
+  const fields = deps.resolveTemplateFields ? await deps.resolveTemplateFields(opts.templateId) : null;
+  const schema = fields ? { required: fields.required, optional: fields.allKeys.filter((k) => !fields.required.includes(k)) } : void 0;
   if (deps.cache && !opts.forceReissue && !opts.dryRun) {
     const cached2 = await deps.cache.get(opts.templateId);
     if (cached2 && isVcValid(cached2)) {
+      const originalPayment = { txHash: cached2.txHash, asset: cached2.paidAsset, amount: cached2.amountPaid };
+      const paidOriginally = cached2.amountPaid !== void 0 && cached2.amountPaid !== "0";
+      const staleAttributes = fields ? diffAgainstTemplate(cached2.vc, fields) : void 0;
       return {
         issued: true,
         vcId: cached2.vcId,
         vc: cached2.vc,
-        txHash: cached2.txHash,
-        paidAsset: cached2.paidAsset,
-        amountPaid: cached2.amountPaid,
-        fromCache: true
+        fromCache: true,
+        ...paidOriginally ? { originalPayment } : {},
+        ...schema ? { schema } : {},
+        ...staleAttributes ? { staleAttributes } : {}
       };
     }
   }
-  const fields = deps.resolveTemplateFields ? await deps.resolveTemplateFields(opts.templateId) : null;
   const { agentDid, ...rest } = opts.attributes ?? {};
   const shouldAutoFillAgentDid = !agentDid && fields !== null && fields.allKeys.includes("agentDid");
   const attributes = shouldAutoFillAgentDid ? { agentDid: deps.holderDid, ...rest } : opts.attributes ?? {};
-  const schema = fields ? { required: fields.required, optional: fields.allKeys.filter((k) => !fields.required.includes(k)) } : void 0;
   if (fields) {
     const attrs = attributes;
     const missing = fields.required.filter((k) => attrs[k] === void 0 || attrs[k] === null || attrs[k] === "");
@@ -22221,18 +22339,27 @@ async function subscribeAndIssue(deps, opts) {
     }
     throw err;
   }
+  const rawAsset = String(accept.asset ?? "");
+  const paidAsset = deps.resolveSymbol ? await deps.resolveSymbol(rawAsset) : rawAsset;
+  const amountPaid = String(accept.maxAmountRequired ?? "");
   let issued;
   try {
     issued = await deps.mbi.applySettle({ ...body, paymentId: challenge.paymentId }, xPayment);
   } catch (err) {
     if (err instanceof MbiError) {
-      return { issued: false, reason: err.message, httpStatus: err.httpStatus, ...schema ? { schema } : {} };
+      const paymentAttempted = { asset: paidAsset, amount: amountPaid, paymentId: challenge.paymentId };
+      const recovery = err.mbiStatus === MBI_SETTLEMENT_INDETERMINATE && challenge.paymentId ? await pollSettlementOutcome(deps, challenge.paymentId) : void 0;
+      return {
+        issued: false,
+        reason: err.message,
+        httpStatus: err.httpStatus,
+        ...schema ? { schema } : {},
+        paymentAttempted,
+        ...recovery ? { recovery } : {}
+      };
     }
     throw err;
   }
-  const rawAsset = String(accept.asset ?? "");
-  const paidAsset = deps.resolveSymbol ? await deps.resolveSymbol(rawAsset) : rawAsset;
-  const amountPaid = String(accept.maxAmountRequired ?? "");
   if (deps.cache) {
     await deps.cache.set(opts.templateId, {
       templateId: opts.templateId,
@@ -22726,6 +22853,37 @@ function createTools(deps) {
         }
       };
     },
+    /**
+     * Free schema lookup. Previously the only way to ask "what does this template need?" was
+     * subscribe_and_issue({ dryRun: true }) — a tool whose name reads as "this charges money", so
+     * an agent reasoning about required fields had no obvious reason to reach for it. Reported
+     * live: an agent discovered a newly-required attribute only by failing an issuance first.
+     */
+    async get_template_schema(input) {
+      const resolved = resolveTemplateAlias(input.templateId, deps.config.network);
+      const templateId = resolved ?? input.templateId;
+      if (!/^did:zid:/.test(templateId)) {
+        return {
+          templateId,
+          error: `templateId must be a did:zid:... credential-definition id or a known template name, got "${input.templateId}"`
+        };
+      }
+      const fields = deps.subscribeDeps.resolveTemplateFields ? await deps.subscribeDeps.resolveTemplateFields(templateId) : null;
+      if (!fields) {
+        return {
+          templateId,
+          error: `template schema could not be read from chain for ${templateId} (unknown/inactive template, or node unavailable)`
+        };
+      }
+      const hidden = /* @__PURE__ */ new Set(["agentDid", ...derivedAttributeKeys(templateId, deps.config.network)]);
+      return {
+        templateId,
+        schema: {
+          required: fields.required.filter((k) => !hidden.has(k)),
+          optional: fields.allKeys.filter((k) => !fields.required.includes(k) && !hidden.has(k))
+        }
+      };
+    },
     query_contract(input) {
       return deps.queryContract(input);
     },
@@ -22799,7 +22957,7 @@ function buildToolList() {
         type: "object",
         properties: {
           heldCredentials: { type: "array", items: { type: "object" }, description: "VCs the client holds. Omit to report whatever the wallet has cached locally from prior subscribe_and_issue calls instead." },
-          token: { type: "string", description: 'Optional token symbol (e.g. "ZTX", "JMYR") to check its balance for the active network, alongside the usual status fields.' }
+          token: { type: "string", description: `Optional token symbol (e.g. "ZTX", "JMYR") to check its balance for the active network, alongside the usual status fields. Returns { balance, decimals } where balance is in the asset's raw base units \u2014 divide by 10^decimals for the human amount (e.g. balance "473999900" with decimals 6 is 473.9999 JMYR). A failed lookup reports { error: "query_failed" } rather than a zero balance.` }
         }
       }
     },
@@ -22838,6 +22996,20 @@ function buildToolList() {
         required: ["url"]
       }
     },
+    {
+      name: "get_template_schema",
+      description: `Read a VC template's declared attribute schema from chain \u2014 FREE, no payment, no signing, no MBI issuance. Call this BEFORE subscribe_and_issue to find out which attributes a template requires, rather than discovering a missing one by attempting an issuance and being rejected. Accepts a did:zid:... credential-definition id or a known template name (e.g. "AI Birthcert"). Returns { templateId, schema: { required, optional } }; attributes the wallet fills in itself (agentDid, alias-derived keys) are omitted since you never supply them. A template that cannot be read reports { error } rather than an empty schema, so "needs nothing" is never confused with "could not look it up".`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          templateId: {
+            type: "string",
+            description: 'The MBI credential-definition id (did:zid:...) or a known template name, e.g. "AI Birthcert".'
+          }
+        },
+        required: ["templateId"]
+      }
+    },
     {
       name: "query_contract",
       description: 'Read-only query against a Zetrix contract or account \u2014 call an arbitrary contract method (e.g. "balanceOf", "contractInfo") and return its raw result. No signing, no state change.',
@@ -22853,7 +23025,7 @@ function buildToolList() {
     },
     {
       name: "subscribe_and_issue",
-      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true) \u2014 pass forceReissue:true to pay and issue fresh regardless. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay. Every response (success, dry-run, or a missing-attribute error) also includes { schema: { required, optional } } \u2014 the template's full declared attribute schema read from chain \u2014 so you always see the complete field list, not just what went wrong.",
+      description: "Obtain a VC from MBI: build the signed payload, pay x402, and return the issued credential. If a still-valid credential for this templateId is already cached locally, it is returned directly with no payment (fromCache: true) \u2014 pass forceReissue:true to pay and issue fresh regardless. Payment is asset-agnostic \u2014 MBI's 402 challenge may quote the native ZETRIX token or a ZTP20 token (e.g. JMYR); pass dryRun:true first to see the quoted asset/amount for free before committing to pay. What a call actually cost is reported precisely: paidAsset/amountPaid are set ONLY when this call paid, a cache hit reports the earlier charge under originalPayment instead (never as amountPaid, so summing spend cannot double-count), and any failure after the payment has settled on chain reports paymentAttempted: { asset, amount, paymentId }. Two such failures exist and mean different things: MBI 4006 is a definitive facilitator rejection, while 4012 (HTTP 502) means the outcome is INDETERMINATE \u2014 the payment may well have landed. On 4012 the wallet automatically polls MBI's recovery endpoint and reports recovery: { status, txHash?, vcId?, polls }, where status is ISSUED (the credential exists after all \u2014 fetch it by vcId, since recovery returns no VC body), FAILED, or REQUIRED/SETTLED (still unresolved) / UNKNOWN (recovery itself unreachable). NEVER retry a payment after either failure: the funds may already be gone, and a retry charges the full amount again \u2014 look the paymentId up instead. Every response except a cache hit also includes { schema: { required, optional } } \u2014 the template's full declared attribute schema read from chain \u2014 so you see the complete field list, not just what went wrong; a cache hit skips the chain lookup and omits it.",
       inputSchema: {
         type: "object",
         properties: {
@@ -22952,25 +23124,20 @@ async function main() {
   const sdk = new import_zetrix_sdk_nodejs.default({ host: config2.nodeHost, port: config2.nodePort });
   const contractQuery = (a) => sdk.contract.call(a);
   const resolveSymbol = (asset) => resolveAssetSymbol(asset, contractQuery);
-  const queryTokenBalance = async (token) => {
-    const symbol = token.toUpperCase();
-    if (symbol === "ZTX") {
-      try {
-        const { balance } = await import_x402_zetrix_client2.PaymentEngine.fetchAccountInfo(zetrixAddress, node);
-        return { token: symbol, balance };
-      } catch {
-        return { token: symbol, error: "query_failed" };
-      }
-    }
-    const contractAddress = resolveTokenAddress(symbol, config2.network);
-    if (!contractAddress) return { token: symbol, error: "unknown_token" };
-    try {
-      const { balance } = await import_x402_zetrix_client2.PaymentEngine.fetchZTP20Balance(contractAddress, zetrixAddress, node);
-      return { token: symbol, balance };
-    } catch {
-      return { token: symbol, error: "query_failed" };
-    }
+  const fetchNativeBalance = async (address) => {
+    const res = await sdk.account.getInfo(address);
+    if (res.errorCode !== 0) throw new Error(`getInfo failed with errorCode ${res.errorCode}`);
+    const balance = res.result?.balance;
+    if (typeof balance !== "string") throw new Error("getInfo returned no balance");
+    return balance;
+  };
+  const tokenBalanceDeps = {
+    address: zetrixAddress,
+    fetchNativeBalance,
+    resolveTokenAddress: (symbol) => resolveTokenAddress(symbol, config2.network) ?? null,
+    query: contractQuery
   };
+  const queryTokenBalance2 = (token) => queryTokenBalance(tokenBalanceDeps, token);
   const nodeBaseUrl = `https://${config2.nodeHost}${config2.nodePort ? `:${config2.nodePort}` : ""}`;
   const nodeMetaQuery = (url) => fetch(url, { headers: { Accept: "application/json" } }).then((r) => r.json());
   const resolveTemplateFields = (templateId) => fetchTemplateFields(templateId, config2.templateRegistryAddress, nodeBaseUrl, nodeMetaQuery);
@@ -23031,7 +23198,7 @@ async function main() {
     payer,
     subscribeDeps: { mbi, sign: subscribeSign, pay, resolveSymbol, holderDid, resolveTemplateFields, cache: vcCache },
     queryContract: (input) => queryContract(input, contractQuery),
-    queryTokenBalance,
+    queryTokenBalance: queryTokenBalance2,
     createAccount: (password, label, purpose) => be.createAccount(password, label, purpose),
     saveAccount: (account) => accountStore.set({ ...account, createdAt: (/* @__PURE__ */ new Date()).toISOString() }),
     checkActivationStatus: (address) => be.checkActivationStatus(address),

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "agentic-wallet-mcp",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Agent-facing MCP wallet for Zetrix — orchestrates x401 identity proof, x402 payment, and MBI VC issuance",
-  "keywords": ["mcp", "model-context-protocol", "zetrix", "wallet", "x401", "x402", "blockchain"],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zetrix",
+    "wallet",
+    "x401",
+    "x402",
+    "blockchain"
+  ],
   "license": "MIT",
   "author": "MyEG Services Berhad",
   "homepage": "https://github.com/Zetrix-Chain/zetrix-agentic-wallet",
@@ -23,6 +31,7 @@
   "files": [
     "dist/server-bundle.cjs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {