pull in latest upstream

.agents/skills/authoring-specs/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: authoring-specs
+description: Guidelines for authoring x402 specification files. Use when writing or proposing a new x402 spec, such as a per-network scheme spec (scheme_<name>_<chain>.md).
+---
+
+# Authoring x402 specs
+
+Guidance for writing x402 specification files under `specs/`. Use RFC-2119 keywords for normative statements (MUST / MUST NOT, SHOULD / SHOULD NOT, MAY).
+
+## General rules
+
+These apply to every spec type (scheme, extension). The references below add type-specific detail.
+
+### Naming
+
+- Name schemes and extensions in lowercase, hyphen-separated kebab-case (e.g. `batch-settlement`, `offer-receipt`), never camelCase.
+
+### Protocol version, networks, and units
+
+- Target protocol v2 only: `x402Version: 2`, the `amount` field (not v1's `maxAmount`), and the `PAYMENT-REQUIRED` / `PAYMENT-SIGNATURE` / `PAYMENT-RESPONSE` headers (not v1's `X-PAYMENT` / `X-PAYMENT-RESPONSE`). See the [v1 to v2 migration guide](../../../docs/guides/migration-v1-to-v2.mdx).
+- Use canonical CAIP-2 network notation (e.g. `eip155:84532`, not `base-sepolia`).
+- Use atomic units for all amounts.
+
+### Wire format
+
+- Be transport agnostic: specify message contents, not how a particular transport carries them.
+- Reference core types (`PaymentRequirements`, `PaymentPayload`, `SettlementResponse`) from [`x402-specification-v2.md`](../../../specs/x402-specification-v2.md).
+- Every field a spec defines on the wire must be consumed by a downstream role. Do not include human-readable or otherwise purely informational fields.
+- Reuse field names, patterns, and conventions established by existing specs instead of coining new ones.
+
+## References
+
+- New network scheme spec (`scheme_<name>_<chain>.md`): see [references/new-network-scheme-spec.md](references/new-network-scheme-spec.md).
+- New extension spec: to be added.

.agents/skills/authoring-specs/references/new-network-scheme-spec.md

