xln

Historical Raiden account-mechanism findings

Pinned implementation baseline: 5d89c1ebbd7b4f6216db76a09ca30ff16bf3ca6c. This preserves the original read-only research; its open items describe that baseline. Later deadline work and verification are recorded in the current implementation handoff. Use the consolidated comparison for current framing.


Raiden and generalized-account mechanism comparison

Read-only xln baseline: 5d89c1ebbd7b4f6216db76a09ca30ff16bf3ca6c. No shared-tree edits, benchmarks, test execution or paid models. Sources inspected as code, not adoption proxies. References to tests mean inspected assertions, not freshly green results.

Immutable source inventory

Highest-value followups

  1. Deadline-budget production regression, evidence gap/candidate, not a verified loss. Raiden mediator.py:90–111 and :735–789 switches from waiting to immediate public reveal at a remaining-lifetime safety threshold. xln already supports starter arguments, so importing another secret registry would duplicate an existing primitive. However, xln core/entity/paybook/lifecycle.ts:13,66–75 waits a fixed 120s after observing a secret; core/entity/scheduler/due-hooks.ts:46–57 defers another 120s if eight dispute starts fill the draft. Account admission needs only 30s enforcement reserve (core/account/consensus/dispute/deadline-policy.ts:7,35–43). Sequence: accept live upstream lock; settle downstream and learn secret; upstream withholds ACK; before the fixed timeout the upstream signed reveal deadline expires, or eight starts postpone reaction. Exercise this through real Runtime/WAL/J inclusion, compare secured rights on both legs. If reproduced, derive the existing scheduler deadline from the earliest signed lock deadline minus a configured J-inclusion budget; publish through the existing registry/start arguments and canonical outbox. No new durable oracle/cache. Starter evidence works only if start is timely: Account:1764/1797 binds evidence timestamp to J start; DeltaTransformer:278–286 checks that timestamp against the signed deadline. Finalize:157 independently queues public reveals, usually later. Test omitted from current ACK-timeout coverage, which asserts preparing the dispute rather than deadline-safe on-chain inclusion.
  2. Finish the custom-clause artifact before claiming implemented generalized superset, actual implementation gap. Account.sol:863–1032 already executes arbitrary signed staticcall clauses with per-token allowances. core/protocol/dispute/proof-builder.ts:229–245 serializes existing subcontract entries. But AccountSubcontract has address/bytes/allowances only (core/types/account.ts:95); searches of AccountTx/EntityTx handlers found no wallet-authored clause admission/approval/CREATE2 execution path. docs/counterfactual-transformers.md is explicitly SPEC. Counterfactual has actual CREATE2 address derivation and deployment assertions (packages/node/src/utils/create2-address.ts:30–79; funding test/create2.spec.ts:55–96). Minimum artifact: compile a constructorless approved clause, independently reproduce bytecode/address, sign, restart, deploy only for dispute, enforce exact allowance-limited outcome. Then establish what generalized apps are deliberately outside xln’s financial model.
  3. Remove stale skip-on-failure advice from SPEC, verified documentation conflict. SPEC section 2.5 recommends skipping a faulted clause; actual Account.sol:863–938 says a clause is the executable signed right and must fail finalization on missing code/revert/OOG/malformed return. Foundry TransformerFaultModes.t.sol:122–153 explicitly asserts fail-closed. Skipping an option exercise clause could give the writer the raw signed balance despite a valid holder right. Preserve strict policy and require executable/admitted immutable clauses; do not convert rights to optional hints. A bad jointly signed clause can freeze settlement: allowances bound value movement, not liveness. Production code has a 2M post-call gas reserve, not the SPEC’s proposed fixed 1M-per-clause policy.
  4. Measure watchtower service funding/inclusion under one correlated failure, operational evidence gap. Raiden MonitoringService:112–167 binds signed reward to authentic TokenNetwork and latest proof nonce; :238–296 schedules eligible services; :303–363 pays after response and timeout from UserDeposit. xln already has narrower owner-authorized, tower-address/account/proof-bound encrypted remedies (core/watchtower/last-resort-appointment.ts:121–175) and latest appointment selection, so do not import Raiden’s registry/token bureaucracy. Its default eligibility is final 20% of the signed sum (:231–253); core/watchtower/action.ts sends the transaction using towerWallet, with no implemented reimbursement found. maxFeeToken/feeBudget are accepted optional HTTP metadata, not evidence of a payment engine. Smallest experiment: real funded tower, owner offline, exact signed appointment, stale adversarial close, gas spike, eight+ simultaneous disputes, tower restart, prove latest counterproof inclusion before timeout. Then choose a simple service subscription or explicit funded gas arrangement outside RJEA; on-chain rewards would be a real new protocol choice.

