BofAI · roger-gan · Aug 28, 2026 · Aug 28, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -10,6 +10,7 @@ See here for instructions: https://docs.github.com/en/authentication/managing-co
 
 <!--
 Please provide a clear and concise description of what the changes are, and why they are needed.
+The completed Description section must contain at least 20 characters.
 Include a link to the issue this PR addresses, if applicable (e.g. "Closes #123").
 -->
 
@@ -20,16 +21,20 @@ Please describe the tests you've performed to verify your changes.
 Include relevant code samples, unit test cases, or screenshots if applicable.
 
 For TypeScript: Run `pnpm test` from the `/typescript` directory
-For Python: Run `uv run pytest` from the `/python/x402` directory
 -->
 
+## Branch route
+
+- [ ] Normal development targets `develop`
+- [ ] Only `release_*` or `hotfix/*` targets `main`
+
 ## Checklist
 
 - [ ] I have formatted and linted my code
 - [ ] All new and existing tests pass
+- [ ] I added a Changeset for publishable package changes, or this PR does not require one
 - [ ] My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits
 
 <!--
 For TypeScript: Run `pnpm lint` from `/typescript`
-For Python: Run `uvx ruff check && uvx ruff format --check` from `/python/x402`
 -->
diff --git a/.github/workflows/audit-pr.yml b/.github/workflows/audit-pr.yml
@@ -3,6 +3,7 @@ name: Audit PR
 on:
   pull_request:
     branches:
+      - develop
       - main
     types: [opened, synchronize, reopened, ready_for_review]
   issue_comment:

diff --git a/.github/workflows/branch-policy.yml b/.github/workflows/branch-policy.yml
@@ -0,0 +1,21 @@
+name: Validate branch policy
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, edited]
+
+permissions:
+  contents: read
+
+jobs:
+  source-and-target:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+      - name: Validate pull request route
+        run: sh scripts/check_branch_policy.sh "${{ github.base_ref }}" "${{ github.head_ref }}"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,51 @@
+name: TypeScript CI
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: typescript-ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  typescript-quality:
+    name: TypeScript quality
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: typescript
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11.1.1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: typescript/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm format:check
+
+      - name: Check lint
+        run: pnpm lint:check
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run unit tests
+        run: pnpm test
diff --git a/.github/workflows/pr-metadata.yml b/.github/workflows/pr-metadata.yml
@@ -0,0 +1,25 @@
+name: Validate PR metadata
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  pr-metadata:
+    name: PR metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+      - name: Validate title and description
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: node scripts/check_pr_metadata.mjs
diff --git a/BRANCHING.md b/BRANCHING.md
@@ -0,0 +1,61 @@
+# Branching and Release Policy
+
+This repository uses a two-branch development model based on java-tron's release workflow.
+
+## Long-lived branches
+
+- `develop` is the default development and integration branch. Start normal work from `develop`
+  and merge it back through a pull request.
+- `main` contains stable, released code. Do not send feature, fix, documentation, or upstream-sync
+  pull requests directly to `main`.
+
+Both branches are protected. Direct pushes, force pushes, and branch deletion are prohibited.
+
+## Development branches
+
+Create day-to-day branches from `develop`. Supported prefixes are:
+
+- `feature/*` or `feat/*` for features
+- `fix/*` for non-release fixes
+- `docs/*`, `chore/*`, `refactor/*`, `test/*`, `perf/*`, or `ci/*` for their corresponding work
+- `sync/*` for upstream synchronization
+
+Open these pull requests against `develop`.
+
+## Release branches
+
+When `develop` is ready for release:
+
+1. Create `release_vX.Y.Z` from `develop`.
+2. Apply version changes, consume Changesets, update release notes, and complete regression testing
+   on the release branch.
+3. If regression identifies a bug, merge its fix directly into the release branch and repeat the
+   regression test.
+4. Open `release_vX.Y.Z` into `main` and merge it with a merge commit.
+5. Tag and publish from the resulting `main` commit.
+6. Merge the release branch back into `develop` after the release passes regression.
+7. Retain the release branch permanently as the release snapshot.
+
+Release branches must use the `release_*` pattern. Never open `develop` directly into `main`.
+
+## Hotfix branches
+
+For an urgent production fix:
+
+1. Create `hotfix/<description>` from `main`.
+2. Open it into `main`, complete review and CI, and merge it with a merge commit.
+3. Merge the same hotfix branch into `develop`.
+
+Retain the hotfix branch until both merges are complete.
+
+## Allowed pull request routes
+
+| Source | Target | Purpose |
+| --- | --- | --- |
+| Development branch | `develop` | Normal development |
+| `release_*` | `main` | Stable release |
+| `release_*` | `develop` | Mandatory release back-merge |
+| `hotfix/*` | `main` | Production hotfix |
+| `hotfix/*` | `develop` | Hotfix back-merge |
+
+The `source-and-target` workflow enforces these routes.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- Adopted `develop` as the integration branch and retained `main` for stable releases.
+- Added enforced pull request routes for development, release, and hotfix branches.
+- Added automated pull request title and description validation.
+- Added pull request CI for formatting, linting, build, and unit tests.
+
+### Removed
+
+- Removed the root `legacy/` archive containing the retired Python SDK, old TypeScript SDK, and
+  superseded examples and specifications. The compatibility npm packages under
+  `typescript/packages/legacy/` remain supported by the current workspace.
+
 ## [1.1.0] - 2026-08-25
 
 ### Upgrade notes

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,32 +6,31 @@ This file tells Claude Code how to work in this repository.
 
 x402 is an open-source SDK for the **x402 open payment standard** — an HTTP `402 Payment Required` challenge-response protocol for serverless on-chain payments. Three roles participate: **Client** (payer), **Server** (resource provider), **Facilitator** (on-chain settlement).
 