@@ -0,0 +1,45 @@
+# New network scheme spec
+
+Checklist for authoring a new per-network scheme spec file (`scheme_<name>_<chain>.md`). Follow the [general spec rules](../SKILL.md) as well.
+
+## Spec contents
+
+- Scheme-specific information (e.g. in `PaymentRequired`) goes in `extra`, not in `extensions` or at the top level.
+- Define any scheme-specific `extra` fields (optional/required, with description), and show them in `PaymentRequired`, `PaymentPayload`, and `SettlementResponse` messages or `supported/` examples.
+- Every field placed in `PaymentRequired.extra` must be consumed by the client to construct the payment or by the facilitator to verify or settle it; do not include human-readable or otherwise purely informational fields.
+
+## Compliance and conventions
+
+- Comply with the network-agnostic scheme definition (e.g. `scheme_exact_<network>.md` complies with [`scheme_exact.md`](../../../../specs/schemes/exact/scheme_exact.md)).
+- Reuse field names already established by existing schemes instead of coining new ones. For example, when the scheme must name the account that sponsors network fees (typically the facilitator), use `extra.feePayer` as in [`scheme_exact_svm.md`](../../../../specs/schemes/exact/scheme_exact_svm.md); when the scheme offers more than one payload format, use `extra.assetTransferMethod` to select among them as in [`scheme_exact_evm.md`](../../../../specs/schemes/exact/scheme_exact_evm.md).
+
+## Fee sponsorship and infrastructure
+
+- Fee sponsorship is strongly preferred; clients and servers should not need to pay gas or hold the native token.
+- The server should not need an RPC; the client may use an RPC; a facilitator RPC can be considered a given.
+
+## Statelessness
+
+- Stateless design is strongly preferred for client and server, and especially the facilitator. A short-lived cache is acceptable but needs to be well justified (see the duplicate-settlement mitigation in [`scheme_exact_svm.md`](../../../../specs/schemes/exact/scheme_exact_svm.md#duplicate-settlement-mitigation-recommended)). Persistent storage warrants discussion with maintainers.
+
+## Nonces
+
+- Sequential nonces are strongly discouraged. They effectively lock the client account until the server route handler completes and the transaction settles, which may take several minutes (bounded only by `maxTimeoutSeconds`, on which the protocol enforces no upper limit). If the client submits another transaction from that account between verification and settlement, the nonce is consumed, settlement fails, and the work the server already performed is wasted.
+
+## Verification and settlement
+
+- Do not introduce new facilitator endpoints beyond `verify/`, `settle/`, and `supported/`. A scheme must express all facilitator interactions through these existing endpoints.
+- Use transaction simulation, not only structural payload checks, to confirm the transaction would actually succeed onchain. If that is not possible, at least targeted checks of onchain state MUST be done (e.g. sufficient client token balance, nonce unconsumed).
+- Verify should provide the strongest possible guarantee that settlement will succeed. If settle fails, the client does NOT get access to the resource; but if verify succeeded, the server did unnecessary work, wasting resources (compute). This is a server protection.
+- The facilitator must confirm transaction success onchain before returning success to the server.
+- The facilitator must protect its own funds and bound its fee exposure. Its signature must authorize only the network fee: the facilitator must not appear as the authority, source, or sender of any value-moving instruction (fee-payer isolation), so it cannot be induced to transfer its own funds. It must also cap the fees it pays against client-controlled parameters (e.g. explicit gas limits, compute-unit and priority-fee caps), so a client cannot inflate them.
+
+## Trust model
+
+- The client must treat all server-provided fields as untrusted and must not rely on a server value for anything it can determine authoritatively itself. For example, if a scheme placed token `decimals` in `extra` and the client trusted it, a misconfigured or malicious server could report a wrong value, causing the client to compute too large an atomic `amount` and overpay; the client must instead read `decimals` (and similar token metadata) from onchain state.
+- The server and facilitator must consider the client payload untrusted.
+- The client should never interact with the facilitator directly, always via the server as proxy.
+
+## Account requirements
+
+- Enumerate every account precondition that must hold before a payment can be verified and settled, naming the responsible role (client, server, or facilitator). Examples: a minimum native balance for rent or fees, an asset trustline or token association / opt-in, and account or associated-token-account creation.

.agents/skills/contributing/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: contributing
+description: Guidelines and conventions for contributing to the x402 codebase. Use when preparing a PR to the upstream x402-foundation/x402 repository such as fixing a bug or Issue, implementing a new feature, adding a mechanism/scheme or extension.
+---
+
+# Contributing to x402
+
+## Reuse before writing new code
+
+- Before writing anything, check in order whether the standard library (TS: ECMAScript and Node.js built-ins like `node:crypto`; Python: the stdlib; Go: packages like `net/http`, `encoding/json`, `crypto`), a native platform feature, or an already-installed dependency already does it; if so, use it.
+- Always reuse shared and core utilities.
+- No new dependencies if it can be avoided.
+
+## Keep changes minimal
+
+- Address a single issue per contribution, not multiple.
+- Targeted edits, minimal diff, atomic commits.
+- No abstractions or boilerplate that were not explicitly requested.
+- No edits to legacy/v1 code; it is effectively frozen (security patches only). This includes the paths `typescript/packages/legacy/`, `go/legacy`, `python/legacy` and the `java/` SDK.
+
+## Code style
+
+- Write clean, readable code (e.g. prefer guard clauses over nested conditionals, use descriptive names and small, single-purpose functions).
+- Strong typing, avoid any weak types (`any`, `unknown`, and their equivalents in other languages). Research the codebase to find the correct type, reuse existing type definitions rather than redeclaring them and confirm no type errors remain.
+- No overly defensive code or silent fallbacks.
+- Apply DRY only where it reduces complexity; keep single-use logic inline rather than extracting a helper for it.
+
+## Comments
+
+- Write comments that help a new reader understand the codebase.
+- Never narrate in-progress work or describe code being replaced.
+- Write onchain - never "on-chain" or "on chain".
+- Don't change/remove existing comments, unless strictly needed due to code changes.
+
+## AI-assisted contributions
+
+Follow the repository AI-assisted contribution policy in [CONTRIBUTING.md](../../CONTRIBUTING.md#ai-assisted-contributions). Review all AI-generated output before requesting maintainer review.
+
+## Working on an Issue
+
+- Independently reproduce and verify the Issue first.
+- When in doubt, ask clarifying questions on the Issue before writing code.
+
+## Bug fixes
+
+- Add a test that fails before the fix and passes after it.
+- Don't write tests for what the type system already guarantees.
+- Cover edge cases, not only happy path.
+
+## Commits and PRs
+
+- Verifying (signing) ALL commits is strictly required; maintainers will not check a PR otherwise. See [GitHub: about commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
+- PR description: short and matching the diff; explain what and why; link relevant issues; state the root cause in one paragraph, citing file and line.
+- Justify design decisions where there were ambiguities and discuss the tradeoffs of the approach you picked against the alternatives you considered.
+
+## Per-language
+
+### Per commit: format, lint, build, test
+
+Format, lint, build, and run unit tests before each commit.
+
+```bash
+# TypeScript (from typescript/)
+pnpm format && pnpm lint && pnpm build && pnpm test
+
+# Go (from go/)
+make fmt && make lint && make build && make test
+
+# Python (from python/x402/)
+uvx ruff format && uvx ruff check && uv run pytest
+```
+
+### Per PR: changelog
+
+Add a changelog fragment for the SDK you changed.
+
+```bash
+# TypeScript (from typescript/)
+pnpm changeset
+
+# Go (from go/)
+make changelog-new
+
+# Python (from python/x402/)
+uv run towncrier create --content "Fixed ..." <PR>.bugfix.md
+```
+
+## New mechanism or extension
+
+- New payment mechanism / scheme: see [references/new-mechanism.md](references/new-mechanism.md).
+- New extension: see [references/new-extension.md](references/new-extension.md).

.agents/skills/contributing/references/new-extension.md

@@ -0,0 +1,61 @@
+# New extension implementation
+
+Checklist for adding a new extension. Follow the [general contributing rules](../SKILL.md) as well.
+
+## Spec first
+
+- A spec file must exist. If it does not, write it first.
+- The spec must be approved by maintainers (merged into upstream `main`). If it is not, open a PR with the spec only first (`specs/extensions/...`).
+- The implementation must follow the spec file exactly.
+- The wire formats `PAYMENT-REQUIRED` (in particular the extension field), `PAYMENT-RESPONSE` and facilitator `supported/` output must match the spec strictly. Include only fields actually consumed downstream or required by the extension. Don't add purely informational fields.
+- Spec amendments and edits are allowed, but must be well justified.
+
+## Scope
+
+- One language per PR. Never implement the extension in more than one SDK (TS, Python, Go) in a single PR.
+- Implement v2 only. Common v1 tells (see the [V1→V2 migration guide](../../../../docs/guides/migration-v1-to-v2.mdx)): `maxAmount` in payment requirements, `X-PAYMENT`/`X-PAYMENT-RESPONSE` headers (v2 uses `PAYMENT-SIGNATURE`/`PAYMENT-RESPONSE`), string network names like `base-sepolia` (v2 uses CAIP-2 like `eip155:84532`) or `x402Version: 1`.
+
+## Code patterns
+
+- Wire extensions with lifecycle hooks via the extension-hooks adapter pattern.
+- Reuse core and extension utilities instead of reimplementing them.
+- Do NOT modify other packages (core, http, ...). If this is deemed necessary, discuss with maintainers first.
+
+## Tests
+
+### Unit tests
+
+- Pure-logic tests that run offline. Add them under **TS** `typescript/packages/extensions/test/`; **Go** `go/extensions/<extension>/`; or **Py** `python/x402/tests/unit/extensions/<extension>/`. Run them and confirm all pass.
+- New additions must have **>80%** line coverage.
+
+```bash
+# from typescript/
+pnpm --filter @x402/extensions test
+# go/
+make test
+# python/x402/
+uv run pytest tests/unit/extensions/
+```
+
+### Integration tests
+
+- In-process client/server/facilitator flow tests within the SDK. Requires funded testnet accounts.
+- Add them under **TS** `typescript/packages/extensions/test/integrations/`; **Go** `go/extensions/<extension>/`; or **Py** `python/x402/tests/integrations/`. Suites skip when required env vars are missing.
+- Run them and confirm all pass.
+
+```bash
+# from typescript/
+pnpm --filter @x402/extensions test:integration
+# go/
+make test-integration
+# python/x402/
+uv run pytest tests/integrations/
+```
+
+## Examples
+
+Add server, client, and facilitator examples (as appropriate). Manually confirm a successful payment by running facilitator server and client examples locally.
+
+## Docs
+
+- Add READMEs for the SDK and all examples.

.agents/skills/contributing/references/new-mechanism.md

@@ -0,0 +1,86 @@
+# New mechanism implementation
+
+Checklist for adding a new payment mechanism / scheme. Follow the [general contributing rules](../SKILL.md) as well.
+
+## Spec first
+
+- A spec file must exist. If it does not, write it first.
+- The spec must be approved by maintainers (merged into upstream `main`). If it is not, open a PR with the spec only first (`specs/schemes/...`).
+- The implementation must follow the spec file exactly. Facilitator verification rules are security-critical. 
+- The wire formats `PAYMENT-REQUIRED` (in particular the `extra` field), `PAYMENT-RESPONSE` and facilitator `supported/` output must match the spec strictly. Include only fields actually consumed downstream or required by the scheme. Don't add purely informational fields.
+- Spec amendments and edits are allowed, but must be well justified.
+
+## Scope
+
+- One language per PR. Never implement the mechanism in more than one SDK (TypeScript, Python, Go) in a single PR.
+- If a reference implementation already exists in another SDK, cross-check against it; otherwise yours is the reference and the spec is the only source of truth.
+- Implement v2 only. Common v1 tells (see the [V1→V2 migration guide](../../../../docs/guides/migration-v1-to-v2.mdx)): `maxAmount` in payment requirements, `X-PAYMENT`/`X-PAYMENT-RESPONSE` headers (v2 uses `PAYMENT-SIGNATURE`/`PAYMENT-RESPONSE`), string network names like `base-sepolia` (v2 uses CAIP-2 like `eip155:84532`) or `x402Version: 1`.
+
+## Code patterns
+
+- Wire schemes with the builder pattern, not `register*` helpers. A new v2-only mechanism registers its scheme under the family wildcard: `client.register("<family>:*", new Exact<Chain>Scheme(...))` (and the same on `x402ResourceServer`). Do NOT implement a `registerExact<Chain>Scheme` helper. Those exist only in the EVM/SVM mechanisms to also register the legacy v1 schemes for backward compat.
+- Reuse core utilities instead of reimplementing them. For example, import `convertToTokenAmount`, `numberToDecimalString`, and `parseMoney` from `@x402/core/utils` for TS or similar for Go/python SDKs.
+- If the mechanism supports `$` string pricing, add `defaultAssets.ts` / `default_assets.go` / `default_assets.py` with `DEFAULT_ASSETS`, `getDefaultAsset`/`GetDefaultAsset`/`get_default_asset`, and `findDefaultAsset`/`FindDefaultAsset`/`find_default_asset` (see [DEFAULT_ASSETS.md](../../../../DEFAULT_ASSETS.md)). Expose the reverse lookup on the client scheme so `@x402/core` spend controls recognize USD-pegged defaults. Chains without a canonical USD stablecoin may omit the file and require explicit `AssetAmount` pricing instead. Do not put default assets in `constants` or bundled network-config maps.
+- Do NOT modify other packages (core, http, ...). If this is deemed necessary, discuss with maintainers first.
+
+## Tests
+
+### Unit tests
+
+- Pure-logic tests that run offline with no live RPC or network calls. Add them with comparable coverage to the EVM reference under **TS** `typescript/packages/mechanisms/<chain>/test/unit/`; **Go** `go/mechanisms/<chain>/` or **Py** `python/x402/tests/unit/mechanisms/<chain>/`. Run them and confirm all pass.
+- New additions must have **>80%** line coverage.
+
+```bash
+# typescript/
+pnpm --filter @x402/<chain> test
+# go/
+make test
+# python/x402/
+uv run pytest
+```
+
+### Integration tests
+
+- In-process client/server/facilitator flow tests within the SDK that exercise real RPC endpoints and may submit onchain transactions. Requires funded testnet accounts. 
+- Add them with comparable coverage to the EVM reference under **TS** `typescript/packages/mechanisms/<chain>/test/integrations/` (see `exact-evm.test.ts`); **Go** `go/test/integration/`; **Py** `python/x402/tests/integrations/`. Suites skip when required env vars are missing. 
+- Run them and confirm all pass.
+
+```bash
+# typescript/
+pnpm --filter @x402/<chain> test:integration
+# go/
+make test-integration
+# python/x402/
+uv run pytest tests/integrations/
+```
+
+### E2E tests
+
+- The `e2e/` harness runs client × server × facilitator combinations from the mechanisms catalog. Requires funded testnet accounts.
+- Add `e2e/config/mechanisms_<id>.json` (`env`, `testnet`/`mainnet`, `routes` with `sdks`). Do **not** edit per-framework route lists or CAIP-2 pattern tables — HTTP/MCP endpoints are derived from the catalog.
+- Register the scheme once per language in the shared modules only: `e2e/servers/<lang>/`, `e2e/clients/<lang>/`, `e2e/facilitators/<lang>/`.
+- Add wallet/payee placeholders to `e2e/.env-local`.
+- Run them and confirm all pass.
+
+```bash
+# from e2e/
+pnpm install:all && pnpm test --testnet --min --families=<chain> --versions=2
+```
+
+## Examples
+
+- Add network to server, client and facilitator examples under `examples/<sdk>/*/advanced/all_networks`. 
+- Manually confirm a successful payment by running facilitator, server and client examples locally.
+
+## Docs
+
+- Add READMEs for the SDK and all examples.
+- Include link to a testnet faucet and detail all necessecary setup steps (e.g. token association/opt-ins or minimum balance requirements).
+
+## Publishing scripts
+
+Mirror the EVM setup per SDK:
+
+- **TS**: Add `publish_npm_scoped_x402_<chain>.yml` workflow and add package to `publish_npm_scoped_x402_all.yml`.
+- **Py**: Add an optional extra in `python/x402/pyproject.toml`; uses existing `publish_pypi_x402.yml`.
+- **Go**: no new workflow required; ships with the `go/` module.

.gitbook.yaml

@@ -0,0 +1,5 @@
+root: ./docs/
+
+structure:
+  readme: README.md
+  summary: SUMMARY.md