Skip to content

RELEASE_NOTES.md

Latest commit

 

History

History
281 lines (205 loc) · 19.1 KB

RELEASE_NOTES.md

File metadata and controls

281 lines (205 loc) · 19.1 KB
Raw

v2.1.0 — TRON Official Core and Independent Resource Extension

  • Migrate the payment call chain to official @x402/core@2.28.0 and matching HTTP/MCP integrations.
  • Install resource sponsorship separately and explicitly register both client and facilitator extensions.
  • Remove local EVM and legacy packages; use official @x402/evm@2.28.0 and @x402/extensions@2.28.0 directly.
  • Preserve the 2.0 Agent Wallet 3 transaction artifacts, canonical TRON networks and pending transaction IDs.
  • Reject failed/malformed upto allowance and balance reads with chain_read_failed before settlement broadcast.
  • Apply resolved spend caps to actual batch deposits and GasFree value plus maximum provider fee.
  • Reconcile pending payments against the original transaction or GasFree trace, preserving batch snapshots and preventing duplicate broadcasts. Production recovery uses an injected durable pending store with shared locking.
  • Synchronize pending records across workers and preserve batch claims added while settlement is in flight.
  • Report callback execution failures separately from pending-store failures.
  • Require Node.js 24.22.1 or newer; local development and CI pin 24.22.1.

Release packages: @bankofai/x402-tron@2.1.0, @bankofai/x402-tron-extensions@2.1.0, and the Express, Fastify, Hono, and Next.js adapters at 1.1.2. The two TRON packages must be upgraded together; the resource extension pins the exact mechanism version.

This is a source migration from 2.0. See the migration guide for imports, wallet capabilities, resource runtime registration, limits and pending recovery. Persistent resource coordination and application HTTP delivery/recovery remain deployment responsibilities.

v2.0.0 — Canonical TRON Networks and Pending Settlement

Release date: September 18, 2026

Highlights

Version 2.0.0 makes decimal TRON CAIP-2 identifiers canonical and hardens receipt-backed settlement when a transaction has been broadcast but final on-chain status is not yet known. The release keeps deprecated hexadecimal network aliases as accepted inputs, normalizes them at boundaries, and preserves transaction IDs in non-terminal settlement_pending responses so callers can reconcile without rebroadcasting. Wallet adapters and runnable examples also support the typed transaction artifacts and strict per-network resolution introduced by @bankofai/agent-wallet 3.0.

Upgrade Notes

  • Upgrade @bankofai/x402-tron to 2.0.0, @bankofai/x402-core to 1.1.1, and @bankofai/x402-evm to 1.1.1 together.
  • Upgrade example and application wallet integrations to @bankofai/agent-wallet 3.0 or newer. Use the raw_secret, wallet_cli, or privy providers; the former local_secure password flow is no longer available.
  • Replace configured and persisted hexadecimal TRON network identifiers with tron:728126428 (mainnet), tron:3448148188 (Nile), or tron:2494104990 (Shasta).
  • Hexadecimal aliases remain accepted for migration, but newly emitted values and internal lookups use decimal identifiers.
  • Treat settlement_pending as non-terminal. Preserve its transaction ID and reconcile that transaction rather than resubmitting the authorization.
  • The default HTTP facilitator timeout is now 120 seconds; override timeoutMs only when the deployment has a different confirmation budget.

Reliability Changes

  • TRON receipt confirmation waiting is configurable and defaults to 90 seconds across exact, upto, batch-settlement, and GasFree paths.
  • Confirmed reverts remain terminal failures, while unavailable or indeterminate post-broadcast receipts return settlement_pending with the original transaction ID.
  • GasFree settlement validates relayer transaction IDs and rejects success responses that do not identify a transaction.
  • Settlement reconciliation is single-shot and does not rebroadcast an already submitted payment.
  • EVM and TRON wallet adapters accept agent-wallet 3.0 typed transaction artifacts while retaining compatibility with structural legacy signing results.
  • Runnable examples normalize deprecated hexadecimal TRON network aliases before resolving strict agent-wallet 3.0 wallets, and server-side PAY_TARGETS filtering follows the same matching rules as clients.
  • Legacy main, module, and types package metadata now points to files present in the published tarballs.

Verification

  • pnpm format:check: 17/17 workspace tasks passed.
  • pnpm lint:check: 17/17 workspace tasks passed.
  • pnpm build:release: forced release build passed for all 17 packages.
  • pnpm test: all 34 workspace tasks passed without using the build cache.
  • pnpm -r typecheck in examples/typescript: all 30 runnable example projects passed.
  • pnpm test in examples/typescript: all 4 payment-target configuration tests passed.
  • Core integration tests: 31/31 passed. Credential-backed EVM and TRON on-chain tests remain a pre-publish gate in the release environment.
  • All three npm tarballs contain the expected generated declarations and versions, with no remaining workspace: dependency ranges; the EVM and TRON tarballs depend on @bankofai/x402-core@~1.1.1.