-This repository hosts the BankofAI SDK (Python + TypeScript), the reference facilitator bindings, on-chain mechanisms for TRON and EVM, and the protocol specs.
+This repository hosts the TypeScript BankofAI SDK, reference facilitator bindings, on-chain
+mechanisms for TRON and EVM, runnable examples, and the protocol specs.
 
 ## Components
 
-Each component has its own `CLAUDE.md` (where present) with build/test commands and conventions.
-
-> The `legacy/` tree holds the previous-generation SDK (Python + old TypeScript + e2e), kept only as reference and **slated for removal**. New work lives in `typescript/` and `examples/`.
+Each component has its own guidance with build/test commands and conventions where needed.
 
 | Path | Language | Purpose |
 |---|---|---|
-| [legacy/python/x402/](legacy/python/x402/) | Python | SDK: client, server (FastAPI/Flask), facilitator, mechanisms (EVM + TRON). |
-| [legacy/typescript/](legacy/typescript/) | TypeScript | SDK: fetch client, server middleware, facilitator, mechanisms (EVM + TRON). |
-| [legacy/specs/](legacy/specs/) | Markdown | Protocol specs (`protocol.md`, `roles.md`, `config.md`, `schemes/*.md`) + in-flight feature specs (`NNN-<slug>/`). Read **first** when touching wire formats. Mirrors upstream `x402-foundation/x402/specs/` layout. |
+| [typescript/](typescript/) | TypeScript | Current SDK monorepo: core, EVM/TRON mechanisms, extensions, HTTP adapters, and MCP. |
+| [specs/](specs/) | Markdown | Normative v2 protocol, transport, scheme, and extension specifications. Read **first** when touching wire formats. |
+| [examples/typescript/](examples/typescript/) | TypeScript | Runnable client, server, facilitator, logging, and MCP examples. |
 | [docs/solutions.md](docs/solutions.md) | Markdown | Hard-won debugging knowledge. **Read before investigating bugs in related areas.** |
-| [legacy/examples/](legacy/examples/) | Mixed | Smoke tests and integration examples. |
-| [legacy/integration/](legacy/integration/) | Python | Generic step runner used by `legacy/e2e/scenarios/`. |
-| [legacy/e2e/](legacy/e2e/) | Python | End-to-end scenarios (mock facilitator + resource server + client). See [legacy/e2e/README.md](legacy/e2e/README.md). Wired into CI via `check_e2e.yml`. |
-| [tron-contribution/](tron-contribution/) | Markdown | Upstream contribution planning for `x402-foundation/x402`. |
 
 ## Key reading order (new contributor)
 
