This post is the index. Each phase has its own deep-dive post and a living docs page, so you can deep-link to exactly the part you care about.

Why we are doing this​

The current flow works, but it has a simple structural problem: between deposit and settlement, OrcaRail holds the funds. That is true even though we never hold merchant operating balances — the in-flight moment between "payer sent" and "merchant received" is custodial. Removing that moment is a security, compliance, and reliability win.

Concretely, the legacy path looks like:

The target is:

Funds never pass through a wallet we control. Splits happen on-chain. Subscriptions pull from an allowance the payer can revoke at any time.

What is changing, in one page​

The roadmap​

Each phase is self-contained and shippable. Early phases remove custody for the largest volumes (EVM payments and subscriptions) and later phases tackle the harder chains and optional decentralization.

• Phase 0: Designing a non-custodial payment stack — fee/split spec freeze, chain selection, audit vendor, deployer multisig, the subscription-model decision matrix.
• Phase 1: Contract-based payment links on EVM — PaymentLinkFactory + PaymentLinkReceiver + FeeSplitter, deterministic addresses, event indexer.
• Phase 2: Allowance-pull subscriptions — SubscriptionHub, new payer flow, keeper replacing the custodial auto-charge processor.
• Phase 3: Multi-EVM rollout and keeper redundancy — Ethereum, Arbitrum, Optimism, Polygon + Chainlink/Gelato fallback.
• Phase 4: Non-custodial Solana with Anchor PDAs — payment_link and subscription Anchor programs, SPL delegate auto-charge.
• Phase 5: Bitcoin — taproot 2-of-2 and honest scope — reduced custody, pre-signed refunds, Lightning BOLT12 as future work.
• Phase 6: Decentralized scheduler and EigenLayer — when an AVS helps and when it does not.
• Phase 7: Retiring the custody infrastructure — dropping hd_wallet_seed, removing sweep paths, updating TOS.

A companion post, Why allowance-pull beats escrow and session keys, explains how we picked the subscription model.

What this means in practice​

For merchants: after Phase 1, nothing changes in the API — payment-link URLs and webhooks behave the same. Withdrawal rules move from "settle after sweep" to "emit on pay". You get a faster, cheaper, more auditable path without code changes. Phase 2 adds a new public endpoint for payers to register their on-chain approve, matching the flow documented in Auto-charge.

For payers: one-off payments feel identical. Subscriptions add one extra signature at setup (the on-chain approve) and a clearer "revoke" path: revoke on-chain, and OrcaRail stops trying. Your funds never leave your wallet until the contract pulls them, and never sit in a wallet we control.

For integrators: API shape stays stable. New fields (contract addresses, deployment chain, allowance metadata) are additive, behind a feature flag per chain. Existing integrations keep working through their current renewal cycle and migrate on opt-in.

What stays custodial (for now)​

Bitcoin. We will reduce custody materially in Phase 5 by moving every link to a 2-of-2 taproot multisig with a merchant signer, plus pre-signed refund PSBTs. But Bitcoin L1 does not have the contract expressiveness to eliminate custody outright today. BTC subscriptions remain out of scope until Lightning BOLT12 recurring payments are ready.

Timeline and status​

The full plan is tracked at /docs/non-custodial/roadmap and each phase has a status page:

• Planned: 0 — 7
• In progress: none yet
• Shipped: none yet

We will publish a dated update post each time a phase ships.

Read the architecture docs​

For the reference version of all of this — architecture diagrams, contract surface, migration guide, security model — start at /docs/non-custodial/overview.

OrcaRail App · Docs · Non-custodial docs

It extends — it does not replace — the non-custodial roadmap and the protocol debate. The non-custodial roadmap (Track N, Phases 0-7) removes custody. This whitepaper adds a parallel Track P that decentralizes the rest: indexers, frontends, standards, keepers, and governance.

Abstract​

OrcaRail Protocol is a set of on-chain primitives — payment-link factories and receivers, allowance-pull subscription hubs, fee splitters, Anchor programs on Solana, and taproot multisig descriptors on Bitcoin — together with public specifications for indexers, keepers, frontends, and SDKs that operate on top of those primitives. The protocol satisfies four invariants: non-custodial (no party holds funds in transit), non-stop (legitimate settlement continues without OrcaRail), credibly neutral (no single party can censor a well-formed paid transaction), and web2-compatible (merchants keep API keys, webhooks, and dashboards). The rollout is two parallel tracks: Track N removes custody in seven phases; Track P decentralizes indexing, frontends, standards, and settlement routing in five phases. No token exists at launch and none is planned as part of this whitepaper; a future governance token is explicitly reserved as an option for post-decentralization and would, if introduced, ship under its own whitepaper.

1. Introduction — Why a protocol, not just a product​

OrcaRail ships today as a hosted payments product with self-hosted options on the way. That is a product, not a protocol. Products can be improved; protocols can be trusted in absentia.

The non-custodial roadmap takes custody out of the path. That is necessary but not sufficient. Even without custody, a payment rail can still break if the company running it stops paying AWS bills, gets sanctioned, or simply pivots. A protocol has to keep working when those things happen.

The protocol debate walked through five architectures. The synthesis was: ship the Pragmatist path, enforce Maximalist pressure against it, adopt intents for payer UX, write standards along the way, keep own-chain as an optional future. This whitepaper is that synthesis written as commitments.

2. Design goals​

Each goal is stated with a precise, testable definition. "Does the design satisfy this?" must have a yes-or-no answer.

1. Non-custodial — At no point during a payment or subscription charge does a wallet or account controlled by OrcaRail, a merchant's processor, or any intermediary hold the payer's funds. Test: can a regulator freeze in-flight funds by serving OrcaRail alone? No.
2. Non-stop — If OrcaRail's servers go dark indefinitely, a legitimate due subscription charge still settles on-chain, and a payer can still complete a one-off payment. Test: after a 30-day OrcaRail outage, has any correctly-configured subscription missed a charge? No.
3. Credibly neutral — The on-chain rules are public, immutable per-link, and applied equally. OrcaRail cannot selectively deny service at the settlement layer (only at its own frontend). Test: can an unwelcome merchant still be paid through a third-party frontend? Yes.
4. Web2-compatible — Merchants retain the ergonomics they already have (REST endpoints, webhooks, API keys, dashboards, email). Protocolization does not require a merchant to run Ethereum tooling to accept a payment. Test: can a non-crypto-native merchant integrate in under an hour? Yes.
5. Real P2P — Defined precisely in the next section.

A design that misses any goal is incomplete.

3. What "real P2P" means here​

Peer-to-peer is overloaded. In this protocol it has three concrete layers.

• Settlement P2P — Payer signs; funds flow payer → on-chain contract (EVM) or program-owned PDA (Solana) or 2-of-2 multisig (Bitcoin) → merchant and fee recipients, atomically. No OrcaRail wallet is in the path. This is enforced by Track N.
• Discovery P2P — A payment link or subscription is fully resolvable from its on-chain data plus (optionally) IPFS-pinned metadata. Any wallet, any frontend, any third-party processor can render and complete it. OrcaRail's hosted dashboard is one implementation of the rendering layer, not the registry.
• Liveness P2P — SubscriptionHub.charge(id) and the Anchor charge instruction are public. Any EOA or solver can call them. OrcaRail's scheduler is one participant among several (Chainlink, Gelato, merchant-run, solver-run).

What "real P2P" does not mean here: we are not Lightning; we are not a direct wallet-to-wallet channel layer; we are not replacing a payment app with a DHT. OrcaRail is an on-chain protocol with off-chain UX. The P2P property comes from the impossibility of a middleman interposing on settlement, discovery, or liveness — not from avoiding on-chain rails.

4. System architecture​

At the highest level, the protocol is five layers.

The settlement layer is immutable-per-link on EVM and Solana, and per-link descriptor-derived on Bitcoin. The other four layers are swappable. A reader who wants the full technical diagram should go to /docs/non-custodial/architecture.

5. Settlement primitives​

Full reference: /docs/non-custodial/contract-reference. Summary:

• EVM — PaymentLinkFactory (CREATE2 deterministic addresses), PaymentLinkReceiver (EIP-1167 minimal clone, immutable per link), FeeSplitter (basis-points atomic split), SubscriptionHub (allowance-pull with monotonic lastChargedAt).
• Solana — payment_link Anchor program (PDA per link, CPI splits) and subscription Anchor program (SPL delegate authority, identical charge semantics to the EVM hub).
• Bitcoin — 2-of-2 taproot multisig per link (merchant signer + platform signer from HSM/MPC) with pre-signed refund PSBTs. No recurring BTC until Lightning BOLT12 recurrence matures.

Every primitive is designed so that the same linkId or subscriptionId resolves to the same deterministic address on the same chain forever — no address rotation, no re-issuance, no server-held mapping.

6. Cross-chain as intents​

A protocol that treats cross-chain as "our backend calls Relay" is still a product. A protocol treats cross-chain as a payer intent:

• The payer signs: "pay merchant X, $50 USDC, from any of my wallets on any supported chain, within 1 hour, with fees up to Y."
• Existing solver networks — Across, Relay, deBridge, CoW-style — compete to fulfill the intent. Solvers are paid a bounty embedded in the intent.
• For un-economic long-tail routes (small amounts, obscure chains) OrcaRail runs a fallback solver at cost so the tail still settles. The fallback is public and anyone else can run one too.

The payer signature is bounded by amount, recipient, deadline, and max fee. Worst case a malicious solver is slow; they cannot redirect funds. This is the "Intents Believer" synthesis from the protocol debate, written as a commitment.

7. Standards and interoperability​

OrcaRail's payment-link and subscription primitives are a generic rail. Their value compounds only if other processors, wallets, and indexers implement them natively.

Commitments:

• Draft an EIP for non-custodial payment links using PaymentLinkFactory and PaymentLinkReceiver as the reference surface. Co-author with at least one other processor or wallet team to avoid the "EIP from one vendor" pattern.
• Draft an EIP for allowance-pull subscriptions using SubscriptionHub as the reference. Monotonic lastChargedAt and the ChargeSkipped(reason) reason set are standardization targets.
• Publish a Solana mirror via Anchor IDL and a written spec, so any Solana wallet or indexer can render a payment link from first principles.
• Publish the canonical subgraph schema so any indexer (The Graph, Goldsky, Envio, self-hosted) can be drop-in compatible.

Writing the EIP does not reduce our moat. As argued in the debate, the moat is in integrations, compliance, SLAs, and merchant trust — none of which an EIP copies.

8. Governance​

Governance sits on two horizons.

Today and near-term​

• EVM: 3-of-5 Safe multisig on each deployed chain. Hardware-wallet signers. Annual rotation. 48-hour timelock on proxy upgrades. Per-link PaymentLinkReceiver instances are immutable.
• Solana: 3-of-5 Squads multisig with the same signer set and rotation policy.
• Upgrade scope: factories and hubs sit behind UUPS proxies; per-link receivers and per-subscription records do not move under upgrades.
• Publicly auditable: every deploy and upgrade runs as an announced multisig ceremony with signed transactions recorded.

This is the governance described in /docs/non-custodial/security-model.

Post-decentralization​

Over time the signer set stops being exclusively OrcaRail employees and becomes a public council drawn from integrators, audit firms, keeper operators, and independent contributors. Upgrade authority migrates to the council. On-chain governance becomes a live option at this point — but only as a governance mechanism, not as a speculation vehicle.

The threshold for "post-decentralization" is explicit: at least three independent production frontends hosting the rail, at least three independent keepers firing charges, and at least one non-OrcaRail processor shipping integrations. Until those are real, the protocol is not yet decentralized regardless of what governance mechanism sits on top.

