██████╗ ██╗      ██████╗  ██████╗██╗  ██╗ ██████╗██╗  ██╗ █████╗ ██╗███╗   ██╗
██╔══██╗██║     ██╔═══██╗██╔════╝██║ ██╔╝██╔════╝██║  ██║██╔══██╗██║████╗  ██║
██████╔╝██║     ██║   ██║██║     █████╔╝ ██║     ███████║███████║██║██╔██╗ ██║
██╔══██╗██║     ██║   ██║██║     ██╔═██╗ ██║     ██╔══██║██╔══██║██║██║╚██╗██║
██████╔╝███████╗╚██████╔╝╚██████╗██║  ██╗╚██████╗██║  ██║██║  ██║██║██║ ╚████║
╚═════╝ ╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝

Blockchain Integration Guide

Focus: what a blockchain actually is (a replicated append-only ledger nobody owns), the trade-off that governs every design choice (the trilemma), and where it earns its keep for codeAmani — stablecoin settlement and remittance rails that complement M-Pesa, not replace it. EVM-anchored, read-mostly, secrets server-side.

Overview

A blockchain is a shared, append-only ledger replicated across thousands of independent computers, where new entries ("blocks") are only accepted if a majority agree they follow the rules. Each block carries the cryptographic hash of the one before it, so the chain is tamper-evident: change one historical transaction and every later block's hash breaks, and the network rejects your fork. No single party — no bank, no company, no government — can silently edit it. That single property (verifiable state without a trusted operator) is the whole point; everything else is engineering trade-offs around it.

Three honest truths frame every blockchain decision:

