pull in latest upstream

.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,60 @@
+# 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.
+
+```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,83 @@
+# 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 `parseMoneyString` from `@x402/core/utils` for TS or similar for Go/python SDKs.
+- 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 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.
+
+```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 every client × server × facilitator combination. Requires funded testnet accounts.
+- Register the network signer in the facilitator and all client frameworks. 
+- Add protected routes for all server frameworks. 
+- 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