Security model
This page states exactly who controls what, what can be upgraded, and where the trust boundaries are — before and after the non-custodial transition.
Trust assumptions
Before (custodial sweep model)
| Who | Controls |
|---|---|
| OrcaRail API server | WALLET_ENCRYPTION_KEY, encrypted hd_wallet_seed |
| OrcaRail keeper | Unilateral signing authority over every deposit address |
| Payer | Their own external wallet |
| Merchant | Withdrawal destination configuration; no in-flight control |
Implication: an OrcaRail compromise puts in-flight funds at risk.
After (non-custodial contract model)
| Who | Controls |
|---|---|
| 3-of-5 Safe (EVM) | Factory proxy upgrade (timelocked), refund emergency, deployer ceremony |
| 3-of-5 Squads (Solana) | Anchor program upgrade authority |
| OrcaRail keeper EOA per chain | Gas-only wallet; can call public charge(), nothing else |
| Payer | Signs approve(SubscriptionHub, cap) or SPL Approve; can revoke anytime |
| Merchant | Withdrawal destinations; BTC per-link multisig signer |
Implication: an OrcaRail compromise cannot move in-flight EVM/Solana funds. The worst case is a temporary keeper outage (charges delayed), which Chainlink/Gelato fallback mitigates.
Key custody
Deployer multisigs
- EVM Safe (Base, Ethereum, Arbitrum, Optimism, Polygon): 3-of-5. Signers use hardware wallets (Ledger + optional HSM). No signer keys on servers.
- Solana Squads: 3-of-5 with the same signer set.
- Signer rotation: annual or on departure; each rotation is a multisig transaction.
- Ceremony: every deploy and every upgrade runs as an announced multisig ceremony; signed PSBTs (for BTC) and Safe transactions are recorded for audit.
Keeper EOAs
- One hot EOA per chain for
charge()and Relay executor calls. - Gas-only: zero fee destination, zero refund authority, zero contract ownership.
- Key material lives in a secrets manager (Doppler / AWS Secrets Manager); rotation logged via the standard infrastructure pipeline.
- Alarms when balance drops below
gasPrice × gasLimit × 100.
BTC keys (Phase 5)
- Merchant key: held by the merchant (browser extension, mobile, hardware wallet). OrcaRail never sees the private material.
- Platform key: held by an HSM or MPC service (candidates: Lit Protocol, Turnkey, or on-prem HSM). API server does not hold the raw key.
- Pre-signed refund PSBTs: encrypted at rest with a separate KMS key.
Contract immutability and upgrade policy
| Component | Upgradeable? | Controlled by | Timelock |
|---|---|---|---|
PaymentLinkFactory | Yes (UUPS) | 3-of-5 Safe | 48 hours |
PaymentLinkReceiver (per link) | No | — | — |
FeeSplitter | No | — | — |
SubscriptionHub | Yes (UUPS) | 3-of-5 Safe | 48 hours |
payment_link (Solana Anchor) | Yes | 3-of-5 Squads | (program-level) |
subscription (Solana Anchor) | Yes | 3-of-5 Squads | (program-level) |
Breaking semantic changes are published as new versions (V2) and migrated, not upgraded in place. The 48-hour timelock on proxies gives the community time to see and react to upgrade proposals on-chain.
Audit posture
- Primary audit on initial EVM contracts (
PaymentLinkFactory,PaymentLinkReceiver,FeeSplitter,SubscriptionHub) before Base mainnet launch. Vendors shortlisted from Spearbit / Trail of Bits / Zellic. - Solana audit on both Anchor programs before SOL mainnet launch. Vendors from OtterSec / Neodyme.
- Competitive review or bug bounty alongside the primary audit.
- Audit reports published publicly; linked from Contract reference.
- Delta audits for subsequent meaningful changes (e.g. new fee logic, new token standards).
Incident response
- On-call rotation via PagerDuty for keeper outages, indexer lag, and keeper EOA balance.
- Pause controls: factories and
SubscriptionHubhave apause()callable by the multisig; per-link receivers cannot be paused (trust win for payers). - Bug bounty: public program scoped to the contracts and to the indexer logic; payouts from the platform treasury.
- Disclosure: material incidents get a postmortem published within 30 days, signed by the multisig signers.
Threat model highlights
| Threat | Mitigation |
|---|---|
Reorg double-charge on SubscriptionHub | lastChargedAt monotonic invariant |
| USDT-style non-standard ERC-20 | SafeERC20 everywhere; invariant tests |
| Fee-on-transfer tokens | Token allowlist gated by multisig |
| CREATE2 predeploy grief (someone sends before deploy) | Factory's deployAndPay is idempotent; balance waiting at predicted address is still recoverable via factory-led deploy |
| Keeper compromise | Gas-only EOA; no contract authority |
| Multisig signer compromise | 3-of-5 threshold; hardware-only; annual rotation |
| Solana delegate revoked mid-subscription | charge() emits ChargeSkipped(DelegateRevoked); standard email + webhook |
| BTC merchant key loss | Backup key option at onboarding; multisig ceremony recovery documented |
| Indexer downtime | Alchemy primary + public RPC fallback; hourly reconcile |
| Paymaster policy exhaustion | 70% quota alert; keeper self-funds gas as fallback |
Custody transparency
After Phase 7, we can state factually:
- OrcaRail holds zero EVM seed material.
- OrcaRail holds zero Solana seed material.
- OrcaRail holds a platform-side signing key for Bitcoin; this key alone cannot move funds — it requires a merchant co-signature.
That posture is reflected in the Terms of Service update accompanying Phase 7.