9. Future governance token (explicit reservation)​

This section is deliberately short and deliberately specific.

• No token at launch. No presale. No allocation. No points. No retroactive claims.
• A future governance token is reserved as an option, not as a commitment. It becomes appropriate only after the post-decentralization threshold in section 8 is met and a live base of integrators, keepers, and frontends exists that would benefit from formal signaling rights.
• If we ever introduce one, it ships under its own whitepaper, with complete transparency on distribution, lockups, supply, and governance surface. The token whitepaper would be debated publicly before issuance.
• The token would be governance-first, not speculation-first. Mechanisms that make sense: signaling upgrade votes, parameter setting within safe bounds, keeper operator reputation. Mechanisms that do not: fee discounts tied to holdings, pay-to-pay, yield farming.
• We will not claim the protocol is decentralized because a token exists. Decentralization is measured by the things in section 8. A token is an instrument that can formalize already-achieved decentralization; it cannot manufacture it.

This reservation is recorded in the protocol whitepaper — this document — and nowhere else. Any future change to this stance is a change to this whitepaper, published publicly, not a unilateral announcement.

10. Economics and fees — how the protocol sustains itself without a token​

The protocol's revenue model is the same as the product's, just encoded on-chain.

• Fee split lives in the FeeSplitter basis-points configuration per payment. Same buckets the withdrawals page describes today: merchant, platform (OrcaRail's hosted share), referral/affiliate, bridge fee.
• OrcaRail-hosted surface (dashboard, email, paymaster gas, customer support) is paid for by OrcaRail's share of the split.
• Alternative hosts — third-party processors, self-hosted operators, IPFS-pinned frontends — can ship with a zero-platform-bps split, or configure their own fee recipient. The protocol does not privilege OrcaRail's fee over anyone else's.
• No emission, no subsidy, no staking yield. Costs are cash costs and cash revenues. The only way the protocol gets cheaper is if gas gets cheaper or a host accepts a smaller margin — not by issuing tokens to paper over running costs.

11. Security model​

Full statement: /docs/non-custodial/security-model. Core posture:

• Per-link receivers and per-subscription records are immutable.
• Factories and hubs are upgradeable only through multisig + timelock.
• Keepers are gas-only EOAs with no fund-movement authority.
• BTC signing uses an HSM or MPC service on the platform side, plus a merchant key; no server holds unilateral spend authority.

One addition specific to protocolization: independent frontend hosts must verify contract addresses against an on-chain registry (or a signed release manifest) before rendering a payment link. A malicious clone frontend that points payments at a look-alike contract is the most likely phishing vector once the ecosystem has multiple hosts. The canonical registry lives on-chain and the verification flow is documented as part of P2.

12. Roadmap — two parallel tracks​

The protocol rollout runs as two tracks at once.

Track N is the existing roadmap, unchanged. Track P formalizes the M1-M5 commitments from the debate post as phases. Both tracks target the same end state: a rail that keeps running if OrcaRail steps away.

Track P never blocks Track N and Track N never blocks Track P. Either track can ship a phase before the other.

13. Track P phases​

Five phases, each a natural extension of an M-commitment from the debate post.

P1 — Public subgraph and open indexer​

Scope: a canonical subgraph (The Graph, Envio, or equivalent) that indexes every Paid, SubscriptionCreated, Charged, ChargeSkipped, Canceled, and Refunded event from PaymentLinkReceiver and SubscriptionHub across every deployed chain. Schema published. Self-host instructions shipped so anyone can run the same index.

Status checklist

• Subgraph manifest + mappings for EVM chains live in Phase 1 and Phase 3
• Solana equivalent (Helius webhooks or Triton stream) with same event shapes
• Schema documented and stable-versioned
• One external indexer demonstrated running the same schema against live events

P2 — Decentralized frontends (IPFS / ENS)​

Scope: pin the OrcaRail pay app and merchant dashboard to IPFS with content-addressed release bundles. Resolve via ENS (pay.orcarail.eth, app.orcarail.eth). Reproducible builds so any reader can verify the bundle matches the source. A malicious clone has to impersonate both the contract addresses and the ENS record, not just the hostname.

Status checklist

• Pay app builds reproducibly
• Dashboard builds reproducibly
• ENS records pointing to IPFS CIDs
• Release-signing ceremony from the Safe multisig
• On-chain contract-address registry frontends verify against before rendering

P3 — Standards (draft EIP)​

Scope: draft and submit an EIP for non-custodial payment links and a companion EIP for allowance-pull subscriptions. Co-author with at least one other processor or wallet team. Reference implementation is the OrcaRail contracts. Solana mirror spec published alongside the EIPs.

Status checklist

• Co-author confirmed
• Payment-link EIP draft in discussion-thread state
• Subscription EIP draft in discussion-thread state
• Solana spec published alongside Anchor IDLs
• EIP editor feedback incorporated through Last Call

P4 — Intent-based payer SDK​

Scope: an SDK surface (orcarail.pay(intent)) that accepts a payer-signed intent and routes it through existing solver networks (Across, Relay, deBridge) with an OrcaRail-run fallback solver for long-tail routes. Intent schema standardized in sync with P3.

Status checklist

• Intent schema finalized
• SDK adapter for at least two solver networks
• Fallback solver deployed and metered
• Payer UX in the pay app supports same-intent + cross-chain
• Spec published as part of the Node SDK reference

P5 — Self-host / reference implementation kit​

Scope: a Docker-compose (and Helm chart) that lets anyone run an OrcaRail-compatible processor end-to-end from the public contracts. Includes subgraph, keeper, indexer, optional dashboard, and an OpenAPI specification of the processor API that others can conform to.

Status checklist

• Docker-compose that boots against a live chain and services a test merchant
• OpenAPI spec for the processor API
• Helm chart for Kubernetes operators
• End-to-end test that a self-hosted operator can process payments identical to the hosted version
• Documentation in /docs/non-custodial/ (added in a future docs-only change; out of scope for this whitepaper)

14. Optional P6 — Own-chain evaluation​

P6 mirrors the EigenLayer evaluation pattern. It is not a commitment. It is a quarterly review with specific triggers.

Current recommendation: defer.

Triggers that would open a design doc for a Phase P6 build:

1. Payment volume on a single chain exceeds a threshold where gas becomes a material line-item of the platform fee.
2. A canonical L2/L3 toolchain offers specialized precompiles for payment-split semantics at near-zero cost.
3. Merchant demand for sub-cent settlement latency that mainnet / L2 consistently cannot meet.
4. A partner rollup-as-a-service lets OrcaRail ship with shared sequencing on day one.

If triggered, the build would prefer OP Stack with shared-sequencing (Espresso, Astria) and a credible exit bridge to the canonical chains we already support. Even then, Phases N0-N7 and P1-P5 must be mature enough that an own chain is an optimization, not a dependency.

15. What OrcaRail is today vs. what it becomes​

A before/after at the rail level.

The Web2-facing surface stays stable on purpose. Merchants that integrated against the REST API in 2026 do not break in 2028.

16. Threat model​

The threats we are explicit about, with their mitigations:

• Contract bug → multiple audits per contract; immutable per-link receivers; UUPS upgrades behind 48-hour timelock on factories and hubs; public bug bounty.
• Keeper outage → Track N Phase 3 keeper redundancy (Chainlink/Gelato) + Track P P4 solver network + public manual charge() fallback.
• Frontend phishing → Track P P2 on-chain contract registry + ENS content-addressing + release-signing ceremony from the Safe multisig.
• Governance capture → Multisig signer rotation; 3-of-5 threshold; post-decentralization council drawn from independent operators; public ceremonies.
• Regulatory action against one host → Track P P5 self-host kit + multiple independent frontends so merchants have alternate rails.
• Subgraph or indexer drift → Canonical schema + reproducibility tests; multiple independent indexers.
• Solver market thinness → OrcaRail fallback solver at cost; permissionless entry for new solvers.
• BTC key loss → Backup xpub at merchant onboarding; HSM failover; pre-signed refund PSBTs keep payer recovery possible.
• EVM reorgs → Monotonic lastChargedAt in SubscriptionHub; Solana equivalent in last_charged_at.
• Token-induced distortion → No token at launch; explicit reservation; any future token gated on independent-operator thresholds before it can claim a governance role.

17. Open questions we are honest about​

Writing this document does not solve every question it raises.

• When does "post-decentralization" start, precisely? Section 8 gives a threshold (three independent frontends, three independent keepers, one non-OrcaRail processor). Whether that threshold is the right one is an open debate.
• Who pays for the public subgraph at scale? The Graph has a market; self-hosted is free but operationally heavy. Economics are not yet settled.
• What is the exit story for a merchant whose primary frontend host disappears? P5 makes self-hosting possible; it does not make it automatic. A "migrate-my-store-to-another-host" flow is future work.
• What does governance actually decide in a protocol with immutable per-link contracts? Upgrades to factories, parameter-setting on hubs (paused token lists, new chain deployments), fee-split defaults for OrcaRail-hosted traffic — but not much more. Whether that is enough scope to justify on-chain governance is part of the post-decentralization conversation.
• What happens to the protocol if OrcaRail, the company, changes its mind about the reservation in section 9? Any change is a published change to this whitepaper. No unilateral, quiet pivot.

18. Conclusion — A call to builders​

The non-custodial roadmap gets the rail off custody. This whitepaper gets the rail off OrcaRail. Both need to ship for either to matter.

If you are building a wallet, a dashboard, an indexer, a solver, a compliance tool, or a rival processor — the protocol is designed to accept your contribution without asking permission. Co-author the EIP. Run the subgraph. Pin your own frontend. Run a keeper or a solver. File issues against the reference implementation. The more of Track P is done by people who do not work at OrcaRail, the more the protocol earns the word protocol.

The Web2 merchants we work with today will not notice any of this — their API keys, webhooks, and dashboards keep working. That stability is the point. We are changing the foundation of the rail, not the surface the merchants touched when they signed up.

References

• The OrcaRail Non-Custodial Roadmap — Track N
• The Protocol Debate: Five Visions for a Fully Non-Custodial OrcaRail — origin of Track P
• Why allowance-pull beats escrow and session keys — subscription-model decision
• Architecture — full technical architecture
• Contract reference — ABIs, events, and addresses
• Security model — trust assumptions and key custody
• Roadmap — Track N phase status
• EigenLayer evaluation — pattern reused for P6

TL;DR​

• Fee split is frozen to four buckets: merchant, platform, referral/affiliate, bridge fee. Everything in the on-chain splitter is expressible in basis points; no off-chain fix-ups.
• Base is the launch chain for Phase 1. Cheap, fast, already in the wallet service chain list, and USDC-native.
• Subscriptions adopt ERC-20 approve + pull (EVM) and SPL delegate (Solana). Escrow and session-key designs were rejected — see the decision matrix below.
• Contracts are deployed by a 3-of-5 Safe multisig (EVM) and 3-of-5 Squads multisig (Solana). Per-link receivers are immutable. Factories and SubscriptionHub sit behind a small proxy with a 48-hour timelock.

What this phase changes​

Nothing in production. Phase 0 is a written spec, three audit proposals, a deployer-key ceremony, and a couple of merged ADRs.

The fee split spec (frozen)​

Today, SmartAccountWalletService.drainSmartAccountWallet in api/src/withdrawals/services/smart-account-wallet.service.ts composes transfers into a UserOperation with three recipients: the merchant (toAddress), the support wallet (supportWalletAddress), and the commission wallet. The contract version mirrors this exactly:

struct Split {
    address merchant;   // main receiver
    address platform;   // support / platform fee
    address referral;   // commission / affiliate (optional, zero = skip)
    address bridgeFee;  // Relay bridge fee carrier (optional, zero = skip)
    uint16 platformBps;
    uint16 referralBps;
    uint16 bridgeFeeBps;
}

Everything the keeper does today in TypeScript is computable from this struct and the payment amount. Anything the current keeper cannot express (e.g. dynamic taxes, merchant-level holdbacks) is out of scope for Phase 1 — we add it in a later phase if needed.

Chain selection​

Launch chain for Phase 1 is Base:

• Already in our chainId map (8453 → base, 84532 → baseSepolia) in api/src/payments/wallet.service.ts.
• Gas is cheap enough that PaymentLinkReceiver deploy + split on first pay is pennies per transaction.
• Alchemy paymaster policy already supports it, which gives us an escape hatch if we want the keeper on SubscriptionHub.charge() sponsored.
• Native USDC (not bridged), which matters for subscription allowances.

Ethereum mainnet, Arbitrum, Optimism, and Polygon follow in Phase 3. Solana is a separate program, tracked in Phase 4.

Subscription model: the decision matrix​

We evaluated three designs. Only one works for us.

Approve + pull is the only one that works with the wallets payers already use (MetaMask, Phantom, hardware wallets, Safes). It is also the design we already publish in Auto-charge, which documents approve(spender, amount) and SPL delegation. Phase 2 replaces the pull side with a smart contract and leaves the payer side unchanged.

The long-form argument is in Why allowance-pull beats escrow and session keys.

Deployer key custody​

• EVM: Safe (formerly Gnosis Safe) on Base with 3-of-5 threshold. Signers: two founders, one ops lead, one advisor, one cold backup. Each signer uses a hardware wallet; no key on a server.
• Solana: Squads multisig with the same 3-of-5 setup and the same signers.
• Rotation: every signer rotates annually or on departure; any single rotation is a Safe/Squads transaction.
• No hot keeper can deploy. The NestJS keeper EOA (used to call charge() in Phase 2) has no deploy authority, no upgrade authority, and no fee address.

Upgrade policy​

• Per-link PaymentLinkReceiver: immutable. No upgrade. This is a trust win for payers — the code they are paying into can't change after the fact.
• PaymentLinkFactory: small UUPS proxy owned by the multisig, 48-hour timelock on upgradeTo. Upgrades cannot change already-deployed receivers.
• SubscriptionHub: same pattern. charge() and cancel() semantics are stable between versions; if we ever need a breaking change, we deploy SubscriptionHubV2 and migrate instead of upgrading.
• Refund and dispute semantics: on-chain refund(txId) callable by the merchant signer (via their API key → keeper EOA) or the deployer multisig. Payer cannot self-refund (matches today's product).

Audit vendor strategy​

We will shortlist three firms and run one primary audit + one competitive review:

• Primary candidates (EVM): Spearbit, Trail of Bits, Zellic.
• Secondary candidates (Solana): OtterSec, Neodyme.
• Scope: PaymentLinkFactory, PaymentLinkReceiver, FeeSplitter, SubscriptionHub. The Anchor programs get their own audit in Phase 4.
• Budget: treat the audit as a hard prerequisite for Base mainnet launch. No mainnet before the fix-all report.
• Public disclosure: audit reports land in the repo and link from /docs/non-custodial/security-model.

Risks and mitigations​

• Spec scope creep. Mitigation: everything not expressible as basis-points-split is deferred to a later phase. Phase 1 does not block on dynamic taxation or per-merchant overrides.
• Multisig signer availability. Mitigation: 3-of-5, not 2-of-3, so any two signers can be unavailable without freezing deploys.
• Audit timing. Mitigation: start vendor conversations now; ship contracts to testnet during audit; mainnet deploy is gated.
• Forgotten fee case. Mitigation: reproduce every path in drainSmartAccountWallet today (native + ERC-20, with/without support, with/without commission) as a Foundry invariant test before audit.

Status checklist​

• Fee split struct approved and tagged
• Base selected as Phase 1 launch chain
• Three audit vendors shortlisted
• Safe (Base) and Squads (Solana) deployer multisigs created and tested
• ADR merged covering upgrade policy and timelock
• ADR merged covering subscription model decision
• Refund / dispute semantics documented

What is next​

Phase 1 implements the spec: Contract-based payment links on EVM.

Reference docs: Phase 0 status · Security model · Architecture

TL;DR​

• PaymentLinkFactory.computeAddress(linkId) returns a deterministic CREATE2 address. We show that address to the payer before anything is deployed.
• PaymentLinkReceiver is an EIP-1167 minimal clone. It accepts native or ERC-20, emits Paid, and calls FeeSplitter.split() in the same transaction.
• api/src/payments/wallet.service.ts stops generating HD wallets for EVM links; it calls the factory view instead.
• The sweep path (drainSmartAccountWallet, getSmartAccountClientForDepositWallet) is bypassed for links created under the useOnChainReceiver flag.

What this phase changes​

The "after" side has no box we control sitting on the funds.

Contracts introduced​

All under a new package contracts/evm/.

PaymentLinkFactory​

• computeAddress(bytes32 linkId) view returns (address) — deterministic CREATE2 address derived from linkId (the existing payment-link UUID, hashed to bytes32).
• deployAndPay(bytes32 linkId, Split split, address token, uint256 amount) — lazy deploy + pay in one transaction. The factory clones the PaymentLinkReceiver implementation, initializes it with the Split, and forwards funds.
• isDeployed(bytes32 linkId) view returns (bool) — helper used by the indexer and UI.
• Upgradeable behind a UUPS proxy, owned by the deployer multisig (3-of-5 Safe), 48-hour timelock on upgradeTo.

PaymentLinkReceiver (clone)​

• Immutable after initialization. Stores the Split struct and the FeeSplitter address.
• pay(address token, uint256 amount) — handles native and ERC-20 in one entry point. Uses SafeERC20 so non-standard tokens (USDT) work. Emits Paid(linkId, payer, token, amount).
• Calls FeeSplitter.split() atomically. If the split reverts, the pay reverts.
• Explicit refund(bytes32 txId) callable only by the merchant keeper EOA or deployer multisig.

FeeSplitter​

• split(Split s, address token, uint256 amount) — distributes by basis points. Remaining wei goes to the merchant (no dust loss).
• Emits Split(txId, merchant, platform, referral, bridgeFee) for indexer parity with legacy webhook payloads.

API changes​

The single biggest code change is in api/src/payments/wallet.service.ts. Today, getOrCreateAddressForPaymentLink derives from hd_wallet_seed, computes the Alchemy counterfactual address, and stores it in wallet_address. After Phase 1, for EVM chains under the feature flag, that function becomes:

async function getOrCreateAddressForPaymentLink(paymentLinkId, network) {
  if (isEvm(network) && featureFlags.useOnChainReceiver(network.chainId)) {
    const address = await factory.computeAddress(hashLinkId(paymentLinkId))
    return { address, walletAddressId: null, derivationPath: null }
  }
  // legacy path unchanged
}

No HD derivation. No private material in the database for new links.

A new service, payments/indexer/evm-paid-event.service.ts, subscribes to Paid events on each enabled chain via viem.watchContractEvent. On match, it:

1. Looks up the paymentLinkId from the event (indexed in bytes32).
2. Upserts a PaymentTransaction row — same shape as today.
3. Emits the same webhooks today's sweep-completion path does (api/src/webhooks/webhooks.service.ts).

The feature flag useOnChainReceiver is scoped per chain id. A link created while the flag is off stays on the legacy sweep path forever — we do not migrate in-flight links.

Deprecations​

Inside this phase we bypass but do not delete:

• SmartAccountWalletService.drainSmartAccountWallet — no longer called for flagged chains.
• SmartAccountWalletService.getSmartAccountClientForDepositWallet — not needed when addresses come from the factory.
• Rows in wallet_address — not written for flagged EVM chains.

Actual deletion happens in Phase 7, once all legacy links on the chain are settled.

Migration plan​

• New links on Base: get a factory-computed CREATE2 address. The UI displays it the same as today.
• Existing open links on Base: stay on the legacy sweep path until they expire or settle. No forced migration.
• Other EVM chains: legacy until Phase 3 flips their flag.

Risks and mitigations​

• CREATE2 address shown before any code exists. Mitigation: document that recoverability depends on the factory deployer. Cap maxLinkValue in the factory for the first 30 days.
• USDT and other non-standard ERC-20s. Mitigation: SafeERC20 in both PaymentLinkReceiver and FeeSplitter; Foundry fuzz tests against a USDT mainnet fork.
• Fee-on-transfer tokens. Mitigation: token allowlist; tokens outside it fall back to legacy path.
• Chain indexer lag. Mitigation: dual-subscribe (Alchemy + fallback public RPC); reconcile jobs run hourly; idempotent upsert.
• Audit finding during development. Mitigation: audit gated; no mainnet deploy before fix-all report.

Status checklist​

• Foundry project scaffolded at contracts/evm/
• PaymentLinkFactory + PaymentLinkReceiver + FeeSplitter implemented
• Fuzz + invariant tests for split math (merchant always gets ≥ expected minus fees)
• USDT / non-standard ERC-20 fork tests passing
• useOnChainReceiver feature flag wired in api/src/payments
• evm-paid-event.service.ts indexer shipping and emitting existing webhooks
• Audit kicked off, fixes landed
• Base mainnet deploy from multisig
• Canary cohort of merchants on the flag

What is next​

With Base merchants on contract receivers, Phase 2 does the same for subscriptions: Allowance-pull subscriptions.

Reference docs: Phase 1 status · Contract reference · Architecture

TL;DR​

• SubscriptionHub.createSubscription(...) records the schedule on-chain.
• Payer signs approve(USDC, hub, cap) once in their normal wallet. That is the same step we already document in Auto-charge.
• Any EOA can call charge(id). Our NestJS scheduler does it by default; Chainlink/Gelato will back it up from Phase 3 onward.
• Reorg protection via monotonic lastChargedAt. No double-charges.
• Existing subscribers migrate opt-in, at renewal.

What this phase changes​

Today, api/src/scheduler/processors/subscription-auto-charge.processor.ts uses an OrcaRail-controlled smart account to pull from the payer via existing approve. It works, but the smart account is ours — trust flows through us.

After Phase 2:

The allowance is still from the payer to a contract, but the contract is auditable and immutable, and anyone — not just us — can be the keeper.

Contracts introduced​

SubscriptionHub​

One instance per chain. Minimal surface:

function createSubscription(
    bytes32 id,
    address payer,
    IERC20 token,
    uint256 amount,
    uint64 interval,
    uint256 cap,
    Split calldata split
) external;

function charge(bytes32 id) external;        // any caller
function cancel(bytes32 id) external;        // payer only
function subscription(bytes32 id) view returns (Subscription memory);

event SubscriptionCreated(bytes32 indexed id, address indexed payer, ...);
event Charged(bytes32 indexed id, uint256 amount, uint64 nextChargeAt);
event ChargeSkipped(bytes32 indexed id, bytes32 reason);
event Canceled(bytes32 indexed id);

Invariants enforced in charge()​

• block.timestamp >= nextChargeAt — cannot charge early.
• block.timestamp > lastChargedAt — monotonic, so reorgs cannot double-charge.
• amountCharged + amount <= cap — enforces the approval limit in addition to ERC-20 allowance.
• token.allowance(payer, hub) >= amount — explicit revert with InsufficientAllowance for clean webhook copy.
• token.balanceOf(payer) >= amount — same, with InsufficientBalance.

The Split is reused from Phase 1 — same FeeSplitter, same basis-points semantics.

API changes​

The big change is that api/src/scheduler/processors/subscription-auto-charge.processor.ts stops pulling from our smart account and starts calling SubscriptionHub.charge(id) with a keeper EOA.

Concretely:

• Keeper EOA is a per-chain hot wallet with only gas. It has zero authority over merchant funds.
• If the chain has an Alchemy paymaster policy (see api/src/withdrawals/services/gas-strategy), the keeper uses the sponsored path; otherwise it self-funds from its gas balance.
• On revert, the processor parses the error selector and updates the same SubscriptionAutoChargeEntity states we use today (past_due, insufficient_balance, etc.).
• Webhooks and emails from api/src/mail/mail-templates/subscription-*.hbs fire unchanged.

Payer UX in pay gets two adjustments, both minor:

1. The approve() step now points spender to the SubscriptionHub address instead of our hot wallet. That is one copy change and one config value — the flow the payer sees is identical.
2. A "revoke" button that calls SubscriptionHub.cancel(id) then prompts an on-chain approve(hub, 0) for full cleanup. Today's Auto-charge revoke docs remain accurate.

Deprecations​

• The custodial pull path in subscription-auto-charge.processor.ts — behind the flag, only the SubscriptionHub.charge branch runs.
• OrcaRail-owned smart account as approval_spender_address — new subs store the hub address instead.
• The approval_spender_address field stays in the API response, it just points somewhere new and auditable.

Migration plan​

Existing subscribers are never force-migrated. We offer two paths:

1. Renewal-triggered: at the next cycle, the dashboard banner asks the payer to resign approve(hub, cap) on the new SubscriptionHub. One click. Old allowance to the legacy hot wallet can be left or revoked; it no longer matters.
2. User-initiated: a "Move to non-custodial" button in the subscription detail page does the same thing immediately.

Subs that never migrate stay on the custodial path until cancellation. That path is turned off in Phase 7, with plenty of notice.

Risks and mitigations​

• Payer confusion at migration. Mitigation: email template mirrors existing subscription-auto-charge-approved.hbs language; banner in dashboard; FAQ entry at /docs/non-custodial/migration-guide.
• Keeper outage misses a charge. Mitigation: charge() is permissionless — any Chainlink Automation or Gelato instance can be a fallback; manual merchant-initiated charge() is also possible. Full plan in Phase 3.
• Reorg double-charge. Mitigation: lastChargedAt monotonic invariant; unit test with fork reorgs.
• Payer revokes between cycles. Mitigation: charge() emits ChargeSkipped(AllowanceRevoked); the existing subscription-insufficient-allowance.hbs email template fires; sub moves to past_due.
• Token allowlist drift. Mitigation: hub only accepts tokens on SubscriptionHub.isAllowed(token); changes are multisig-gated.

Status checklist​

• SubscriptionHub implemented with all invariants
• Fuzz tests for cap, allowance, reorg, and skip cases
• Audit delta covering SubscriptionHub landed
• Keeper EOA provisioned per chain, gas monitored via Sentry + Datadog
• Pay app migrated approve target to SubscriptionHub
• approve-auto-charge endpoint updated to accept hub-spender allowances
• Dashboard banner for existing subs
• Canary cohort migrated and stable for 14 days

What is next​

Multi-chain rollout and a second keeper: Phase 3.

Reference docs: Phase 2 status · Migration guide · Contract reference · Why allowance-pull

TL;DR​

• Deploy PaymentLinkFactory, PaymentLinkReceiver implementation, FeeSplitter, and SubscriptionHub to Ethereum mainnet, Arbitrum, Optimism, and Polygon.
• Same CREATE2 salt scheme everywhere — the factory address is the same on every chain (clean for docs, clean for integrations, clean for computeAddress from the client).
• Register Chainlink Automation (preferred) and/or Gelato Web3 Functions as a second keeper calling the same charge(ids[]).
• Publish SLOs: 99.5% of charges within 10 minutes of due time, measured.

What this phase changes​

Multiple keepers calling the same public charge() is the liveness story. None of them has custody; any of them can save a due charge.

Deployment plan​

Deploy order (one chain per week, canary per chain):

1. Ethereum mainnet (chainId 1)
2. Arbitrum One (42161)
3. Optimism (10)
4. Polygon PoS (137)

Addresses on each chain are published in /docs/non-custodial/contract-reference. The deployer key is the same 3-of-5 Safe multisig defined in Phase 0, redeployed per chain from the same ceremony.

All four chains share the same useOnChainReceiver feature flag scoped by chainId inside api/src/payments/wallet.service.ts. Merchants opt in chain-by-chain; defaults flip to on once the canary week is clean.

Gas strategy for charge()​

The keeper's charge() transactions need gas. We reuse the existing paymaster plumbing in api/src/withdrawals/services/gas-strategy:

• Alchemy paymaster enabled (Base, Arbitrum, Optimism, Polygon): keeper calls SubscriptionHub.charge() as a UserOperation with policy sponsorship. Zero gas cost for the keeper EOA.
• Ethereum mainnet (no paymaster): keeper self-funds from its hot-gas balance. Funded daily by the platform wallet; monitored with a Datadog alert for low balance.
• Merchant-subsidized gas (optional): merchants can set a gas_refund_address and the keeper pulls reimbursement from there, matching the existing support/commission pattern. Out of scope for initial rollout.

Second keeper: Chainlink and Gelato​

The second keeper is a redundancy play, not a replacement. It runs alongside the NestJS scheduler.

Chainlink Automation (preferred on EVM)​

• Register an Upkeep per SubscriptionHub.
• checkUpkeep() returns performData = abi.encode(ids[]) for all id with block.timestamp >= nextChargeAt (read from a view function).
• performUpkeep(performData) calls charge(ids) in a batch.
• Funded with LINK from the platform treasury; balance monitored.

Gelato Web3 Functions (alternative)​

• A JS Web3 Function polls the hub, finds due IDs, and submits a charge(ids[]) transaction.
• Pricing is post-paid from Gelato's 1Balance.

Either one is sufficient on its own; we will pick based on operational experience during Phase 3. Running both is fine — charge() is idempotent within a period thanks to lastChargedAt.

SLOs and monitoring​

Published SLO targets:

Monitoring hooks into the existing Sentry setup documented in the repo's Sentry workflow skill. Alerts:

• charge() reverts per hour > threshold → PagerDuty
• Keeper EOA native balance below N gwei × gasLimit × 100 → PagerDuty
• Chainlink/Gelato upkeep unhealthy → warning
• Paid event indexer lag > 5 min → warning

Deprecations​

Same as Phase 1 and 2, but on more chains. Nothing is deleted yet — deletion waits for Phase 7.

Migration plan​

• New payment links: use contract receivers on any chain with the flag on.
• New subscriptions: use SubscriptionHub on any chain with the flag on.
• Existing customers: opt-in migration at renewal, same as Phase 2.
• Cross-chain settlement (Relay): unchanged surface; the keeper still calls Relay executors in api/src/withdrawals/services/bridge, just from an EOA that has no custody.

Risks and mitigations​

• Multi-chain address drift. Mitigation: deterministic CREATE2 deployer (e.g. 0x4e59b44847b379578588920cA78FbF26c0B4956C) with a locked init-code hash; factories share an address across all four chains.
• Per-chain paymaster policy limits. Mitigation: per-chain monitoring and policy quota alerts at 70% usage.
• Chainlink upkeep registration churn. Mitigation: one upkeep per chain; the list of IDs is read on-chain, so merchant onboarding does not require Chainlink config changes.
• Double-charge across keepers. Mitigation: lastChargedAt monotonic plus ChargeSkipped for duplicates; both keepers are idempotent by design.
• Mainnet gas spikes. Mitigation: per-chain batch size tuning; a gas-price ceiling above which charge() is deferred one block.

Status checklist​

• Deploys completed on Ethereum, Arbitrum, Optimism, Polygon
• Factory + hub addresses published in contract reference
• Paymaster policies validated per chain
• Chainlink Automation upkeep live on at least 2 chains
• SLO dashboard in Datadog
• Runbook for keeper outage (manual charge() from merchant CLI)
• Canary merchants rolled per chain

What is next​

Solana is the other big chain we must make non-custodial: Phase 4.

Reference docs: Phase 3 status · Keeper strategy · Contract reference

TL;DR​

• payment_link program owns a PDA per payment link, derived from seeds = [b"pl", link_id]. No keypair, no seed, no sweep.
• subscription program uses SPL delegate authority — the same primitive we already rely on in Auto-charge — as an explicit allowance granted by the payer.
• Splits are done via CPI to the same fee_splitter logic we built on EVM, adapted to Solana accounts.
• Sweep service api/src/withdrawals/services/solana-withdrawal-transfer.service.ts is bypassed for flagged links and removed in Phase 7.

What this phase changes​

The "after" side replaces the HD seed in api/src/payments/wallet.service.ts (the m/44'/501'/i'/0' branch) with a pure deterministic PDA computation.

Programs introduced​

New package contracts/solana/ (Anchor).

payment_link program​

Accounts per link:

#[account]
pub struct PaymentLink {
    pub link_id: [u8; 32],
    pub expected_mint: Pubkey,        // e.g. USDC on SOL
    pub expected_amount: u64,
    pub split: Split,
    pub created_at: i64,
    pub status: PaymentStatus,
}

Instructions:

• initialize(link_id, expected_mint, expected_amount, split) — lazy; called on first deposit by the factory-style wrapper.
• pay(link_id, amount) — validates mint + amount, CPI-transfers into the PDA's ATA, then CPI-splits atomically. Emits PaymentReceived { link_id, payer, amount }.
• refund(link_id) — multisig-gated, mirrors EVM refund.

PDA seeds: [b"pl", link_id]. PDA has no private key — it signs via invoke_signed.

subscription program​

Leverages SPL Approve / Revoke for authority delegation. The payer signs spl_token::approve designating the program's PDA as delegate for up to cap tokens. Then:

pub fn charge(ctx: Context<Charge>, id: [u8; 32]) -> Result<()>

Can be called by anyone, checks:

• clock.unix_timestamp >= next_charge_at
• clock.unix_timestamp > last_charged_at // monotonic
• amount_charged + period_amount <= cap
• delegate authority still present on payer ATA

On pass, CPI spl_token::transfer_checked pulls from the payer's ATA (as delegate) and CPI-splits.

Events: SubscriptionCreated, Charged, ChargeSkipped, Canceled. Same shapes the EVM indexer produces, so api/src/webhooks is agnostic.

API changes​

• The Solana branch of WalletService.generateAddressForNetwork stops deriving keypairs and returns findProgramAddressSync(["pl", linkId], programId) instead. No encryptedSeed row written for new Solana links.
• A new indexer service watches program logs (Helius webhooks or Triton streams) and emits existing webhook events.
• api/src/scheduler/processors/subscription-auto-charge.processor.ts adds a SOL branch: build a charge transaction, sign with the keeper (gasless path via sponsor tx, similar to Phase 2 paymaster).
• withdrawals/services/solana-withdrawal-transfer.service.ts is not called for flagged links.

Gas on Solana​

Solana fees are small (typically 5000 lamports per sig, 0.000005 SOL). The keeper uses a hot-SOL balance with the same alerting pattern as Phase 3. Because Solana does not have an Alchemy-style paymaster, sponsored transactions use a simple co-signer pattern: the keeper signs as fee payer, payer does not need SOL at all.

Deprecations​

• SOL HD derivation (m/44'/501'/i'/0') for new links — not called when flag is on.
• solana-withdrawal-transfer.service.ts — bypassed for flagged links.
• SolanaRelayBridgeExecutorService in api/src/withdrawals/services/bridge/solana-relay-bridge-executor.service.ts stays: bridging from SOL to EVM when the merchant lives on EVM still uses Relay, but the trigger moves to the program.

Migration plan​

Same opt-in model as Phase 2:

• New payment links: PDA-addressed.
• New subscriptions: SPL-delegate-based.
• Existing active subscriptions: banner + email at next renewal to re-delegate to the new program.
• In-flight deposits on legacy addresses keep settling on the legacy path.

Risks and mitigations​

• SPL delegate is overridable. Mitigation: charge double-checks delegated_amount before transferring; failed checks emit ChargeSkipped(DelegateRevoked) and follow the same email template as the EVM allowance-revoked case.
• Anchor upgrade authority. Mitigation: 3-of-5 Squads multisig owns the upgrade authority, timelocked. Matches the EVM Safe posture from Phase 0.
• Wrapped SOL vs native SOL. Mitigation: payment_link supports both, with explicit expected_mint per link to avoid ambiguity.
• Priority fee spikes. Mitigation: dynamic priority fee calculation in the keeper; fallback retry with higher priority after one slot.
• Audit. Mitigation: OtterSec or Neodyme audit of both programs before mainnet deploy.

Status checklist​

• Anchor workspace contracts/solana/ scaffolded
• payment_link program with all instructions + tests
• subscription program with all instructions + tests
• Helius webhook indexer shipping
• Keeper SOL branch in subscription-auto-charge.processor.ts
• Audit report landed
• Mainnet deploy from Squads multisig
• Canary merchant cohort

What is next​

Bitcoin. The hardest chain for non-custody, and the one where we have to be honest about the limits: Phase 5.

Reference docs: Phase 4 status · Contract reference · Architecture

TL;DR​

• Every BTC payment link becomes a 2-of-2 taproot multisig: one merchant signer, one platform signer. Platform cannot move funds unilaterally.
• Every deposit gets a pre-signed refund PSBT stored off-chain so the payer is recoverable if the merchant disappears.
• Master xpubs move off the API server to an HSM or MPC service (e.g. Lit, Turnkey). No mnemonic on disk.
• Recurring payments on BTC are out of scope until Lightning BOLT12 is production-ready. Today, Auto-charge already states BTC is not supported for auto-charge — that stays true.

What this phase changes​

Today, BitcoinHotWalletService in api/src/withdrawals/services/bitcoin-hot-wallet.service.ts derives a unilateral p2wpkh address from a server-held mnemonic and sweeps it via bitcoin-withdrawal-transfer.service.ts. That is a single key we control.

After Phase 5:

No single party can spend. No server holds a unilateral seed.

What we are shipping​

1. Taproot 2-of-2 per link​

• Descriptor wallet per link: wsh(multi(2, merchant_pubkey, platform_pubkey)) or a taproot equivalent (tr(NUMS, {pk(m), pk(p)}) with MuSig2 for a single-sig-looking output — nice for privacy and fees).
• Merchant key lives in the merchant's browser or mobile extension. Merchant onboarding flow prompts for an xpub; per-link keys derive from it.
• Platform key lives behind an HSM or MPC service. The API server never sees the private material.

2. Pre-signed refund PSBT​

When a deposit is detected:

1. API assembles a PSBT that returns the deposit minus gas to the payer's address (captured at pay-link creation when payer wallet is known; fallback is sendback policy).
2. Both signers sign the refund PSBT immediately and store it (encrypted) in the database.
3. Merchant can broadcast the refund at any time with one click; no further signing needed.

This is the BTC analog of an on-chain refund() function.

3. MPC key rotation​

• Master xpubs for platform keys rotate annually.
• All derived per-link keys roll with rotations — old links keep working because their multisig is already on-chain with the specific pubkey.
• Rotation is logged in the same audit trail as the multisig deploys from Phase 0.

What we are not shipping​

• BTC subscriptions / auto-charge. No credible design on L1 today. The existing Auto-charge docs already exclude BTC; that stays correct.
• On-chain atomic splits for BTC. Splits happen in the merchant-signed settlement PSBT. The split is still deterministic and visible in the broadcast transaction, but it is not enforced by script.
• Fedimint or statechains. Interesting research; not in this phase.

Lightning as the future path​

Recurring BTC payments have one realistic option: Lightning BOLT12 offers + recurrence extension. That would give us a BTC subscription story comparable to ERC-20 approve + pull. We track it as a future phase:

• Depends on mature BOLT12 recurrence implementations in LND and CLN.
• Depends on Lightning wallet support (Phoenix, Zeus, Blink) for BOLT12 recurrence.
• Requires an LN node fleet with sufficient liquidity; probably via a partner (Voltage, Greenlight).

We will post a dedicated design doc when the upstream tooling is ready. Until then, BTC stays one-shot.

Deprecations​

• BitcoinHotWalletService — keeps its interface, but the key provider moves to HSM/MPC. The unilateral p2wpkh deposit address stops being generated for new links.
• Legacy BTC deposit addresses stay settleable until their expiry via the old sweep path.

Migration plan​

• New BTC payment links: 2-of-2 multisig addresses. UI unchanged; address format updates to taproot.
• Existing open BTC links: legacy unilateral addresses remain active until expiry; we do not force migration.
• Merchants without a configured BTC signer: fall back to a platform-only multisig for now, with a mandatory onboarding step to attach a merchant key within 30 days. This preserves the refund path and avoids blocking existing BTC volume.

Risks and mitigations​

• Merchant loses their key. Mitigation: merchant onboarding asks for two xpubs (primary + backup); the backup is optional but heavily encouraged.
• Platform HSM outage. Mitigation: HSM is redundant across regions; emergency key recovery via multisig ceremony documented in the runbook.
• Refund PSBT storage compromise. Mitigation: refund PSBTs encrypted at rest with a separate KMS key; they are still useless without the merchant's signature being re-signed for a different destination (the destination is fixed in the pre-signed PSBT).
• MuSig2 maturity. Mitigation: v1 ships with explicit 2-of-2 wsh(multi(...)); MuSig2 comes later once tooling is widely audited.
• Fee market spikes. Mitigation: settlement PSBTs include a CPFP hook the merchant can bump; keeper monitors mempool and warns merchants when settlement gas exceeds a threshold.

Status checklist​

• Taproot descriptor template finalized
• HSM / MPC provider selected (Lit vs Turnkey vs in-house HSM)
• Merchant xpub onboarding flow in dashboard
• Per-link descriptor derivation and storage
• Pre-signed refund PSBT generation + encrypted storage
• Settlement co-sign UI (one-click merchant sign)
• Runbook for HSM failover and merchant key loss
• Canary cohort of merchants on BTC 2-of-2

What is next​

Optional decentralization of the keeper via EigenLayer: Phase 6.

Reference docs: Phase 5 status · Bitcoin considerations · Security model

TL;DR​

• EigenLayer is restaking + slashable attestations from ETH operators. It is not a chain, not a contract platform, not a custody solution.
• Two places it could help OrcaRail: a Keeper AVS for decentralized charge() and a Bridge Attestation AVS for cross-chain settlement.
• We will defer the build unless a customer or compliance requirement demands decentralized liveness beyond what Chainlink Automation + NestJS gives us.
• If we ever build one, we start with Othentic / Eigen Foundation templates, not from scratch.

What EigenLayer actually gives you​

An AVS (Actively Validated Service) is a network of operators running an off-chain computation whose attestations are posted on-chain with cryptoeconomic security from restaked ETH. Misbehavior is slashable.

What that gets you:

• Decentralized liveness: a task runs even if one party (OrcaRail) goes offline.
• Slashable correctness: a bad attestation loses the operator stake.
• ETH-economic security: you inherit a slice of Ethereum's validator stake instead of bootstrapping your own token.

What it does not get you:

• A smart contract platform. Contracts still deploy on Ethereum / L2s.
• Custody. EigenLayer does not hold USDC for you.
• Solana or Bitcoin native support. Cross-chain bridges exist, and they add complexity and trust.
• A general scheduler. You still define the off-chain task and on-chain verification yourself.

Where an AVS could help OrcaRail​

1. Keeper AVS (decentralized charge())​

Today and through Phase 3, the keeper picture is:

• NestJS scheduler (primary)
• Chainlink Automation or Gelato (fallback)

That gives us two-way redundancy. A Keeper AVS would give us N-way redundancy with slashable liveness: operators attest "these IDs were due and I called charge," and missing a due charge is a slashable offense.

When it is worth it:

• When we have a customer whose contract forbids any single-party reliance on our infrastructure.
• When regulatory compliance explicitly asks for it (rare today).

When it is not worth it:

• When the marginal reliability over Chainlink is small and the engineering cost is months.

2. Bridge attestation AVS (Relay replacement)​

Our cross-chain settlement today uses Relay (see api/src/withdrawals/services/bridge). Relay is trusted. An AVS could attest "funds observed on chain X, release on chain Y" with slashable security — similar shape to Hyperlane ISM-with-EigenLayer or Omni.

When it is worth it:

• When Relay introduces terms or performance we cannot accept.
• When the platform processes enough cross-chain volume that bridge risk is material.

3. Fraud / compliance oracle​

"Is this wallet sanctioned?" "Was the merchandise delivered?" — policy checks currently in the NestJS webhook path could become AVS attestations. Niche use; only useful if the platform takes on an explicit on-chain policy responsibility.

Why we defer the build​

• Chainlink Automation + NestJS is ~0 engineering cost. A Keeper AVS is months.
• Building an AVS means running operators (or coordinating others to) and maintaining slashing conditions. That is an operational burden comparable to running our own blockchain node fleet.
• The security improvement is only meaningful once we already have two-way redundancy. We do not yet (we get it in Phase 3). Compounded: only after Phase 3 is stable does a Keeper AVS become a candidate.
• Even conservatively scoped, an AVS will have its own custody considerations (restaked ETH, operator compensation economics).

Decision log​

We will keep a public decision log at /docs/non-custodial/eigenlayer-evaluation with the current recommendation and any triggers that would flip it. Today's recommendation: defer.

Triggers that would re-open the discussion:

1. A sales conversation explicitly blocked by "single-party keeper" risk.
2. A regulatory framework that names AVS-backed liveness as an acceptable control.
3. Chainlink Automation pricing or availability degrading meaningfully on our most-used chains.
4. A partnership where we could reuse someone else's keeper AVS at near-zero ops cost.

If we do build it​

• Start from a template. Othentic and Eigen Foundation publish templates for task-attestation AVSes. We will not hand-roll slashing.
• Keep the on-chain entry point unchanged. SubscriptionHub.charge(ids[]) stays public and permissionless. The AVS just becomes one more caller alongside NestJS and Chainlink.
• Don't introduce new tokens or staking mechanics for our own volume. Operators are paid in ETH out of the platform gas budget; no OrcaRail token.
• Audit it. Even a template-based AVS needs an audit.

Status checklist​

• Decision log page live
• Quarterly review of triggers
• POC sandbox (not production) if a trigger fires

What is next​

The final phase deletes the custody code paths that Phases 1 to 5 replaced: Phase 7.

Reference docs: Phase 6 status · EigenLayer evaluation · Keeper strategy

TL;DR​

• Drop hd_wallet_seed, the WALLET_ENCRYPTION_KEY config, and the derivation logic for flagged chains.
• Delete EVM/SOL paths in api/src/withdrawals/: SmartAccountWalletService.drainSmartAccountWallet, solana-withdrawal-transfer.service.ts, related spec files.
• Keep the BTC path (reduced to Phase 5's 2-of-2 model).
• Update TOS, privacy policy, and SOC2 controls to reflect a materially smaller custody surface.
• Publish a postmortem summarizing what we learned.

What this phase changes​

Before this phase lands, the codebase has two of everything — the old sweep path and the new contract path — behind feature flags. After this phase, the new path is the only path on EVM and Solana.

What we delete​

Database​

• hd_wallet_seed table and its TypeORM entity at api/src/payments/infrastructure/persistence/relational/entities/hd-wallet-seed.entity.ts.
• wallet_address.derivationPath column is retained for historical lookups but becomes nullable; no new rows write it for EVM/SOL.
• A migration archives the encrypted seed rows to cold storage for seven years (regulatory retention), then drops the table.

Code​

In api/src/payments/wallet.service.ts:

• Delete encryptSeed, decryptSeed, getOrCreateHDWallet, generateAddressForNetwork (EVM + SOL branches), getNextAvailableIndex, and the @account-kit/wallet-client dynamic import.
• getOrCreateAddressForPaymentLink becomes a thin wrapper over factory.computeAddress for EVM and findProgramAddressSync for Solana.

In api/src/withdrawals/services/smart-account-wallet.service.ts:

• Delete drainSmartAccountWallet, transferFromSmartAccount, batchTransferFromSmartAccount, getSmartAccountClientForDepositWallet, and derivePrivateKey.
• The module stays (it still has a small footprint for BTC-related helpers and for reading balances).

Other deletions:

• api/src/withdrawals/services/solana-withdrawal-transfer.service.ts
• Corresponding .spec.ts files and fixtures.
• The subscription-auto-charge.processor.ts custodial branch (the SubscriptionHub.charge branch is what remains).

Config​

• WALLET_ENCRYPTION_KEY — dropped from .env, deployment secrets, and docs.
• Any Alchemy Account Kit signer material in config (API keys for @account-kit/* remain if still used for paymaster).

What stays​

• BTC hot wallet — reduced to the 2-of-2 multisig model from Phase 5. No EVM/SOL HD seeds remain.
• Alchemy paymaster policy — used by the keeper to sponsor charge() where applicable.
• Relay bridge executors — still orchestrate cross-chain settlement; callers are keeper EOAs, not custodial signers.
• All webhooks, emails, invoicing, dashboard, analytics — unchanged.

Legal and compliance updates​

• Terms of Service: "OrcaRail does not custody EVM or Solana funds during payment settlement" becomes a factual statement, not aspirational copy.
• Privacy policy: remove references to stored seed material.
• SOC2 scope: custody controls shrink; audit findings map to the new smaller surface.
• Money transmitter posture: re-review with counsel. Fewer custody touchpoints simplify the analysis in several jurisdictions.

Postmortem​

A companion post will summarize what we learned across Phases 0 to 7 — what took longer than expected, what went smoother, what the real engineering cost of non-custody was, and how merchants reacted. Expected cadence: one post within 30 days of Phase 7 shipping.

Deprecations (none new)​

This phase is itself the deprecation. Every useOnChainReceiver-flagged path becomes default-on; the flag is deleted.

Migration plan​

By the time Phase 7 runs, every new payment and subscription for 12+ months has been non-custodial. The migration is about long-tail legacy links:

• Legacy open payment links past expiry → settle any residual dust via a one-time script, then stop.
• Legacy subscriptions that never migrated → email notice 30 days before shutdown, offer one-click migration in dashboard, suspend auto-charge if no migration.
• Residual balances on legacy deposit addresses → sweep with the old drain path one last time, to merchant withdrawal addresses, then retire the keys.

Risks and mitigations​

• Residual dust on old addresses. Mitigation: final-sweep script run before decommission; any unrecoverable dust published in a public report.
• Legal risk from deleting too early. Mitigation: 7-year archival of encrypted seed rows (never decryptable without the encryption key, which is destroyed in ceremony); auditors can still verify historical state.
• Someone depends on an undocumented API shape. Mitigation: 90-day public deprecation notice; API changelog entry; targeted outreach to top merchants.

Status checklist​

• All EVM + SOL merchants on non-custodial flow for at least 90 days
• Residual legacy subscriptions zeroed
• Final-sweep script completed
• Migration completed for hd_wallet_seed to cold archive
• Code deletions merged
• TOS + privacy policy updated and shipped
• Postmortem post published

The end of the roadmap​

After Phase 7, the custody posture is:

• EVM, Solana: non-custodial. OrcaRail holds zero seed material.
• Bitcoin: reduced custody via 2-of-2 multisig with merchant signer.
• In-flight moment: eliminated on EVM/SOL; reduced to a multisig refund path on BTC.

That is what we set out to do in the Non-Custodial Roadmap.

Reference docs: Phase 7 status · Security model · Roadmap

Several readers — rightly — asked: if the goal is to become a protocol, why stop at removing custody? What would the rail look like if OrcaRail could go dark tomorrow and payments kept flowing?

This post is a debate. Five positions argue for five different architectures. A moderator pokes at each. Nobody wins outright, but by the end we are clearer about which trade-offs we are actually making.

What "fully non-custodial protocol" means, precisely​

Before the debate starts, we need a shared definition. A system is a fully non-custodial protocol if all of these hold:

1. Custody: no party holds user funds in transit, not even for a block.
2. Liveness: no single party is required for a legitimate payment or subscription charge to happen.
3. Censorship-resistance: no single party can deny a well-formed, paid transaction.
4. Upgrade / change control: upgrades require multi-party consent, not a single company's deploy.
5. Transparency: the rules a user is trusting are fully readable on-chain or under verifiable hash.

The current plan clears (1). It partially clears (3), (4), (5). It does not clear (2) — OrcaRail's keeper and API are still required for the happy path to fire reliably. The debate below is about whether to push the remaining four bars all the way, and at what cost.

The positions​

Five architects walk in. Let's hear them.

• Pragmatist — Smart contracts + OrcaRail API (current roadmap).
• Maximalist — Pure on-chain protocol + decentralized frontend (the "Uniswap model").
• Sovereign — OrcaRail as an L3 / appchain with payment-specific precompiles.
• Intents Believer — Payers express intents; a permissionless solver network settles them.
• Standards Advocate — An open EIP for payment links and subscriptions; anyone implements.

Round 1 — The opening statements​

Pragmatist: "Ship something real, then decentralize the painful parts."​

The roadmap already removes the hard problem (custody). Keepers can be anyone — our NestJS scheduler is one caller among several; Chainlink and Gelato can be registered tomorrow. The indexer is public: anyone can subscribe to the same Paid and Charged events and rebuild state. The "OrcaRail API" is not the settlement layer, it is a convenience layer on top of public contracts. Merchants who want the fully-protocol path can already skip us and call the factory directly.

Claim: we are 80% protocol. The remaining 20% is tooling (wallets, dashboards, email), not trust. Tooling should stay iterable.

Maximalist: "No API. Events, contracts, subgraph. That's it."​

Uniswap exists. 1inch exists. They are accessed via the frontends their companies host, but any of those frontends could go dark and the protocol would keep working. That is what "protocol" means.

For OrcaRail, that looks like:

• Factories, hubs, splitters on every EVM/Solana chain.
• A canonical subgraph (or Solana indexer) anyone can query.
• A decentralized frontend pinned to IPFS/Arweave, resolved via ENS (orcarail.eth). The merchant dashboard and pay app are static bundles; every release is content-addressed.
• No OrcaRail REST API in the critical path. The SDK calls the subgraph. Webhooks are derived from on-chain events by indexer-as-a-service (Alchemy, QuickNode, self-hosted).

Claim: anything that requires an api.orcarail.com for a payment to work is a partial protocol.

Sovereign: "Make payments a precompile on our own chain."​

Payments are latency-sensitive and repetitive. We pay the same gas for the same split every time. Why are we renting L1/L2 security for a use case that can be specialized?

Launch OrcaRail Chain as an OP Stack rollup (or a Cosmos appchain, or an Arbitrum Orbit chain). Then:

• Payment-link semantics are a precompile, not an 80-line Solidity contract. Fees go from cents to ~zero.
• Keeper logic is baked into block production: the sequencer fires charge() calls as part of the block, slashable by the chain's own security.
• Bridging to "real" chains (Ethereum, Arbitrum, Solana) uses the existing canonical bridge + Relay; OrcaRail Chain is the coordination layer, not the value layer.
• Subscriptions become first-class — "subscription" is a transaction type, like "transfer" on Bitcoin.

Claim: the cheapest way to make a protocol work reliably at scale is to not share a block space with random NFT mints.

Intents Believer: "Payers express intent. Solvers compete to settle."​

The payer says: "I want to pay merchant X $50 in USDC from any of my wallets, within the next hour, optimizing for fees." That's an intent, signed but not yet a transaction.

A permissionless solver network (CoW-style, SUAVE, Anoma, Across-style relayers) sees the intent, finds the cheapest route — including bridging, cross-chain, from whatever token the payer holds — and settles it. Solvers are paid a bounty embedded in the intent.

For subscriptions: the payer signs a recurring intent ("pull $20/month of USDC from my wallet to this merchant PDA, for 12 months, cancellable anytime"). Solvers compete to call charge() when due, earning a micro-fee. This is what Phase 6's "keeper AVS" becomes if you squint, but with a real market instead of a slashing scheme.

Claim: keepers aren't really a reliability problem — they're a market-design problem. Build the market.

Standards Advocate: "Write an EIP. Everyone wins, including us."​

OrcaRail's payment links and subscriptions are a generic primitive. Shopify, Coinbase Commerce, other hosted crypto checkout stacks, and two dozen startups are building the same thing. We should write an EIP for non-custodial payment links and a companion EIP for allowance-pull subscriptions, with a reference implementation.

Then:

• Any wallet can render a payment-link URL with a standard UI ("you are paying merchant X, $50, USDC, non-custodial").
• Any indexer (The Graph, Goldsky, Envio) supports the standard events out of the box.
• Any processor — including a future OrcaRail competitor — can host the same protocol.
• OrcaRail's product becomes the best implementation of an open standard, not a locked-in stack.

Claim: the biggest moat in payments is trust in the primitive, not in one company's stack. Make the primitive public.

Round 2 — The moderator cross-examines​

To Pragmatist: "Be honest — if OrcaRail stops paying the paymaster bill, does Alice's subscription still charge?"​

Pragmatist: In the current roadmap, after Phase 3, yes — Chainlink Automation keeps firing charge(). The paymaster bill is for keeper gas; Chainlink uses LINK for the same job. But merchants who need OrcaRail's dashboard to reconcile would degrade: emails, retries, human-readable failure codes all live in our API. The contracts keep running; the product doesn't.

Moderator: Is "contracts keep running but humans can't tell" really liveness?

Pragmatist: It's settlement liveness without UX liveness. That's a real distinction — we should own it, not hide it. It's also cheap to fix over time: publish our email templates, open-source the indexer, let someone else host the dashboard. We don't have to do all of that in Phase 1.

To Maximalist: "ENS-pinned IPFS dashboards are great until a regulator sends us a letter about a merchant."​

Maximalist: Then OrcaRail stops hosting that merchant on our dashboard. The protocol keeps serving them via another frontend, or their own. That is feature, not bug — compare TradFi, where "the processor froze my account" is a recurring drama that has no protocol-level remedy.

Moderator: Merchants who get off-boarded from a card processor usually also get off-boarded from Visa's network. In payments, the rails and the processor are often the same censor.

Maximalist: Correct, and that is exactly the problem a protocol solves. Visa cannot censor Ethereum. OrcaRail, on a protocol architecture, cannot censor merchants at the rail level — only at the frontend. Frontends are swappable; rails are not.

To Sovereign: "How do merchants withdraw to USDC on Ethereum if settlement lives on OrcaRail Chain?"​

Sovereign: Same way anyone leaves any L2: the canonical bridge. We'd integrate Relay natively so the exit is immediate for stables. The daily withdrawal throughput is tiny compared to the in-chain volume.

Moderator: You're asking us to run a chain. Every chain that matters has failure modes — sequencer halts, state-root posting lag, bridge exits. Those fail publicly and visibly. "OrcaRail sequencer offline for 3 hours, payments halted globally" is a worse headline than "OrcaRail API had a 3-hour outage."

Sovereign: It's a worse headline only until you decentralize the sequencer. OP Stack's fault-proofs and shared sequencing (Espresso, Astria) make this progressively less of a single-party risk. You're right that we're not starting there. But you're also right that we shouldn't run a chain alone; we'd launch via a partner rollup-as-a-service with a credible path to shared sequencing.

Moderator: That is a lot of dependencies.

Sovereign: It is. The trade is: we stop paying gas forever, we stop fighting for mainnet blockspace, and we get to ship custom primitives. If payment volume is large enough to justify any of this, it's justified. If it's not, I'm wrong.

To Intents Believer: "Solver markets have an MEV problem. Who protects the payer from a solver that skims?"​

Intents Believer: The intent is signed with strict constraints. Amount paid cannot exceed what the payer authorized. What can vary is the route (which bridge, which DEX if a swap is needed) and the timing. A malicious solver cannot redirect funds; at worst, they can be slow. Competition drives that out.

Moderator: Competition drives fees low on high-volume routes. What about the $5 USDC → USDC cross-chain micropayment nobody is paid enough to solve?

Intents Believer: That's a real gap. The answer is fallback solvers — OrcaRail runs one at cost. The market handles the top 95%; we handle the long tail. Over time, cheaper chains and better bridges close the gap.

Moderator: So you're also running a keeper, just calling it a solver.

Intents Believer: A keeper that is one of several, competing on a public intent, with a fallback — yes. That is the difference between "OrcaRail's backend is the keeper" and "OrcaRail is a participant in an open market."

To Standards Advocate: "EIPs take years. What do we do until then?"​

Standards Advocate: You ship the reference implementation first, using your current plan. Then you draft the EIP around what you shipped, not in advance. That's how ERC-4337, ERC-721, and ERC-20 got written. The current roadmap is compatible with this — the SubscriptionHub surface could be the ERC surface, with small naming adjustments.

Moderator: Any risk in publishing your "moat" as a standard?

Standards Advocate: The moat isn't the contract. The moat is integrations, SLAs, compliance work, dashboards, email deliverability, merchant trust. All things a competitor can't copy by reading an EIP. Open-sourcing the contract surface moves competition to the places where we are strong.

Round 3 — Where each position actually wins​

After the cross-examination, each position is stronger in specific dimensions. Honest scorecard:

No row is dominant. Which is why this is a debate and not a rollout plan.

Round 4 — Moderator's synthesis​

Here is how I would actually read the debate, as the person who has to pick.

Pragmatist wins today because the product has to keep shipping and we do not have the luxury of pausing for an 18-month architecture rewrite. The current roadmap is a strictly-better-than-custodial version of what we run today, with compatible incremental improvements.

Maximalist wins on principle and captures a real constraint: the day our API is the reason a merchant cannot get paid is the day we stop being a protocol. That is the pressure that should guide every Phase 1-7 engineering decision: publish the indexer, publish the subgraph, pin the dashboard to IPFS under ENS, document how to self-host. The Pragmatist roadmap makes this possible, it does not force it. We should force it.

Sovereign wins if scale justifies it. Below some volume threshold, running a chain is overhead. Above it, renting Ethereum block space to split $3 six ways every time is absurd. We will know we've crossed that threshold when a dominant fraction of our volume is same-chain merchant-to-payer routes and gas optimization is measurable line-item savings. Not yet.

Intents Believer wins on cross-chain. Payments are inherently multi-asset, multi-chain. An intent-based payer flow ("pay merchant X, I don't care how") is the best UX possible for a crypto payer. We should adopt intents at the payer-SDK layer before we adopt them at the settlement layer. That makes existing solvers (Across, deBridge, Relay) a natural fit without requiring us to build a new market.

Standards Advocate wins everywhere Maximalist does, with less risk. Writing an EIP around what we ship in Phases 1 and 2 is free, helpful for the ecosystem, and does not slow us down. It also gives us a credible "we are building a rail, not a trap" story for merchants evaluating crypto rails for the first time.

The blended answer​

The boring-but-correct synthesis: ship Pragmatist, enforce Maximalist, adopt Intents for payer UX, write an EIP along the way, keep Sovereign as a Phase 8+ option conditional on scale.

Concretely, what that means as incremental commitments on top of the existing roadmap:

• M1: Public subgraph from Phase 1. Every Paid and Charged event in a canonical subgraph anyone can query. Non-blocking for the API.
• M2: IPFS-pinned pay app from Phase 2. Every release is content-addressed, pay.orcarail.eth resolvable via ENS.
• M3: Self-host kit from Phase 3. Docker-compose + docs that let anyone run an OrcaRail-compatible dashboard from the same contracts.
• M4: Intent SDK from Phase 3. orcarail.pay(intent) on the client routes through existing solver networks (Across/Relay) for cross-chain payments. OrcaRail-run solver fallback for the long tail.
• M5: EIP draft from Phase 2. Co-author the payment-link EIP with another processor or a wallet team, using our SubscriptionHub as the basis.
• M6: Sovereign evaluation quarterly alongside EigenLayer evaluation. Triggers: payments volume by chain, gas cost per payment as % of payment value, demand from merchants for sub-cent settlement.

These five additions take the existing roadmap from "non-custodial" to "non-custodial, protocol-shaped, credibly neutral." They do not slow down Phases 1-7. They are tracked as separate living workstreams.

They are formalized as Track P in the protocol whitepaper, which turns M1-M5 into phases P1-P5 and keeps M6 (own-chain) as an optional P6.

What we are explicitly not doing yet​

• Own chain. Not in the next 18 months. Re-evaluate quarterly.
• OrcaRail token at launch. No token now. A future governance token is reserved as an option for post-decentralization (see the protocol whitepaper for the full stance). No presale, no allocation, no points.
• Pure on-chain Maximalist path with no API at all. The product needs human-readable surfaces, and merchants need someone to call when things go wrong. We will enable API-free usage, not require it.
• Our own solver network. Use existing ones. We may run a fallback solver at cost for the long-tail routes existing solvers ignore, but we will not bootstrap a new competing network.

Where this lands​

This post is a companion to the non-custodial roadmap, not a replacement. The roadmap still tracks Phases 0-7. This debate adds a sixth axis — protocol-shape — that every phase should be evaluated against.

If you were in the debate, send us your position. We will publish strong counter-arguments.

Related reading

• The OrcaRail Non-Custodial Roadmap — the canonical roadmap
• Why allowance-pull beats escrow and session keys — the subscription-model debate, in the same format
• EigenLayer evaluation — companion decision log for decentralized keepers
• Architecture — what the Pragmatist path actually builds

The three models​

1. Allowance-pull (ERC-20 approve + SPL delegate)​

The payer signs approve(spender, cap) — once — on the token contract. Later, the spender (our SubscriptionHub or Solana program) calls transferFrom (EVM) or transfers with delegate authority (SOL) when a period is due. The payer keeps custody; the spender can pull up to cap over the subscription's life.

Cancellation: payer signs approve(spender, 0) or Revoke. From that point, no pull can succeed.

This is what Auto-charge already uses today. Phase 2 moves the spender from a platform-controlled hot wallet to an on-chain contract, but the payer side does not change.

2. Escrow deposit​

The payer deposits N periods of funds into a per-subscription escrow contract. The contract releases to the merchant on schedule. Payer can withdraw the unused balance at any time (minus paid periods).

3. Smart-wallet with session keys​

The payer uses an ERC-4337 smart wallet and grants a scoped session key to the subscription contract. The session key can only do things the scope allows (e.g. "transfer USDC up to X per 30 days to this address"). Payer revokes by removing the session key.

The scoring​

We evaluated all three on five axes:

Why not escrow​

Escrow has the best-sounding pitch ("payer funds are locked in a contract, not a company") but worst real-world UX:

• Payers do not like locking N months of funds. A $20/month subscription with a 12-month escrow means $240 locked. Ceiling on conversion rate.
• Withdrawals become complicated: the contract must track paid vs unpaid periods, handle partial refunds, and prevent the merchant from reading future funds.
• "Escrow that holds customer funds" has a regulatory smell in several jurisdictions that "allowance to a smart contract" does not.

Why not session keys​

Session keys on 4337 smart wallets are elegant. But they require the payer's wallet to be a smart wallet. Most payers in 2026 still use EOAs (MetaMask, Rabby, hardware wallets, Safe signers) and Solana payers use Phantom-style keypair wallets. Forcing 4337 onboarding for a subscription is a conversion killer.

There is a path where 4337 becomes the default payer wallet and session keys become trivial. We are not there yet.

Why allowance-pull wins today​

• Zero change to payer wallet. Every wallet that can sign an ERC-20 approve works, which is all of them.
• Zero funds locked. Payer keeps custody; pull happens just-in-time.
• Revoke is universal. approve(0) or Revoke is a primitive every wallet UI already surfaces.
• Keeper is commodity. SubscriptionHub.charge(id) is public and permissionless. NestJS, Chainlink, Gelato, or an EigenLayer AVS (see Phase 6) can all call it.
• Regulatory story is simpler. The platform never holds funds in transit.

Known limitations and how we mitigate them​

Allowance-pull is not perfect. The honest drawbacks:

1. Infinite approvals​

Wallets often default to infinite approve values. Malicious contracts with infinite allowances drain wallets. Our mitigation: UI explicitly asks for a capped approval (e.g. 12 × monthly_amount for an annual sub), shows the dollar number, and offers "cancel anytime" copy. The contract enforces cap separately from the ERC-20 allowance.

2. Revoke-between-cycles​

A payer can revoke mid-subscription and the next charge will fail. Same failure mode as a saved card being canceled. Handled via existing webhook + email: subscription-insufficient-allowance.hbs and subscription-past-due.hbs.

3. Stale allowance after price change​

If the merchant raises the price mid-subscription, the old cap may be too small. Handled by the cap invariant reverting the charge() and the merchant UI prompting for a re-approve.

4. Reorg-induced double-charge​

Bot-scraping a block reorg can replay charge(). Handled by monotonic lastChargedAt in SubscriptionHub.

What changes for payers today​

Nothing. Today's Auto-charge flow already asks for approve(spender, amount) and SPL Approve — the same steps. Phase 2 moves the spender to a non-custodial contract address. Your wallet sees the same permission screen.

What changes for merchants​

Nothing in the API response shape. The approval_spender_address field in the subscription's auto_charge object just points at the SubscriptionHub contract instead of an OrcaRail hot wallet. The webhooks fire at the same moments.

Summary​

Allowance-pull wins outright on wallet compatibility and working capital; it ties or wins on every other axis. That is why OrcaRail subscriptions are built on it.

Related: Phase 2: Allowance-pull subscriptions · Auto-charge docs · Security model

Why subscriptions on OrcaRail​

Subscriptions are for SaaS, memberships, retainers, and any product billed on a fixed interval (day, week, month, year) with optional trials, cycle limits, and cancellation rules. You use the same Payments Auth as the rest of the platform, and you can react to lifecycle events with subscription webhooks.

Two ways to collect: payment links vs auto-charge​

• send_payment_link (default): Each billing cycle, the payer gets a payment link (email and/or hosted flow). They pay when they open the link—familiar for crypto checkout and easy to combine with Relay routes and wallet choice.
• auto_charge: The payer pre-authorizes OrcaRail’s hot wallet to pull the period amount on each renewal. After setup, renewals do not require the payer to click a new link each time—as long as balance and authorization remain valid.

Create and configure collection with POST /api/v1/subscriptions; list, update, pause, and cancel with manage subscriptions. Full request fields and examples live in those guides.

Auto-charge: how we handle it​

1. Merchant creates a subscription with collection_method: "auto_charge" and the usual amount, interval, token_id, network_id, and payer contact fields.
2. Payer opens the subscription or first-cycle payment experience. They see the total approval scope (for example, the sum of upcoming charges you ask them to cover) and signs an on-chain authorization:
   • On EVM chains, that is a standard ERC-20 approve(spender, amount) to our hot wallet as spender.
   • On Solana, the analogous step is SPL token delegation of at least one period’s amount to our Solana hot wallet.
3. Payer calls the public POST /api/v1/subscriptions/:id/approve-auto-charge endpoint with the allowance (or delegation) transaction hash, payer_wallet_address, payer_network_id, and payer_token_id. No merchant API key is required—the payer proves intent by having signed the chain transaction.
4. OrcaRail verifies on-chain that the allowance or delegation is at least one billing cycle for the expected hot wallet before marking auto-charge approved. Before each pull, we can re-check authorization so transient RPC issues are not confused with a revoked allowance.
5. Each billing cycle, the billing pipeline attempts the pull (EVM transferFrom-style flow from the payer to settlement; Solana uses the delegated balance). On success, the period advances; on repeated failure (e.g. insufficient balance or revoked approval), the subscription can move to past_due and the payer is notified—you can listen for webhooks such as subscription.payment_link.payment_failed or subscription.past_due as described in Auto-charge and webhooks.

Revoke and fallback: If the payer revokes on-chain, later pulls fail. They can also complete POST .../revoke-auto-charge after revoking so we record the state and can switch collection to send_payment_link, with email guidance to manage the subscription and pay via links again. Details are in Auto-charge and Manage subscriptions.

Security and clarity: Only the wallet that completed approval is used for pulls; we align UX with clear totals and cycle counts so payers know what they authorized. For very long or open-ended plans, consider capping approved amounts and refreshing approval periodically, or staying on payment links—see Auto-charge.

Multichain: how it fits subscriptions​

• Merchant anchor: Every subscription is created with a network_id and token_id that define how the subscription is priced and settled in API terms—the “home” network and asset for that plan.
• Payer context for auto-charge: Auto-charge stores payer_network_id and payer_token_id—the network and token where the payer actually set allowance or delegation. That can differ from the subscription’s primary fields when payers fund from another supported chain or asset, consistent with how quotes and checkout resolve payer-side routes.
• Relay-aligned coverage: Supported networks and currencies stay aligned with Relay; when Relay expands chains and tokens, our inventory follows. We summarized that model in Supported networks and currencies: powered by Relay.
• Where proceeds land: Merchants still configure withdrawal addresses per chain type (and can override per payment where supported). For the full picture of multichain withdrawals and multiple addresses per chain, see OrcaRail is multichain: withdrawals and Relay alignment.

Summary​

Subscriptions on OrcaRail combine RESTful subscription resources with non-custodial payer authorization for auto-charge and multichain payouts—without giving up the hosted pay experience and APIs you already use for one-off payments.

OrcaRail App · Docs · Relay

Where the List Comes From​

We don’t maintain a separate, hand-curated list of supported networks and tokens. Instead:

• Networks are synced from Relay’s Chains API (api.relay.link/chains for mainnet, plus testnets). Our seed process builds network records from Relay’s chain data—including EVM, Bitcoin, and Solana chain types where Relay supports them.
• Currencies and tokens are synced from Relay’s Currencies v2 API (get-currencies-v2). Tokens are upserted per network, so each chain gets the right set of payables and bridgeable assets.

When Relay adds a new chain or currency, our seed/update process brings it in. You get automatic alignment with Relay’s coverage without extra integration work on your side.

What “Support” Means​

Payments and (where applicable) bridging follow Relay’s supported routes. Relay currently supports 69+ blockchain networks across:

• EVM chains (Ethereum, Base, Polygon, Arbitrum, Optimism, and many more)
• Bitcoin
• Solana (SVM)
• Tron

Per chain, token support can be "All" (tokens where Solver or DEX liquidity exists) or "Limited" (only tokens listed with supportsBridging: true). For the canonical picture of routes and token support, see Relay’s docs:

• Supported Tokens & Routes — how to check if a route is supported
• Contract Addresses — solver and contract addresses per chain

How to See What OrcaRail Supports​

Use our API to get the current set of networks and tokens available in OrcaRail:

• Networks: GET /payments/networks — list all supported networks (optionally filter with ?active=true).
• Tokens per network: GET /payments/networks/:id/tokens — list tokens for a given network (use the network id from the list above).
• Fiat/display currencies: GET /price/currencies — list supported fiat currencies for pricing and quotes.

Full details are in the Payments API – List Networks / List Tokens and Price API – List Currencies docs.

Summary​

Supported networks and currencies at OrcaRail are powered by Relay and updated automatically—one integration, many chains.

OrcaRail App · Docs · Relay

Multichain, Not Every Chain (Yet)​

OrcaRail today is built for EVM-compatible chains. We do not support Bitcoin or Solana (or Solana-native tokens) as first-class chains in our payment and withdrawal flows. That keeps our integration surface focused and our APIs consistent while we scale.

If your stack is Ethereum, Base, Polygon, Arbitrum, Optimism, or other EVM L1s/L2s, you get one integration and one set of docs. No separate Bitcoin or Solana-specific flows—for now.

Multiple Withdrawal Addresses per Chain Type​

Withdrawals are where “multichain” really pays off. You can configure multiple withdrawal addresses per chain type in OrcaRail.

• Per-chain control: Set a different default (or set of addresses) for Ethereum, Base, Polygon, etc., so funds land where you want on each network.
• Per-payment override: When creating a payment intent, you can still pass a withdrawal_address to route that specific payment to a vendor or treasury on the right chain.
• No single bottleneck: Run marketplaces, SaaS, or multi-entity setups without forcing everything through one chain or one address.

So: multichain means multiple networks and multiple withdrawal destinations per chain, all configurable in the dashboard and via API.

Relay Supports Bitcoin and Solana—And So Do We (On the Roadmap)​

Relay supports Bitcoin and Solana (and their tokens) as part of its multichain coverage. OrcaRail is built to align with Relay’s model: one link, many chains.

We don’t support Bitcoin or Solana today, but our architecture and roadmap are built so that when we add them, it’s the same product: same APIs, same withdrawal model (multiple addresses per chain), same dashboard. “So we do” here means: we’re committed to the same multichain vision Relay embodies—Bitcoin and Solana included—and we’re expanding in that direction.

Until then, you get a stable, EVM-first multichain experience with full control over where funds go on each supported chain.

Summary​

Multichain at OrcaRail means: many EVM chains now, multiple withdrawal addresses per chain, and a path to Bitcoin and Solana in step with Relay.

OrcaRail App · Docs · Relay

Built with the assistance of AI and driven by a singular conviction: crypto payments must be open, transparent, and accessible across all chains. For too long, merchants and developers have been forced to choose between complex, unmaintained open-source tools or expensive, closed-ecosystem payment gateways that lock you in and charge high fees.

We built OrcaRail to break that paradigm. OrcaRail is a multichain payment platform that bridges Web2 business logic and Web3 settlement — hosted with simple per-transaction pricing and a generous free tier, or self-hosted Open source soon for full sovereignty.

The Philosophy: A Transparent Public Good​

We believe the financial rails of the internet should be a public good. Hosted OrcaRail is $0.10 per completed transaction, with your first 1,000 transactions free, so we can run reliable infrastructure while staying approachable for builders. Self-hosted OrcaRail Open source soon is free: deploy the open-source stack on your own hardware and pay only what your infrastructure costs.

Individual payment quotes can still include optional line items you control — for example a configurable support fee (percentage) and commission on API keys — plus bridge fees when routing across tokens or networks. Those are documented in our Fees & limits guides; they are separate from the hosted platform per-transaction price.

By staying open source and letting the community improve the product, we aim for non-custodial, high-performance rails with less counterparty risk than closed gateways — transparent by design.

If builders use hosted OrcaRail, self-host Open source soon, or mix both, together we can push back on opaque, high-fee payment silos. The future of commerce should be open and inspectable.

The Developer Experience: Familiar payment primitives​

If you know how to integrate traditional Web2 payment processors, you already know how to use OrcaRail. We designed our architecture to give you predictable states, auditable flows, and retry-safe webhooks.

• Stablecoin-First: Price your goods in fiat (USD/EUR) and settle instantly in USDC or USDT. Eliminate volatility risk for your business while offering customers a seamless checkout experience.
• Drop-In Checkout: Use our hosted payment links, embeddable widgets, and WalletConnect-ready interfaces to provide a clean UX.
• Webhooks & Idempotency: Keep your database perfectly synced with on-chain reality. Our system provides reliable events for succeeded, processing, and canceled states, complete with automated retries.
• Node.js SDK & REST API: Build once, connect everywhere.

  npm install @orcarail/node
  

Multi-Chain and Multi-Token Native​

Web3 is fragmented, but your payment gateway shouldn't be. You get one integration that works seamlessly across networks.

Currently, OrcaRail supports EVM-compatible chains out of the box. But we are not stopping there—all Relay-supported chains are actively on the way. Our smart routing technology automatically helps select the fastest or lowest-fee network for each specific payment, ensuring your customers never abandon a cart due to exorbitant gas fees.

Dynamic Withdrawals: Built for SaaS & Marketplaces​

Modern internet businesses are complex. Whether you are running a SaaS platform, a multi-vendor marketplace, or a creator economy app, routing funds manually is a nightmare. OrcaRail solves this natively:

• Per-Payment Routing: Pass a withdrawal_address when creating a payment intent. When the customer pays, funds are automatically routed directly to that specific vendor's wallet.
• Default Fallbacks: For simpler setups, omit the address and let funds settle into your global account default.
• Split Commissions: Running a platform? Set a commission percentage on your API keys. You earn your platform cut on every transaction, visibly calculated at checkout, and automatically sent to your own withdrawal address.

What's Next on the Roadmap?​

This is just day one. As we scale, our commitment to an open ecosystem only deepens:

1. Expanding Chain Support: Rapidly rolling out support for non-EVM chains via Relay integration.
2. Self-Hosted Open source soon: Deploy the open-source stack on your own infrastructure for sovereignty and privacy — no per-transaction software fee from us.
3. Advanced Compliance Tools: Optional metadata fields and integrations for seamless KYT/KYC workflows.

Try It: Feel the Difference​

We invite you to experience how easy crypto payments can be.

• 🚀 Start Building — Create an account, generate an API key, and make your first payment link in under two minutes.
• 🎮 Try the Live Demo — Test the complete end-to-end flow from intent creation to webhook confirmation.
• 📖 Read the Documentation — Explore our API reference, SDK guides, and architectural overviews.

The future should be open and transparent. Let's build it together.

OrcaRail App · GitHub · X/Twitter