From 12603dd9504b29ad023e765e5ad87ee77cb1eef4 Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Sun, 6 Sep 2026 23:46:18 +0200 Subject: [PATCH 1/2] docs(plan): define hashless recovery --- .agent/AGENTS.md | 7 +- .agent/PROJECT_CONTEXT.md | 17 +- .agent/SECURITY_INVARIANTS.md | 2 +- .agent/SPONSOR_REQUIREMENTS.md | 70 +++-- .agent/TEST_MATRIX.md | 4 +- .../20260906T201351Z-product-roadmap.md | 45 +++- .../20260906-integration-decisions.md | 33 ++- .../skills/oneshot-failure-injection/SKILL.md | 2 +- .agents/skills/oneshot-idempotency/SKILL.md | 2 +- .agents/skills/sponsor-qualification/SKILL.md | 21 +- docs/DOMAIN_ARCHITECTURE.md | 49 ++-- milestones/CONTRACTS.md | 24 +- milestones/README.md | 4 +- .../coder-a/A01-foundation-contracts.md | 4 +- milestones/coder-a/A02-durable-intents.md | 2 +- milestones/coder-a/A03-atomic-worker.md | 2 +- .../coder-a/A05-frontend-intent-status.md | 2 +- milestones/coder-a/A06-release-operations.md | 14 +- .../coder-b/B01-sdk-network-compatibility.md | 28 +- .../coder-b/B02-request-policy-receipt.md | 12 +- .../coder-b/B03-live-settlement-harness.md | 2 +- .../coder-b/B04-ambiguity-integration.md | 2 +- milestones/coder-b/B06-sponsor-evidence.md | 16 +- .../coder-c/C01-recovery-evidence-strategy.md | 67 +++++ .../coder-c/C01-subgraph-index-health.md | 60 ----- .../coder-c/C02-reconciliation-engine.md | 8 +- milestones/coder-c/C03-failure-injection.md | 2 +- .../C04-recovery-matrix-integration.md | 8 +- milestones/coder-c/C05-frontend-recovery.md | 8 +- milestones/coder-c/C06-qualification-demo.md | 36 ++- milestones/coder-c/README.md | 22 +- plan.md | 245 +++++++++++++----- 32 files changed, 541 insertions(+), 279 deletions(-) create mode 100644 milestones/coder-c/C01-recovery-evidence-strategy.md delete mode 100644 milestones/coder-c/C01-subgraph-index-health.md diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md index c8073b3..eb24dca 100644 --- a/.agent/AGENTS.md +++ b/.agent/AGENTS.md @@ -34,8 +34,9 @@ OneShot's core promise is: `One job. Many retries. One settlement.` - Privy provides corporate wallet access and scoped authorization, policy, and spending permissions. - Arc is the USDC settlement rail. -- The Graph provides live indexed history and recovery context. It is never the - duplicate-payment lock or authority for creating another Settlement. +- Direct Privy and Arc evidence resolves known transaction identities. The Graph + is the selected v1 hashless candidate-discovery layer after its C01 evidence + gate; it is never the duplicate-payment lock or settlement authority. Read `.agent/PROJECT_CONTEXT.md`, `.agent/SECURITY_INVARIANTS.md`, and `.agent/SPONSOR_REQUIREMENTS.md` before changing these boundaries. @@ -50,7 +51,7 @@ Read `.agent/PROJECT_CONTEXT.md`, `.agent/SECURITY_INVARIANTS.md`, and - Make state durable and transitions atomic and concurrency-safe. - Represent money as integer atomic units or `bigint`, never JavaScript floating point. -- Graph absence or indexing delay is not proof that payment did not happen. +- External-index absence or delay is not proof that payment did not happen. - Normal execution must not bypass Privy policy or OneShot controls. - Use testnet only unless the user explicitly authorizes another network. - Never log, expose, persist, commit, or send secrets, private keys, seed diff --git a/.agent/PROJECT_CONTEXT.md b/.agent/PROJECT_CONTEXT.md index 3267b67..61d8a6f 100644 --- a/.agent/PROJECT_CONTEXT.md +++ b/.agent/PROJECT_CONTEXT.md @@ -34,13 +34,14 @@ verticals over the same durable intent contract. - Privy is the corporate wallet and scoped authorization boundary. OneShot must use its policies and spending permissions on the normal execution path. - Arc is the real USDC settlement rail used by the demo. -- The Graph supplies live indexed recovery/history context and agent decision - support after ambiguous outcomes. It can corroborate or locate activity, but - cannot authorize a duplicate payment. +- Direct Privy lookup and Arc RPC receipt/log evidence resolve known transaction + identities after ambiguous outcomes. +- The Graph is the selected v1 candidate-discovery layer when the transaction + hash is missing. C01 must prove live hashless discovery and AI-track value; + Graph results remain non-authoritative and can never authorize another payment. When an external submission may have happened but the result is uncertain, -OneShot records `UNKNOWN` and reconciles. Missing Graph data never converts -`UNKNOWN` into permission to submit again. +OneShot records `UNKNOWN` and reconciles. Missing external-index data never converts `UNKNOWN` into permission to submit again. ## Glossary @@ -64,14 +65,14 @@ have zero or one committed Settlement, never more than one. ### Reconciliation The process that resolves an ambiguous external effect using durable local -state, provider identifiers and receipts, Arc state, and indexed evidence. +state, provider identifiers and receipts, Graph-discovered candidates, and Arc proof. Reconciliation precedes any decision to retry payment when settlement state is `UNKNOWN`. ### Recovery View -A derived, non-authoritative view assembled from durable OneShot records and -live indexed history, including The Graph. It helps operators and agents explain +A derived, non-authoritative view assembled from durable OneShot records, live +Graph candidate discovery, and Arc verification. It helps operators and agents explain and recover work but does not grant permission to create a Settlement. ## Decision test diff --git a/.agent/SECURITY_INVARIANTS.md b/.agent/SECURITY_INVARIANTS.md index c9c8aa3..fd5c83f 100644 --- a/.agent/SECURITY_INVARIANTS.md +++ b/.agent/SECURITY_INVARIANTS.md @@ -9,7 +9,7 @@ These rules fail closed. A feature, demo, or deadline does not override them. - Use durable, atomic, concurrency-safe transitions for settlement ownership. - A timeout, crash, disconnect, lost response, or provider error after possible submission creates `UNKNOWN`; reconcile before any payment retry. -- Never infer non-payment from an empty or delayed Graph result. +- Never infer non-payment from an empty or delayed external-index result. - Preserve a successful payment result even if a later supplier or API step fails. - Do not offer a normal code path that bypasses OneShot state controls or Privy diff --git a/.agent/SPONSOR_REQUIREMENTS.md b/.agent/SPONSOR_REQUIREMENTS.md index 6116c2f..867a68c 100644 --- a/.agent/SPONSOR_REQUIREMENTS.md +++ b/.agent/SPONSOR_REQUIREMENTS.md @@ -3,38 +3,64 @@ Use this document before sponsor-facing implementation, demo preparation, release, or submission claims. -## Privy +## Primary target: Privy - Privy must be core corporate wallet authorization, not login-only branding. -- The working path must demonstrate scoped authorization, policies, or spending - permissions that constrain settlement. +- The working path must demonstrate a Privy wallet plus scoped authorization, + policies, signers, quorum, or spending permissions that constrain settlement. - Policy denial or an amount above policy must produce zero settlement. - The normal agent path must not bypass Privy authorization. -## Arc +## Primary target: Arc -- The demo must execute a real USDC settlement on the authorized Arc testnet. -- Showing an Arc network label, wallet address, explorer page, or mocked payment - alone does not qualify. -- OneShot must retain the settlement identity and result through retries and +- The demo must execute a real USDC settlement on Arc Testnet. +- Showing a network label, wallet, explorer page, or mocked payment alone does + not qualify. +- The product must have a working frontend, backend, architecture diagram, + public source, documentation, and short demonstration. +- OneShot must retain settlement identity and result through retries and downstream failures. +- For the Launch track, include a disabled Arc Mainnet profile, deployment and + rollback artifacts, and readiness evidence. Actual mainnet execution remains + disabled until Circle publishes official production access/identities and a + human explicitly authorizes real-value activation. -## The Graph +## Alternative target: Hedera AI & Agentic Payments -- The integration must use live indexed data for recovery, history, or agent - decision support. -- The demo should show how indexed evidence helps resolve or explain an - ambiguous outcome. -- The Graph must never be the sole duplicate-payment lock, authoritative intent - state, or proof that another settlement may be submitted. -- Empty results and indexing delay must preserve safe behavior. +Select this instead of Arc before P0; do not build two settlement rails for the +same MVP. + +- Host a live x402-gated service on Hedera testnet or mainnet and settle it + through Blocky402. +- Demonstrate an agent or platform completing one real paid request end to end. +- Keep Privy core by proving a real wallet plus policy, signer, key quorum, or + intent that constrains the financial action. EVM compatibility alone is not + evidence; the Privy/Hedera path needs a B01 spike. +- Use Hedera transaction or Mirror Node history as recovery evidence, never as + the durable duplicate lock. +- Add Bazantic only after the core path works and only when its recipe/gateway + creates a separate, demonstrated agent capability. + +## Selected target: The Graph AI Tooling or AI Use Case + +The Graph is load-bearing for automatic recovery when a successful submission +lost its transaction hash. It discovers candidates; Arc verifies them; OneShot +decides. C01 must prove this with live data before any qualification claim. + +- Target the AI Tooling or AI Use Case track. The recovery agent must use live + Graph data for meaningful candidate selection, explanation, and automation. +- Do not target Composable/Standardized with one custom Subgraph; that track + requires two Graph products or meaningful standardized-schema work. +- Empty, delayed, multiple, or contradictory candidates preserve `UNKNOWN` and + cannot unlock another settlement. +- Include a public repository, clear README, and a two-to-four-minute demo. ## Claim standard -Do not state or imply sponsor qualification unless the integration exists in -working code and the demo proves the required behavior. Plans, placeholders, -mockups, environment variables, dependency declarations, and network labels are -not implementation evidence. +Do not state or imply sponsor qualification unless working code and live demo +evidence prove every selected track requirement. Plans, placeholders, mocks, +environment variables, dependencies, and network labels are not evidence. -Use the `sponsor-qualification` skill to report each sponsor as `QUALIFIED`, -`NOT QUALIFIED`, or `NOT VERIFIED`, with code, test, and demo evidence. +Use the `sponsor-qualification` skill to report each selected sponsor as +`QUALIFIED`, `NOT QUALIFIED`, or `NOT VERIFIED`, with code, test, demo, network, +and limitation evidence. \ No newline at end of file diff --git a/.agent/TEST_MATRIX.md b/.agent/TEST_MATRIX.md index 8d60369..1b85e20 100644 --- a/.agent/TEST_MATRIX.md +++ b/.agent/TEST_MATRIX.md @@ -1,7 +1,7 @@ # OneShot Test Matrix Select every applicable case for changes to intents, retries, workers, queues, -payments, settlements, reconciliation, Privy, Arc, or The Graph. Prefer tests at +payments, settlements, reconciliation, Privy, Arc, or The Graph discovery. Prefer tests at the public domain boundary plus focused adapter tests. A test must assert durable state and external settlement count, not only an HTTP response. @@ -15,7 +15,7 @@ state and external settlement count, not only an HTTP response. | Crash before submission | Kill process before any external submission | 0 settlements; retry is allowed from durable state | | Crash after submission | Kill process after possible submission but before local confirmation | Enter `UNKNOWN`; reconcile; no blind retry | | Lost payment response | Payment succeeds but HTTP response is lost | Exactly 1 committed settlement after reconciliation | -| Graph delay or absence | The Graph temporarily returns nothing or lags | No duplicate settlement; absence is not non-payment proof | +| Graph delay, absence, or ambiguity | The Graph returns nothing, lags, is unavailable, or returns multiple candidates | Remain `UNKNOWN`; no duplicate settlement; absence is not non-payment proof | | Privy denial | Policy denies or amount exceeds permission | 0 settlements and explicit authorization failure | | Service restart | Restart after durable intent creation or in-flight work | Intent and settlement state survive; invariant holds | | Downstream failure after payment | Supplier/API step fails after settlement | Payment result remains durable; no replacement payment | diff --git a/.agent/context/20260906T201351Z-product-roadmap.md b/.agent/context/20260906T201351Z-product-roadmap.md index 6ec0d63..f0e792e 100644 --- a/.agent/context/20260906T201351Z-product-roadmap.md +++ b/.agent/context/20260906T201351Z-product-roadmap.md @@ -56,4 +56,47 @@ contributes to the complete product. - Branch: `milestone/product-roadmap` - Base: `develop` at `5ef6a66313614e67b476f56c98f47c65344fb6ec` -- Pull request: `https://github.com/SWOFART/OneShot/pull/7` +- Original roadmap pull request: `https://github.com/SWOFART/OneShot/pull/7` + (merged into `develop` before this architecture correction). +- Follow-up pull request: pending from `milestone/product-roadmap`. + +## 2026-09-06 architecture correction + +- The working Arc Testnet product remains the first live proof. +- Mainnet readiness is now part of P0-P6 through a disabled typed profile, + deployment/preflight evidence, safe disable, rollback, and a human activation + gate. No unavailable Arc Mainnet values are guessed. +- PostgreSQL remains authoritative. Direct Privy lookup and Arc receipt/log + evidence form the required recovery path. +- The Graph is the selected v1 hashless candidate-discovery layer. C01 must + prove live value, freshness, multiple-candidate handling, and AI-track fit; + Arc remains authoritative and a failed gate removes the Graph claim. +- Review gates for this corrected tree are intentionally not embedded here; + immutable Gate A/B evidence is recorded on PR #7 so recording it cannot alter + the reviewed tree. +## 2026-09-06 migration options + +- Arc with direct Privy/RPC evidence remains the smallest default. +- The Graph is the primary `IndexViewPort` adapter for hashless discovery; + direct Arc or managed RPC remain migration fallbacks. +- Hedera with Privy and x402/Blocky402 is a coherent alternative settlement + rail for the paid-API vertical. It replaces Arc-specific adapter/evidence + work while retaining the OneShot domain, PostgreSQL authority, `UNKNOWN`, and + reconciliation rules. +- A Hedera pivot must be selected before P0 and must prove Privy compatibility; + it is not a second rail in the same MVP. +- Bazantic is the closest optional third sponsor after the core Hedera flow, + but it must add a real agent-facing capability and cannot replace Blocky402. +## 2026-09-06 Graph and Arc Memo decision + +- Primary submission direction: Privy authorizes, The Graph discovers, Arc + proves, and OneShot/PostgreSQL decides. +- Target The Graph AI Tooling or AI Use Case, not Composable/Standardized. +- Demonstrate a real Arc payment whose successful response/hash is discarded at + the adapter fault boundary, followed by live Graph discovery and direct Arc + verification with no second payment. +- Prefer Arc Memo `memoId = hash(business_intent_id)` for unique correlation only + if B01 proves Privy can constrain the forwarded USDC call. Otherwise preserve + stricter authorization and use tuple/window search or a narrow typed contract. +- Hedera + Privy + x402/Blocky402 remains a separate P0 alternative, not a + second settlement rail in the Arc MVP. diff --git a/.agent/research/20260906-integration-decisions.md b/.agent/research/20260906-integration-decisions.md index f9554dc..6af62e8 100755 --- a/.agent/research/20260906-integration-decisions.md +++ b/.agent/research/20260906-integration-decisions.md @@ -2,7 +2,7 @@ Date: 2026-09-06 Scope: primary-source facts needed to make the first product implementation plan decision-complete. -Target: Privy-authorized USDC settlement on Arc Testnet with The Graph as a non-authoritative recovery view. +Target: Privy-authorized exactly-once settlement on Arc Testnet by default, with provider-neutral recovery and Hedera x402 as an explicit alternative rail. ## Decisions @@ -21,13 +21,25 @@ Target: Privy-authorized USDC settlement on Arc Testnet with The Graph as a non- - Arc transactions are pending until included, then immediately and deterministically final; there is no accumulating-confirmation state. A receipt with `status: 1` is final success only after validating the expected USDC `Transfer` log. A receipt with `status: 0` is final execution failure and zero settlement ([transaction lifecycle](https://docs.arc.io/integrate/wallets/transaction-lifecycle), [deterministic finality](https://docs.arc.io/arc/concepts/deterministic-finality)). - Deterministic finality does not eliminate submission ambiguity. A lost Privy/RPC response or process crash after a possible broadcast still becomes `UNKNOWN`; a new-nonce payment is forbidden until reconciliation proves a safe terminal result. -### The Graph: live recovery evidence, never settlement authority +### The Graph: selected for hashless discovery, never settlement authority -- The Graph lists Arc Testnet as `arc-testnet`, protocol Ethereum, CAIP-2 `eip155:5042002` ([Arc Testnet support](https://thegraph.com/docs/en/supported-networks/arc-testnet/)). -- Build a custom Subgraph over the unified USDC `Transfer` event. Identify each event by transaction hash plus log index and retain block number, block timestamp, sender, recipient, and amount as Graph `BigInt` ([Arc event indexing](https://docs.arc.io/integrate/infrastructure/indexing-events), [Subgraph quick start](https://thegraph.com/docs/en/subgraphs/quick-start/)). -- Every query must request `_meta` block data, deployment ID, and `hasIndexingErrors`. Operational health must also compare indexed `latestBlock` with `chainHeadBlock`; `synced` only means the deployment caught up at least once ([GraphQL API](https://thegraph.com/docs/en/subgraphs/querying/graphql-api/), [indexing health](https://thegraph.com/docs/en/subgraphs/developing/deploying-publishing/multiple-networks/)). -- Missing, empty, lagging, or unhealthy indexed results mean only that no matching event was observed through a known indexed block. They never prove non-payment or authorize another submission. Direct Arc receipts plus durable OneShot state remain authoritative. -- Use a deployment-pinned query endpoint for schema-stable demo evidence. Do not claim sponsor qualification until a deployed endpoint returns live Arc data and lag/error behavior is demonstrated ([Subgraph ID versus deployment ID](https://thegraph.com/docs/en/subgraphs/querying/subgraph-id-vs-deployment-id/)). +- Direct Privy lookup plus exact Arc receipt/log verification resolves known transaction identities. PostgreSQL remains authoritative for ownership, intent state, and the `UNKNOWN` hold. +- The Graph is the selected v1 path for discovering candidate transfers when a successful submission lost its hash. C01 must prove this live and show a capability that disappears when Graph is removed. +- Every query carries deployment and freshness/error evidence. Missing, empty, lagging, unhealthy, multiple, or contradictory candidates preserve `UNKNOWN`; Arc verifies every candidate before any commit. +- Arc RPC can scan logs without a hash, so The Graph is a product choice for structured automatic discovery rather than the only technically possible scanner ([Arc event indexing](https://docs.arc.io/integrate/infrastructure/indexing-events), [Graph querying](https://thegraph.com/docs/en/subgraphs/querying/introduction/)). +- Arc's Memo contract can attach a caller-supplied `memoId` and `callDataHash` to a forwarded USDC call specifically for correlation and reconciliation. C01/B01 must test `memoId = hash(business_intent_id)` as the preferred unique lookup key ([Arc Memo indexing](https://docs.arc.io/integrate/infrastructure/indexing-events)). +- Privy can enforce chain, destination contract, decoded function, and decoded top-level calldata parameters. Before choosing Memo for settlement, B01 must prove the policy can constrain the forwarded USDC target and required business fields; otherwise use the tuple-search fallback or a narrow typed settlement contract without weakening authorization ([Privy policy fields](https://docs.privy.io/controls/policies/overview)). +- Target the Graph AI Tooling or AI Use Case track: live Graph data must drive meaningful recovery-agent selection, explanation, or automation. The composable/standardized track requires two Graph products or meaningful use of a standardized schema; one custom Subgraph query is insufficient ([ETHOnline 2026 prize requirements](https://ethglobal.com/events/ethonline2026/prizes)). + +### Hedera x402: coherent alternative settlement rail + +- The Hedera AI & Agentic Payments track requires a live x402-gated service on Hedera testnet or mainnet, settlement through the Blocky402 facilitator, and an agent/platform completing at least one real paid request end to end ([ETHOnline 2026 Hedera requirements](https://ethglobal.com/events/ethonline2026/prizes/hedera)). +- This maps directly to OneShot's first vertical: the agent pays for one API job while the durable Business Intent prevents a duplicate financial outcome after repeated HTTP calls, restarts, or lost settlement responses. +- A Hedera choice replaces the Arc-specific network, token/request, receipt, explorer, and evidence adapters. It does not replace PostgreSQL authority, atomic ownership, the one-attempt submission job, `UNKNOWN`, or reconciliation. +- Hedera Mirror Nodes expose validated transaction history through REST APIs and can serve as a read/recovery source. They remain external observation, not the OneShot duplicate lock ([Mirror Node model](https://docs.hedera.com/learn/core-concepts/mirror-nodes)). +- Hedera exposes an Ethereum JSON-RPC interface, so reusing EVM transaction tooling is plausible, but it is not proof of Privy product support ([Hedera Hardhat and ethers.js guide](https://docs.hedera.com/hedera/tutorials/smart-contracts/hscs-workshop/hardhat)). +- Privy is not assumed compatible merely because Hedera exposes an EVM interface. B01 must prove wallet creation, signing, chain configuration, policy enforcement, submission, and lookup on the chosen Hedera path before Privy/Hedera qualification is claimed. +- `x402` plus Blocky402 is the required third technical component. Bazantic is the closest optional third sponsor because it can expose a finished API through a recipe or gateway, but it is added only after the Hedera paid-request path works and it must not replace Blocky402 settlement. ### Durable state and work delivery @@ -41,9 +53,10 @@ Target: Privy-authorized USDC settlement on Arc Testnet with The Graph as a non- 1. Pin exact SDK and runtime versions only after a compatibility spike validates Privy request signing, Arc chain support, and policy condition syntax. 2. Assert `eth_chainId == 5042002` and bytecode exists at the configured USDC address during testnet startup checks. 3. Prove the chosen Privy policy denies wrong chain, wrong contract, wrong recipient, wrong method, non-zero native value, and above-cap amount with zero settlement. -4. Prove The Graph deployment health and lag thresholds against live Arc Testnet before sponsor qualification. -5. Keep Privy webhooks outside the critical path until plan availability and signature verification are demonstrated. +4. Prove live The Graph hashless discovery, freshness, multiple-candidate handling, safe degradation, and AI-track value; otherwise remove the Graph claim and use direct recovery. +5. If Hedera is selected at P0, prove the full Privy + x402/Blocky402 paid-request path and Mirror Node/transaction evidence before replacing Arc packets. +6. Keep Privy webhooks outside the critical path until plan availability and signature verification are demonstrated. ## Planning consequence -The work can be split into three independent backend tracks after one contract freeze: (A) domain/storage/API, (B) Privy/Arc settlement, and (C) indexing/reconciliation. Each track must ship its own contract simulator and tests so progress does not depend on another track's implementation. Frontend begins only after the integrated backend contract and recovery semantics are stable. +The work can be split into three independent backend tracks after one contract freeze: (A) domain/storage/API, (B) the selected Privy/settlement-rail adapter, and (C) provider-neutral reconciliation/evidence. Each track must ship its own contract simulator and tests so progress does not depend on another track's implementation. Frontend begins only after the integrated backend contract and recovery semantics are stable. diff --git a/.agents/skills/oneshot-failure-injection/SKILL.md b/.agents/skills/oneshot-failure-injection/SKILL.md index 6ef3fc9..a37c98d 100644 --- a/.agents/skills/oneshot-failure-injection/SKILL.md +++ b/.agents/skills/oneshot-failure-injection/SKILL.md @@ -17,7 +17,7 @@ submitted, and definitely confirmed. - Deliver the same request repeatedly and from 10 parallel workers; prove at most one committed settlement. - Restart services between durable transitions and external responses. -- Delay or empty The Graph results; prove no duplicate settlement. +- Delay, empty, corrupt, or multiply-match The Graph candidate results and prove `UNKNOWN` plus no duplicate settlement. - Deny Privy policy and exceed spending amount; prove zero settlement. - Fail a supplier/API action after payment; prove settlement result remains. - Assert external settlement count, durable intent/attempt/settlement state, and diff --git a/.agents/skills/oneshot-idempotency/SKILL.md b/.agents/skills/oneshot-idempotency/SKILL.md index 38312b9..d696032 100644 --- a/.agents/skills/oneshot-idempotency/SKILL.md +++ b/.agents/skills/oneshot-idempotency/SKILL.md @@ -20,7 +20,7 @@ Read `.agent/PROJECT_CONTEXT.md`, `.agent/SECURITY_INVARIANTS.md`, and where the provider supports it. This supplements, not replaces, OneShot state. - Treat any possibly submitted but unconfirmed payment as `UNKNOWN`. Reconcile from durable/provider/Arc evidence before retrying. -- Never use Graph absence or indexing delay as permission to pay. +- Never use external-index absence or delay as permission to pay. - Keep money in integer atomic units or `bigint`; validate asset, network, recipient, amount, and Privy policy before submission. - Preserve payment results when later supplier/API work fails. diff --git a/.agents/skills/sponsor-qualification/SKILL.md b/.agents/skills/sponsor-qualification/SKILL.md index 6624883..dcae10b 100644 --- a/.agents/skills/sponsor-qualification/SKILL.md +++ b/.agents/skills/sponsor-qualification/SKILL.md @@ -1,25 +1,26 @@ --- name: sponsor-qualification -description: Validate Privy, Arc, and The Graph integration evidence before OneShot demos, releases, submissions, sponsor checklists, or qualification claims. +description: Validate selected sponsor integration evidence before OneShot demos, releases, submissions, or qualification claims. --- # Sponsor Qualification Read `.agent/SPONSOR_REQUIREMENTS.md`, `.agent/PROJECT_CONTEXT.md`, and relevant -code/tests/demo instructions. Review actual working evidence, not plans. +code, tests, and demo instructions. Review working evidence, not plans. ## Mandatory checks - Privy: prove corporate wallet authorization constrains the normal settlement path through scoped policy or spending permission. Login-only is insufficient. -- Arc: prove the demo performs a real USDC settlement on the authorized testnet. - A network label, address, explorer link, or mock alone is insufficient. -- The Graph: prove live indexed data supports recovery/history/agent decisions, - while OneShot durable state remains authoritative and empty/indexing-delayed - results cannot unlock another settlement. +- Arc: prove a real USDC settlement on Arc Testnet and, for the Launch track, + fail-closed mainnet-readiness artifacts without inventing unavailable values. +- The Graph: prove live indexed data drives hashless candidate discovery and + meaningful recovery-agent automation beyond direct known-hash lookup. Arc + verifies candidates; empty, stale, multiple, or contradictory results cannot + unlock another settlement. - Verify the demo preserves `1 intent / N attempts / <=1 settlement` and never exposes secrets. -For each sponsor, report `QUALIFIED`, `NOT QUALIFIED`, or `NOT VERIFIED`, citing -code, tests, live demo evidence, network, and known limitations. Never upgrade -missing or mocked evidence into a qualification claim. +For each selected sponsor, report `QUALIFIED`, `NOT QUALIFIED`, or +`NOT VERIFIED`, citing code, tests, live demo evidence, network, and known +limitations. Never upgrade missing or mocked evidence into qualification. \ No newline at end of file diff --git a/docs/DOMAIN_ARCHITECTURE.md b/docs/DOMAIN_ARCHITECTURE.md index c26f095..49b71e5 100644 --- a/docs/DOMAIN_ARCHITECTURE.md +++ b/docs/DOMAIN_ARCHITECTURE.md @@ -17,11 +17,11 @@ flowchart LR Worker --> Privy Privy --> Arc[Arc USDC settlement] Arc --> SupplierWallet[Supplier wallet] - Arc --> Index[The Graph index] + Arc --> Graph[The Graph candidate index] Ledger --> Recovery[Recovery service and audit view] Recovery -->|provider lookup| Privy Recovery -->|receipt and log lookup| Arc - Recovery -->|indexed history and freshness| Index + Recovery -->|candidate query and freshness| Graph Recovery --> Agent Recovery --> Operator ``` @@ -109,7 +109,7 @@ stateDiagram-v2 ``` Only the domain and PostgreSQL transition rules own these states. Privy, Arc, -The Graph, queues, and UI components report facts or perform bounded actions; +optional indexers, queues, and UI components report facts or perform bounded actions; none may reinterpret the state machine. ## Component responsibilities @@ -124,7 +124,7 @@ none may reinterpret the state machine. | Graphile Worker | Deliver execution and reconciliation jobs | Authority to pay because a job was redelivered | | Privy adapter | Wallet authorization, policy checks, provider request identity | Durable Business Intent authority | | Arc adapter | Transaction construction, submission, receipt and Transfer verification | Deciding whether another attempt is allowed | -| The Graph Subgraph/client | Indexed transfer history, deployment identity, freshness and health | Proof that an absent payment never happened | +| The Graph candidate adapter | Indexed transfer discovery, deployment identity, freshness, and health after passing the C01 value gate | Proof that an absent payment never happened | | Reconciliation engine | Combine bound evidence and emit versioned safe commands | Settlement submission | | Operator console | Explain state, evidence, policy and safe recovery actions | Force-pay or bypass controls | | Telemetry/runbooks | Reveal failures, lag, `UNKNOWN` age and safe-disable state | Secrets or mutation of financial truth | @@ -155,7 +155,7 @@ sequenceDiagram Arc-->>Worker: Final receipt and logs Worker->>Worker: Verify chain, token, recipient, amount, and Transfer Worker->>DB: Persist COMMITTED and settlement identity - Arc-->>Graph: Transfer event indexed independently + Arc-->>Graph: Transfer and correlation event are indexed independently Agent->>API: GET intent status API-->>Agent: One committed settlement with evidence ``` @@ -168,23 +168,36 @@ sequenceDiagram participant DB as PostgreSQL participant Privy participant Arc - participant Reconciler participant Graph as The Graph + participant Reconciler + participant Domain Worker->>DB: Persist SUBMITTING and request identity Worker->>Privy: Submit authorized transfer Privy->>Arc: Broadcast transaction - Arc--xWorker: Success response is lost + Arc--xWorker: Success response and hash are lost Worker->>DB: Persist UNKNOWN - Reconciler->>DB: Load intent, request identity, and observations + Reconciler->>DB: Load intent and request identity Reconciler->>Privy: Lookup original provider request - Reconciler->>Arc: Lookup exact transaction receipt and Transfer - Reconciler->>Graph: Query indexed observation plus freshness - Note over Reconciler,Graph: Graph may locate or corroborate activity but cannot authorize a retry - Reconciler->>Domain: Emit MARK_COMMITTED with expected version - Domain->>DB: Compare and set UNKNOWN to COMMITTED + Privy-->>Reconciler: Transaction hash or no usable identity + alt transaction hash recovered + Reconciler->>Arc: Verify recovered receipt and Transfer + else transaction hash missing + Reconciler->>Graph: Query memo ID or transfer tuple plus freshness + Graph-->>Reconciler: Zero, one, or multiple candidates + loop each candidate + Reconciler->>Arc: Verify receipt, Memo when used, and Transfer + end + end + Note over Reconciler,Graph: Graph discovers candidates, Arc proves, and Graph never authorizes a retry + alt exactly one bindable final match + Reconciler->>Domain: Emit MARK_COMMITTED with expected version + Domain->>DB: Compare and set UNKNOWN to COMMITTED + else no safe resolution + Reconciler->>DB: Keep UNKNOWN and record escalation evidence + end Worker->>DB: Check the same intent after redelivery - DB-->>Worker: Terminal state means no second submission + DB-->>Worker: COMMITTED or UNKNOWN means no second submission ``` ## Port and adapter boundary @@ -206,17 +219,17 @@ flowchart LR Settle --> ArcWrite[Arc write adapter] Evidence --> PrivyRead[Privy lookup] Evidence --> ArcRead[Arc receipt and log lookup] - Index --> GraphClient[Graph client] + Index --> HistoryAdapter[The Graph adapter] Privy --> External1[Privy service] ArcWrite --> External2[Arc RPC] PrivyRead --> External1 ArcRead --> External2 - GraphClient --> External3[The Graph] + HistoryAdapter --> External3[The Graph live provider] ``` The domain consumes stable result families. Adapters translate external SDK, -RPC, and GraphQL behavior into those results. External response shapes never +RPC, and Graph-query behavior into those results. External response shapes never leak into the state machine. ## A/B/C ownership and convergence @@ -242,7 +255,7 @@ flowchart TB end subgraph C[Coder C - evidence and recovery] - C1[Subgraph and health] + C1[Graph discovery and evidence strategy] C2[Reconciliation engine] C3[Failure injection] C4[Recovery service] diff --git a/milestones/CONTRACTS.md b/milestones/CONTRACTS.md index 27c6ed2..fa771bc 100644 --- a/milestones/CONTRACTS.md +++ b/milestones/CONTRACTS.md @@ -11,7 +11,7 @@ Change rule: expand-migrate-contract only - OneShot durable state grants submission ownership. - Privy authorizes and constrains the wallet action but is not the durable duplicate lock. - Arc receipt plus expected ERC-20 Transfer evidence establishes committed settlement. -- The Graph is non-authoritative recovery/history evidence. +- Direct Privy/Arc evidence resolves known transaction identities. The Graph is the selected v1 hashless candidate-discovery layer after C01; all indexed evidence remains non-authoritative. - Any possibly submitted but unconfirmed outcome is `UNKNOWN`; reconciliation precedes another submission. ## 2. Canonical identifiers and money @@ -24,11 +24,12 @@ Change rule: expand-migrate-contract only | `payload_fingerprint` | deterministic hash of normalized immutable payload | safe hash | | `amount_atomic` | canonical unsigned base-10 integer string, no sign/decimal/exponent/whitespace | safe business datum; do not over-log | | `asset` | exactly `USDC` | public | -| `network` | exactly `eip155:5042002` | public | -| `token_contract` | exactly `0x3600000000000000000000000000000000000000` | public | +| `network` | exactly the enabled Arc deployment profile; v1 live proof uses `eip155:5042002`; mainnet remains disabled until official values are pinned and human-approved | public | +| `token_contract` | exactly the enabled profile USDC interface; v1 testnet uses `0x3600000000000000000000000000000000000000`; no implicit mainnet default | public | | `recipient` | normalized EVM address; allowlist/policy checked | display only where required | | `privy_idempotency_key` | stable derivative of intent identity; same key requires same body | never log raw if classified sensitive | | `privy_reference_id` | stable lookup identity derived from intent | sanitized evidence only | +| `memo_id` | optional `bytes32` hash of the Business Intent used only when the Arc Memo path passes B01 policy validation | public correlation hash | `purpose` is a bounded, non-secret display/audit string. It participates in the immutable payload fingerprint and is redacted from routine logs by default. @@ -98,7 +99,7 @@ Results: ### IndexViewPort.lookup -Returns observations plus indexed block, block timestamp, deployment ID, chain-head comparison, lag, `hasIndexingErrors`, retrieval time, and health classification: `FRESH`, `LAGGING`, `UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. +The v1 implementation queries The Graph for candidate transfers and returns observations plus observed block/time, provider/deployment identity, chain-head comparison, lag, provider health details, retrieval time, and health classification: `FRESH`, `LAGGING`, `UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS`. No IndexViewPort result grants settlement permission. @@ -127,6 +128,7 @@ All transitions are compare-and-set with monotonic versioning. No database trans - Transactional outbox/job record. - Persisted request body fingerprint, Privy request identities, wallet/policy identity, chain/token/recipient/amount, provider transaction ID/hash/nonce when learned. - Receipt block/hash/status and verified Transfer log transaction hash plus log index. +- When enabled, Arc Memo ID, call-data hash, event log identity, and proof that the Memo and Transfer share the verified transaction. - Append-only evidence observations with source, retrieval time, block/freshness, sanitized payload or digest, and authority label. ## 8. Fixture catalog @@ -146,16 +148,18 @@ The canonical fixture root is `packages/contracts/fixtures/v1/`. Every fixture h | `settlement/lost-response.json` | `POSSIBLY_SUBMITTED` -> durable `UNKNOWN` | | `settlement/mismatched-transfer.json` | not confirmed, hold safely | | `evidence/not-found.json` | no permission change | -| `graph/empty.json` | labeled observation through indexed block, no permission change | -| `graph/lagging.json` | `LAGGING`, no permission change | -| `graph/indexing-error.json` | `UNHEALTHY`, no permission change | -| `graph/unavailable.json` | `UNAVAILABLE`, local authority still returned | +| `index/candidate-one.json` | one bindable candidate still requires Arc verification | +| `index/candidate-multiple.json` | remain `UNKNOWN`; no candidate selection by guess | +| `index/empty.json` | labeled observation through observed block, no permission change | +| `index/lagging.json` | `LAGGING`, no permission change | +| `index/provider-error.json` | `UNHEALTHY`, no permission change | +| `index/unavailable.json` | `UNAVAILABLE`, local authority still returned | ## 9. Simulator behavior - Domain simulator exposes the HTTP seam and deterministic clock/IDs with an external-submission counter. - Settlement simulator consumes canonical requests and emits each SettlementPort/EvidencePort result family without network access. -- Recovery simulator consumes local state plus provider/Arc/Graph fixtures and emits deterministic commands and labeled recovery view. +- Recovery simulator consumes local state plus Privy/Arc and Graph candidate fixtures and emits deterministic commands and a labeled recovery view. - Simulators reject unknown fixture versions and schema drift. - Simulators never silently default an unknown enum to a successful or retryable result. @@ -165,7 +169,7 @@ The canonical fixture root is `packages/contracts/fixtures/v1/`. Every fixture h 2. Worker task plus durable state and external-submission counter. 3. Adapter ports plus official-response fixtures. 4. Reconciliation command plus durable transition and evidence record. -5. Subgraph mapping/GraphQL query plus entity and `_meta` classification. +5. Graph candidate query plus deployment-specific freshness and ambiguity classification after C01. 6. Browser UI through frozen OpenAPI/mock server after Gate P4. ## 11. Compatibility and ownership diff --git a/milestones/README.md b/milestones/README.md index 357aec1..1b0a81a 100644 --- a/milestones/README.md +++ b/milestones/README.md @@ -14,7 +14,7 @@ This directory turns `plan.md` into small, independently closable work packets f - [`coder-a/`](coder-a/README.md): domain, storage, API, worker, composition, intent/status UI, operations. - [`coder-b/`](coder-b/README.md): Privy, Arc, request/receipt safety, provider ambiguity, settlement UI, sponsor evidence. -- [`coder-c/`](coder-c/README.md): Subgraph, Graph client, reconciliation, failure injection, recovery UI, qualification. +- [`coder-c/`](coder-c/README.md): The Graph candidate discovery behind a provider-neutral port, reconciliation, failure injection, recovery UI, qualification. Each lane has six ordered packets. A packet depends only on the frozen contract pack and the preceding packet in the same directory. A real package from another coder is never required for packet closure; use the checked simulator until project Gate P4. @@ -89,4 +89,4 @@ For a required contract change: 4. Let each owner migrate independently. 5. Remove the old form only in a later, separately reviewed packet. -Never reinterpret `UNKNOWN`, monetary precision, settlement ownership, or Graph authority through a compatibility shortcut. +Never reinterpret `UNKNOWN`, monetary precision, settlement ownership, or external evidence authority through a compatibility shortcut. diff --git a/milestones/coder-a/A01-foundation-contracts.md b/milestones/coder-a/A01-foundation-contracts.md index b681fd6..bfdbdeb 100644 --- a/milestones/coder-a/A01-foundation-contracts.md +++ b/milestones/coder-a/A01-foundation-contracts.md @@ -32,7 +32,7 @@ A strict, independently runnable workspace exposes the frozen contracts, OpenAPI ### A01.4 — Fixture validator - Create the v1 fixture directories and schema validation command. -- Include accepted, replay, conflict, authorization, settlement, evidence, and Graph fixture placeholders with safe synthetic values. +- Include accepted, replay, conflict, authorization, settlement, evidence, and Graph candidate fixture placeholders with safe synthetic values. - Reject unversioned, extra-sensitive, malformed, float-money, and unknown-result fixtures. ### A01.5 — Domain simulator @@ -59,4 +59,4 @@ Start A02 after A01 local review. Missing provider examples become additive fixt ## Non-goals -No PostgreSQL persistence, real worker queue, provider SDK, real settlement, Subgraph, or production UI. +No PostgreSQL persistence, real worker queue, provider SDK, real settlement, external index implementation, or production UI. diff --git a/milestones/coder-a/A02-durable-intents.md b/milestones/coder-a/A02-durable-intents.md index 9a8ee99..89c36a5 100644 --- a/milestones/coder-a/A02-durable-intents.md +++ b/milestones/coder-a/A02-durable-intents.md @@ -58,4 +58,4 @@ Start A03 with the settlement simulator. Real B output and C recovery code are n ## Non-goals -No external wallet call, Arc transaction, Graph query, or frontend. +No external wallet call, settlement-rail transaction, external-index query, or frontend. diff --git a/milestones/coder-a/A03-atomic-worker.md b/milestones/coder-a/A03-atomic-worker.md index c4a1c5a..706d3dd 100644 --- a/milestones/coder-a/A03-atomic-worker.md +++ b/milestones/coder-a/A03-atomic-worker.md @@ -57,4 +57,4 @@ Start A04 using B/C simulators. A project gate will later repeat these proofs wi ## Non-goals -No real Privy/Arc call, Graph lookup, automatic replacement, or UI. +No real Privy/settlement-rail call, external-index lookup, automatic replacement, or UI. diff --git a/milestones/coder-a/A05-frontend-intent-status.md b/milestones/coder-a/A05-frontend-intent-status.md index 8f17d96..9515d04 100644 --- a/milestones/coder-a/A05-frontend-intent-status.md +++ b/milestones/coder-a/A05-frontend-intent-status.md @@ -59,4 +59,4 @@ Start A06. Final assembly of B05/C05 is project Gate P5, not A05 closure. ## Non-goals -No settlement details, Graph timeline, visual polish campaign, or force-pay action. +No settlement details, optional history timeline, visual polish campaign, or force-pay action. diff --git a/milestones/coder-a/A06-release-operations.md b/milestones/coder-a/A06-release-operations.md index 16e68bd..3b9afdb 100644 --- a/milestones/coder-a/A06-release-operations.md +++ b/milestones/coder-a/A06-release-operations.md @@ -7,7 +7,7 @@ Project convergence: Gate P6 ## Outcome -The authoritative-state and operations portion of the demo is repeatable from a clean testnet environment and produces sanitized evidence for release review. +The authoritative-state and operations portion of the demo is repeatable from a clean testnet environment, includes a disabled mainnet-ready deployment profile, and produces sanitized release evidence. ## Small tasks @@ -32,7 +32,12 @@ The authoritative-state and operations portion of the demo is repeatable from a - Finalize architecture, API/worker operation, migrations, debugging, recovery escalation, and known limitations. - Link exact B/C evidence slots without copying secrets or raw provider responses. -### A06.5 — Candidate verification +### A06.5 — Mainnet-readiness package + +- Validate the disabled Arc Mainnet profile schema, deployment manifest, safe-disable, rollback, and environment separation without sending a transaction. +- Document the human gate for pinning official chain/token values and activating a limited real-value pilot. + +### A06.6 — Candidate verification - Run root quality, migration, matrix, browser, secret, and intended-file checks against the exact candidate. - Prepare concise release evidence for mandatory independent review and human merge. @@ -43,10 +48,11 @@ The authoritative-state and operations portion of the demo is repeatable from a - Every scripted money/retry case includes durable state and settlement count. - Safe disable halts new submissions and retains recovery visibility. - Evidence contains no credentials, private wallet material, or sensitive provider payloads. +- Mainnet readiness fails closed while official values or human approval are absent, and requires no domain redesign once supplied. ## Handoff artifact -Publish the operations runbook, invariant scenario runner, sanitized result table, architecture/API links, and release checklist. +Publish the operations runbook, invariant scenario runner, sanitized result table, architecture/API links, mainnet-readiness manifest, rollback procedure, and release checklist. ## No-wait continuation @@ -54,4 +60,4 @@ A06 closes independently. Gate P6 composes exact reviewed A06/B06/C06 artifacts; ## Non-goals -No mainnet readiness claim, production compliance certification, or agent-performed merge. +No real mainnet transaction, production compliance certification, or agent-performed merge. diff --git a/milestones/coder-b/B01-sdk-network-compatibility.md b/milestones/coder-b/B01-sdk-network-compatibility.md index 6bcd564..2e865ab 100644 --- a/milestones/coder-b/B01-sdk-network-compatibility.md +++ b/milestones/coder-b/B01-sdk-network-compatibility.md @@ -17,25 +17,35 @@ A package-local spike pins compatible Privy and Ethereum tooling, validates Arc - Pin exact versions only after request-signing and Arc chain support compile/run in an isolated spike. - Record rejected combinations and upgrade constraints. -### B01.2 — Arc constants +### B01.2 — Arc deployment profiles -- Encode chain ID `5042002`, CAIP-2 `eip155:5042002`, RPC/explorer configuration, ERC-20 USDC address, and six decimals. -- Separate ERC-20 settlement amounts from native USDC gas accounting. -- Reject runtime overrides that silently change network, token, or precision. +- Encode the enabled Arc Testnet chain ID `5042002`, CAIP-2 `eip155:5042002`, RPC/explorer configuration, official USDC interface, and precision. +- Define the same typed profile for Arc Mainnet with no guessed defaults; keep it disabled until official values are published, pinned, probed, and human-approved. +- Separate settlement amounts from native USDC gas accounting and reject silent network/token/precision overrides. -### B01.3 — Configuration schema +### B01.3 — Memo and policy compatibility spike + +- Probe the official Arc Memo contract identity and ABI without assuming it is + safe for the settlement path. +- Test whether Privy policy decoding can constrain the Memo function, forwarded + USDC target, recipient/amount-bearing calldata, chain, and zero native value. +- Record `SUPPORTED` only with deny fixtures for every wrong dimension. If the + nested call cannot be constrained, retain direct transfer and tuple/window + discovery or propose a narrow typed settlement contract. + +### B01.4 — Configuration schema - Classify each variable as public, secret, optional, or human-only. - Validate wallet, policy, network, token, recipient allowlist, cap, RPC, timeout, and feature switches. - Produce safe `.env.example` entries with placeholders only. -### B01.4 — Readiness probe library +### B01.5 — Readiness probe library - Assert RPC chain ID and bytecode at the configured token contract. - Validate expected wallet/policy identity format without printing credentials. - Classify unavailable versus identity mismatch; mismatch fails closed. -### B01.5 — Fixture capture boundary +### B01.6 — Fixture capture boundary - Define sanitized official-response fixture wrappers and redaction tests. - Prohibit headers, tokens, signatures, key material, and raw authorization responses from fixtures/logs. @@ -43,13 +53,13 @@ A package-local spike pins compatible Privy and Ethereum tooling, validates Arc ## Acceptance evidence - Package install, lint, type, unit, and build pass independently. -- Wrong chain, missing bytecode, wrong token, invalid recipient/cap, or policy mismatch fails readiness. +- Wrong chain, missing bytecode, wrong token, invalid recipient/cap, policy mismatch, incomplete mainnet profile, or unapproved activation fails readiness. - No credential is needed for offline checks; network probes are explicitly separate. - Version decision and upgrade risks are documented. ## Handoff artifact -Publish `settlement-config-v1`, pinned dependency rationale, Arc constants, readiness simulator/fixtures, redaction test, and package-local commands. +Publish `settlement-config-v1`, pinned dependency rationale, Arc testnet/mainnet profile schema, readiness simulator/fixtures, redaction test, and package-local commands. ## No-wait continuation diff --git a/milestones/coder-b/B02-request-policy-receipt.md b/milestones/coder-b/B02-request-policy-receipt.md index d799794..7380f2b 100644 --- a/milestones/coder-b/B02-request-policy-receipt.md +++ b/milestones/coder-b/B02-request-policy-receipt.md @@ -11,11 +11,13 @@ Pure adapter logic builds one byte-stable ERC-20 request, expresses the expected ## Small tasks -### B02.1 — ERC-20 calldata builder +### B02.1 — Correlated USDC calldata builder -- Encode `transfer(address,uint256)` for the normalized recipient and `bigint` amount. -- Require exact chain/token/method, zero native transaction value, and six-decimal semantic boundary. -- Add golden calldata and request-fingerprint vectors. +- Encode the direct `transfer(address,uint256)` fallback and, when B01 marks it + policy-safe, the Arc Memo forwarded call with `memoId = hash(business_intent_id)`. +- Require exact chain/token/method, recipient, amount, zero native transaction + value, and six-decimal semantic boundary. +- Add golden transfer, memo, call-data-hash, and request-fingerprint vectors. ### B02.2 — Privy request identity @@ -58,4 +60,4 @@ Start B03 in offline mode. Human provisioning may happen asynchronously. ## Non-goals -No production credentials, domain state mutation, Graph query, or frontend. +No production credentials, domain state mutation, external-index query, or frontend. diff --git a/milestones/coder-b/B03-live-settlement-harness.md b/milestones/coder-b/B03-live-settlement-harness.md index 2936cd3..e9d8e3e 100644 --- a/milestones/coder-b/B03-live-settlement-harness.md +++ b/milestones/coder-b/B03-live-settlement-harness.md @@ -62,4 +62,4 @@ Mark B03 `DONE` when offline criteria pass, even if live setup is pending. Start ## Non-goals -No mainnet, automatic funding, unattended policy mutation, domain database write, or qualification claim from fixtures alone. +No real mainnet transaction, automatic funding, unattended policy mutation, domain database write, or qualification claim from fixtures alone. diff --git a/milestones/coder-b/B04-ambiguity-integration.md b/milestones/coder-b/B04-ambiguity-integration.md index 5344ced..72b1fb2 100644 --- a/milestones/coder-b/B04-ambiguity-integration.md +++ b/milestones/coder-b/B04-ambiguity-integration.md @@ -58,4 +58,4 @@ B04 closes against the contract host. Do not start production frontend until P4. ## Non-goals -No reconciliation decision, Graph authority, automatic transaction replacement, or UI. +No reconciliation decision, external-index authority, automatic transaction replacement, or UI. diff --git a/milestones/coder-b/B06-sponsor-evidence.md b/milestones/coder-b/B06-sponsor-evidence.md index 13975e7..42b8fa5 100644 --- a/milestones/coder-b/B06-sponsor-evidence.md +++ b/milestones/coder-b/B06-sponsor-evidence.md @@ -7,7 +7,7 @@ Project convergence: Gate P6 ## Outcome -A sanitized, repeatable evidence bundle demonstrates Privy as the real authorization boundary and Arc Testnet as the real USDC settlement rail, with limitations stated honestly. +A sanitized, repeatable evidence bundle demonstrates Privy as the real authorization boundary and Arc Testnet as the working USDC settlement rail and proves the disabled Arc Mainnet profile is deployment-ready without claiming a real mainnet transaction. ## Small tasks @@ -26,12 +26,17 @@ A sanitized, repeatable evidence bundle demonstrates Privy as the real authoriza - Intentionally lose the local success response after possible submission. - Show B adapter reports ambiguity and evidence lookup locates the original transaction without submitting another. -### B06.4 — Sanitization audit +### B06.4 — Mainnet-readiness evidence + +- Validate the production profile, official-value placeholders, deployment/preflight commands, safe-disable, and rollback without broadcasting to mainnet. +- Record the human approval and official-value gates that prevent accidental activation. + +### B06.5 — Sanitization audit - Review screenshots, logs, fixtures, commands, and docs for keys, tokens, signatures, private wallet data, raw authorization responses, and environment contents. - Retain only public/sanitized testnet identifiers. -### B06.5 — Qualification input +### B06.6 — Qualification input - Provide code, test, live-demo, network, transaction, policy, and limitation references for `sponsor-qualification`. - Use `NOT VERIFIED` when live proof is missing; never promote fixtures into qualification. @@ -42,10 +47,11 @@ A sanitized, repeatable evidence bundle demonstrates Privy as the real authoriza - Arc evidence proves a real final ERC-20 transfer, not only a label or explorer screenshot. - Repeated demo/reset does not create an unintended second settlement. - Bundle passes secret/redaction and reproducibility checks. +- Mainnet profile remains disabled when official values or human approval are absent. ## Handoff artifact -Publish sanitized Privy/Arc evidence index, exact demo commands, transaction/policy references, denial table, and limitation statement. +Publish sanitized Privy/Arc evidence index, exact demo commands, transaction/policy references, denial table, mainnet-readiness evidence, and limitation statement. ## No-wait continuation @@ -53,4 +59,4 @@ B06 closes independently. Gate P6 consumes its exact reviewed bundle alongside A ## Non-goals -No mainnet claim, wallet-key export, external-account mutation by an agent, or final sponsor verdict for The Graph. +No claim of a completed mainnet transaction, wallet-key export, external-account mutation by an agent, or final sponsor verdict for The Graph. diff --git a/milestones/coder-c/C01-recovery-evidence-strategy.md b/milestones/coder-c/C01-recovery-evidence-strategy.md new file mode 100644 index 0000000..4e34efa --- /dev/null +++ b/milestones/coder-c/C01-recovery-evidence-strategy.md @@ -0,0 +1,67 @@ +# C01 — Recovery Evidence Strategy + +Owner: Coder C +Branch: `milestone/c01-recovery-evidence-strategy` +Depends on: frozen `milestones/CONTRACTS.md` only +Next: C02 immediately after closure + +## Outcome + +A provider-neutral recovery evidence contract proves the known-identity +Privy/Arc baseline and validates The Graph as the selected hashless +candidate-discovery layer. Arc remains authoritative; a failed live Graph value +gate removes the Graph claim and selects the direct-recovery fallback. + +## Small tasks + +### C01.1 — Required evidence baseline + +- Model persisted OneShot identity, Privy request lookup, exact selected-rail + transaction/receipt evidence, observed position, finality, retrieval time, + and evidence binding. +- Keep all payment authority outside the Graph candidate view. + +### C01.2 — Indexer removal/value test + +- Compare The Graph with no-index, direct Arc event search, and enhanced RPC by + lost-hash discovery, freshness, testnet/mainnet support, + operational dependency, reuse, and sponsor leverage. +- Retain The Graph only if removing it breaks automatic hashless recovery or a + named recovery-agent decision instead of merely removing a dashboard query. + +### C01.3 — Graph candidate and correlation contract + +- Define Graph observations, provider/deployment identity, observed-through + block/time, lag, health, retrieval time, candidate count, and contradiction. +- Model tuple/window lookup and the preferred Arc Memo `memoId` correlation; + distinguish empty or multiple candidates from authoritative non-payment. + +### C01.4 — Fixtures and simulator + +- Cover fresh, empty, lagging, unhealthy, unavailable, duplicate, out-of-order, + and contradictory results without selecting a vendor in domain code. +- Add provider-specific mapping tests only after the decision record selects an + implementation. + +## Acceptance evidence + +- Known-identity recovery remains safe with The Graph disabled; automatic + hashless discovery is explicitly unavailable in that fallback. +- No Graph result grants settlement permission. +- Live evidence shows whether The Graph finds the lost-hash candidate, how + freshness and multiple matches behave, and what capability removal loses. +- All fixtures run without network access or credentials. + +## Handoff artifact + +Publish `index-view-v1`, the baseline recovery evidence schema, removal/value +matrix, decision record, simulator fixtures, and package-local checks. + +## No-wait continuation + +Start C02 with the provider-neutral evidence contract and recorded decision. + +## Non-goals + +No settlement submission, database authority, mandatory third-party indexer, +sponsor claim, or production UI. \ No newline at end of file diff --git a/milestones/coder-c/C01-subgraph-index-health.md b/milestones/coder-c/C01-subgraph-index-health.md deleted file mode 100644 index e38f359..0000000 --- a/milestones/coder-c/C01-subgraph-index-health.md +++ /dev/null @@ -1,60 +0,0 @@ -# C01 — Subgraph Mapping and Index Health - -Owner: Coder C -Branch: `milestone/c01-subgraph-index-health` -Depends on: frozen `milestones/CONTRACTS.md` only -Next: C02 immediately after closure - -## Outcome - -A standalone Subgraph maps Arc USDC Transfer fixtures, and a Graph client returns freshness-labeled observations including `_meta`, deployment, lag, and indexing health. - -## Small tasks - -### C01.1 — Subgraph schema - -- Define transfer entity identity as transaction hash plus log index. -- Store sender, recipient, Graph `BigInt` amount, transaction hash, log index, block number, and block timestamp. -- Document public/sanitized fields and immutable IDs. - -### C01.2 — Manifest and mapping - -- Target Arc Testnet and the exact ERC-20 USDC Transfer event. -- Map duplicate/out-of-order fixture events deterministically. -- Reject assumptions that one transaction has only one log. - -### C01.3 — Mapping tests - -- Add Matchstick/unit fixtures for normal, multiple-log, duplicate delivery, wrong contract/topic, zero/large amount, and ordering behavior. -- Assert exact decimal-string/BigInt preservation. - -### C01.4 — Graph query client - -- Query transfers plus `_meta` block, deployment identity, timestamp, and `hasIndexingErrors`. -- Compare indexed block with chain head supplied through an injectable seam. -- Validate all untrusted GraphQL output. - -### C01.5 — Freshness classifier - -- Emit `FRESH`, `LAGGING`, `UNHEALTHY`, `UNAVAILABLE`, or `UNKNOWN_FRESHNESS` with observed-through bounds. -- Make empty data distinct from authoritative non-payment. -- Add simulator fixtures for every health/result combination. - -## Acceptance evidence - -- Subgraph tests run without network or credentials. -- Identity remains transaction hash plus log index and amount never becomes a JS float. -- Missing `_meta`, indexing errors, head-query failure, or excessive lag is visibly non-fresh. -- Empty result says only “not observed through block N” and grants no permission. - -## Handoff artifact - -Publish `index-view-v1`, schema/manifest digest, mapping fixture pack, Graph query schema, freshness simulator, and package-local commands. - -## No-wait continuation - -Start C02 with synthetic local/Privy/Arc evidence. A/B packages and live deployment are not required. - -## Non-goals - -No durable state authority, settlement submission, provider wallet operation, or UI. diff --git a/milestones/coder-c/C02-reconciliation-engine.md b/milestones/coder-c/C02-reconciliation-engine.md index baf68af..1d85c56 100644 --- a/milestones/coder-c/C02-reconciliation-engine.md +++ b/milestones/coder-c/C02-reconciliation-engine.md @@ -7,7 +7,7 @@ Next: C03 immediately after closure ## Outcome -A pure decision engine combines authoritative local/Arc evidence, provider lookup, and non-authoritative Graph observations to emit safe reconciliation commands and a provenance-labeled recovery view. It can never submit payment. +A pure decision engine combines authoritative local/Arc evidence, provider lookup, and non-authoritative Graph candidate observations to emit safe reconciliation commands and a provenance-labeled recovery view. It can never submit payment. ## Small tasks @@ -19,7 +19,7 @@ A pure decision engine combines authoritative local/Arc evidence, provider looku ### C02.2 — Precedence table - Make durable committed record and exact verified Arc receipt authoritative. -- Use Privy status to locate provider activity and The Graph only to corroborate/explain. +- Use Privy status and direct Arc evidence to resolve the original activity; use The Graph only to locate, corroborate, or explain. - Encode contradictory, stale, missing, and unavailable combinations explicitly. ### C02.3 — Reconciliation commands @@ -43,7 +43,7 @@ A pure decision engine combines authoritative local/Arc evidence, provider looku - Verified matching success resolves `UNKNOWN -> COMMITTED`. - Matching final revert/no-effect proof may resolve `UNKNOWN -> FAILED_SAFE`. -- Pending, not found, unavailable, empty/lagging/unhealthy Graph, mismatch, or contradiction remains `UNKNOWN`. +- Pending, not found, unavailable, empty/lagging/unhealthy Graph candidates, mismatch, or contradiction remains `UNKNOWN`. - Every decision explains authority and provenance without leaking raw sensitive data. - Package imports no A/B implementation and contains no SettlementPort call. @@ -57,4 +57,4 @@ Start C03 using the local state and provider simulators from the frozen pack. ## Non-goals -No direct database mutation, queue ownership, settlement submission, live Graph requirement, or frontend. +No direct database mutation, queue ownership, settlement submission, live external-index requirement, or frontend. diff --git a/milestones/coder-c/C03-failure-injection.md b/milestones/coder-c/C03-failure-injection.md index 57d403d..ca76416 100644 --- a/milestones/coder-c/C03-failure-injection.md +++ b/milestones/coder-c/C03-failure-injection.md @@ -19,7 +19,7 @@ A deterministic chaos harness proves that crashes, lost responses, duplicate/out ### C03.2 — Graph degradation suite -- Delay/empty results, trail chain head, set indexing errors, omit `_meta`, fail query, return duplicates/out-of-order events, and switch deployment identity. +- Delay/empty results, trail chain head, set provider health errors, omit freshness metadata, fail query, return duplicates/out-of-order events, and switch deployment identity. - Assert health labels and no permission change. ### C03.3 — Provider/RPC contradiction suite diff --git a/milestones/coder-c/C04-recovery-matrix-integration.md b/milestones/coder-c/C04-recovery-matrix-integration.md index 017071a..5c5dfea 100644 --- a/milestones/coder-c/C04-recovery-matrix-integration.md +++ b/milestones/coder-c/C04-recovery-matrix-integration.md @@ -36,19 +36,19 @@ The recovery service composes frozen local-state, provider/Arc, and Graph simula ### C04.5 — Gate P4 replacement guide - Document exact simulator-to-reviewed-package replacement points. -- Define live Graph deployment checks, lag thresholds, expected package versions, and rollback to safe simulator/read-only mode. +- Define checks, lag thresholds, expected package versions, and safe-disable behavior for a Graph deployment; keep the no-index baseline runnable. ## Acceptance evidence - Package-local lint/type/test/build and full fixture matrix pass. - Reconciliation retries are idempotent and zero-submit by construction. - Recovery view always distinguishes authority and observation freshness. -- Contract mismatch, missing `_meta`, raw provider payload, and unknown enum fail closed. +- Contract mismatch, missing freshness metadata, raw provider payload, and unknown enum fail closed. - Packet closes with simulators; live gaps are explicit Gate P4 items. ## Handoff artifact -Publish recovery service package, evidence command pack, matrix report, simulator lock, live replacement guide, and Graph deployment checklist. +Publish recovery service package, evidence command pack, matrix report, simulator lock, live replacement guide, and Graph decision and deployment checklist. ## No-wait continuation @@ -56,4 +56,4 @@ C04 is `DONE` on simulator proof. Do not start production frontend until P4. Whi ## Non-goals -No production frontend, direct settlement, Graph-based authorization, or sponsor qualification from offline data. +No production frontend, direct settlement, index-based authorization, or sponsor qualification from offline data. diff --git a/milestones/coder-c/C05-frontend-recovery.md b/milestones/coder-c/C05-frontend-recovery.md index 8bf8e1b..f590340 100644 --- a/milestones/coder-c/C05-frontend-recovery.md +++ b/milestones/coder-c/C05-frontend-recovery.md @@ -1,4 +1,4 @@ -# C05 — Frontend Recovery Timeline and Indexed History +# C05 — Frontend Recovery Timeline and Evidence History Owner: Coder C Branch: `milestone/c05-frontend-recovery` @@ -22,12 +22,12 @@ An independently composable recovery slice shows authoritative state, attempts, ### C05.2 — Evidence provenance -- Label local, Privy, Arc, and Graph sources plus authority class. +- Label local, Privy, Arc, and The Graph source plus authority class. - Show verified transaction binding and contradiction warnings without raw sensitive payloads. -### C05.3 — Graph freshness +### C05.3 — Graph freshness and candidate state -- Display deployment, indexed-through block/time, chain-head lag, health, indexing errors, and unavailable state. +- When enabled, display provider/deployment identity, observed-through block/time, chain-head lag, health errors, and unavailable state; hide the section cleanly when the C01 fallback disables Graph. - Empty result reads “not observed through block N,” never “not paid.” ### C05.4 — UNKNOWN experience diff --git a/milestones/coder-c/C06-qualification-demo.md b/milestones/coder-c/C06-qualification-demo.md index 29c5eca..d585350 100644 --- a/milestones/coder-c/C06-qualification-demo.md +++ b/milestones/coder-c/C06-qualification-demo.md @@ -1,4 +1,4 @@ -# C06 — The Graph, Recovery, and Qualification Bundle +# C06 — Graph Discovery and Recovery Qualification Bundle Owner: Coder C Branch: `milestone/c06-qualification-demo` @@ -7,23 +7,33 @@ Project convergence: Gate P6 ## Outcome -A repeatable recovery demo proves live indexed Arc observations add useful history/recovery context while degraded Graph states remain non-authoritative, and it supplies evidence-based sponsor qualification inputs. +A repeatable recovery demo proves The Graph can discover a candidate after the +transaction hash is lost, Arc can verify the exact final transfer, and OneShot +can resolve or safely hold `UNKNOWN` without a second payment. ## Small tasks -### C06.1 — Live index health +### C06.1 — Live recovery evidence -- Query the pinned live Arc Testnet deployment with `_meta`, deployment ID, indexed block/time, chain head, lag, and indexing errors. -- Record sanitized endpoint/deployment evidence and freshness threshold. +- Place the fault injector after Privy/Arc broadcast and before the adapter + returns to OneShot. Swallow the successful response and transaction hash so + the chain receives the real payment while the durable intent records only + `UNKNOWN`; do not delete a hash that OneShot already persisted. +- Query the original Privy request; deliberately exercise the branch where no transaction hash is recovered. +- Query live The Graph data for candidate transfers and record sanitized deployment, observed block, lag, health, and candidate count. +- Verify the selected candidate through exact Arc Testnet receipt/log evidence. ### C06.2 — Recovery story -- Show one exact transaction in durable/Privy/Arc evidence and indexed history. -- Demonstrate `UNKNOWN` reconciliation to the original transaction with no new submission. +- Show The Graph discovering the candidate, Arc proving it, and OneShot deciding the durable transition. +- Show the operator view before recovery with no transaction hash, then after + recovery with the discovered hash, exact transfer evidence, and unchanged + Business Intent identity. +- Demonstrate zero, stale, multiple, and contradictory candidates staying `UNKNOWN` with no new submission. -### C06.3 — Degraded index story +### C06.3 — Graph removal and degradation story -- Run delayed, empty, unhealthy, unavailable, missing `_meta`, and contradictory fixtures against the same recovery UI/engine. +- Run recovery with The Graph disabled, then delayed, empty, unhealthy, unavailable, missing freshness metadata, and returning multiple/contradictory candidates. - Show safe hold/escalation and accurate observed-through language. ### C06.4 — Audit and repeatability @@ -34,19 +44,19 @@ A repeatable recovery demo proves live indexed Arc observations add useful histo ### C06.5 — Sponsor qualification - Run `sponsor-qualification` against actual code, tests, live demo, network, deployment, and known limitations. -- Report Privy, Arc, and The Graph individually as `QUALIFIED`, `NOT QUALIFIED`, or `NOT VERIFIED`. +- Report Privy, Arc, and The Graph individually as `QUALIFIED`, `NOT QUALIFIED`, or `NOT VERIFIED`; target the Graph AI Tooling or AI Use Case track only. - Never treat plans, mocks, variables, labels, or dependency declarations as proof. ## Acceptance evidence -- Live indexed data is demonstrably used for recovery/history or agent decision support. +- Live The Graph data demonstrably enables hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup. - OneShot remains authoritative and Graph degradation never unlocks settlement. - Demo is repeatable and evidence is sanitized. - Qualification verdicts cite concrete code, test, and live evidence or honestly remain `NOT VERIFIED`. ## Handoff artifact -Publish Graph/recovery evidence index, live health snapshot, degraded-state matrix, demo steps, qualification report, and limitations. +Publish recovery evidence index, Graph deployment/health/value snapshot, degraded-state matrix, demo steps, qualification report, and limitations. ## No-wait continuation @@ -54,4 +64,4 @@ C06 closes independently. Gate P6 composes exact reviewed A06/B06/C06 bundles; a ## Non-goals -No Graph authority claim, production SLA, mainnet evidence, external mutation by an agent, or agent-performed merge. +No index authority claim, production SLA, real mainnet transaction, external mutation by an agent, or agent-performed merge. diff --git a/milestones/coder-c/README.md b/milestones/coder-c/README.md index 28b89d2..6677c12 100644 --- a/milestones/coder-c/README.md +++ b/milestones/coder-c/README.md @@ -1,22 +1,28 @@ -# Coder C Lane — Reconciliation and Indexed Recovery +# Coder C Lane — Reconciliation and Recovery Evidence -Mission: index Arc transfer observations, classify Graph health/freshness, reconcile ambiguous settlement evidence without submitting payments, build failure-injection proof, render recovery UI, and assemble qualification evidence. +Mission: implement The Graph as the hashless candidate-discovery path behind a +provider-neutral contract, reconcile ambiguous settlement evidence without +submitting payments, build failure-injection proof, render recovery UI, and +assemble qualification evidence. -Stay inside C-owned paths. The reconciliation package emits frozen commands; it never writes A’s tables directly and never calls SettlementPort. +Stay inside C-owned paths. The reconciliation package emits frozen commands; it +never writes A’s tables directly and never calls SettlementPort. ## Technology focus -The Graph Subgraph stack, `graph-cli`, AssemblyScript mappings, GraphQL, -Matchstick, `viem` read paths, Vitest, deterministic failure injection, and -React/Vite recovery components. +Provider-neutral evidence contracts, `viem` read models, Vitest, deterministic +failure injection, React/Vite recovery components, and a GraphQL/Subgraph +adapter admitted only after C01 proves live discovery and safe degradation. ## Sequence -1. [C01 — Subgraph and index health](C01-subgraph-index-health.md) +1. [C01 — Recovery evidence strategy](C01-recovery-evidence-strategy.md) 2. [C02 — Reconciliation engine](C02-reconciliation-engine.md) 3. [C03 — Failure injection](C03-failure-injection.md) 4. [C04 — Recovery matrix and integration](C04-recovery-matrix-integration.md) 5. [C05 — Frontend recovery](C05-frontend-recovery.md), held until project Gate P4 6. [C06 — Qualification demo](C06-qualification-demo.md) -C01–C04 close against frozen local/provider/Graph fixtures. A/B implementations and a deployed live Subgraph are project-gate evidence, not reasons to stop local progress. +C01–C04 close against frozen local, Privy, Arc, and Graph fixtures. +A/B implementations and live Graph evidence are project-gate inputs, +not reasons to stop local progress. \ No newline at end of file diff --git a/plan.md b/plan.md index a82d07d..6847e67 100644 --- a/plan.md +++ b/plan.md @@ -1,6 +1,6 @@ # OneShot Product Delivery Plan -Status: production MVP roadmap +Status: working testnet MVP and mainnet-readiness roadmap Team: exactly three coders Implementation base: the human-approved commit containing this plan Research basis: `.agent/research/20260906-integration-decisions.md` @@ -36,11 +36,107 @@ Business Intent contract. 5. Arc settles the payment. OneShot verifies the receipt and expected ERC-20 Transfer before recording `COMMITTED`. 6. A timeout, crash, or lost response becomes durable `UNKNOWN`. Reconciliation - looks up the original Privy and Arc activity; The Graph adds indexed history, - freshness, and recovery context. + first asks Privy for the original transaction identity. When the hash is + missing, The Graph searches live indexed transfers for candidates; Arc then + verifies each candidate receipt and exact Transfer. No candidate, multiple + candidates, stale data, or contradiction leaves the intent `UNKNOWN`. 7. Repeated HTTP requests, queue deliveries, processes, or agents return the same Business Intent and cannot create a second committed settlement. +## Sponsor and product configuration + +The primary product configuration is **Privy + Arc + The Graph**: + +- Privy authorizes and constrains the corporate wallet action. +- The Graph discovers candidate transfers when a successful submission lost its + transaction hash or provider response. +- Arc verifies the candidate receipt and exact USDC `Transfer`. +- OneShot and PostgreSQL alone decide the durable state transition. + +This is a provisional implementation choice with a hard C01 evidence gate. The +Graph is load-bearing for automatic hashless discovery, but never becomes +settlement authority. If C01 cannot demonstrate live candidate discovery beyond +direct lookup, remove the Graph claim and ship the Privy + Arc fallback. + +| Configuration | Product meaning | Decision | +| --- | --- | --- | +| Privy + Arc + The Graph | Authorized payment, hashless candidate discovery, authoritative chain verification | Primary build; target Best AI Tooling or AI Use Case with The Graph | +| Privy + Arc | Safe settlement and known-identity recovery without automatic indexed discovery | Fallback if C01 fails | +| Privy + Hedera + x402/Blocky402 | One paid API call produces at most one Hedera settlement | Coherent alternative rail; select before P0 instead of dual-chain MVP | +| Hedera configuration + Bazantic | Publishes the finished OneShot API as an agent-usable recipe/gateway | Optional third sponsor only after the core paid-request flow works | +| Privy + Uniswap | Changes the vertical to one trading intent producing one swap | Separate trading pivot, not an additive sponsor | +| Privy + Arc + confidential workflow | Protects private policy or routing inputs | Optional only if confidentiality becomes a core user requirement | + +The Graph submission targets the AI Tooling or AI Use Case track. One custom +Subgraph does not satisfy the Composable/Standardized track. The recovery agent +uses live Graph data to choose and explain candidates; deterministic Arc checks +and the OneShot state machine retain all financial authority. + +### Settlement-rail and data migration options + +The Business Intent, PostgreSQL authority, atomic ownership, queue, `UNKNOWN` +state, reconciliation policy, and operator experience remain stable. A rail or +index change occurs behind frozen ports and never changes payment cardinality. + +| Option | What changes | What stays | Sponsor/product fit | Selection rule | +| --- | --- | --- | --- | --- | +| Arc with The Graph | Deploy a live transfer index and recovery-agent query behind `IndexViewPort` | PostgreSQL and exact Arc evidence remain authoritative | Strong Privy + Arc + Graph story | Primary when C01 proves hashless discovery and live sponsor eligibility | +| Arc with direct Privy/RPC evidence | Remove Graph deployment and automatic indexed search | Entire safety invariant and known-hash/provider-ID recovery | Strong Privy + Arc fallback | Use when Graph adds no demonstrated recovery value | +| Arc with managed RPC history | Replace the Graph adapter | Direct evidence remains authoritative | Operational alternative; no Graph sponsor claim | Use when it materially outperforms direct RPC and sponsor value is irrelevant | +| Arc with OneShot Router contract | Submit through a small contract that binds an intent ID and emits a canonical event | Business Intent and Privy policy stay central | Stronger Arc-native audit and unique lookup | Select only if the team accepts the added contract surface | +| Hedera with Privy and x402/Blocky402 | Replace Arc request, receipt, token, network, and evidence adapters; add a live x402 service and consumer | Domain ledger, PostgreSQL locks, queue, ambiguity rules, and UI model stay | Direct match for Hedera AI & Agentic Payments plus Privy B2B financial product | Serious alternative; choose before implementation freeze, not as a second MVP rail | +| Privy with Uniswap | Replace payment obligation semantics with quote, slippage, deadline, and swap outcome | Some idempotency infrastructure can be reused | Uniswap trading product | Separate product branch | + +```mermaid +flowchart TB + P0{Choose one settlement product before P0} + P0 --> ArcPath[Primary Arc USDC product] + P0 --> HederaPath[Alternative Hedera x402 product] + ArcPath --> Graph[The Graph candidate discovery] + Graph --> ArcProof[Direct Arc receipt and Transfer proof] + HederaPath --> Blocky[Blocky402 facilitator] + Blocky --> HederaEvidence[Hedera transaction or Mirror Node evidence] + ArcProof --> Core[Shared OneShot domain and PostgreSQL authority] + HederaEvidence --> Core +``` + +```mermaid +flowchart LR + Unknown[UNKNOWN after lost response] --> Provider{Privy returns original hash} + Provider -->|yes| Verify[Verify on Arc] + Provider -->|no| Discover[The Graph searches wallet, recipient, amount, and block window] + Discover --> Candidates{Candidate set} + Candidates -->|one bindable candidate| Verify + Candidates -->|none, many, stale, or contradictory| Hold[Remain UNKNOWN and escalate] + Verify -->|exact final Transfer| Commit[COMMITTED] + Verify -->|not safely resolved| Hold +``` + +The Graph discovers candidates, not truth. Arc RPC can also scan logs without a +hash, so Graph is not mathematically indispensable; it is the selected product +dependency for fast, structured, automatic recovery. Empty, lagging, unhealthy, +or multiple candidate results keep the intent `UNKNOWN`. + +The preferred correlation spike uses Arc's official Memo contract: +`memoId = hash(business_intent_id)`. The Graph indexes the Memo event and linked +USDC Transfer, then Arc verifies their shared transaction and exact calldata. +B01 must prove Privy policy can restrict the Memo destination, forwarded USDC +target, and required business parameters. If it cannot, preserve the stricter +policy and use tuple/window candidate search for the demo or a narrow typed +settlement contract; never weaken authorization to obtain a cleaner lookup. + +For the Hedera option, `x402` and Blocky402 are part of the required payment +flow, not a decorative third sponsor. Privy remains the wallet authorization +boundary only after B01 proves the chosen Privy wallet and policy path against +Hedera's EVM interface. Bazantic is the closest optional third sponsor after +the core flow works; it must not replace Blocky402 settlement or turn the +project into an MCP-only submission. + +If Hedera is selected, A01-A06 remain intact. Before P0, replace the Arc-specific +B01-B06 contracts and rail labels in C01-C06 with Hedera x402, Blocky402, and +transaction/Mirror Node evidence variants. Preserve packet IDs, port meanings, +gates, and the cardinality invariant. + ## Product surfaces | Surface | User | Purpose | @@ -62,11 +158,11 @@ flowchart LR Worker -->|authorized transfer request| Privy Privy -->|ERC-20 USDC transaction| Arc[Arc] Arc -->|one settlement| SupplierWallet[Supplier wallet] - Arc --> Graph[The Graph index] + Arc --> History[The Graph candidate index] DB --> Recovery[Recovery service and view] Recovery -->|provider lookup| Privy Recovery -->|receipt and log lookup| Arc - Recovery -->|indexed history and freshness| Graph + Recovery -->|candidate query and freshness| History Recovery --> Agent Recovery --> Company ``` @@ -77,7 +173,7 @@ contract. ## Production roadmap model -- The roadmap targets a production-quality testnet MVP, not a disposable demo. +- The roadmap targets a working Arc Testnet product plus a mainnet-ready deployment path. - Work is ordered by domain dependencies and evidence gates. - A, B, and C progress independently inside frozen contracts and converge only through reviewed package entry points, fixtures, and simulators. @@ -88,7 +184,7 @@ contract. ## 1. Mission and v1 release -Deliver a testnet application that accepts one approved Business Intent, safely survives retries, crashes, duplicate delivery, parallel workers, and ambiguous provider responses, and produces at most one committed ERC-20 USDC settlement on Arc Testnet through a Privy-controlled corporate wallet. The Graph supplies live indexed recovery and history evidence without becoming settlement authority. +Deliver a working application that accepts one approved Business Intent, survives retries, crashes, duplicate delivery, parallel workers, and ambiguous provider responses, and produces at most one committed USDC settlement on Arc Testnet through a Privy-controlled corporate wallet. The same build must include a fail-closed Arc Mainnet profile, deployment and rollback procedure, and readiness evidence so official mainnet values can be enabled without redesigning the domain. Known-identity recovery uses OneShot, Privy, and direct Arc evidence; hashless automatic recovery uses The Graph for candidate discovery after C01 proves live value and sponsor fit. The release claim is: @@ -105,6 +201,7 @@ This plan optimizes for five properties: 3. Low merge contention: each coder owns disjoint directories and shared files have a single editor. 4. Verifiable handoffs: ports, OpenAPI, schemas, fixtures, and simulators are versioned artifacts. 5. Late frontend: UI work consumes a stable backend contract instead of driving it. +6. Network promotion: testnet proves behavior; mainnet readiness proves the same boundaries can be configured safely when Arc publishes official production values. ## 3. Product success criteria @@ -113,9 +210,11 @@ This plan optimizes for five properties: - A valid intent can produce one real ERC-20 USDC transfer on Arc Testnet and persist a verified receipt and Transfer identity. - A timeout, disconnect, lost response, or crash after possible submission produces durable `UNKNOWN`; a new payment is forbidden until authoritative reconciliation resolves it. - Ten sequential retries, ten parallel workers, restart recovery, queue redelivery, and two agent instances never produce more than one committed settlement. -- Live The Graph data supports history and recovery. Empty, delayed, unhealthy, or contradictory indexed data never authorizes payment. +- Privy/direct Arc lookup resolves known transaction identities. The Graph enables automatic hashless candidate discovery; its absence, delay, multiple matches, or contradiction never authorizes payment. - Money remains a canonical integer string at JSON boundaries and `bigint` internally, using six-decimal ERC-20 USDC atomic units. -- The demo proves working Privy, Arc, and The Graph integrations with sanitized testnet evidence and no exposed secrets. +- The demo proves working Privy and Arc integrations with sanitized testnet evidence and no exposed secrets. +- A mainnet-readiness check proves network, token, explorer, policy, deployment, rollback, and safe-disable configuration fail closed while official Arc Mainnet values remain disabled until published and human-approved. +- The Graph sponsor claim is retained only when live evidence proves hashless discovery and meaningful recovery-agent automation beyond direct known-hash lookup. ## 4. Scope @@ -124,34 +223,47 @@ This plan optimizes for five properties: - Strict TypeScript monorepo, shared contracts, API, worker, PostgreSQL state, migrations, and transactional jobs. - Privy execution-wallet authorization and fail-closed wallet policy. - Arc Testnet ERC-20 USDC request construction, submission, receipt verification, and explorer evidence. -- Durable reconciliation using OneShot state, Privy identifiers/status, Arc RPC receipts, and The Graph observations. -- Custom Subgraph, indexed-history query, freshness and health classification. +- Durable reconciliation using OneShot state, Privy identifiers/status, and direct Arc RPC receipts/logs. +- Provider-neutral candidate-index port, The Graph deployment/health contract, and freshness/multiple-candidate classification. - Contract simulators, failure injection, concurrency and restart testing, structured logs, metrics, and operator runbooks. - Minimal operator/user frontend after backend acceptance. +- Arc Mainnet configuration seam, deployment manifest, readiness probe, safe-disable and rollback runbooks, with real-value execution disabled until official values and explicit human authorization exist. ### Excluded -- Mainnet, additional chains/assets, swaps, bridges, fiat rails, automatic transaction replacement, or unrestricted payment overrides. -- The Graph as duplicate lock, durable intent store, or proof that another settlement is safe. +- Actual mainnet value transfer before Arc publishes official production access/addresses and a human authorizes the operation; additional chains/assets, swaps, bridges, fiat rails, automatic transaction replacement, and unrestricted payment overrides. +- Any external indexer as duplicate lock, durable intent store, or proof that another settlement is safe. - General workflow automation, arbitrary supplier/ERP integrations, native mobile clients, production compliance certification, or multi-region HA. - UI polish that is not necessary to demonstrate the invariant and sponsor requirements. ### Post-MVP production path -The current implementation commitment ends with a production-quality testnet -MVP. A real-funds release requires separate evidence and human approval: +The implementation commitment includes a working testnet MVP and mainnet-ready +deployment artifacts. Real-value activation remains a separate human-controlled gate: -1. **Pilot readiness:** tenant authentication and authorization, retention and - deletion policy, backup/restore proof, load limits, incident response, - dependency and contract security review, and production Privy/Arc support. -2. **Limited production pilot:** allowlisted organizations, conservative - spending caps, safe-disable drills, operator escalation, SLO measurement, - and staged rollout with no automatic mainnet migration. +1. **Mainnet activation:** pin official Arc Mainnet chain, RPC, explorer, USDC and contract identities; rerun compatibility, security, rollback, and safe-disable checks; require explicit human authorization. +2. **Limited production pilot:** add tenant authorization, retention/deletion policy, backup/restore proof, allowlisted organizations, conservative spending caps, incident response, monitoring, and staged rollout with no automatic migration of testnet state. 3. **Product expansion:** invoice and procurement connectors, subscriptions, supplier APIs, additional settlement networks/assets, and higher-availability deployment only after the core invariant remains proven in the pilot. -These stages extend the roadmap without expanding the P0-P6 build commitment. +P0-P6 delivers testnet functionality and mainnet readiness. Actual production activation and real-value pilot execution remain outside automatic agent authority. +### Deployment path + +```mermaid +flowchart LR + Local[Local and simulator proof] --> Testnet[Working Arc Testnet product] + Testnet --> Ready[Disabled Arc Mainnet profile and deployment evidence] + Ready --> Values{Official Arc Mainnet values available} + Values -->|no| Hold[Remain testnet-only] + Values -->|yes| Human{Human security and launch approval} + Human -->|no| Hold + Human -->|yes| Pilot[Allowlisted real-value pilot] +``` + +Testnet proves product behavior. Mainnet readiness proves configurability, +deployment, safe disable, and rollback. It never grants an agent permission to +activate real-value execution. ## 5. Fixed technical baseline @@ -164,14 +276,14 @@ These stages extend the roadmap without expanding the P0-P6 build commitment. | Work delivery | Graphile Worker over the same PostgreSQL database; at-least-once delivery is assumed | | EVM encoding and RPC | `viem` for typed addresses, calldata, chain access, receipt reads, and log verification | | Authorization | Privy Node SDK, execution wallet, scoped wallet policy, persisted idempotency key, and reference identity | -| Settlement | Arc Testnet `eip155:5042002`, ERC-20 USDC `0x3600000000000000000000000000000000000000`, six decimals | -| Indexing | The Graph custom Subgraph, `graph-cli`, AssemblyScript mappings, GraphQL client, `_meta` health data, and Matchstick mapping tests | +| Settlement profiles | Arc Testnet `eip155:5042002` and its official USDC interface are enabled for live proof; the Arc Mainnet profile is structurally complete but disabled until official chain/token values are published, pinned, verified, and human-approved | +| Hashless discovery | `IndexViewPort` is provider-neutral; The Graph is the selected v1 adapter for live candidate discovery. C01 must prove the lost-hash flow, freshness, degradation behavior, and AI-track fit; direct RPC remains the safe fallback | | Money | Canonical integer strings at JSON boundaries and `bigint` internally; no JavaScript monetary floats | | Frontend | React and Vite, generated OpenAPI client, exact integer amount formatting, and no direct settlement capability | -| Testing | Vitest for unit/contract tests, Testcontainers for PostgreSQL integration, Playwright for browser flows, Matchstick for Subgraph mappings, and deterministic failure simulators | +| Testing | Vitest for unit/contract tests, Testcontainers for PostgreSQL integration, Playwright for browser flows, deterministic failure simulators, and Graph adapter/degradation tests | | Local and CI | Docker Compose for reproducible local services and GitHub Actions for install, lint, type, test, build, migration, contract, and policy checks | | Submission jobs | One queue attempt; the task persists `COMMITTED`, `FAILED_SAFE`, or `UNKNOWN` before returning | -| Recovery authority | OneShot state and verified Arc evidence are authoritative; Privy helps locate activity; The Graph is freshness-labeled observation and history | +| Recovery authority | PostgreSQL state and verified Arc evidence are authoritative; Privy may locate the original request; The Graph supplies freshness-labeled candidates and never grants settlement permission | Exact dependency versions are pinned only after A01/B01 compatibility spikes. The exact v1 contracts, state table, fixture catalog, redaction rules, and change @@ -203,15 +315,15 @@ flowchart TB SettlementPort --> ArcAdapter[packages/arc-adapter] EvidencePort --> PrivyAdapter EvidencePort --> ArcAdapter - IndexPort --> GraphClient[packages/graph-client] + IndexPort -.-> HistoryAdapter[packages/history-adapter] PrivyAdapter --> Privy[Privy wallet and policy] ArcAdapter --> Arc[Arc USDC and RPC] - GraphClient --> Subgraph[The Graph Subgraph] - Subgraph --> Arc + HistoryAdapter --> GraphIndex[The Graph candidate index] + GraphIndex -.-> Arc ``` -OneShot decides whether settlement may be attempted. Privy constrains authorized wallet actions. Arc provides final settlement evidence. The Graph explains indexed history and freshness but grants no settlement right. Detailed entity, state, sequence, and ownership diagrams live in [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md). +OneShot decides whether settlement may be attempted. Privy constrains authorized wallet actions. Arc provides final settlement evidence. Direct Privy/Arc lookup resolves known transaction identities. The Graph is the selected automatic discovery path when that identity is lost; it proposes candidates but grants no settlement right. Detailed entity, state, sequence, and ownership diagrams live in [`docs/DOMAIN_ARCHITECTURE.md`](docs/DOMAIN_ARCHITECTURE.md). ## 7. Team topology and exclusive ownership @@ -228,7 +340,7 @@ Owns: - root workspace/build configuration after the initial scaffold - migrations and OpenAPI -Coder A never implements provider-specific Privy, Arc, or Graph behavior. +Coder A never implements provider-specific Privy, Arc, or external-index behavior. ### Coder B — authorization and settlement adapters @@ -243,14 +355,14 @@ Owns: Coder B never changes domain tables or state meanings directly. -### Coder C — reconciliation and indexed recovery +### Coder C — reconciliation and recovery evidence Owns: - `packages/reconciliation` -- `packages/graph-client` +- optional `packages/history-adapter` after the C01 decision - `packages/testkit-failures` -- `subgraph/` +- `subgraph/` after The Graph passes the C01 live discovery and qualification gate - recovery-view schemas and queries - failure matrix orchestration and recovery runbooks @@ -312,13 +424,13 @@ contract passes. | Phase | Entry condition | Coder A | Coder B | Coder C | Exit evidence | | --- | --- | --- | --- | --- | --- | -| R0 — product and contract freeze | Product vertical selected | Confirm domain/API contract | Confirm provider/chain contract | Confirm recovery/index contract | P0 approved scope and immutable v1 pack | +| R0 — product and contract freeze | Product vertical selected | Confirm domain/API contract | Confirm provider/chain contract | Confirm recovery/evidence contract | P0 approved scope and immutable v1 pack | | R1 — independent foundations | P0 | A01 | B01 | C01 | P1 runnable toolchains and recorded compatibility findings | | R2 — durable core and adapters | Own R1 packet | A02 | B02 | C02 | P2 compatible contract packs and simulators | | R3 — safety under failure | Own R2 packet | A03 | B03 | C03 | P3 concurrency, ambiguity, and failure proofs | -| R4 — backend convergence | A03/B03/C03 artifacts available | A04 and composition owner | B04 and live settlement evidence | C04 and live index/recovery evidence | P4 integrated backend, one real settlement, lost-response recovery | +| R4 — backend convergence | A03/B03/C03 artifacts available | A04 and composition owner | B04 and live settlement evidence | C04 and live recovery evidence | P4 integrated backend, one real settlement, lost-response recovery | | R5 — product interface | P4 | A05 application shell | B05 policy/settlement slice | C05 recovery/history slice | P5 composed operator experience | -| R6 — hardening and release | P5 | A06 operations bundle | B06 Privy/Arc evidence | C06 Graph/recovery evidence | P6 repeatable release candidate | +| R6 — hardening and release | P5 | A06 operations/mainnet-readiness bundle | B06 Privy/Arc evidence and network profiles | C06 Graph discovery/recovery evidence | P6 repeatable testnet release plus mainnet-readiness candidate | Provider access, SDK incompatibility, or failed integration evidence opens an owner-specific compatibility task. It never weakens the safety invariant or @@ -340,12 +452,12 @@ silently changes a contract. | [B04](milestones/coder-b/B04-ambiguity-integration.md) | B | B03 | Conservative outcomes and production adapter pack | | [B05](milestones/coder-b/B05-frontend-settlement-details.md) | B | B04 + project Gate P4 | Authorization/settlement UI slice against fixtures | | [B06](milestones/coder-b/B06-sponsor-evidence.md) | B | B05 | Privy/Arc sanitized evidence bundle | -| [C01](milestones/coder-c/C01-subgraph-index-health.md) | C | Frozen contract pack | Subgraph mappings and Graph health client | +| [C01](milestones/coder-c/C01-recovery-evidence-strategy.md) | C | Frozen contract pack | Recovery evidence contract and indexer value decision | | [C02](milestones/coder-c/C02-reconciliation-engine.md) | C | C01 | Deterministic reconciliation and evidence contract | | [C03](milestones/coder-c/C03-failure-injection.md) | C | C02 | Cross-source chaos and restart harness | | [C04](milestones/coder-c/C04-recovery-matrix-integration.md) | C | C03 | Recovery matrix and simulator integration pack | | [C05](milestones/coder-c/C05-frontend-recovery.md) | C | C04 + project Gate P4 | Recovery timeline UI slice against fixtures | -| [C06](milestones/coder-c/C06-qualification-demo.md) | C | C05 | Graph/recovery qualification bundle | +| [C06](milestones/coder-c/C06-qualification-demo.md) | C | C05 | Recovery and conditional-index qualification bundle | Each packet contains smaller, one-commit-sized tasks, exact acceptance criteria, tests, output artifacts, and a no-wait continuation instruction. @@ -415,19 +527,20 @@ This is the frontend unlock gate. - One real allowed Arc Testnet payment commits exactly once through Privy. - Wrong-scope and above-cap cases produce zero settlement. - A lost-response scenario reaches `UNKNOWN` and reconciles to the original transaction without a duplicate. -- Live Graph evidence is shown with `_meta`, deployment, indexed block, lag, and health. +- The lost-hash scenario uses live The Graph data to discover candidates, direct Arc evidence to verify the bound transaction, and no second submission; stale, empty, multiple, or contradictory candidates remain `UNKNOWN`. - OpenAPI and recovery-view semantics are frozen for frontend. ### P5 — frontend acceptance - A05, B05, and C05 compose against the frozen API. -- Browser tests cover create, replay, conflict, denial, committed, `UNKNOWN`, reconciliation, Graph lag/error, and service-unavailable states. +- Browser tests cover create, replay, conflict, denial, committed, `UNKNOWN`, Graph discovery, Graph lag/error/multiple-candidate, and service-unavailable states. - No force-pay or unguarded settlement action exists. - Accessibility smoke, responsive layout, lint, type, build, and no-secret checks pass. ### P6 — release candidate - A06, B06, and C06 evidence bundles compose into one repeatable testnet demo. +- The disabled Arc Mainnet profile passes configuration, deployment-manifest, readiness, safe-disable, and rollback checks without sending a mainnet transaction. - Sponsor qualification cites working code, tests, live evidence, network, and limitations. - Safe-disable and recovery runbooks work without manual database surgery. - Exact candidate tree passes repository checks and mandatory independent review gates before human merge. @@ -444,7 +557,7 @@ This is the frontend unlock gate. | Crash before submission | A | Worker kill point | P4 zero external settlement | | Crash after possible submission | B | Adapter fault fixture | P4 durable `UNKNOWN` | | Lost payment response | B | Proxy/fixture | P4 original transaction reconciled | -| Graph delay/absence/error | C | Graph simulator | P4 no submission grant | +| Graph delay/absence/multiple candidates | C | Provider-neutral Graph simulator | P4 remain `UNKNOWN`; no submission grant | | Privy denial/above cap | B | Policy fixture/live-ready harness | P4 zero settlement | | Service restart | A | Process orchestration | P4 evidence durability | | Downstream failure after payment | A | Supplier fake | P4 original receipt retained | @@ -458,7 +571,7 @@ After P4, the three frontend packets remain independent: - A05 owns application shell, create/replay/conflict, and authoritative status. - B05 owns policy, authorization, transaction, and explorer details. -- C05 owns recovery timeline, evidence provenance, Graph freshness, and escalation. +- C05 owns recovery timeline, evidence provenance, Graph freshness/candidate state, and escalation. Each slice is built against the frozen mock server. Final composition is a project gate, not a packet closure requirement. @@ -473,7 +586,7 @@ Each slice is built against the frozen mock server. Final composition is a proje ## 16. Human-only external configuration -Coder B produces a repeatable setup guide or wizard, but a human performs Privy application/wallet/key-quorum/policy creation, Arc testnet funding, Graph Studio credential entry, and CI-secret configuration. +Coder B produces a repeatable setup guide or wizard, but a human performs Privy application/wallet/key-quorum/policy creation, Arc Testnet funding, any selected index-provider credential entry, Mainnet profile activation, and CI-secret configuration. - Secret input is hidden and written only to ignored runtime files or approved secret stores. - Public network, contract, deployment, and policy identifiers are separated from secrets. @@ -483,9 +596,9 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy ## 17. Observability and operations -- Correlation fields: Business Intent ID, Attempt ID, settlement version, Privy reference/transaction ID, Arc transaction hash, and Graph deployment/indexed block. +- Correlation fields: Business Intent ID, Attempt ID, settlement version, Privy reference/transaction ID, Arc transaction hash, active network profile, and Graph deployment/observed block. - Never log signatures, credentials, private keys, raw authorization bodies, or private wallet material. -- Metrics: intent states, oldest/count `UNKNOWN`, transition conflicts, queue lag, reconciliation outcomes, policy denials, provider/RPC errors, Graph lag/health, duplicate and conflict counts. +- Metrics: intent states, oldest/count `UNKNOWN`, transition conflicts, queue lag, reconciliation outcomes, policy denials, provider/RPC errors, Graph lag/health/candidate count, duplicate and conflict counts. - Safe disable stops new submission ownership while preserving status, evidence ingestion, and reconciliation reads. - Operators inspect durable identity and evidence. There is no generic retry or force-pay button. @@ -498,7 +611,7 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy | ERC-20/native precision confusion | Six-decimal ERC-20 is the only settlement amount; native balance is gas only | B/C | | Lost response after broadcast | Persist identity first, enter `UNKNOWN`, reconcile, forbid another payment | All | | Pending/evicted Arc transaction | Hold `UNKNOWN`; no automatic replacement in v1 | B/C | -| Graph lag/error/empty result | Surface freshness and health; never infer non-payment | C | +| Graph lag/error/empty/multiple result | Surface freshness and candidate ambiguity; never infer non-payment | C | | Queue redelivery | Domain CAS/constraints plus single-attempt submission task | A | | Shared-file conflicts | Exclusive path ownership and A-only root composition | A | | Credentials unavailable | Offline contract packs and simulators remain sufficient for packet closure | B | @@ -525,19 +638,19 @@ Coder B produces a repeatable setup guide or wizard, but a human performs Privy | A03 | One submission owner under redelivery/concurrency | Ten-worker/two-process counter proof | | A04 | Restart-safe, operable backend composition | Restart matrix, safe disable, simulator root suite | | A05 | Safe intent creation and authoritative status UI | Frozen-mock browser/accessibility tests | -| A06 | Repeatable invariant and operations demo | Clean bootstrap plus scenario result table | +| A06 | Repeatable invariant, operations, and mainnet-readiness bundle | Clean bootstrap, scenario table, disabled-profile readiness and rollback proof | | B01 | Known-compatible provider/network boundary | SDK spike and fail-closed readiness tests | | B02 | Exact request/policy/receipt semantics | Golden calldata, deny matrix, receipt corpus | | B03 | Testnet-capable policy-constrained settlement | Offline harness plus optional sanitized live proof | | B04 | Conservative handling of provider ambiguity | Fault taxonomy and lookup contract suite | | B05 | Safe authorization/transaction UI | Fixture-driven component and redaction tests | | B06 | Verifiable Privy/Arc sponsor evidence | Policy denial and real transfer evidence bundle | -| C01 | Correct Arc transfer indexing and visible freshness | Mapping and Graph-health fixture tests | +| C01 | Minimal recovery evidence strategy with an explicit indexer decision | Removal/value matrix and provider-neutral contract tests | | C02 | Deterministic zero-submit reconciliation | Complete evidence/decision matrix | | C03 | Safety under loss, lag, contradiction, and restart | Seeded failure-injection suite | | C04 | Recovery service ready for real adapter replacement | Simulator composition and matrix report | -| C05 | Accurate recovery/index UI | Degraded-evidence component tests | -| C06 | Verifiable Graph/recovery sponsor evidence | Live health, degraded demo, qualification report | +| C05 | Accurate recovery/evidence UI | Degraded-evidence component tests | +| C06 | Verifiable recovery and conditional-index evidence | Live recovery, degraded demo, qualification report | Every success criterion in Section 3 has at least two independent proof surfaces: a producer packet and a later project-gate verification. Packet closure establishes the producer proof; it never claims final integrated behavior by itself. @@ -548,7 +661,7 @@ Every success criterion in Section 3 has at least two independent proof surfaces Purpose: default mode for every coder packet. - Uses synthetic, versioned, schema-checked fixtures only. -- Requires no Privy, Arc, Graph, or secret configuration. +- Requires no Privy, Arc, The Graph, or secret configuration. - Runs package-local checks and deterministic simulators. - Is sufficient to close A01–A04, B01–B04, and C01–C04. - Cannot support sponsor qualification or real-settlement claims. @@ -558,7 +671,7 @@ Purpose: default mode for every coder packet. Purpose: compose reviewed packages with PostgreSQL and local services before external effects. - Uses real PostgreSQL and Graphile Worker. -- Replaces provider/Graph network access with simulators. +- Replaces Privy, Arc, and The Graph network access with simulators. - Runs migrations, API/worker orchestration, concurrency, restart, failure, and recovery suites. - Remains the fallback when external providers are unavailable. @@ -566,7 +679,7 @@ Purpose: compose reviewed packages with PostgreSQL and local services before ext Purpose: Gate P4 and P6 live proof. -- Requires human-approved Privy/Arc/Graph configuration in ignored/approved secret stores. +- Requires human-approved Privy/Arc and any selected index-provider configuration in ignored/approved secret stores. - Checks Arc chain/token/policy/deployment identities before running. - Limits settlement to an approved recipient and cap. - Produces sanitized public identifiers and result tables only. @@ -577,7 +690,7 @@ Purpose: Gate P4 and P6 live proof. Purpose: independently close A05/B05/C05. - Uses the P4-frozen OpenAPI and sanitized response fixtures. -- Simulates every authoritative, provider, and Graph state. +- Simulates every authoritative, provider, Arc, and Graph state. - Contains no provider credentials or direct settlement capability. - Must behave identically to production UI for state labeling and disabled actions. @@ -588,15 +701,15 @@ P4 is deliberately procedural so convergence does not turn into open-ended share 1. Record exact reviewed A04, B04, and C04 package versions and tree SHAs. 2. Coder A creates the single composition branch from the approved integration base. 3. Replace the settlement simulator with B04’s public package entry point; run contract compatibility before any live call. -4. Replace the recovery/index simulators with C04 public entry points; run command/evidence compatibility. +4. Replace the recovery/evidence simulators with C04 public entry points; run command/evidence compatibility. 5. Run offline root checks first. A contract mismatch stops composition and opens one owner-specific compatibility ticket. 6. Run empty and upgrade migrations, API/worker boot, readiness, and safe-disable checks. 7. Run the complete local failure matrix with real packages but simulated external services. -8. A human enables testnet evidence mode and confirms network, token, wallet, policy, recipient, cap, funding, and Graph deployment. -9. Execute one allowed intent and bind durable identity, Privy identity, Arc receipt/Transfer, and indexed observation. +8. A human enables testnet evidence mode and confirms network, token, wallet, policy, recipient, cap, funding, and the Graph deployment. +9. Execute one allowed intent, discard the returned transaction hash at the fault boundary, discover it through live The Graph data, and bind durable identity, Privy identity, Arc receipt/Transfer, and Graph freshness. 10. Execute wrong-scope and above-cap denials; confirm zero settlements. 11. Inject a lost local response after possible broadcast; confirm durable `UNKNOWN`, zero replacement transaction, and reconciliation to original evidence. -12. Simulate empty, lagging, unhealthy, unavailable, and contradictory Graph results; confirm no permission change. +12. Simulate empty, lagging, unhealthy, unavailable, multiple, and contradictory Graph candidates; confirm `UNKNOWN` and no permission change. 13. Publish a sanitized Gate P4 manifest and freeze OpenAPI/recovery-view semantics. P4 failures never produce ad hoc edits by multiple coders on the composition branch. The owning coder fixes their package in a focused branch, republishes a reviewed version, and A updates only the version slot. @@ -607,7 +720,7 @@ P4 failures never produce ad hoc edits by multiple coders on the composition bra - A owns root package manager files, shared compiler/lint/test configuration, OpenAPI, migrations, API, worker, contracts, and domain/storage packages. - B owns only provider/chain adapter packages, provider fixtures, and human provider setup docs. -- C owns only reconciliation/Graph/failure packages, Subgraph files, and recovery docs. +- C owns only reconciliation/failure packages, recovery docs, and the Graph adapter/Subgraph after C01. - Frontend composition reserves one shell/route registry editor; B/C expose components through documented entry points instead of editing the registry concurrently. ### Commit controls @@ -636,7 +749,7 @@ Continue asynchronously with a documented conservative assumption for ordinary i - when `UNKNOWN` may transition to `FAILED_SAFE`; - Privy policy scope or bypass availability; - Arc network/token identity; -- The Graph’s non-authoritative role; +- the non-authoritative role of any external indexer; - use of non-testnet funds or irreversible external configuration; - public API breaking compatibility after P4. @@ -652,7 +765,7 @@ If time is constrained, cut in this order: 2. Rolling/multiple policy support; retain one explicit policy. 3. Nonessential dashboard panels and telemetry dimensions; retain safety alerts. 4. Visual animation, theming, and secondary responsive polish; retain accessible core flows. -5. Extra demo narratives; retain invariant, authorization, settlement, `UNKNOWN`, and Graph-degradation proof. +5. The Graph integration if it fails C01 live hashless-discovery or sponsor-fit proof; retain invariant, authorization, settlement, `UNKNOWN`, and direct Arc recovery. Never cut: @@ -661,7 +774,7 @@ Never cut: - denial/zero-settlement proof; - concurrency, restart, and lost-response tests; - exact Arc receipt/Transfer verification; -- Graph freshness/health labeling and non-authority; +- Graph freshness/candidate labeling and non-authority; - secret/redaction checks; - independent review and human merge controls. @@ -675,7 +788,7 @@ artifact_version: source_commit: source_tree: contract_versions: -environment: offline | local-integration | testnet | frontend-mock +environment: offline | local-integration | testnet | mainnet-readiness | frontend-mock commands: acceptance: external_effect_count: @@ -698,12 +811,12 @@ Before Gate P6 can pass, confirm: - Denial and invalid-scope flows have zero settlement. - Lost-response flow has no replacement and reconciles to the original transaction or safely remains `UNKNOWN`. - Restart and two-agent scenarios preserve the invariant. -- Graph empty/lag/error/unavailable states never alter settlement permission. +- Empty, lagging, erroneous, unavailable, or multiple Graph candidates never alter settlement permission. - Safe disable stops new submissions while status and recovery reads continue. - UI has no direct/bypass/force-pay action and labels authority/freshness correctly. - Demo/reset instructions require no unsafe database surgery or external-history rewrite. - Evidence, repository, logs, screenshots, fixtures, source maps, and reviews contain no secrets. -- Privy, Arc, and The Graph claims use the qualification standard and cite live evidence or remain `NOT VERIFIED`. +- Privy and Arc claims use the qualification standard. The Graph claim requires live hashless discovery plus meaningful recovery-agent automation; otherwise it is `NOT VERIFIED` and removed from the submission. - Mandatory FreePi gates and required CI apply to the exact candidate tree/head. - A human performs the final review and merge. From 8b55623b1490b64e2e4ac66e2aed22d371d4c94e Mon Sep 17 00:00:00 2001 From: Matvii Nesterenko <51422901+kapustazh@users.noreply.github.com> Date: Sun, 6 Sep 2026 23:57:20 +0200 Subject: [PATCH 2/2] docs(plan): finalize Arc Graph stack --- .agent/SPONSOR_REQUIREMENTS.md | 18 +----- .../20260906T201351Z-product-roadmap.md | 29 +++------ .../20260906-integration-decisions.md | 23 +++----- plan.md | 59 ++----------------- 4 files changed, 23 insertions(+), 106 deletions(-) diff --git a/.agent/SPONSOR_REQUIREMENTS.md b/.agent/SPONSOR_REQUIREMENTS.md index 867a68c..432c5d1 100644 --- a/.agent/SPONSOR_REQUIREMENTS.md +++ b/.agent/SPONSOR_REQUIREMENTS.md @@ -25,22 +25,6 @@ release, or submission claims. disabled until Circle publishes official production access/identities and a human explicitly authorizes real-value activation. -## Alternative target: Hedera AI & Agentic Payments - -Select this instead of Arc before P0; do not build two settlement rails for the -same MVP. - -- Host a live x402-gated service on Hedera testnet or mainnet and settle it - through Blocky402. -- Demonstrate an agent or platform completing one real paid request end to end. -- Keep Privy core by proving a real wallet plus policy, signer, key quorum, or - intent that constrains the financial action. EVM compatibility alone is not - evidence; the Privy/Hedera path needs a B01 spike. -- Use Hedera transaction or Mirror Node history as recovery evidence, never as - the durable duplicate lock. -- Add Bazantic only after the core path works and only when its recipe/gateway - creates a separate, demonstrated agent capability. - ## Selected target: The Graph AI Tooling or AI Use Case The Graph is load-bearing for automatic recovery when a successful submission @@ -63,4 +47,4 @@ environment variables, dependencies, and network labels are not evidence. Use the `sponsor-qualification` skill to report each selected sponsor as `QUALIFIED`, `NOT QUALIFIED`, or `NOT VERIFIED`, with code, test, demo, network, -and limitation evidence. \ No newline at end of file +and limitation evidence. diff --git a/.agent/context/20260906T201351Z-product-roadmap.md b/.agent/context/20260906T201351Z-product-roadmap.md index f0e792e..40f3e05 100644 --- a/.agent/context/20260906T201351Z-product-roadmap.md +++ b/.agent/context/20260906T201351Z-product-roadmap.md @@ -42,7 +42,7 @@ contributes to the complete product. - All local Markdown links in `plan.md`, `milestones/`, and `docs/` resolve. - Exactly 18 packet files remain. - Packet headers contain no planning-size metadata. -- Mermaid CLI 11.17.0 rendered all 10 diagrams successfully. +- Mermaid CLI 11.17.0 rendered all 12 diagrams successfully. - `git diff --check` passes. - Gate A and Gate B were intentionally not run because the user explicitly requested skipping the two-review procedure for the planning phase. @@ -55,10 +55,11 @@ contributes to the complete product. ## Git state - Branch: `milestone/product-roadmap` -- Base: `develop` at `5ef6a66313614e67b476f56c98f47c65344fb6ec` +- Original roadmap base: `develop` at `5ef6a66313614e67b476f56c98f47c65344fb6ec`. +- Follow-up base: `develop` at `4336e04d9fd42b419a9cfa961f4f8d25b15cd3cb`. - Original roadmap pull request: `https://github.com/SWOFART/OneShot/pull/7` (merged into `develop` before this architecture correction). -- Follow-up pull request: pending from `milestone/product-roadmap`. +- Follow-up pull request: `https://github.com/SWOFART/OneShot/pull/8`. ## 2026-09-06 architecture correction @@ -71,22 +72,8 @@ contributes to the complete product. - The Graph is the selected v1 hashless candidate-discovery layer. C01 must prove live value, freshness, multiple-candidate handling, and AI-track fit; Arc remains authoritative and a failed gate removes the Graph claim. -- Review gates for this corrected tree are intentionally not embedded here; - immutable Gate A/B evidence is recorded on PR #7 so recording it cannot alter - the reviewed tree. -## 2026-09-06 migration options - -- Arc with direct Privy/RPC evidence remains the smallest default. -- The Graph is the primary `IndexViewPort` adapter for hashless discovery; - direct Arc or managed RPC remain migration fallbacks. -- Hedera with Privy and x402/Blocky402 is a coherent alternative settlement - rail for the paid-API vertical. It replaces Arc-specific adapter/evidence - work while retaining the OneShot domain, PostgreSQL authority, `UNKNOWN`, and - reconciliation rules. -- A Hedera pivot must be selected before P0 and must prove Privy compatibility; - it is not a second rail in the same MVP. -- Bazantic is the closest optional third sponsor after the core Hedera flow, - but it must add a real agent-facing capability and cannot replace Blocky402. +- Gate A and Gate B are skipped for this follow-up planning change by explicit + user instruction. Required repository CI and human review still apply. ## 2026-09-06 Graph and Arc Memo decision - Primary submission direction: Privy authorizes, The Graph discovers, Arc @@ -98,5 +85,5 @@ contributes to the complete product. - Prefer Arc Memo `memoId = hash(business_intent_id)` for unique correlation only if B01 proves Privy can constrain the forwarded USDC call. Otherwise preserve stricter authorization and use tuple/window search or a narrow typed contract. -- Hedera + Privy + x402/Blocky402 remains a separate P0 alternative, not a - second settlement rail in the Arc MVP. +- Privy + Arc + The Graph is the final selected stack; alternative settlement + rails are outside this roadmap. diff --git a/.agent/research/20260906-integration-decisions.md b/.agent/research/20260906-integration-decisions.md index 6af62e8..a4ee3c1 100755 --- a/.agent/research/20260906-integration-decisions.md +++ b/.agent/research/20260906-integration-decisions.md @@ -2,7 +2,8 @@ Date: 2026-09-06 Scope: primary-source facts needed to make the first product implementation plan decision-complete. -Target: Privy-authorized exactly-once settlement on Arc Testnet by default, with provider-neutral recovery and Hedera x402 as an explicit alternative rail. +Target: Privy-authorized exactly-once settlement on Arc Testnet with The Graph +as the hashless recovery index. ## Decisions @@ -31,16 +32,6 @@ Target: Privy-authorized exactly-once settlement on Arc Testnet by default, with - Privy can enforce chain, destination contract, decoded function, and decoded top-level calldata parameters. Before choosing Memo for settlement, B01 must prove the policy can constrain the forwarded USDC target and required business fields; otherwise use the tuple-search fallback or a narrow typed settlement contract without weakening authorization ([Privy policy fields](https://docs.privy.io/controls/policies/overview)). - Target the Graph AI Tooling or AI Use Case track: live Graph data must drive meaningful recovery-agent selection, explanation, or automation. The composable/standardized track requires two Graph products or meaningful use of a standardized schema; one custom Subgraph query is insufficient ([ETHOnline 2026 prize requirements](https://ethglobal.com/events/ethonline2026/prizes)). -### Hedera x402: coherent alternative settlement rail - -- The Hedera AI & Agentic Payments track requires a live x402-gated service on Hedera testnet or mainnet, settlement through the Blocky402 facilitator, and an agent/platform completing at least one real paid request end to end ([ETHOnline 2026 Hedera requirements](https://ethglobal.com/events/ethonline2026/prizes/hedera)). -- This maps directly to OneShot's first vertical: the agent pays for one API job while the durable Business Intent prevents a duplicate financial outcome after repeated HTTP calls, restarts, or lost settlement responses. -- A Hedera choice replaces the Arc-specific network, token/request, receipt, explorer, and evidence adapters. It does not replace PostgreSQL authority, atomic ownership, the one-attempt submission job, `UNKNOWN`, or reconciliation. -- Hedera Mirror Nodes expose validated transaction history through REST APIs and can serve as a read/recovery source. They remain external observation, not the OneShot duplicate lock ([Mirror Node model](https://docs.hedera.com/learn/core-concepts/mirror-nodes)). -- Hedera exposes an Ethereum JSON-RPC interface, so reusing EVM transaction tooling is plausible, but it is not proof of Privy product support ([Hedera Hardhat and ethers.js guide](https://docs.hedera.com/hedera/tutorials/smart-contracts/hscs-workshop/hardhat)). -- Privy is not assumed compatible merely because Hedera exposes an EVM interface. B01 must prove wallet creation, signing, chain configuration, policy enforcement, submission, and lookup on the chosen Hedera path before Privy/Hedera qualification is claimed. -- `x402` plus Blocky402 is the required third technical component. Bazantic is the closest optional third sponsor because it can expose a finished API through a recipe or gateway, but it is added only after the Hedera paid-request path works and it must not replace Blocky402 settlement. - ### Durable state and work delivery - PostgreSQL is the authoritative store. Use primary/unique constraints on `business_intent_id` and one settlement row per intent; use `INSERT ... ON CONFLICT` plus an immutable payload fingerprint to distinguish a replay from a same-ID conflict ([constraints](https://www.postgresql.org/docs/current/ddl-constraints.html), [`INSERT`](https://www.postgresql.org/docs/current/sql-insert.html)). @@ -54,9 +45,13 @@ Target: Privy-authorized exactly-once settlement on Arc Testnet by default, with 2. Assert `eth_chainId == 5042002` and bytecode exists at the configured USDC address during testnet startup checks. 3. Prove the chosen Privy policy denies wrong chain, wrong contract, wrong recipient, wrong method, non-zero native value, and above-cap amount with zero settlement. 4. Prove live The Graph hashless discovery, freshness, multiple-candidate handling, safe degradation, and AI-track value; otherwise remove the Graph claim and use direct recovery. -5. If Hedera is selected at P0, prove the full Privy + x402/Blocky402 paid-request path and Mirror Node/transaction evidence before replacing Arc packets. -6. Keep Privy webhooks outside the critical path until plan availability and signature verification are demonstrated. +5. Keep Privy webhooks outside the critical path until plan availability and signature verification are demonstrated. ## Planning consequence -The work can be split into three independent backend tracks after one contract freeze: (A) domain/storage/API, (B) the selected Privy/settlement-rail adapter, and (C) provider-neutral reconciliation/evidence. Each track must ship its own contract simulator and tests so progress does not depend on another track's implementation. Frontend begins only after the integrated backend contract and recovery semantics are stable. +The work can be split into three independent backend tracks after one contract +freeze: (A) domain/storage/API, (B) the Privy/Arc adapter, and (C) The Graph +reconciliation/evidence. Each track must ship its own contract simulator and +tests so progress does not depend on another track's implementation. Frontend +begins only after the integrated backend contract and recovery semantics are +stable. diff --git a/plan.md b/plan.md index 6847e67..e4016e1 100644 --- a/plan.md +++ b/plan.md @@ -53,53 +53,16 @@ The primary product configuration is **Privy + Arc + The Graph**: - Arc verifies the candidate receipt and exact USDC `Transfer`. - OneShot and PostgreSQL alone decide the durable state transition. -This is a provisional implementation choice with a hard C01 evidence gate. The -Graph is load-bearing for automatic hashless discovery, but never becomes -settlement authority. If C01 cannot demonstrate live candidate discovery beyond -direct lookup, remove the Graph claim and ship the Privy + Arc fallback. - -| Configuration | Product meaning | Decision | -| --- | --- | --- | -| Privy + Arc + The Graph | Authorized payment, hashless candidate discovery, authoritative chain verification | Primary build; target Best AI Tooling or AI Use Case with The Graph | -| Privy + Arc | Safe settlement and known-identity recovery without automatic indexed discovery | Fallback if C01 fails | -| Privy + Hedera + x402/Blocky402 | One paid API call produces at most one Hedera settlement | Coherent alternative rail; select before P0 instead of dual-chain MVP | -| Hedera configuration + Bazantic | Publishes the finished OneShot API as an agent-usable recipe/gateway | Optional third sponsor only after the core paid-request flow works | -| Privy + Uniswap | Changes the vertical to one trading intent producing one swap | Separate trading pivot, not an additive sponsor | -| Privy + Arc + confidential workflow | Protects private policy or routing inputs | Optional only if confidentiality becomes a core user requirement | +This is the final implementation direction. The Graph is load-bearing for +automatic hashless discovery, but never becomes settlement authority. C01 must +prove its live data, freshness, and candidate-selection behavior before the +sponsor claim is made. The Graph submission targets the AI Tooling or AI Use Case track. One custom Subgraph does not satisfy the Composable/Standardized track. The recovery agent uses live Graph data to choose and explain candidates; deterministic Arc checks and the OneShot state machine retain all financial authority. -### Settlement-rail and data migration options - -The Business Intent, PostgreSQL authority, atomic ownership, queue, `UNKNOWN` -state, reconciliation policy, and operator experience remain stable. A rail or -index change occurs behind frozen ports and never changes payment cardinality. - -| Option | What changes | What stays | Sponsor/product fit | Selection rule | -| --- | --- | --- | --- | --- | -| Arc with The Graph | Deploy a live transfer index and recovery-agent query behind `IndexViewPort` | PostgreSQL and exact Arc evidence remain authoritative | Strong Privy + Arc + Graph story | Primary when C01 proves hashless discovery and live sponsor eligibility | -| Arc with direct Privy/RPC evidence | Remove Graph deployment and automatic indexed search | Entire safety invariant and known-hash/provider-ID recovery | Strong Privy + Arc fallback | Use when Graph adds no demonstrated recovery value | -| Arc with managed RPC history | Replace the Graph adapter | Direct evidence remains authoritative | Operational alternative; no Graph sponsor claim | Use when it materially outperforms direct RPC and sponsor value is irrelevant | -| Arc with OneShot Router contract | Submit through a small contract that binds an intent ID and emits a canonical event | Business Intent and Privy policy stay central | Stronger Arc-native audit and unique lookup | Select only if the team accepts the added contract surface | -| Hedera with Privy and x402/Blocky402 | Replace Arc request, receipt, token, network, and evidence adapters; add a live x402 service and consumer | Domain ledger, PostgreSQL locks, queue, ambiguity rules, and UI model stay | Direct match for Hedera AI & Agentic Payments plus Privy B2B financial product | Serious alternative; choose before implementation freeze, not as a second MVP rail | -| Privy with Uniswap | Replace payment obligation semantics with quote, slippage, deadline, and swap outcome | Some idempotency infrastructure can be reused | Uniswap trading product | Separate product branch | - -```mermaid -flowchart TB - P0{Choose one settlement product before P0} - P0 --> ArcPath[Primary Arc USDC product] - P0 --> HederaPath[Alternative Hedera x402 product] - ArcPath --> Graph[The Graph candidate discovery] - Graph --> ArcProof[Direct Arc receipt and Transfer proof] - HederaPath --> Blocky[Blocky402 facilitator] - Blocky --> HederaEvidence[Hedera transaction or Mirror Node evidence] - ArcProof --> Core[Shared OneShot domain and PostgreSQL authority] - HederaEvidence --> Core -``` - ```mermaid flowchart LR Unknown[UNKNOWN after lost response] --> Provider{Privy returns original hash} @@ -125,18 +88,6 @@ target, and required business parameters. If it cannot, preserve the stricter policy and use tuple/window candidate search for the demo or a narrow typed settlement contract; never weaken authorization to obtain a cleaner lookup. -For the Hedera option, `x402` and Blocky402 are part of the required payment -flow, not a decorative third sponsor. Privy remains the wallet authorization -boundary only after B01 proves the chosen Privy wallet and policy path against -Hedera's EVM interface. Bazantic is the closest optional third sponsor after -the core flow works; it must not replace Blocky402 settlement or turn the -project into an MCP-only submission. - -If Hedera is selected, A01-A06 remain intact. Before P0, replace the Arc-specific -B01-B06 contracts and rail labels in C01-C06 with Hedera x402, Blocky402, and -transaction/Mirror Node evidence variants. Preserve packet IDs, port meanings, -gates, and the cardinality invariant. - ## Product surfaces | Surface | User | Purpose | @@ -765,7 +716,7 @@ If time is constrained, cut in this order: 2. Rolling/multiple policy support; retain one explicit policy. 3. Nonessential dashboard panels and telemetry dimensions; retain safety alerts. 4. Visual animation, theming, and secondary responsive polish; retain accessible core flows. -5. The Graph integration if it fails C01 live hashless-discovery or sponsor-fit proof; retain invariant, authorization, settlement, `UNKNOWN`, and direct Arc recovery. +5. Arc Memo correlation if Privy cannot constrain the forwarded call; retain The Graph tuple/window discovery and strict authorization. Never cut: