Wallet v1 spec

interface Wallet {
  // Identity
  walletId: string;           // Unique identifier
  actorId: string;            // Citizen/agent ID
  publicKey: string;          // Ed25519 public key (hex)

  // Balances
  micBalance: number;         // Confirmed MIC
  ksBalance: number;          // Confirmed KS (mic × 1,000,000)
  pendingMic: number;         // Unconfirmed MIC
  pendingKs: number;          // Unconfirmed KS

  // Metadata
  createdAt: string;          // ISO 8601 timestamp
  lastUpdated: string;        // ISO 8601 timestamp
  version: number;            // Schema version
}

interface Transaction {
  id: string;                 // Transaction ID
  type: 'mint' | 'burn' | 'transfer' | 'reward';

  // Amounts
  mic: number;                // MIC amount
  ks: number;                 // KS amount

  // Parties
  from?: string;              // Sender (null for mint)
  to: string;                 // Recipient (BURN_ADDRESS for burn)

  // Context
  action: string;             // Action type (reflection, civic, etc.)
  mii?: number;               // MII score if applicable

  // Status
  status: 'pending' | 'confirmed' | 'failed';
  timestamp: string;
  signature?: string;         // Ed25519 signature
}

interface Keypair {
  publicKey: Uint8Array;      // 32 bytes
  secretKey: Uint8Array;      // 64 bytes (Ed25519)
}

async function createWallet(actorId: string): Promise<Wallet> {
  // Generate Ed25519 keypair
  const keypair = generateKeypair();

  // Create wallet
  const wallet: Wallet = {
    walletId: generateWalletId(),
    actorId,
    publicKey: toHex(keypair.publicKey),
    micBalance: 0,
    ksBalance: 0,
    pendingMic: 0,
    pendingKs: 0,
    createdAt: new Date().toISOString(),
    lastUpdated: new Date().toISOString(),
    version: 1
  };

  // Save keypair (encrypted)
  await saveKeypair(keypair, password);

  // Save wallet
  await saveWallet(wallet);

  return wallet;
}

function getBalance(wallet: Wallet): {
  confirmed: { mic: number; ks: number };
  pending: { mic: number; ks: number };
  total: { mic: number; ks: number };
} {
  return {
    confirmed: {
      mic: wallet.micBalance,
      ks: wallet.ksBalance
    },
    pending: {
      mic: wallet.pendingMic,
      ks: wallet.pendingKs
    },
    total: {
      mic: wallet.micBalance + wallet.pendingMic,
      ks: wallet.ksBalance + wallet.pendingKs
    }
  };
}

async function send(
  wallet: Wallet,
  to: string,
  ks: number
): Promise<Transaction> {
  // Validate
  if (wallet.ksBalance < ks) {
    throw new Error('Insufficient balance');
  }

  const mic = ks / KS_PER_MIC;

  // Create transaction
  const tx: Transaction = {
    id: generateTxId(),
    type: 'transfer',
    mic,
    ks,
    from: wallet.actorId,
    to,
    action: 'transfer',
    status: 'pending',
    timestamp: new Date().toISOString()
  };

  // Sign transaction
  tx.signature = await signTransaction(tx, keypair);

  // Update balance optimistically
  wallet.micBalance -= mic;
  wallet.ksBalance -= ks;
  wallet.pendingMic -= mic;
  wallet.lastUpdated = new Date().toISOString();

  // Submit to network
  await submitTransaction(tx);

  return tx;
}

async function processIncoming(
  wallet: Wallet,
  tx: Transaction
): Promise<void> {
  if (tx.to !== wallet.actorId) return;

  if (tx.status === 'confirmed') {
    wallet.micBalance += tx.mic;
    wallet.ksBalance += tx.ks;
  } else {
    wallet.pendingMic += tx.mic;
    wallet.pendingKs += tx.ks;
  }

  wallet.lastUpdated = new Date().toISOString();
  await saveWallet(wallet);
}

interface WalletExport {
  version: number;
  wallet: Wallet;
  keypair: {
    publicKey: string;    // hex
    secretKey: string;    // hex, encrypted
  };
  transactions: Transaction[];
  exportedAt: string;
}

async function exportWallet(
  wallet: Wallet,
  password: string
): Promise<WalletExport> {
  const keypair = await loadKeypair(password);

  return {
    version: 1,
    wallet,
    keypair: {
      publicKey: toHex(keypair.publicKey),
      secretKey: encrypt(toHex(keypair.secretKey), password)
    },
    transactions: await loadTransactions(),
    exportedAt: new Date().toISOString()
  };
}

function signTransaction(tx: Transaction, keypair: Keypair): string {
  const message = canonicalize(tx);
  const signature = nacl.sign.detached(
    new TextEncoder().encode(message),
    keypair.secretKey
  );
  return toHex(signature);
}

// Balance
GET /v1/mic/balance/:id
Response: { mic, ks, pending_mic, pending_ks }

// Transactions
GET /v1/mic/transactions?actor_id=X&limit=50
Response: { transactions: [...] }

// Submit transaction
POST /v1/mic/transfer
Body: { from, to, ks, signature }
Response: { transaction_id, status }

// MII score
GET /v1/mii/score/:id
Response: { mii, components, above_threshold }