-1. [legacy/specs/protocol.md](legacy/specs/protocol.md) — wire format, headers, encoding
-2. [legacy/specs/roles.md](legacy/specs/roles.md) — Client / Server / Facilitator; **payment selection pipeline** (policy hook at step 5)
-3. [legacy/specs/config.md](legacy/specs/config.md) — network + contract registry
-4. Scheme spec for the scheme you are touching: [`schemes/exact.md`](legacy/specs/schemes/exact.md) · [`schemes/exact-permit.md`](legacy/specs/schemes/exact-permit.md) · [`schemes/exact-gasfree.md`](legacy/specs/schemes/exact-gasfree.md)
-5. [docs/solutions.md](docs/solutions.md) — bug-avoidance checklist (TRON address hex, GasFree deadline bounds, balance source, etc.)
+1. [specs/x402-specification-v2.md](specs/x402-specification-v2.md) — shared wire objects,
+   facilitator API, discovery, and security rules
+2. Transport spec for the surface you are touching: [HTTP](specs/transports-v2/http.md) or
+   [MCP](specs/transports-v2/mcp.md)
+3. Scheme overview and network binding under [specs/schemes/](specs/schemes/)
+4. [specs/CONTRIBUTING.md](specs/CONTRIBUTING.md) — normative documentation rules and review
+   checklist
+5. [docs/solutions.md](docs/solutions.md) — bug-avoidance checklist (TRON address hex, GasFree
+   deadline bounds, balance source, etc.)
 
 ## Conventions
 
@@ -42,6 +41,15 @@ Each component has its own `CLAUDE.md` (where present) with build/test commands
 - **Mechanism registration**: `tron:0xcd8690dc` (exact match, higher priority) beats `tron:*` (wildcard, lower priority).
 - **Commit messages**: `<type>(<scope>): <description>` — e.g. `fix(tron): preserve raw_data_hex in tron approvals`.
 
+## Branch workflow
+
+- Start normal development, documentation, maintenance, and upstream-sync branches from `develop`
+  and open them back to `develop`.
+- Treat `main` as stable release history. Only `release_*` and `hotfix/*` branches may target
+  `main`.
+- Never open `develop` directly into `main`.
+- Follow [BRANCHING.md](BRANCHING.md) for release back-merges, hotfixes, and branch retention.
+
 ## AI-native development
 
 This repo uses a Claude-Code-native layout: rules, commands, and agents that let Claude (and other agents following the same conventions) contribute safely without reading every file first.
@@ -56,7 +64,9 @@ This repo uses a Claude-Code-native layout: rules, commands, and agents that let
 | [.claude/commands/x402/](.claude/commands/x402/) | Slash-command wizards (`/x402:compound`) |
 | [.claude/agents/](.claude/agents/) | Specialized subagents (`code-reviewer`, `security-reviewer`) |
 
-Each major component also has its own `CLAUDE.md` with build/test commands and local conventions: [legacy/python/x402/](legacy/python/x402/CLAUDE.md), [legacy/typescript/](legacy/typescript/CLAUDE.md), [legacy/e2e/](legacy/e2e/CLAUDE.md), [legacy/examples/](legacy/examples/CLAUDE.md), [docs/](docs/CLAUDE.md), [legacy/specs/](legacy/specs/CLAUDE.md), [legacy/integration/](legacy/integration/CLAUDE.md).
+Component-specific instructions live in [typescript/CLAUDE.md](typescript/CLAUDE.md),
+[docs/CLAUDE.md](docs/CLAUDE.md), [specs/CONTRIBUTING.md](specs/CONTRIBUTING.md), and
+[.claude/rules/CLAUDE.md](.claude/rules/CLAUDE.md).
 
 ## Safety rules
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -26,17 +26,27 @@ By participating in this project, you agree to abide by our Code of Conduct. We
 
 - Fill in the required template (if available).
 - Do not include more than one fix/feature per pull request.