Release Artifacts

  • @bankofai/x402-tron@2.0.0
  • @bankofai/x402-core@1.1.1
  • @bankofai/x402-evm@1.1.1

Implemented in PR #96 and PR #98.

v1.2.0 — TRON Approval Resource Sponsoring

Release date: August 28, 2026

Highlights

Version 1.2.0 adds protocol-level resource sponsoring for the first TRC-20 Permit2 Approval. A Client signs the Approval without broadcasting it; the Facilitator validates the exact transaction intent, temporarily delegates TRON Energy to the payer, broadcasts the Approval, continues settlement after confirmation, and reclaims the delegated resource through a recoverable state machine. The Extension works with TRON exact, upto, and the deposit/top-up path of batch-settlement.

Upgrade Notes

  • Upgrade @bankofai/x402-extensions and @bankofai/x402-tron to 1.2.0 together.
  • Applications using the HTTP server adapters should use @bankofai/x402-express, @bankofai/x402-fastify, @bankofai/x402-hono, or @bankofai/x402-next 1.1.1, which declare the updated Extension dependency.
  • core, evm, mcp, axios, and fetch remain at 1.1.0; they have no API or dependency change in this release.
  • Resource Servers advertise trc20ApprovalResourceSponsoring version 1. Clients attach the signed Approval only when the token-to-Permit2 allowance is insufficient. Facilitators opt in by registering the sponsoring runtime and policy.
  • Production Facilitators should back the operation coordinator with durable storage and run reconciliation at startup and on an interval. The process-local coordinator is intended for tests and development.

Protocol Flow

  1. The Resource Server returns the payment requirements and the resource-sponsoring Extension declaration.
  2. When Permit2 allowance is insufficient, the Client builds and signs a single TRC-20 approve(Permit2, MaxUint256) transaction but does not broadcast it.
  3. The Facilitator strictly decodes the signed protobuf and verifies the network, token, owner, Permit2 spender, approval amount, expiration, fee limit, and absence of additional contracts.
  4. The Facilitator delegates the estimated Energy, broadcasts the validated Approval, waits for confirmation, and allows the normal Permit2 settlement to continue.
  5. Resource reclamation is tracked independently and retried by reconciliation if the process stops or an undelegation attempt fails.

Security and Reliability

  • Resource Owner delegate and undelegate transactions are checked against an explicit signing intent before the wallet signs them.
  • Sponsorship policies bound per-operation resource limits, capacity, concurrency, approval lifetime, and fee limits.
  • The operation state machine records immutable actions and resumes interrupted delegation, approval, and reclamation windows.
  • Settlement success is not converted into payment failure merely because resource reclamation needs a later retry.
  • The Extension sponsors only the Approval transaction; the existing Permit2 payment authorization continues to bind each payment's amount, recipient, nonce, deadline, and scheme-specific context.

Verification

  • pnpm format:check: 17/17 workspace tasks passed.
  • pnpm lint:check: 17/17 workspace tasks passed.
  • pnpm test: 34/34 workspace tasks passed, including 532 Extension tests and 247 TRON tests.
  • pnpm build:release: forced release build passed for all 17 packages.
  • All six release tarballs were inspected for generated CJS/ESM declarations, expected versions, and published dependency rewriting with no remaining workspace: ranges.

Release Artifacts

  • @bankofai/x402-extensions@1.2.0
  • @bankofai/x402-tron@1.2.0
  • @bankofai/x402-express@1.1.1
  • @bankofai/x402-fastify@1.1.1
  • @bankofai/x402-hono@1.1.1
  • @bankofai/x402-next@1.1.1

Implemented by @boboliu-1010 in PR #84.

v1.1.0 — Payment Flow and Wallet Compatibility

Release date: August 25, 2026

Highlights

Version 1.1.0 aligns all 11 public TypeScript packages and brings the BankofAI SDK up to date with the latest upstream TypeScript payment orchestration work. It adds explicit authorization, upfront, and escrow payment flows; safer client payment policies; broader EVM wallet support; more precise EVM and TRON settlement handling; and hardened HTTP and MCP integrations.

