From 1878e993bc37bd498866a2b2f03048a481c50835 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:24:37 -0400 Subject: [PATCH] =?UTF-8?q?docs(v2):=20spec=20v0.2=20=E2=80=94=20fold=20co?= =?UTF-8?q?de-reality=20corrections=20from=20the=20architecture=20bridge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies bridge §4.5: Mode D confirmed as BitUnlock protocol version change (Phase E only); pledges are TORCH-side signed events (BitUnlock has no holds/escrow); milestone-grained fees as static products, never per-task; poll-driven order tracking; refunds scoped to the provider layer; Phase A is Mode A only with Mode B gated behind a durable- custody design review; BitUnlock license/vendoring recorded as a Stage 0 blocker. Adds companions header and changelog. Co-Authored-By: Claude Fable 5 --- docs/v2/DEVELOPMENT_NETWORK_SPEC.md | 57 ++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 14 deletions(-) diff --git a/docs/v2/DEVELOPMENT_NETWORK_SPEC.md b/docs/v2/DEVELOPMENT_NETWORK_SPEC.md index 0b9037d..4b393ee 100644 --- a/docs/v2/DEVELOPMENT_NETWORK_SPEC.md +++ b/docs/v2/DEVELOPMENT_NETWORK_SPEC.md @@ -2,10 +2,11 @@ ## Community-Funded Stewardship, Feature Development, and Open-Source Project Incubation -**Status:** Draft v0.1 +**Status:** Draft v0.2 (2026-08-03) **Product:** TORCH — Task Orchestration via Relay-Coordinated Handoff **Relationship:** TORCH operates as a BitUnlock tenant -**Purpose:** Expand TORCH from community-funded analysis and maintenance into a complete development network for improving existing software, delivering new features, and incubating new open-source projects. +**Purpose:** Expand TORCH from community-funded analysis and maintenance into a complete development network for improving existing software, delivering new features, and incubating new open-source projects. +**Companions:** [`V2_ARCHITECTURE_BRIDGE.md`](./V2_ARCHITECTURE_BRIDGE.md) (verified code-reality mapping), [`INCREMENTAL_DEV_PLAN.md`](./INCREMENTAL_DEV_PLAN.md) (cross-repo staged execution). v0.2 folds the bridge's §4.5 corrections into this document; see the Changelog at the end. --- @@ -790,6 +791,8 @@ Although this still creates responsibility for a bearer credential, the exposure - No withdrawal to TORCH. - Refund to the sponsor or original funding destination. +**v0.2 gate:** Mode B places a bearer credential under TORCH gateway custody. It is deferred until the provider gateway exists **and** its handling of session keys passes a durable-custody design review meeting the criteria from the BitUnlock Cashu post-mortem (`bitunlock/docs/CASHU_MICROPAYMENTS_PLAN.md` §8a): custody of the bearer value must be designed first-class before any code handles it. Until then, a sponsor who prefers Routstr may still fund a session and deliver the key **directly into the runner environment** — that is Mode A delivery, and TORCH never touches the credential. + --- ## 14.3 Mode C — Pledge First, Pay When Work Is Ready @@ -811,7 +814,7 @@ A sponsor may publish or sign a pledge: } ``` -The pledge is not money held by TORCH. +The pledge is not money held by TORCH — and cannot be money held anywhere else in the stack either. BitUnlock has no holds, no escrow, and explicitly rejects both (`bitunlock/docs/BITUNLOCK_SPEC.md`); a pledge is therefore a **TORCH-side signed Nostr event**, nothing more. Settlement happens just-in-time as an ordinary BitUnlock purchase when the milestone goes ready. When a milestone is approved and ready to execute: @@ -840,7 +843,7 @@ Sponsor No recipient holds another recipient’s funds. -This may require a future BitUnlock payment-plan extension supporting more than the current seller-and-service arrangement, or a coordinated set of linked invoices with one idempotency key. +**v0.2 correction:** this is confirmed to require a BitUnlock **protocol version change**, not an extension. BitUnlock's payment roles are frozen at seller + service (`PAYMENT_ROLES` in `src/protocol/constants.ts`), and its constants explicitly forbid routing payment to arbitrary third parties. Mode D therefore belongs to Phase E only, may never be needed if per-milestone single-leg plus accrual billing proves sufficient, and **nothing in earlier phases may depend on it**. The nearer-term alternative is a coordinated set of linked invoices with one idempotency key, which needs no protocol change. A settlement contract should define: @@ -912,7 +915,7 @@ The reserve should represent prepaid services or restricted donations, not a gen ## 15. Recommended First Economic Architecture -The first practical release should combine Modes A, B, and C. +The first practical release should combine Modes A and C. (v0.2: Mode B is deferred behind the custody gate in §14.2 — in Phase A, TORCH holds no provider credential of any kind.) ### Campaign discovery @@ -931,7 +934,7 @@ The first practical release should combine Modes A, B, and C. The sponsor chooses: 1. Supply a limited OpenRouter or NanoGPT key. -2. Fund an ephemeral Routstr session. +2. Fund a Routstr session and deliver the session key directly into the runner environment (no TORCH custody). 3. Use personal inference. 4. Purchase a TORCH-operated task ticket as a fallback. @@ -947,6 +950,7 @@ The sponsor chooses: - TORCH coordination fee is paid through a separate BitUnlock product or linked invoice. - BitUnlock earns its normal successful-payment fee. - The compute principal never enters TORCH’s general wallet in the preferred paths. +- Campaign state tracking **polls** BitUnlock order status; BitUnlock has no webhooks today. Signed lifecycle events arrive with a later BitUnlock increment (dev plan Stage 2), and polling remains the reconciliation authority even then. This model is not as frictionless as a pooled account, but it is much safer for an early community system. @@ -972,11 +976,12 @@ TORCH may charge a disclosed percentage or fixed minimum for: Illustrative launch structure: -- Fixed minimum for very small tasks. -- Percentage fee for larger milestones. +- Percentage fee with a fixed minimum, **priced and collected per milestone or per campaign — never per task**. - Lower rate for public open-source campaigns. - Higher rate for private or commercial campaigns. +**v0.2 correction — fee granularity:** BitUnlock's fee policy has a 10-sat per-order floor plus per-order invoice overhead, and no micro-fee rail exists (the Cashu attempt was reverted with its economics blocker unsolved). Sub-1000-sat per-task fees are uneconomical. Each milestone's coordination fee is one BitUnlock static-product purchase. + ## 16.2 Verification fee Independent verification consumes inference and human attention. @@ -990,7 +995,7 @@ A campaign may reserve a separate verification budget and TORCH may charge for: - Maintainer-ready synthesis. - Security disclosure handling. -Verification should appear as a separate economic line rather than being silently taken from the implementation budget. +Verification should appear as a separate economic line rather than being silently taken from the implementation budget. Concretely (v0.2): it is a **second BitUnlock static product** purchased alongside the coordination fee — not a payment split, which BitUnlock does not support. ## 16.3 Maintainer subscriptions @@ -1077,7 +1082,7 @@ BitUnlock can earn from: - Human-contributor access or claim tickets. - Subscription payments. - Premium recovery and reporting. -- Future multi-recipient settlement plans. +- Future multi-recipient settlement plans (Phase E; requires a BitUnlock protocol version change — see §14.4). BitUnlock’s value is not merely holding or routing money. It provides: @@ -1124,10 +1129,12 @@ Instead: 2,000 → sponsor-controlled reserve or explicit broker ``` +The five-way direct routing shown above is the Phase E aspiration; until then, TORCH's fee and the verification reserve are ordinary two-role BitUnlock orders, and the compute principal follows Mode A (sponsor-owned, never routed through TORCH at all). + At campaign completion: -- Unused provider balance returns to the sponsor where possible. -- TORCH’s earned fee is final once the contracted coordination work occurs. +- Unused provider balance returns to the sponsor where possible — **at the provider layer** (a Routstr session refund, or sponsor-owned OpenRouter credit that simply stays with the sponsor). BitUnlock itself has no refund path, by design. +- TORCH’s earned fee is final once the contracted coordination work occurs. Any goodwill return of a TORCH fee is an off-platform act, not a protocol feature. - BitUnlock’s fee follows its signed service policy. - Verification funds are released only for completed verification work. - Any nonrefundable component is disclosed before payment. @@ -1309,7 +1316,6 @@ A convenient pooled wallet may gradually become a general user-balance system. - Integration agents. - Maintainer acceptance gates. - Sponsor-supplied limited provider keys. -- Routstr ephemeral sessions. ### Phase C — Community Build network @@ -1317,6 +1323,7 @@ A convenient pooled wallet may gradually become a general user-balance system. - Pledges rather than upfront deposits. - Human testing. - Direct worker/provider settlement. +- Routstr ephemeral sessions via the TORCH provider gateway (Mode B, after the §14.2 custody design review). - Advanced notifications. - Organization subscriptions. @@ -1355,7 +1362,7 @@ Pilot requirements: - One approved feature contract. - Three to five milestones. - TORCH-operated workers. -- Sponsor-supplied limited OpenRouter key or Routstr session. +- Sponsor-supplied limited OpenRouter key or prefunded Routstr session, delivered directly into the runner environment — TORCH holds no provider credential. - Separate BitUnlock payment for TORCH coordination. - One independent verifier. - No pooled campaign wallet. @@ -1432,6 +1439,8 @@ Economic principle: - Routstr supports Lightning- or Cashu-funded ephemeral sessions, OpenAI-compatible requests, and refunding unused session value. - Routstr provider nodes may set a disclosed markup over upstream model costs. - FinCEN guidance distinguishes users purchasing goods or services from businesses engaged in accepting and transmitting convertible virtual currency, but the application to any particular TORCH structure is fact-specific. +- BitUnlock constraints in this document (no splits, no refunds, no escrow/holds, no webhooks, frozen payment roles, fee floor, Cashu revert) were verified against the BitUnlock codebase on 2026-08-03; see `V2_ARCHITECTURE_BRIDGE.md` §4 for file-level citations. +- The BitUnlock repository currently has **no license** ("all rights reserved") and its `@bitunlock/protocol` / `@bitunlock/sdk` packages are unpublished; TORCH must vendor them, so a license or vendoring grant is a Stage 0 blocker (dev plan item B0.2) for any open-source TORCH release. Official documentation reviewed: @@ -1444,3 +1453,23 @@ Official documentation reviewed: - https://docs.routstr.com/client/payments/ - https://docs.routstr.com/provider/quickstart/ - https://www.fincen.gov/resources/statutes-regulations/guidance/application-fincens-regulations-persons-administering + +--- + +## 27. Changelog + +### v0.2 (2026-08-03) + +Folded the code-reality corrections from `V2_ARCHITECTURE_BRIDGE.md` §4.5 after verifying TORCH 1.x and BitUnlock against their codebases: + +1. Mode D (direct multi-party settlement) confirmed as a BitUnlock protocol version change; Phase E only; nothing earlier may depend on it (§14.4, §17). +2. Pledges are TORCH-side signed Nostr events exclusively; BitUnlock has no holds or escrow (§14.3). +3. Coordination and verification fees are milestone-grained, never per-task; each is its own BitUnlock static-product purchase (§16.1, §16.2). +4. Campaign order tracking is poll-driven until BitUnlock ships lifecycle webhooks, and polling remains the reconciliation authority (§15). +5. Refund language scoped: unused compute returns at the provider layer; BitUnlock never refunds; TORCH fee returns are off-platform (§18). +6. Phase A is Mode A only — TORCH holds no provider credential; Mode B gated behind a durable-custody design review per the Cashu post-mortem (§14.2, §15, §23, §24). +7. Recorded the BitUnlock license/vendoring blocker (§26). + +### v0.1 (2026-08-03) + +Initial draft.