Evidence matrix

Path shorthand TN=raiden_contracts/data/source/raiden/TokenNetwork.sol, SR=.../SecretRegistry.sol, MS=.../services/MonitoringService.sol; all resolve under pinned Raiden contracts above. Python paths resolve under pinned client, other paths explicit. Each row includes an adversarial sequence and next minimal check.

Mechanism Pinned upstream location xln code / inspected test evidence Assessment / adversarial sequence / minimal next check
Signature domain and stale proof TN:1535–1620 binds network, chain, type, channel, nonce, balance hash Account:523–606 binds chain/Depository/pair/nonce/proposer/body/watchseed; OnchainHankoDomain.test.ts:131,352 independent codecs Already covered structurally. Replay same bytes against another chain/Depository/nonce; use existing contract domain suite, do not add aliases.
Opening and funded ownership TN:249–294,1128–1184 creates unique active pair and deposited single token Account:1170–1233 R2C; Depository:63–75 reserve/collateral/debt stores Deliberate difference: xln account can operate with credit and multiple assets. Demonstrate zero-collateral funded claim vs unsecured debt explicitly; no need clone token-network-per-asset model.
Cooperative withdrawal race TN:382–461 cumulative signed withdrawals; :484–514 cooperative settlement complete deposit Account:1240–1300 C2R rejects dispute and stale nonce; current-board Hanko; proof-builder:448–456 next-nonce protection Covered mechanism, exact concurrent proof/withdraw cross-layer experiment unverified. Two signed C2R same nonce plus prior dispute proof: only canonical nonce outcome; then current proof remains enforceable.
Unilateral close and update TN:558–700 close/update;1187–1204 strict higher nonce Account:635–807 finalize selection; :1333 onward counterproof lock; equal-nonce left precedence Deliberate richer xln branch rule. Submit initial close then newer counterproof then old finalize in same batch; old proof must not settle. Existing dispute monotonicity tests inspected; no universal regression gap asserted.
Settlement conservation TN:763–882 verifies transferred/locked/root, clamps to deposited balances Depository:900–1004 wide delta, earmarked collateral, reserves, remaining debt; TransformerAllowance/DepositoryConservation foundry suites present xln superset financially: preserves debt rather than pretend unsecured value collateralized. Simultaneous exits test earmarked rights separately from free reserve first-mover effects.
Pending locks commitment TN:1461–1484 hashes concatenated 96-byte locks, :894–973 unlocks full set proof-builder:178–190 signed bounded payment clauses; constants:59 max32 locks Deliberate bounded representation. Current pinned Raiden is not Merkle inclusion unlock; historical Merkle wording would misdescribe this implementation. Max32 proof/restart/dispute closes all rights within budget.
Public secret / shared preimage SR:18–38 first-seen immutable timestamp, batches repeats harmless DeltaTransformer:404–415 same idempotent immutable timestamp; SecretRevealLiveness.test.ts:7–26 Already covered. Replay reveal at later block never refreshes deadline; shared secret unlocks all matching signed payments. Do not add second registry.
Deadline exactness TN:1487–1516 requires reveal strictly before unlockable_until DeltaTransformer:273–286 accepts <= signed seconds; proof-builder:180 converts exclusive ms via exclusiveUnixMsBigIntToUnixS; Account htlc-deadline.ts:11–25 Covered via representation difference, not automatically off-by-one bug. Verify deadline-1ms/deadline/exclusive-second boundaries through conversion and J timestamps.
Reveal danger zone Python mediator.py:90–111,735–789,805 onward registers known secret before unsafe wait or closed channel lifecycle:66–75 fixed120s; due-hooks:46–57 queue deferral; start-evidence:170–212 starter arguments Missing combined production timing evidence; candidate described above. Smallest real-WAL stalled-ACK/J inclusion regression before changing scheduler.
Expiry / reorg grace Python channel.py:183–202 sender2x/receiver1x confirmation grace;315–340 on-chain-known secret blocks expiry htlc-deadline exclusive timestamp/inclusive Jheight; deadline-policy pure local enforcement; watcher rpc-watcher-canonical.ts:113–145 authenticated rewind Deliberate finality architecture. Unfinalized reveal reorg must not mutate committed Entity truth, while finalized contradiction fail-stops. Need focused combined expiry/reorg artifact if absent; no code gap claimed.
Retry and route identity Python channel.py:817 refund identity, raiden_service.py payment IDs; network/pathfinding.py:702–732 feedback committed-htlc-followups.ts:108–138 Entity-wide live hashlock collision guard; persisted verified secret, exact frame binding :83–99 Already covered core one-live-payment identity, not full multipath promises. Delayed old route message after cancel/retry with fresh hash must not replace active route.
Route fees / liquidity Python network/pathfinding.py:467–501 signed cumulative IOU; routing.py:193–235 filters candidate first hop; feedback:702 pathfinding graph.ts:113, materialize-context.ts:224–242 derives capacity/directional fee and rejects short deadlines PFS feedback is optional operational optimization. Avoid global consensus liquidity registry. Measure whether repeated stale route attempts waste capacity before adding runtime-only hint caching.
Tower authority MS:112–167 validates registry/reward signature and latest nonce last-resort-appointment.ts:121–175 narrow owner Hanko; action.ts verifies exact proof+event+latest nonce; watchtower-last-resort.test.ts:90,207,630,792 Already covered cryptographic delegation, xln narrower financial authority. Malformed/stale tower never spends reserves or picks an unsigned state.
Tower economics MS:238–363 deterministic stagger and signed reward last-resort-appointment final20%; action.ts actual tower tx; HTTP optional feeBudget not payment execution Service funding/inclusion evidence gap. Run funded offline-owner correlated-exit scenario; do not automatically add service token, registry, or durable reward state.
Generic application transitions Nitro ForceMove.sol:39–79,218–232 uses app-specific supported-state relation; Counterfactual MixinRespondToChallenge.sol:25–89 turn-taker action; Perun channel/adjudicator.go:32–98 Register/Progress/Withdraw Account:863–1032 only signed financial transformer evaluation; no equivalent generic unilateral turn-taking API found Deliberate scope difference until a financial application needs forced intermediate progression. Static financial settlement clauses do not establish every generic app’s force-progress liveness. Construct a representative option/escrow financial right first; avoid a generic framework detour.
Counterfactual deployment Counterfactual create2-address.ts:30–79 and test/create2.spec.ts:55–96 implemented address+deployment docs/counterfactual-transformers SPEC; no AccountTx/EntityTx custom clause approval/deploy handlers found; proof-builder merely reads existing entries Real implementation gap for wallet-authored custom clauses. Produce one real compile/sign/restart/deploy/finalize path before broad superset claim.
Clause fault semantics Counterfactual ConditionalTransactionDelegateTarget.sol:122–146 propagates failed interpreter execution Account:863–938 strict failure; TransformerFaultModes.t.sol:122–153 failures tested; SPEC proposes skip Verified doc mismatch. Skipping signed financial meaning destroys rights; preserve strict execution. Wallet admission/immutable artifact is the improvement.
Hierarchical locked sub-apps Perun channel/adjudicator.go:64–80 requires signed child states in register/withdraw; Counterfactual freebalance activeApps in ConditionalTransactionDelegateTarget.sol:101–128 xln subcontracts in one signed ProofBody, 32 clause max; no isolated per-clause adjudication found Do not copy recursive settlement by default. If one broken jointly signed clause freezes otherwise valid obligations, design choice is admitted bounded clauses or independent financial Accounts; isolated child settlement is materially new protocol.

Examined / omitted

Examined actual Raiden close/update/settle/withdraw/unlock, registry timestamps, Python expiry/grace/danger-zone/refund checks, light-client reorg action handling, services fee/reward binding; xln domain/nonces, deadline predicates, starter arguments, queue/finalize ordering, public registry, route identity, proof/allowance/fault handling, tower authority; Counterfactual CREATE2 and turn-taking, Nitro app support predicate, Perun API/watcher intent.

Omitted: exhaustive all-history Raiden contracts/client revision changes; complete light-client/Python WAL crash replay; Perun EVM backend implementation (Go API is not contract proof); every arbitrary financial application’s representation/liveness theorem; all gas schedules/hardware capacities; full upstream or xln test execution. This is a detailed bounded mechanism study, not evidence that every edge case across all projects is exhausted.

XLNC owner scope preserved: conventional stateful EVM J, lower block gas, ordinary rebalance/disputes, phone/laptop full nodes. None of these recommendations requires stateless witnesses, ZK, a new ledger, or changed J/E/A ownership.