Upgrade Notes

  • Upgrade the complete @bankofai/x402-* package set together to 1.1.0; internal package dependencies use the ~1.1.0 release line.
  • Custom money parsers now receive a decimal string rather than a JavaScript number. Use Number(amount) only for threshold comparisons; pass the string directly to token conversion helpers to preserve precision.
  • TRON integrations should use canonical CAIP-2 identifiers: tron:0xcd8690dc (Nile), tron:0x94a9059e (Shasta), and tron:0x2b6653dc (mainnet).
  • Facilitators enabling ERC-6492 deployment must configure eip6492AllowedFactories; an omitted or empty allowlist rejects counterfactual factory calls.
  • The hosted/self-hosted x402-facilitator remains wire-compatible with v2 client and server flows. Upgrade its @bankofai/x402-* dependencies to 1.1.0 after publishing this release so runtime behavior and type declarations stay aligned.

Changes

  • Payment-flow orchestration: server schemes can declare supported flows per asset-transfer method. Core consistently schedules verification and settlement before or after the resource handler for authorization, upfront, and escrow flows.
  • Backward-compatible custom schemes: v1.0 SchemeNetworkServer implementations may omit defaultAssetTransferMethod and paymentFlows; core treats them as legacy authorization flows.
  • Client safety controls: clients gain payment-selection policies, spend caps, transaction limits, and lifecycle hooks for observing and rejecting payment creation.
  • Facilitator reliability: HTTPFacilitatorClient validates responses, normalizes nullable cross-SDK fields, retries rate-limited /supported requests, surfaces typed timeout errors, and now defaults to a 90-second request timeout for receipt-backed settlement.
  • EVM wallet compatibility: verification and settlement support EOAs, deployed smart accounts, ERC-7702 delegation, and allowlisted ERC-6492 counterfactual deployment. Receipt validation confirms the expected transfer instead of trusting transaction status alone.
  • EVM assets and settlement: BSC default assets are restored, Permit2 handling is tightened, and settlement responses distinguish pending receipts from confirmed failures.
  • TRON precision and token selection: decimal prices retain their original string precision, token-symbol prices select the requested asset, and default asset conversion is consistent across exact, upto, and batch settlement.
  • Extensions: builder-code supports multiple service codes, SIWX validation and hooks are expanded, and dynamic extension fields such as nonces and timestamps no longer cause false echo mismatches.
  • HTTP middleware hardening: Express, Fastify, Hono, and Next.js normalize encoded paths and line terminators consistently so alternate path encodings cannot bypass protected routes.
  • MCP interoperability: MCP clients accept optional wire fields encoded as either null or omitted and preserve existing response metadata while adding payment metadata.

Verification

  • pnpm build:release
  • pnpm test (34 workspace tasks)
  • pnpm lint:check
  • pnpm format:check
  • npm package tarballs inspected to confirm versions and rewritten internal dependency ranges

Release Artifacts

  • @bankofai/x402-core@1.1.0
  • @bankofai/x402-extensions@1.1.0
  • @bankofai/x402-mcp@1.1.0
  • @bankofai/x402-evm@1.1.0
  • @bankofai/x402-tron@1.1.0
  • @bankofai/x402-axios@1.1.0
  • @bankofai/x402-express@1.1.0
  • @bankofai/x402-fastify@1.1.0
  • @bankofai/x402-fetch@1.1.0
  • @bankofai/x402-hono@1.1.0
  • @bankofai/x402-next@1.1.0

Credits

Release integration and BankofAI compatibility work by @roger-gan in PR #83, building on the upstream x402 Foundation TypeScript SDK.

v1.0.0 — TypeScript-Only SDK

Release date: July 2, 2026

Highlights

The 1.0.0 release is a ground-up rewrite to a TypeScript-only pnpm/turbo monorepo. At release time, the previous-generation Python + TypeScript SDK moved to a root legacy/ archive, which has since been removed. core and the EVM mechanism are forks of the x402-foundation/x402 upstream; the TRON mechanism is in-house. Supported schemes: exact (ERC-3009 / Permit2), upto, batch-settlement, auth-capture (EVM), and exact_gasfree (TRON).

Changes

  • Monorepo restructure: TypeScript-only SDK published as granular @bankofai/x402-* packages (core, evm, tron, fetch, express, mcp, extensions). The Python SDK and old TS SDK were archived under root legacy/ for this release and removed later.
  • BSC USDT support: express server exact example now advertises BSC testnet USDT (0x337610d2…, 18 dec, permit2) alongside DHLU and USDC. Mainnet USDT is registered in the default-asset registry (eip155:56, permit2).
  • Token symbol resolution: fetch client TOKEN_ADDRESSES now indexes by chain family so the same symbol (e.g. USDT) resolves to the correct contract per network (BSC testnet vs TRON Nile).
  • TRON settle receipt accuracy: facilitator transaction polling switched from trx.getTransaction (fullNode preconfirm, which could transiently read REVERT on mainnet and cause false settle failures) to the fullNode gettransactioninfobyid endpoint, waiting for blockNumber + receipt.result. ~3-6s latency with authoritative results — mirrors tronpy's get_transaction_info.
  • Documentation: README aligned with the TypeScript-only SDK; .env-exact.example updated to list USDT among EVM token options.

