Skip to content

Commit 134fb8a

Browse files
tufedevtufedev
committed
spec(v1.1.0-rc3): AUTHORIZED_SETTLER redefinition — Hub keeper EOA (Am-7)
Retracts v1.1.0-rc2. External review on 2026-05-16 identified that rc2's normative definition of AUTHORIZED_SETTLER (the x402.org facilitator's address) was non-implementable against x402.org as deployed and inverted x402's published trust model. Resolution: Option (b) Pull-to-treasury + Hub keeper recordSettlement. The Splitter contract source is UNCHANGED (JecpSplitter.sol L61 immutable verified). Only the constructor argument for AUTHORIZED_SETTLER is redefined from "facilitator address" to "Hub-controlled keeper EOA". Wire format: ZERO changes. SDK 0.8.x + CLI 0.7.x rc3-conformant unchanged. Normative changes: - ADR-0003 Am-7 — AUTHORIZED_SETTLER redefinition + emergency-only rotation ceremony (Splitter v2 deploy + capability re-registration, <72h SLA) + AV-1..4 disposition (PER_TX_CAP + accountedBalance-only + CEI defense) - spec/v1.1.0-rc3-errata.md (new) — §6.1 / §7.3 / §11 errata - §6.1: AUTHORIZED_SETTLER = Hub-controlled keeper EOA, immutable on v1 - §7.3: settlement timeline corrected to "≤2 Base blocks (typical ~3s)" - §11: reconciler reclassified watcher → keeper-driver (separate module) - I-6 (settlement timing), I-7 (amount attribution) added - CHANGELOG.md — rc3 entry prepended with full retract reason - RETRACT-v1.1.0-rc2.md (new) — operator command sequence + GitHub Release SUPERSEDED marking + npm coordination decision + 4-party notification Conformance: 5 new YAMLs (total v1.1.0-rc3 x402 suite = 27 assertions) - X402_HUB_KEEPER_AUTHORIZED_SETTLER_MATCH - X402_FACILITATOR_NOT_TRUSTED_AS_SETTLER - X402_RECORD_SETTLEMENT_IDEMPOTENT - X402_RECORD_SETTLEMENT_LATENCY_BOUND (p99 < 30s) - X402_AMOUNT_ATTRIBUTION_INVARIANT (I-7) BaseScan facilitator fleet observation (2026-05-16): multi-operator fleet (Canza, Coinbase, Daydreams, X402rs) under shared label pattern "x402 Facilitator N"; non-consecutive Coinbase numbering confirmed (3, 4, 7).
1 parent b0c64e0 commit 134fb8a

9 files changed

Lines changed: 932 additions & 0 deletions

