Create a new branch for this commit and start a pull request

[d-lf]

Pull Request: Specification Improvements to 15-open-ark.md

Summary

This PR improves the OpenARK specification's precision, completeness, and implementability. No changes to the core protocol design — all modifications clarify existing intent, fix errors, and fill gaps that would block independent implementation.

---

Changes by Category

🔴 Correctness Fixes

1. Fixed ambiguous HTLC script notation (Section 12, formerly Section 8)

Problem: The lock base B + H(P) + ( dT1 | S ) | A + ( T | B ) + ( dt2 | S ) used + for both AND and concatenation, making operator precedence unclear. An implementer could read this multiple ways.

Fix: Introduced a formal script notation section (Section 6) defining AND, OR, H(P), AFTER(T), and DELAY(dT) operators. Rewrote all HTLC scripts using this notation:

Success path: B AND H(P) AND (DELAY(dT1) OR S)
Timeout path: A AND (AFTER(T) OR B) AND (DELAY(dT2) OR S)

2. Fixed "signed by P" error in HTLC_Success (Section 12)

Problem: HTLC_Success said "It is signed by B, P, S" — but P is a preimage, not a signing key.

Fix: Changed to: "B signs the transaction and reveals the preimage P. The ASP verifies that SHA256(P) = H(P), verifies B's signature, and cosigns."

3. Fixed vtxo_spend_aborted vs vtxo_spend_failed inconsistency (Sections 9.1.3 and 9.3)

Problem: Section 7.1.3 used vtxo_spend_aborted, Section 7.3 used vtxo_spend_failed — unclear if these were the same message.

Fix: Unified on vtxo_spend_aborted throughout. Single message name, single definition.

4. Fixed Example 1.3 typos and incomplete fields

Problem: Multiple typos ("recives", "cointains", "Daves sees"), an empty bullet at step 3, and step 13 incorrectly said the HTLC_Success contains "H(P)" instead of the preimage P.

Fix: Rewrote Example 1.3 entirely — fixed all typos, completed all fields, added a proper sequence diagram, and added error case descriptions.

5. Fixed vtxo-root locking script ambiguity (Example 1.2, Section 13)

Problem: The notation A+B+C+E+S | S + T=400 implied the timeout path gives S (the ASP) unilateral spend authority after block 400, contradicting the "ASP cannot steal funds" property.

Fix: Changed to (A AND B AND C AND E AND S) OR (S AND AFTER(recycle_block)) using the new notation, and added explicit clarification that the timeout path is ONLY spendable into the presigned recycle transaction, which preserves per-user outputs. Added this explanation in Section 4 (trust assumptions), Section 13.2, and Section 20 (security considerations).

6. Clarified recycle transaction timelock enforcement (Section 3, Section 13.4)

Problem: The unilateral recycle tx was described as "presigned sufficiently for the ASP to broadcast after the recycle block" but nothing prevented early broadcast.

Fix: Added explicit requirement that the unilateral recycle transaction MUST include a script-level OP_CHECKLOCKTIMEVERIFY enforcing the recycle block height.

7. Clarified forfeit atomicity mechanism (Section 3, Section 13.3)

Problem: Forfeit transactions were described as "atomically binding" old VTXOs to the new vtxo-root, but the mechanism for atomicity was never stated. If they were separate transactions, they wouldn't be atomic.

Fix: Added explicit statement that the forfeit root is an output of the new vtxo-root transaction itself, making them atomic in a single on-chain event.

---

🟡 Structural Improvements

8. Added formal Script Notation section (new Section 6)

Why: A BOLT-style spec needs unambiguous script definitions. Defined operators (AND, OR, H(P), AFTER, DELAY) with a grammar that prevents the ambiguity in the original notation.

9. Added Message Catalog (new Section 11)

Why: The original spec described messages narratively ("containing funds to onboard, funds to offboard") but never defined them formally. Added tables for all 14 protocol messages with direction, description, and required fields. This is essential for independent implementation.

10. Added VTXO Tree Construction section (new Section 8)