1. You can't have it all — the trilemma. A chain optimises at most two of decentralisation, security, and scalability. Bitcoin and Ethereum L1 pick decentralisation + security and pay with low throughput and higher fees. High-TPS L1s buy scalability by reducing the number of validators (less decentralised). L2 rollups (Base, Arbitrum, Optimism) are today's pragmatic answer: they execute cheaply off-chain and inherit Ethereum's security by posting proofs back to L1.
2. Reads are free and easy; writes are slow, public, and cost gas. Querying chain state (a balance, a token's supply) is a cheap RPC call. Writing (a transfer, a contract call) is signed by a private key, broadcast to the mempool, included in a block by a validator, and costs a gas fee. Until it has enough confirmations it can still be reorged — writes are eventually-final, not instantly-final.
3. Code is law, and bugs are permanent. A deployed smart contract is immutable and usually controls real money. There is no "undo," no support line. This is why audits, well-trodden token standards (ERC-20, ERC-721), and "don't roll your own crypto" matter more here than almost anywhere else.

For codeAmani, the realistic, non-speculative use is digital dollars on a cheap fast chain: USDC/USDT (stablecoins) on an L2 settle cross-border value in seconds for cents, which is a genuine complement to M-Pesa's domestic strength. The rest of this guide is EVM-centric (Ethereum + its L2s) because that ecosystem has the deepest tooling — viem and ethers — and the widest stablecoin liquidity.

Official Documentation

How a block chain holds together

Each block bundles a batch of transactions plus the hash of the previous block. Because the hash is derived from the contents, any change anywhere ripples forward and invalidates every subsequent block — that's what makes the ledger tamper-evident rather than merely "a database with backups."

Consensus is how the network agrees on which block is next. Ethereum uses Proof of Stake: validators lock up (stake) ETH and are chosen to propose/attest blocks; misbehaviour gets their stake slashed. This replaced energy-hungry Proof of Work and is why "Ethereum is bad for the environment" is now outdated.

The transaction lifecycle (a write)

Reading is a free RPC query. Writing money or state is the part with real consequences — sign locally, broadcast, wait for inclusion, then wait for finality.

Key terms you must internalise:

Reading the chain (viem)

viem is the modern, type-safe TypeScript interface. A Public Client reads; install and query in three lines. Source: viem getting-started + clients/public docs.

npm i viem

// lib/chain.ts
import { createPublicClient, http } from "viem";
import { base } from "viem/chains"; // Base = cheap Ethereum L2 — good default for payments

// A public client is read-only. The transport is your RPC endpoint.
export const publicClient = createPublicClient({
  chain: base,
  transport: http(process.env.RPC_URL), // server-side RPC; falls back to a public node if omitted
});

// Cheap, free reads:
const block = await publicClient.getBlockNumber();
const wei = await publicClient.getBalance({ address: "0xA0Cf…251e" });

Reading an ERC-20 (e.g. a USDC balance)

Tokens like USDC are smart contracts, not native chain balance — you read them by calling balanceOf on the contract. Pattern straight from viem's reading-contracts example.

import { erc20Abi, formatUnits } from "viem";
import { publicClient } from "./chain";

const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC on Base

const [symbol, decimals, raw] = await Promise.all([
  publicClient.readContract({ address: USDC, abi: erc20Abi, functionName: "symbol" }),
  publicClient.readContract({ address: USDC, abi: erc20Abi, functionName: "decimals" }),
  publicClient.readContract({ address: USDC, abi: erc20Abi, functionName: "balanceOf", args: ["0xA0Cf…251e"] }),
]);

const human = formatUnits(raw, decimals); // e.g. "42.5" → never do float math on raw bigint balances

The same read in ethers v6

ethers is the mature alternative; many existing dapps use it. Source: ethers v6 getting-started.

npm i ethers

import { JsonRpcProvider, Contract, formatUnits } from "ethers";

const provider = new JsonRpcProvider(process.env.RPC_URL);
const abi = [
  "function decimals() view returns (uint8)",
  "function symbol() view returns (string)",
  "function balanceOf(address) view returns (uint)",
];
const usdc = new Contract("0x8335…2913", abi, provider);

const decimals = await usdc.decimals();
const balance = await usdc.balanceOf("0xA0Cf…251e");
const human = formatUnits(balance, decimals);

viem vs ethers, for a new codeAmani project: prefer viem — smaller bundle (matters on 2G/3G), first-class TypeScript inference, and it pairs with wagmi for React wallet hooks. Use ethers when integrating with an existing codebase or tutorial that already assumes it.

Writing the chain (and why the key stays off your server)

A write is signed by a private key. There are two safe places for that key, and your app server is never one of them:

• User-custodied (recommended for consumer apps): the user's browser wallet (MetaMask, Coinbase Wallet, or a WalletConnect mobile wallet) holds the key. Your frontend builds the tx; the wallet signs it. Use wagmi + viem (or RainbowKit) for the connect/sign UX. Your backend never touches a key.
• App-custodied (for treasury/automation): use a KMS/HSM-backed signer (AWS KMS, GCP KMS) or a custody provider so the raw key never sits in app memory or env files. viem and ethers both support remote signers.

// Frontend write with a browser wallet (viem) — simulate first, then send.
import { createWalletClient, custom, parseUnits, erc20Abi } from "viem";
import { base } from "viem/chains";
import { publicClient } from "./chain";

const walletClient = createWalletClient({ chain: base, transport: custom(window.ethereum) });
const [account] = await walletClient.getAddresses();

// 1. Simulate — catches reverts BEFORE the user pays gas.
const { request } = await publicClient.simulateContract({
  account,
  address: "0x8335…2913", // USDC
  abi: erc20Abi,
  functionName: "transfer",
  args: ["0xRecipient…", parseUnits("10", 6)], // 10 USDC (6 decimals)
});
// 2. The wallet signs & broadcasts; the key never leaves the wallet.
const hash = await walletClient.writeContract(request);
// 3. Wait for finality before treating it as paid.
const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 3 });

The simulate → write → wait sequence is the canonical safe pattern: simulation surfaces a revert before any gas is spent, and waitForTransactionReceipt is where you enforce your finality threshold.

Smart contracts in one breath

