Light Wallet SDK

A lightweight, TypeScript-based wallet SDK for building credit, debit, and transfer flows with atomic Redis-backed operations, MongoDB transaction logging, and secure wallet signatures. Designed with DRY + KISS + Clean Code principles for clarity and extensibility.

✨ Features

• 🔑 Wallet Creation with strong hasher-based walletId signature
• 💸 Credit, Debit, Transfer (P2P) APIs
• 🔄 Idempotent Transfers (deduplication + Redis-based locks)
• 🛡 Replay Protection (transfer nonce + TTL)
• 📜 Transaction Logging with replay-safe schema in MongoDB
• ⚡ Atomic Operations using Redis Lua scripts
• 🧩 Extensible Adapters (Redis for wallet state, MongoDB for transactions)
• 🏗 Minimal, single-file SDK for clarity – adapt into your project structure
• 🚀 Ready to scale up to 10k TPS with Redis cluster + worker pools

📦 Installation

npm install zeroant-wallet

or with Yarn:

yarn add zeroant-wallet

🛠 Setup

import { WalletSDK, RedisWalletAdapter, MongoTxLogger } from "zeroant-wallet";

// Redis adapter for wallet state
const redis = new RedisWalletAdapter("redis://localhost:6379");

// MongoDB logger for transactions
const mongo = new MongoTxLogger("mongodb://localhost:27017/lightwallet");

// Simple hasher implementation
const hasher = {
  sign: (id: string) => require("crypto").createHash("sha256").update(id).digest("hex"),
  verify: (id: string, sig: string) =>
    require("crypto").createHash("sha256").update(id).digest("hex") === sig,
};

const sdk = new WalletSDK(
  { defaultCurrency: "USD", allowNegativeBalance: false },
  redis,
  mongo,
  hasher
);

await sdk.start();

⚡ Quick Integration

3-line usage:

import { WalletSDK } from "zeroant-wallet";

const sdk = new WalletSDK({ defaultCurrency: "USD", allowNegativeBalance: false }, redis, mongo, hasher);

await sdk.start(); // ready to use sdk.createWallet / sdk.transfer

📚 API Reference

1. Create Wallet

const wallet = await sdk.createWallet("alice", "USD", 100, { plan: "premium" });
console.log(wallet.walletId, wallet.balance);

Options:

• owner: string (optional)
• currency: e.g., "USD", "NGN"
• initial: initial balance (default 0)
• meta: extra metadata
• allowNegativeBalance: per-wallet overdraft flag
• allowNegativeCredit: per-wallet credit flag

2. Credit Wallet

await sdk.credit(wallet.walletId, 50, "credit-1", { note: "Top-up" });

3. Debit Wallet

await sdk.debit(wallet.walletId, 20, "debit-1", { note: "Purchase" });

4. Transfer (P2P)

await sdk.transfer(alice.walletId, bob.walletId, 10, "tx-1", { note: "Payment" });

5. Find Transaction

const tx = await sdk.findTx({ txId: "tx-1" });

6. Verify Wallet Signature

const valid = sdk.verifyWalletSignature(wallet.walletId, wallet.signature);

7. Shutdown SDK

await sdk.shutdown();

8. Find Many Transactions

const txs = await sdk.findManyTx(
  { from: "aliceWalletId" }, 
  { limit: 10, sort: "desc", skip: 10 }
);

• query: Partial<Transaction> – e.g. { from: walletId }, { currency: "USD" }

• filters: TransactionFilter (optional)

  • limit – number of results
  • sort – "asc" or "desc"
  • skip – for pagination

Returns an array of matching transactions. Useful for audit trails, statements, and reporting.

🔒 Error Handling

SDK throws typed errors:

• WalletError
• DuplicateTransactionErr
• WalletNotFoundErr
• InsufficientFundsErr

Example:

try {
  await sdk.debit(wallet.walletId, 5000);
} catch (e) {
  if (e instanceof InsufficientFundsErr) {
    console.error("Balance too low!");
  }
}

🏗 Scaling Notes

• Use Redis Cluster for high throughput.
• Enable Lua scripts for atomic ops.
• Run multiple worker nodes consuming the Redis stream for async jobs.
• Use connection pooling for MongoDB and Redis.
• Carefully tune resource limits to reach 10k TPS.
• Log transactions asynchronously to avoid bottlenecks.

🧪 Testing

Integration test example (using Jest):

it("should transfer funds between two wallets", async () => {
  const alice = await sdk.createWallet("alice", "USD", 100);
  const bob = await sdk.createWallet("bob", "USD", 0);

  const tx = await sdk.transfer(alice.walletId, bob.walletId, 50);

  expect(tx.status).toBe("success");
  const aliceWallet = await sdk.getWallet(alice.walletId);
  const bobWallet = await sdk.getWallet(bob.walletId);

  expect(aliceWallet?.balance).toBe(50);
  expect(bobWallet?.balance).toBe(50);
});

📂 Project Structure

src/
  ├── wallet.sdk.ts         # Core SDK
  ├── redis.adapter.ts      # Redis Wallet Adapter
  ├── mongo.logger.ts       # Mongo Transaction Logger
  ├── types.ts              # Shared Types
  └── index.ts              # Exports

🛡 License

MIT © 2025