Implement a non-custodial crypto payment adapter #3

New issue

Open

opened 2026-08-25 10:53:38 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-25 10:53:38 +00:00

(Migrated from github.com)

Goal

Add cryptocurrency payments as a second provider adapter over billing core #1 without making StarIntel custody customer funds or application private keys.

Provider decision

AUTO-RAGE must research the current ecosystem first and record the provider choice. Prefer a reputable non-custodial or self-hostable processor/invoice model with strong API/webhook support and clear settlement semantics. Do not hard-code a stale provider assumption.

Requirements

Keep wallets/private keys/seed phrases outside starintel-biz; application services must not become a hot wallet.
Create provider invoices/checkout sessions tied to a StarIntel invoice/payment attempt using stable external IDs.
Normalize chain/asset, requested amount/currency, quoted crypto amount where applicable, expiration, payment detection, confirmation/finality policy, settlement state, over/underpayment handling, refund/manual-review state, and provider fees where available.
Explicitly model volatility/quote expiry; do not silently reinterpret a stale crypto amount as satisfying a newer fiat invoice.
Define confirmation/finality policy per supported network/provider and distinguish observed, pending, confirmed/settled, expired, failed, and reversed/reorg/manual-review states.
Verified signed provider events are idempotent and reconciled against provider APIs; browser redirects are never payment proof.
Bound API timeouts/retries/rate limits and implement durable reconciliation for missed/late events.
Webhook/API credentials are runtime-only and never appear in Git/Nix store/logs.
Do not log wallet addresses or transaction identifiers more broadly than operational/accounting needs require; document privacy/retention policy.
Emit normalized billing audit events through #1.

Tests / acceptance

invoice creation + expiry fixtures
exact/under/overpayment handling
duplicate/out-of-order webhook handling
confirmation progression and late settlement
reorg/reversal/manual-review fixture where supported by chosen provider
provider outage + reconciliation recovery
prove no private keys/seed material are required by the service
exact-head integration against provider sandbox/test facilities where available

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: research current crypto payment providers and legal/operational constraints relevant to the implementation; inspect #1 and generic webhook infrastructure; design and record provider/finality/custody boundaries; adversarial review + payment-spoofing/reorg/key/quote/privacy threat model; autonomous decision gate; TDD-first implementation; exact-head sandbox/fixture verification; push a focused branch and open/update a PR targeting main. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Add cryptocurrency payments as a second provider adapter over billing core #1 without making StarIntel custody customer funds or application private keys. ## Provider decision AUTO-RAGE must research the current ecosystem first and record the provider choice. Prefer a reputable non-custodial or self-hostable processor/invoice model with strong API/webhook support and clear settlement semantics. Do not hard-code a stale provider assumption. ## Requirements - Keep wallets/private keys/seed phrases outside `starintel-biz`; application services must not become a hot wallet. - Create provider invoices/checkout sessions tied to a StarIntel invoice/payment attempt using stable external IDs. - Normalize chain/asset, requested amount/currency, quoted crypto amount where applicable, expiration, payment detection, confirmation/finality policy, settlement state, over/underpayment handling, refund/manual-review state, and provider fees where available. - Explicitly model volatility/quote expiry; do not silently reinterpret a stale crypto amount as satisfying a newer fiat invoice. - Define confirmation/finality policy per supported network/provider and distinguish observed, pending, confirmed/settled, expired, failed, and reversed/reorg/manual-review states. - Verified signed provider events are idempotent and reconciled against provider APIs; browser redirects are never payment proof. - Bound API timeouts/retries/rate limits and implement durable reconciliation for missed/late events. - Webhook/API credentials are runtime-only and never appear in Git/Nix store/logs. - Do not log wallet addresses or transaction identifiers more broadly than operational/accounting needs require; document privacy/retention policy. - Emit normalized `billing` audit events through #1. ## Tests / acceptance - invoice creation + expiry fixtures - exact/under/overpayment handling - duplicate/out-of-order webhook handling - confirmation progression and late settlement - reorg/reversal/manual-review fixture where supported by chosen provider - provider outage + reconciliation recovery - prove no private keys/seed material are required by the service - exact-head integration against provider sandbox/test facilities where available ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: research current crypto payment providers and legal/operational constraints relevant to the implementation; inspect #1 and generic webhook infrastructure; design and record provider/finality/custody boundaries; adversarial review + payment-spoofing/reorg/key/quote/privacy threat model; autonomous decision gate; TDD-first implementation; exact-head sandbox/fixture verification; push a focused branch and open/update a PR targeting `main`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

lost-rob0t commented

2026-08-25 10:58:53 +00:00

(Migrated from github.com)

Crypto provider selection rationale, custody boundary, quote/finality semantics, reconciliation/reorg/manual-review behavior, privacy, and operator recovery docs are tracked in #5. Keep the chosen provider contract documented there as this adapter lands.