A smart contract is code (usually Solidity) deployed to an address that runs on the EVM exactly as written, by every validator, forever. You mostly consume existing contracts via their ABI (the JSON describing their functions) rather than writing your own. When you do write one:

• Don't reinvent standards. Use audited OpenZeppelin implementations of ERC-20 (fungible tokens), ERC-721/1155 (NFTs), access control, and pausability.
• Immutability cuts both ways. Plan upgrades (proxy patterns) before deploy, or accept that the bytecode is final.
• Test on a testnet first (Base Sepolia, Sepolia) with free faucet ETH before mainnet. Same discipline as testing M-Pesa against the Daraja sandbox before going live.

Possible use cases for codeAmani (mapped to the existing stack)

Blockchain is not a replacement for the repo's rails — it's a settlement layer that plugs into them. Each row pairs a real product idea with the tech-stack guide it builds on.

The honest framing for the East African market: stablecoins are the killer app, speculation is not. USDC settlement complements M-Pesa's last-mile reach; treat the chain as a fast, borderless clearing layer and let Daraja handle the cash-in/cash-out that users actually touch.

On/off-ramp reality (the hard part)

Moving between fiat (KES) and on-chain dollars is a regulated, partner-dependent step, not an API you self-host:

• On-ramp (KES/M-Pesa/card → USDC): integrate a licensed provider/aggregator; your app orchestrates, the provider handles KYC and custody.
• Off-ramp (USDC → M-Pesa): same — a licensed partner credits the recipient's M-Pesa via Daraja B2C after receiving the stablecoin.
• Your job is orchestration + reconciliation: persist every leg (CheckoutRequestID for the M-Pesa leg, tx hash for the chain leg), dedupe, and reconcile out of band — the same idempotency discipline as the webhooks guide.

Security checklist

• Private keys / seed phrases never on a server, in env files, in git, or in NEXT_PUBLIC_*. User-custodied wallets sign in the browser; app-custodied keys live in KMS/HSM.
• RPC URLs and provider API keys are server-side env vars; proxy chain reads through your backend so keys don't ship to the client bundle.
• Always simulateContract before writeContract — catch reverts before spending gas.
• Enforce a finality threshold (waitForTransactionReceipt with a confirmations count) before treating a payment as received.
• Work in the smallest unit (bigint); parseUnits/formatUnits only at the boundary. Never use JS floats for money.
• Use audited token standards (OpenZeppelin) and audited contracts; never roll your own crypto or token logic.
• Validate addresses and amounts at every system boundary (forms, API routes) — a typo'd address is an irreversible loss.
• Dedupe on transaction hash when indexing on-chain events into your DB (at-least-once, like webhooks).
• Test on a testnet (Base Sepolia) with faucet funds before mainnet — same gate as the Daraja sandbox.
• Pin chain IDs in config and assert the connected wallet is on the expected network before any write.

codeAmani notes

• Secrets server-side only. RPC_URL, provider/custody API keys → .env.local locally, Vercel env vars in prod. Signing keys belong in KMS/HSM or the user's wallet — never in your code. This is the non-negotiable rule of the whole space.
• AI routing is unaffected. Blockchain is a settlement layer, not an AI provider — keep Claude (primary) / OpenAI (structured) routing as-is. Where they meet: an agent can read chain state to answer "did this payment land?" but should never hold a signing key.
• M-Pesa stays the last mile. Don't pitch crypto as a replacement for M-Pesa to Kenyan users — pitch USDC as the borderless settlement rail behind an M-Pesa cash-out. Daraja handles the touchpoint; the chain handles the clearing.
• Mobile-first & low-bandwidth. Prefer viem over ethers/web3.js for bundle size on 2G/3G, lazy-load wallet-connect UI, and proxy reads server-side so the phone isn't hammering an RPC endpoint.
• Reconciliation is a first-class job, exactly like the M-Pesa pattern: persist both legs (tx hash + CheckoutRequestID), dedupe, reconcile out of band, and only mark "settled" after on-chain finality and the M-Pesa B2C result.