Verification

  • BSC testnet USDT exact payment end-to-end: settle tx 0x477f00845964271d53cc36028756fa4ce260674ff6b103e6a86a47f2e79a9edd (SUCCESS).
  • TRON mainnet USDT exact payment on-chain success confirmed (tx 604f51c8…0acc, contractRet: SUCCESS); receipt polling fix verified against this tx.

Release Artifacts

  • npm packages: @bankofai/x402-core@1.0.0, @bankofai/x402-evm@1.0.0, @bankofai/x402-tron@1.0.0, @bankofai/x402-fetch@1.0.0, @bankofai/x402-express@1.0.0, @bankofai/x402-mcp@1.0.0, @bankofai/x402-extensions@1.0.0.

Compatibility

  • TypeScript-only; Node.js >= 20, pnpm >= 11.
  • The Python SDK is no longer published from main; its temporary root legacy/ archive has since been removed.

v0.6.1 — TRON exact_permit Wallet CLI Fix

Release date: June 24, 2026

Changes

  • Python TRON facilitator signer: restored wallet CLI / agent-wallet transaction signing for contract writes while keeping active permission support through TRON_PERMISSION_ID (default 2).
  • exact_permit settlement: facilitator settlement no longer requires TRON_FACILITATOR_PRIVATE_KEY / TRON_PRIVATE_KEY when the active wallet is already available through wallet CLI.
  • Version alignment: Python package metadata, runtime bankofai.x402.__version__, and TypeScript package metadata are aligned to 0.6.1.

Verification

  • Python signer regression tests passed for TRON facilitator contract writes and existing client signer wallet payload behavior.

v0.6.0 — TypeScript / Python Facilitator Parity

Release date: May 13, 2026

Highlights

This release completes the 0.6.0 TypeScript parity work against the Python SDK. TypeScript now has the facilitator client, facilitator engine, server middleware, fetch wrapper, signer-injected facilitator mechanisms, and verify/settle support for exact, exact_permit, and exact_gasfree.

Changes

  • Facilitator client (TS): remote facilitator calls for /supported, /fee/quote, /verify, and /settle.
  • Facilitator engine (TS): mechanism routing by (network, scheme) with normalized settlement responses.
  • Server middleware (TS): Hono and Express adapters backed by a shared framework-neutral request processor.
  • Fetch wrapper (TS): full HTTP verb support, injectable fetch, policy selection, and X-PAYMENT-RESPONSE parsing.
  • Facilitator signers (TS): FacilitatorSigner, EvmFacilitatorSigner, and TronFacilitatorSigner verify typed data, write contracts, check balances, and poll receipts.
  • exact facilitator (TS): verifies ERC-3009/TIP-712 transfer authorizations and settles with transferWithAuthorization.
  • exact_permit facilitator (TS): verifies PaymentPermit signatures and settles with PaymentPermit.permitTransferFrom.
  • exact_gasfree facilitator (TS): verifies GasFree TIP-712 permits, submits through the GasFree API proxy, and returns the resulting TRON transaction hash.
  • Public exports: facilitator client, engine, middleware, fetch wrapper, signer APIs, protocol constants, and updated mechanism constructors are exported from the TypeScript SDK.
  • Python release alignment: Python package metadata is aligned to 0.6.0.

Verification

  • TypeScript build passed.
  • TypeScript test suite passed: 19 files / 158 tests.
  • npm release tarball inspected before final release prep: ExactGasFreeFacilitatorMechanism(signer, options) and ExactEvmFacilitatorMechanism(signer, options?) are present in the declarations.
  • x402-demo TypeScript smoke passed against the 0.6.0 release candidate.
  • TRON Nile on-chain smoke transactions:
    • exact_gasfree: 97ec5443edaf4bbe8633ee8fc0dc923c4809df4f95625718d1f33e499cf2313d
    • exact_permit: ae91d7e02fea6855f22ffcb945dbf280ff526f72ef156f997e22d4cc8c053e80

Release Artifacts

  • npm package version prepared: @bankofai/x402@0.6.0
  • Python package version prepared: bankofai-x402==0.6.0

Compatibility

  • TypeScript facilitator mechanisms now require a facilitator signer instance.
  • Hono and Express are optional peer deps. Apps that don't import the framework adapters do not need to install them.
  • Minimum Node.js 20 (unchanged from 0.5.9). Python 3.11+.