‎CHANGELOG.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,61 @@ The repository follows [SemVer](https://semver.org). Major versions break wire c
66

77
---
88

9+
## v1.1.0-rc3 — 2026-05-16 — AUTHORIZED_SETTLER redefinition (supersedes rc2)
10+
11+
**Retracted**: `jecp-spec@v1.1.0-rc2` (2026-05-13). Tag deleted, GitHub Release marked SUPERSEDED. See `RETRACT-v1.1.0-rc2.md` for the full operator procedure.
12+
13+
**Reason**: External review on 2026-05-16 identified that rc2's normative definition of `AUTHORIZED_SETTLER` — as "the x402 facilitator's settlement contract address (or, if the facilitator uses an EOA, that EOA)" — was non-implementable against x402.org as deployed and inverted x402's published trust model. x402.org operates a multi-operator facilitator fleet (Canza, Coinbase, Daydreams, X402rs observed on BaseScan as `x402 Facilitator N`), not a single contract; the x402 specification's `/verify` + `/settle` API surface does not include a facilitator-initiated post-pull contract call; the x402 README design principles explicitly forbid the facilitator from moving funds outside client intentions.
14+
15+
**Resolution**: Option (b) Pull-to-treasury + Hub keeper `recordSettlement` design adopted (admiral approval 2026-05-16). The Splitter contract source is **unchanged**; only the constructor argument for the `AUTHORIZED_SETTLER` immutable slot is redefined from "facilitator address" to "Hub-controlled keeper EOA". The Hub `services/x402_keeper.rs` module is newly broken out from the v1.1.1 reconciler watcher and actively calls `recordSettlement` from the keeper EOA after the facilitator's settle leg confirms on-chain. SDK and CLI wire format are unchanged.
16+
17+
### Normative changes (versus rc2)
18+
19+
- **ADR-0003 Am-7** (new amendment) — `AUTHORIZED_SETTLER` redefinition; rotation via Splitter v2 ceremony (no setter on v1); decommissioning policy; AV-1..4 disposition. Supersedes the v1.1.1 deferred OQ on settler address resolution.
20+
- **`spec/06-x402-integration.md` §6.1, §7.3, §11** — errata applied per `spec/v1.1.0-rc3-errata.md`:
21+
- §6.1: `AUTHORIZED_SETTLER` redefined as Hub-controlled keeper EOA, immutable on Splitter v1; separation-of-duties enforced at key generation.
22+
- §7.3: settlement timeline corrected from "single-block atomic" (unqualified) to "≤ 2-block on-chain settlement (typical ~3 s, single-block when block timing aligns)". Marketing-grade "single-block atomic" preserved only as observed-measurement claim, never as guaranteed invariant. New invariant I-6 (settlement timing).
23+
- §11: reconciler reclassified watcher → keeper-driver (separate module). New invariant I-7 (amount attribution): on-chain `recordSettlement` amount MUST match USDC `Transfer` log from pull leg; keeper-driver MUST refuse retry on mismatch.
24+
25+
### Conformance
26+
27+
Adds 5 new YAML assertions, raising the v1.1.0-rc3 x402 suite to **27**:
28+
29+
- `X402_HUB_KEEPER_AUTHORIZED_SETTLER_MATCH.yaml`
30+
- `X402_FACILITATOR_NOT_TRUSTED_AS_SETTLER.yaml`
31+
- `X402_RECORD_SETTLEMENT_IDEMPOTENT.yaml`
32+
- `X402_RECORD_SETTLEMENT_LATENCY_BOUND.yaml` (p99 < 30 s)
33+
- `X402_AMOUNT_ATTRIBUTION_INVARIANT.yaml` (I-7)
34+
35+
Hubs that do not advertise x402 remain exempt from all 27 x402-prefixed assertions.
36+
37+
### Wire compatibility
38+
39+
**Zero wire changes** versus rc2. All of the following remain bit-identical: 402 challenge envelope, `payment.accepts[]` shape, `X-Payment` / `X-Payment-Response` headers, `agent-guide.json` `payment.x402` block, error catalog. See `JobDoneBot/docs/jecp/x402-design/rc3/wire-invariance-checklist.md` for mechanical verification commands.
40+
41+
### SDK / CLI status
42+
43+
- `@jecpdev/sdk@0.8.x` — **conformant with rc3 unchanged**. No deprecation. No release required.
44+
- `@jecpdev/cli@0.7.x` — **conformant with rc3 unchanged**. No deprecation. No release required.
45+
- Provider EIP-712 registration flow — unchanged.
46+
47+
### Splitter contract
48+
49+
- `jecp-contracts` Splitter source — unchanged (no Solidity edit required). R-2 verified via `JecpSplitter.sol` L61 immutable declaration.
50+
- Constructor argument layout — `authorizedSettler` now bound to Hub-controlled keeper EOA at deploy time, not facilitator address.
51+
- Foundry tests (52 cases) — unchanged.
52+
53+
### Tag plan
54+
55+
```bash
56+
git -C jecp-spec tag jecp-spec/v1.1.0-rc3
57+
git -C jecp-spec push origin jecp-spec/v1.1.0-rc3
58+
```
59+
60+
Promotion to `jecp-spec/v1.1.0` GA follows: Hub deploys Splitter v1 to Base Sepolia with new `AUTHORIZED_SETTLER` = keeper EOA → 27/27 conformance assertions pass on Sepolia → audit firm sign-off on rc3 constructor change (BS-4 3-scope split) → Base mainnet deploy → GA tag.
61+
62+
---
63+
964
## v1.1.0 — 2026-05-11 — x402 Integration
1065

1166
Backward-compatible minor release. Adds Coinbase's [x402](https://x402.org) (HTTP 402 + USDC-on-Base micropayment) as a **second, parallel payment path** on `POST /v1/invoke`. The existing pre-funded Stripe wallet path is unchanged. v1.1.0 conformance does NOT require x402 support — Hubs that omit the x402 facilitator config remain conformant with the existing v1.0.x suite plus the `payment_methods`-honors-default invariant.

‎RETRACT-v1.1.0-rc2.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Retraction Notice — `jecp-spec@v1.1.0-rc2`
2+
3+
**Date**: 2026-05-16
4+
**Status**: RETRACTED. Superseded by `jecp-spec@v1.1.0-rc3`.
5+
**Reason**: Architectural reassessment of `AUTHORIZED_SETTLER` role definition. No wire-format incompatibility; SDK / CLI / Provider integration unchanged.
6+
7+
---
8+
9+
## 1. What was retracted
10+
11+
`jecp-spec@v1.1.0-rc2`, tagged 2026-05-13, including the cert-pin restoration patch and the three audit-A HIGH header fixes (§11.1 `Cache-Control: no-store`, §11.2 `Access-Control-Expose-Headers`, §11.3 `WWW-Authenticate`). The rc2 spec text is intact and remains historically referenced; only the **release tag and its associated GitHub Release** are retracted, marked SUPERSEDED, and replaced by rc3.
12+
13+
The rc2 retraction is **not** an emergency security advisory. No production deployments of v1.1.0-rc2 exist (Splitter not yet mainnet-deployed; the rc2 mainnet deploy gate was blocked by the same OQ-1 that surfaced the AUTHORIZED_SETTLER defect). The retraction is governance hygiene: external review on 2026-05-16 identified that rc2's normative definition of `AUTHORIZED_SETTLER` (the x402.org facilitator's address) was non-implementable against x402.org as deployed and inverted x402's published trust model. ADR-0003 Am-7 (2026-05-16) records the correction; rc3 is the canonical text.
14+
15+
---
16+
17+
## 2. Retract command sequence (operator runs)
18+
19+
Executed by the `jecpdev` maintainer with push rights to `github.com/jecpdev/jecp-spec`. Commands assume working tree at `/Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec`.
20+
21+
```bash
22+
# Step 1 — confirm current state
23+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec fetch --tags --prune
24+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec tag -l 'jecp-spec/v1.1.0-rc*'
25+
# expected: jecp-spec/v1.1.0-rc1, jecp-spec/v1.1.0-rc2
26+
27+
# Step 2 — delete local rc2 tag
28+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec tag -d jecp-spec/v1.1.0-rc2
29+
30+
# Step 3 — delete remote rc2 tag
31+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec push --delete origin jecp-spec/v1.1.0-rc2
32+
33+
# Step 4 — verify deletion
34+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec ls-remote --tags origin | grep -F 'v1.1.0-rc2' || echo "rc2 tag removed cleanly"
35+
36+
# Step 5 — proceed to rc3 tag after spec edits land
37+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec tag -a jecp-spec/v1.1.0-rc3 -m "v1.1.0-rc3 — supersedes rc2; AUTHORIZED_SETTLER redefinition via Am-7"
38+
git -C /Users/tufecompany/Desktop/開発・プロジェクト/jecp-spec push origin jecp-spec/v1.1.0-rc3
39+
```
40+
41+
**Safety note**: deleting a Git tag is reversible only if the tagged commit remains reachable from another ref (e.g., `main`). The rc2 commit MUST remain reachable; do NOT also delete branches that contain it. The retraction targets the tag pointer only.
42+
43+
---
44+
45+
## 3. GitHub Releases marking
46+
47+
After Step 3 above, the GitHub Release UI requires manual editing (the tag delete does not auto-update the Release page). Operator steps:
48+
49+
1. Navigate to `https://github.com/jecpdev/jecp-spec/releases/tag/jecp-spec/v1.1.0-rc2`. The page now shows "This tag has been deleted" but the Release entity persists.
50+
2. Click "Edit release".
51+
3. Prepend the title with **`[SUPERSEDED] `**: `[SUPERSEDED] jecp-spec v1.1.0-rc2 — header MUSTs + cert-pin patch`.
52+
4. Replace the release-notes body with the public notice below, in full.
53+
5. Check "Set as a pre-release" (should already be checked); leave "Set as the latest release" unchecked.
54+
6. Save.
55+
56+
### Public release-notes body (replace rc2 body verbatim)
57+
58+
> **This release tag has been retracted on 2026-05-16 and is superseded by `jecp-spec@v1.1.0-rc3`.**
59+
>
60+
> External review on 2026-05-16 identified that v1.1.0-rc2's normative definition of `AUTHORIZED_SETTLER` (the x402.org facilitator's address) was non-implementable against x402.org as deployed and inverted x402's published trust model. The rc3 release applies amendment Am-7 to ADR-0003, redefining `AUTHORIZED_SETTLER` as a Hub-controlled keeper EOA driven by the Hub keeper-driver. Wire format is unchanged across rc2 → rc3; SDK `@jecpdev/sdk@0.8.x`, CLI `@jecpdev/cli@0.7.x`, and Provider EIP-712 registration are unaffected. The three audit-A header MUSTs and the cert-pin patch from rc2 are preserved verbatim in rc3.
61+
>
62+
> No production deployments existed at rc2 (Splitter contract was not yet on Base mainnet). Implementers who built against rc2 should update to rc3; no code-level migration is required for SDK / CLI consumers. Splitter contract implementers MUST adopt the rc3 constructor argument layout per `spec/v1.1.0-rc3-errata.md` §E.1.
63+
>
64+
> See `jecp-spec/v1.1.0-rc3` release notes for full details and the ADR-0003 Am-7 record.
65+
66+
---
67+
68+
## 4. npm package coordination
69+
70+
The `@jecpdev/sdk` and `@jecpdev/cli` npm packages are **wire-compatible** with rc3 and DO NOT require deprecation. No `npm deprecate` action is taken. Explicit guidance to consumers (posted in `CHANGELOG.md` of each repo):
71+
72+
> `@jecpdev/sdk@0.8.x` and `@jecpdev/cli@0.7.x` are fully conformant with `jecp-spec@v1.1.0-rc3`. The rc2 → rc3 spec change is server-side (Hub + Splitter contract) only; SDK consumers require no upgrade.
73+
74+
If, in a future rc4 or v1.1.0 GA, a wire-affecting change does occur, deprecation will use the standard form:
75+
76+
```bash
77+
npm deprecate "@jecpdev/sdk@<version>" "use @jecpdev/sdk@<next-version> for jecp-spec@v1.1.0 GA conformance"
78+
```
79+
80+
This is NOT executed for the rc2 → rc3 transition.
81+
82+
---
83+
84+
## 5. Downstream notification
85+
86+
The following parties MUST be notified within 24 h of the retract being pushed:
87+
88+
| Party | Channel | Message owner |
89+
|---|---|---|
90+
| `jecp-contracts` maintainer | GitHub Issue on `jecpdev/jecp-contracts` titled "Splitter v1 constructor — adopt rc3 `AUTHORIZED_SETTLER` semantics (Am-7)" | admiral |
91+
| `jecpdev/website` (LP) maintainer | Copy patch sweep per `JobDoneBot/docs/jecp/release-prep/RC3-COPY-PATCH-TRACKER.md` Patch 4-5 | brand-guardian |
92+
| Audit firm RFP recipients (Spearbit / Cure53 / Trail of Bits) | Email from `security@jecp.dev` with subject "RFP scope update — Splitter v1 rc3 constructor change (Am-7)"; bundle the 3-scope split per BS-4 | admiral + protocol-designer |
93+
| `acromoney777@gmail.com` (admiral inbox) | This document URL + ADR-0003 Am-7 URL | self |
94+
95+
Notification text is published in `docs/jecp/release-prep/rc2-retract-notifications.md` (separate file) and is out of scope of this retraction document.

0 commit comments

Comments
 (0)