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

GitHub Repository

Requirements, design, roadmap

Documentation Set

Approved v1.0 · 26 documents

PRD — Card Spend

Start here: the card flow

Project Status

Requirements and design are approved: version 1.0, tag docs-v1.0, 2026-10-04. Implementation has not started; there is no running service and no demo. Next milestone: S1 — Contracts (v0.1.0). Order, versions and log: roadmap.

Problem

A custodial crypto card makes the user pre-fund a balance the issuer controls.

A card authorization must be answered within 2–3 seconds, but an ERC-20 token has no hold and the wallet is not under the platform's control.

The same authorization can arrive twice and must not charge the cardholder twice.

Consuming systems need one view of a user's crypto accounts across exchanges and self-custody wallets.

Scope

Card spend: on-chain debit wallet → treasury at authorization time. No pre-funding, no custody.
Authorization API for an issuer processor, HTTP/JSON, modelled on JIT Funding: authorize, reverse, refund, status.
Spend contract: debit with expiry, refund, daily limit, roles, pause. Holds no tokens.

Exchange accounts, read-only: Binance balances (spot, funding, Earn) and history.
Canonical ledger for exchanges and chains; reconciliation against the on-chain balance.
gRPC API for consumers, multi-tenant. First consumer: Expense Tracker.

Design Highlights

Topic	Decision
Non-custodial card spend	Token allowance on the cardholder's wallet. Tokens move wallet → treasury at authorization; the contract holds nothing. ADR-9, PRD
Synchronous card, asynchronous chain	Approve only after the debit is preconfirmed or included. Deadline → decline. Every debit expires on-chain; a late debit is refunded automatically. ADR-12
No double debit	Three independent layers: request idempotency, nonce stored before send, single-use authId in the contract. SRS — Card Spend
Bounded platform power	Exchange keys are read-only. The only key that can move tokens lives in a separate binary. It can move them only wallet → treasury within allowance and daily limit, and back as refunds. ADR-3
One ledger for exchanges and chains	Canonical entries with legs, idempotent import, raw record kept, incremental pull by sequence. ADR-5, SRS — Core

Exchange integration, on-chain indexing and real-time signals: design highlights in the README.

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

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

Boundaries

CAS never holds user funds and never signs for the cardholder.

CAS never trades or withdraws on exchanges and never serves rates.

CAS stores no personal data: the owner is an opaque reference.

Test networks only: Anvil and Base Sepolia. No mainnet.

No real keys and no real balances.

Exchange access is read-only.

Documentation Set

BRD, 2 PRDs, 4 SRS, 13 ADRs, C4 context and containers, glossary, roadmap. 26 documents, about 4,500 lines. Markdown in the repository.

Traceability: business goal → business requirement → user story → functional requirement. Each functional requirement is one testable statement.

Map, conventions and identifiers: docs/README.

Time	Read
5 minutes	BRD §2–§4 and the context diagram
20 minutes	PRD — Card Spend, ADR-9, ADR-12
1 hour	SRS — Card Spend, then SRS — Core

Milestones

ID	Content
S1	Contracts `CardSpendController` and `MockUSDC`, tests on a local chain
C1	Core: tenants, connections, encrypted secrets, gRPC API, CI
S2	`card-auth`: end-to-end authorization locally, then on Base Sepolia
S3	Event indexer into the ledger; reconciliation
X1	Binance balances: spot, funding, Earn; key permission check; rate limiter
X2	Binance history; backfill and incremental sync; completeness check
W1	Real-time triggers from Binance account events

Outlined in the BRD: second exchange, Kraken, Expense Tracker integration. Status of each milestone: roadmap.

How It Was Produced

Author-led, AI-assisted. Scope, decisions and review: the author. Text and diagrams: an AI assistant, following the author's templates. No document is accepted without the author's review. Details: README.

Related Services

Currency Rate Service: rates. CAS never serves prices.

Expense Tracker: first consumer of balances and history.

Tech Stack (planned)

Go PostgreSQL gRPC go-ethereum Solidity Foundry OpenZeppelin Anvil Base Sepolia Docker