Crypto Account Service

One view of a user's crypto accounts, and card spend from a self-custody wallet without custody.

Portfolio Project by Igor Kudinov

Project Status

Card spend and Binance balances built and tested: v0.1.0 … v0.5.0, 2026-10-04 … 2026-10-10. 478 test-plan rows and 455 Go tests pass; CI green. Services stopped after the checks: no server deployment, no demo. Next: X2 — Binance history. Roadmap.

Key Features

  • Non-custodial card spend: wallet → treasury at authorization, no pre-funding
  • Card authorization API for an issuer processor, HTTP/JSON, JIT Funding model
  • Spend contract in Solidity: expiry, refund, daily limit, roles, pause
  • Reconciliation: every debit matched to exactly one authorization
  • On-chain indexing from final blocks, with a reorg guard
  • Read-only Binance connector: spot, funding and Earn balances
  • Canonical ledger for exchanges and chains; multi-tenant gRPC API
  • Card quotes from Currency Rate Service

System Context

Rendered from docs/c4/context.md (docs-v1.0) in the Mermaid live editor; title removed, relation labels repositioned. Context and container diagrams in the repository

Live on Base Sepolia

ItemResult
Contracts MockUSDC 0x6c04…f3aB, CardSpendController 0xF75D…5F37
End to end 5 USD approved in 0.52 s (debit), 2 USD returned (refund)
Decision time p95 0.696 s over 30 authorizations; requirement ≤ 2 s
Reconciliation 32 debits and 1 refund matched; no mismatch

Test network and a mock token: no real funds. Evidence: Deployment Guide §12, §13.6.

Design Highlights

TopicDecision
Non-custodial card spend Token allowance on the cardholder’s wallet; the contract holds nothing
Synchronous card, asynchronous chain Approve only after the debit is preconfirmed or included; a late debit is refunded automatically
No double debit Request idempotency, nonce stored before send, single-use authId in the contract
Bounded platform power Exchange keys read-only, any other permission refused; the only key that moves tokens lives in a separate binary, within allowance and daily limit

All decisions: README · 13 ADRs.

Card Authorization Flow

sequenceDiagram
    autonumber
    participant P as Issuer processor
    participant A as card-auth
    participant R as CRS
    participant N as EVM network
    participant S as server (indexer)

    P->>A: Authorize(auth_id, card_ref, amount)
    A->>A: Idempotency, card status, limit
    A->>R: Rate, if currency is not USD
    A->>N: Read balance and allowance
    alt a check fails
        A-->>P: DECLINED + reason
    else all checks pass
        A->>N: debit(wallet, amount, authId, validUntil)
        N-->>A: Preconfirmed or included
        A-->>P: APPROVED
    end
    Note over A,S: Asynchronous part
    N-->>A: Finality reached → debit confirmed
    S->>N: Read Debited event
    S->>S: Ledger entry, reconciliation

Source and edge cases EC-1 … EC-12: PRD — Card Spend §3.3.2. Synchronous part (steps 1–8) measured on Base Sepolia: decision p95 0.696 s.

Boundaries

Non-custodial: CAS never holds user funds or signs for the cardholder.

Read-only on exchanges: no trading, no withdrawals; keys with other permissions refused.

Chains: test networks only. Binance: checked once on the owner’s account with a read-only key, deleted after the check.

Milestones

DoneS1 Contracts · C1 Core · S2 card-auth · S3 EVM connector · X1 Binance balances
NextX2 Binance history · W1 Real-time triggers

Documentation

34 documents: BRD, 2 PRDs, 4 SRS, 13 ADRs, C4, 5 test plans, Deployment and Binance Key guides. Traceability from business goal to test. Start here: PRD — Card Spend · Map: docs/README.

Author-led, AI-assisted; every document reviewed by the author. Details.

Tech Stack

Go PostgreSQL gRPC protobuf / buf OpenAPI sqlc go-ethereum Solidity Foundry OpenZeppelin Anvil Base Sepolia Alchemy Binance API GitHub Actions