Why: The spec never described how the ASP decides tree topology, which directly affects unilateral exit cost. Added constraints (balanced binary tree, max depth 10, no degenerate trees) and cost analysis.

11. Added Parameter Recommendations section (new Section 24)

Why: The spec referenced min_timeout, max_timeout, dT1, dT2, closing block, recycle block, etc. without guidance on values or the required relationships between them. Added a parameter table with recommended ranges and safety constraints (e.g., dT1 < T, recycle_block >= closing_block + RECYCLE_DELTA).

12. Added Fee Model section (new Section 17)

Why: The spec had no discussion of fees. Who pays for on-chain transactions? How are ASP fees structured? What's the XLP return? Added framework covering on-chain fees, ASP service fees, XLP returns, and the requirement that all fees be verifiable before signing.

13. Added HTLC Timelock Safety constraints (Section 12)

Why: Multi-hop HTLC forwarding requires specific timelock relationships for safety. Added constraints: dT1 < T, dT2 < T, T < closing_block, and per-hop cltv_expiry_delta decrement consistent with BOLT #2.

14. Promoted Cloud Agents to a numbered section (new Section 15)

Why: Was an unnumbered block between Sections 9 and 10. Gave it a proper section number, added sub-sections for key structure, deployment models, and an agent capabilities table.

15. Promoted External Liquidity Providers to a numbered section (new Section 16)

Why: Was embedded at the end of another section. Extracted into its own section with sub-sections for the funding mechanism, signing protocol, and funding flow. Added a TODO for specifying the exact threshold signing protocol.

16. Expanded Failure Modes to a table (Section 21)

Why: Original was three bullet points. Expanded to a table covering six failure scenarios with impact and recovery path for each.

17. Consolidated HTLC content (Sections 9.3 and 12)

Why: HTLC mechanics were split between "7.3 HTLC Transitions" and "Section 8 HTLC Semantics." Reorganized: Section 9.3 now describes the generic vtxo_spend_request pattern, Section 12 specializes it for HTLCs with full script definitions.

---

🟢 Cleanup

18. Removed "RM:" working notes at the end

Why: The document ended with raw working notes ("RM: A round transition is done in several phases...") that duplicated Example 1.4 with different terminology ("transferred" state, "Phase 3.1/3.2"). Having two competing descriptions of the same flow in one document would confuse implementers. The content is fully captured in Example 1.4 and the round lifecycle sections.

19. Added unilateral exit cost discussion (Sections 8.2, 14)

Why: The spec claimed users can always exit unilaterally but never acknowledged the cost scales with tree depth. Added explicit cost analysis and bounds.

20. Added privacy note about tree structure (Section 19)

Why: The VTXO tree structure reveals participant count per round. Added note that implementations MAY pad with dummy leaves.

21. Marked RGB section as experimental (Section 18)

Why: Original was three lines of normative-sounding text with no substance. Marked as experimental with a note that detailed template definitions are deferred.

22. Renumbered all sections for consistency

Why: New sections required renumbering. Updated all internal cross-references (e.g., "see Section 7.3" → "see Section 9.3").

---

What This PR Does NOT Change

• Core protocol design: The VTXO model, round lifecycle, forfeit/recycle duality, and Nostr transport are unchanged.
• Message flow: No new messages or flow changes — only formalized what was already described narratively.
• Examples 1.0, 1.1, 1.2, 1.4: Preserved intact (with notation updates). Only Example 1.3 was rewritten to fix errors.
• Trust assumptions: All existing trust properties are preserved and made more explicit.

---

How to Review

1. Start with Section 6 (Script Notation) — this is the new grammar used throughout.
2. Check Section 12 (HTLC Semantics) — the scripts are rewritten; verify they match the original intent.
3. Skim Section 11 (Message Catalog) — verify the message fields match your implementation.
4. Read Section 13 (Forfeit/Recycle) — the atomicity and timelock clarifications are the most security-critical changes.
5. Check Section 24 (Parameters) — verify the constraint relationships make sense operationally.