+- Start normal work from `develop` and open the pull request back to `develop`.
+- Use `release_*` or `hotfix/*` branches for pull requests to `main`; never merge `develop`
+  directly into `main`.
 - Ensure that the tests pass and the code adheres to the project's coding standards.
 - Update the documentation if you've made changes to the API or added new features.
 - Commit messages follow `<type>(<scope>): <description>` (see [.claude/rules/common/conventions.md](.claude/rules/common/conventions.md)).
+- PR titles must use `type(scope): description`, contain 10-72 characters, start the description
+  with a lowercase letter or number, and not end with a period. Allowed types are `feat`, `fix`,
+  `refactor`, `docs`, `style`, `test`, `chore`, `ci`, `perf`, `build`, and `revert`.
+- The PR template's Description section must explain what and why in at least 20 characters.
+
+See [BRANCHING.md](BRANCHING.md) for the complete development, release, back-merge, and hotfix
+workflow.
 
 ---
 
 ## Development Setup
 
 ### Prerequisites
 
-- **Node.js**: 20+
+- **Node.js**: 22+
 - **pnpm**: >= 11 (workspace package manager)
 - **A wallet**: a TRON wallet with TRX (Nile/Shasta testnets) and/or a BSC wallet with BNB, for gas.
 
@@ -45,7 +55,6 @@ By participating in this project, you agree to abide by our Code of Conduct. We
 - **SDK**: [`typescript/`](typescript/CLAUDE.md) — pnpm/turbo monorepo, packages published as `@bankofai/x402-*` (`core`, `mechanisms/{evm,tron}`, `extensions`, `http/*`, `mcp`).
 - **Examples**: [`examples/typescript/`](examples/typescript/) — runnable client/server/facilitator trios per scheme.
 - **Agent rules & reviewers**: [`.claude/`](.claude/rules/CLAUDE.md) — conventions and specialized review subagents.
-- **Legacy**: [`legacy/`](legacy/) — previous-generation Python + TypeScript SDK, reference-only and **slated for removal**. Don't build on it.
 
 ---
 

diff --git a/README.md b/README.md
@@ -14,8 +14,6 @@ x402 currently supports the **TRON** and **BSC** networks, with plans to expand
 
 Version `1.1.0`. The SDK is a **TypeScript-only** pnpm/turbo monorepo published as granular `@bankofai/x402-*` packages (there is no umbrella package). `core` and the EVM mechanism are forks of the [`x402-foundation/x402`](https://github.com/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). See [the v1.1.0 release notes](RELEASE_NOTES.md#v110--payment-flow-and-wallet-compatibility) for upgrade details.
 
-> The previous-generation Python + TypeScript SDK lives under [`legacy/`](legacy/) for reference and is slated for removal.
-
 ## Features
 
 - **Protocol Native**: Restores the HTTP `402` status code to its intended purpose.
@@ -201,7 +199,9 @@ Use `pnpm build:release` before `pnpm pack` or `pnpm publish`. The forced build
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+We welcome contributions! Start normal work from `develop` and submit it back to `develop`.
+Stable releases reach `main` through a `release_*` branch. See [CONTRIBUTING.md](./CONTRIBUTING.md)
+and [BRANCHING.md](./BRANCHING.md) for the complete workflow.
 
 ## License
 

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -59,11 +59,11 @@ Release date: July 2, 2026
 
 ## Highlights
 
-The 1.0.0 release is a ground-up rewrite to a **TypeScript-only** pnpm/turbo monorepo. The previous-generation Python + TypeScript SDK moves to `legacy/` for reference. `core` and the EVM mechanism are forks of the [`x402-foundation/x402`](https://github.com/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).
+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`](https://github.com/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 live under `legacy/`.
+- **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`.
@@ -81,7 +81,7 @@ The 1.0.0 release is a ground-up rewrite to a **TypeScript-only** pnpm/turbo mon
 ## Compatibility
 
 - TypeScript-only; Node.js >= 20, pnpm >= 11.
-- The Python SDK is no longer published from `main`; it remains under `legacy/` for reference.
+- 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