@kido/wallet-ledgerCopy Anchor Link

Architecture Paradigm: Dual-Wallet Isolation (USE vs EARN) + Strict Double-Entry Ledger Invariant + Held/Release Withdrawal State Machine + Stateless Crypto Micro-Decimal Matcher + Anti-Fraud Referral Clawback.

💥 The Real-World Bottleneck (Why It Exists)Copy Anchor Link

In e-commerce, affiliate networks, crypto deposits, and creator monetization platforms:

1. The Mutable Balance Race Condition (UPDATE users SET balance = balance + X):
   • Storing a user's wallet as a single mutable integer or float column in a relational database inevitably suffers from lost updates, negative balance race conditions under concurrent checkouts, and non-existent auditability.
   • When a transaction fails midway, finding where money disappeared or was created out of thin air requires days of manual database forensics.
2. Mixing Withdrawable Affiliate Revenue with Promotional Credits:
   • Platforms that pool promotional vouchers (e.g. signup bonus credits) with real withdrawable earnings (affiliate commissions) get exploited. Fraudsters cycle bonus credits into cash withdrawals, causing direct fiscal hemorrhage.
3. Stateless Crypto Deposit Tracking (Smart Contract Cost & Overhead):
   • Deploying unique smart contract wallets per user on Ethereum or Tron costs \$2–\$5 in network gas fees per address.
   • Alternatively, sharing a single master company deposit address without transaction memos makes it impossible to automatically identify which user deposited \$100 USDT.
4. Referral Fraud & Circular Affiliate Rings:
   • Attackers create rings of puppet accounts with disposable emails and VPNs, triggering payouts to themselves before orders are refunded or chargebacked.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📐 Architecture & Data FlowCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

All capabilities are strictly isolated in packages/wallet-ledger:

1. src/ledger.tsCopy Anchor Link

• DoubleEntryLedger: Pure double-entry financial ledger enforcing Sum(Debit) === Sum(Credit) across all currency journals.
• WalletLedger: High-level wallet engine managing paired USE (promotional/in-app credits) and EARN (withdrawable cash) sub-accounts.
• verifyBalanceEquation(entries): Runtime guard validating ledger parity before committing to persistent storage.
• auditLedgerIntegrity(transactions): Deterministic mathematical audit proving zero funds were created outside verified genesis deposits.

2. src/withdrawal.tsCopy Anchor Link

• WithdrawalStateMachine: Formal state machine managing withdrawal states: REQUESTED ➔ HELD ➔ APPROVED ➔ PROCESSING ➔ COMPLETED (or REJECTED / CANCELLED with automatic balance unfreezing).
• EscrowEngine: Manages multi-party hold and milestone-based fund releases.
• IdempotencyGuard: In-memory and persistent transaction deduplication guard.

3. src/crypto-reconcile/Copy Anchor Link

• MicroDecimalAmountGenerator: Generates deterministic unique fractional offsets (e.g., 50.0001 USDT, 50.0002 USDT) within configured decimal windows to uniquely identify deposits on a single master address.
• CryptoTransactionMatcher: Matches unspent blockchain transactions to pending user intent deposits within an expiry TTL.

4. src/referral-guard/Copy Anchor Link

• ReferralFraudGuard: Analyzes affiliate networks for circular loops, disposable email patterns, IP subnet clustering, and self-referrals.
• ReferralClawbackManager: Automatically claws back pending or unpaid commissions when underlying purchases are refunded or charged back.

5. src/portfolio-nav/Copy Anchor Link

• executeWacbTransaction(holdings, order): Calculates Weighted Average Cost Basis (WACB) and realized profit/loss.
• calculatePortfolioValuation(holdings, quotes): Computes real-time Net Asset Value (NAV).
• calculatePortfolioRiskMetrics(history): Calculates Sharpe ratio and Maximum Drawdown (MDD).

💻 Production Implementation & Code SnippetCopy Anchor Link

1. Dual-Wallet Accounting & Withdrawal Flow (src/services/wallet-service.ts)Copy Anchor Link

import {
  WalletLedger,
  WithdrawalStateMachine,
  verifyBalanceEquation,
} from '@kido/wallet-ledger';

// 1. Initialize ledger and withdrawal state machine
const ledger = new WalletLedger();
const withdrawalMachine = new WithdrawalStateMachine(ledger);

// 2. Create customer wallet with separated USE and EARN sub-accounts
const wallet = ledger.createWallet({
  walletId: 'wal_usr_902',
  userId: 'usr_khanh_22',
  currency: 'VND',
});

// 3. Customer tops up 1,000,000 VND (Credited to non-withdrawable USE account)
ledger.creditUseAccount({
  walletId: wallet.walletId,
  amount: 1_000_000,
  referenceType: 'BANK_DEPOSIT',
  referenceId: 'DEP_20261112_01',
  idempotencyKey: 'idem_dep_001',
});

// 4. Partner earns 350,000 VND affiliate commission (Credited to withdrawable EARN account)
ledger.creditEarnAccount({
  walletId: wallet.walletId,
  amount: 350_000,
  referenceType: 'AFFILIATE_PAYOUT',
  referenceId: 'COMM_ORD_8819',
  idempotencyKey: 'idem_comm_001',
});

// 5. Withdrawal Request: Atomically moves funds from AVAILABLE to HELD
export async function initiatePartnerPayout() {
  const withdrawal = withdrawalMachine.requestWithdrawal({
    walletId: wallet.walletId,
    userId: 'usr_khanh_22',
    amount: 200_000,
    fee: 5_000,
    payoutMethod: 'VIETQR_BANK_TRANSFER',
    destination: {
      bankCode: '970422', // MBBank
      accountNumber: '0987654321',
      accountName: 'DUONG PHUC KHANH',
    },
    idempotencyKey: 'idem_wd_7718',
  });

  console.log(`[Withdrawal] ID ${withdrawal.withdrawalId} status: ${withdrawal.status}`); // HELD

  // Simulating bank payout success callback
  withdrawalMachine.approveWithdrawal(withdrawal.withdrawalId, 'admin_super');
  withdrawalMachine.completeWithdrawal(withdrawal.withdrawalId, 'BANK_TRACE_992144');

  console.log('[Withdrawal] Payout completed. Balance permanently debited.');
}

2. Stateless Crypto Micro-Decimal Reconciliation (src/services/crypto-deposit.ts)Copy Anchor Link

import {
  MicroDecimalAmountGenerator,
  CryptoTransactionMatcher,
} from '@kido/wallet-ledger';

const generator = new MicroDecimalAmountGenerator({
  baseAmount: 100, // Base deposit 100 USDT
  decimalPlaces: 4, // 100.0001 -> 100.0999
  offsetWindowMinutes: 60,
});

const matcher = new CryptoTransactionMatcher();

export function createDepositIntent(userId: string) {
  // Generates unique amount: 100.0024 USDT
  const { expectedAmount, reservationKey, expiresAt } = generator.generateUniqueAmount(userId);

  matcher.registerIntent({
    reservationKey,
    userId,
    expectedAmount,
    currency: 'USDT',
    expiresAt,
  });

  return {
    depositAddress: 'TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', // Single shared company cold wallet
    exactAmountToTransfer: expectedAmount,
    expiresAt,
  };
}

⚡ Benchmark & Verified PerformanceCopy Anchor Link

Tested with 1,000,000 concurrent ledger transactions:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

npx @kido/cli add wallet-ledger