Architecture

Comet Engine is a single Go binary that handles wallet management, token operations, AMM swaps, and double-entry accounting.

System Components

┌─────────────────────────────────────────────────────────────┐
│                     Client Layer                             │
│  app-core-backend / FusionFy / app-dashboard                │
└────────────────────────┬────────────────────────────────────┘
                         │  HTTP (X-API-Key + X-API-Secret)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Comet Engine (Go :8100)                    │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                  Middleware Layer                      │   │
│  │  CORS │ Request ID │ Security Headers │ Auth │ Rate  │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │
│  │ Wallets │  │  Assets  │  │   AMM    │  │   Journal   │ │
│  │ Module  │  │  Module  │  │  Module  │  │   Module    │ │
│  └────┬────┘  └────┬─────┘  └────┬─────┘  └──────┬──────┘ │
│       │            │             │               │          │
│       └────────────┴─────────────┴───────────────┘          │
│                         │                                    │
│                   ┌─────┴──────┐                             │
│                   │ EVM Client │                             │
│                   │  (Celo)    │                             │
│                   └────────────┘                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
            ┌─────────────┼─────────────┐
            ▼             ▼             ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │  Celo    │  │  Celo    │  │ MongoDB  │
      │  EVM     │  │  EVM     │  │ (state)  │
      │  RPC     │  │  Chain   │  │          │
      └──────────┘  └──────────┘  └──────────┘

Module Breakdown

Wallets (internal/chains/evm/client.go)

• Custodial EVM wallet creation (POST /wallets/create)
• AES-GCM encrypted key storage with Shamir backup
• Gas relaying (ensureGas())

Assets (internal/api/dynamic_handlers.go)

• ERC-20 operations: mint, burn, approve, transfer, balance
• Dynamic routing — :symbol in URL resolves to the registered asset
• Chain selection via ?chain= query param

AMM (internal/chains/evm/swap.go)

• Uniswap V2 quote + execution
• Pool listing
• Relayed gas, user-signed transactions

Journal (internal/ledger/)

• Double-entry accounting for every operation
• Append-only MongoDB collection
• Backing-aware: airtime assets debit/credit inventory accounts

Tenants (internal/tenants/)

• Multi-tenant registry
• API key/secret management
• Per-tenant wallet isolation

Request Flow

1. HTTP Request arrives
2. Middleware: Auth (API Key/Secret → tenant context OR Service Token)
3. Route handler extracts tenant + user context
4. Module logic (wallet/asset/swap/journal)
5. EVM Client: sign + broadcast transaction to Celo
6. Journal: record debit/credit entry
7. Response to client

Data Model

MongoDB Collections:
  tenants          — tenant registry (API keys, secrets)
  evm_wallets      — encrypted private keys, per (tenant, user)
  journal_entries  — append-only double-entry ledger

Key Derivation

WALLET_ENCRYPTION_KEY (master)
  └─ deriveUserKey(key, tenantID, userID)
       └─ keccak256(master + "comet-wallet-{tenant}-{user}")
            └─ sealKey(privHex, userKey) → AES-GCM encrypted blob
                 ├─ stored as encrypted_key (for direct decryption)
                 └─ splitKey(sealed) → 5 Shamir shares
                      └─ shares[0] stored as server_shard (backup)