javascript-solid-server 0.0.101 → 0.0.103

package/README.md

@@ -1162,7 +1162,7 @@ npm run benchmark
 npm test
 ```
 
-Currently passing: **279 tests** (including 27 conformance tests)
+Currently passing: **289 tests** (including 27 conformance tests)
 
 ### Conformance Test Harness (CTH)
 

package/bin/jss.js

@@ -85,6 +85,8 @@ program
   .option('--pay-cost <n>', 'Cost per request in satoshis (default: 1)', parseInt)
   .option('--pay-mempool-url <url>', 'Mempool API URL for deposit verification')
   .option('--pay-address <addr>', 'Address for receiving deposits')
+  .option('--pay-token <ticker>', 'Token to sell (enables primary market)')
+  .option('--pay-rate <n>', 'Sats per token for primary market (default: 1)', parseInt)
   .option('--mongo', 'Enable MongoDB-backed /db/ route')
   .option('--no-mongo', 'Disable MongoDB-backed /db/ route')
   .option('--mongo-url <url>', 'MongoDB connection URL (default: mongodb://localhost:27017)')
@@ -155,6 +157,8 @@ program
         payCost: config.payCost,
         payMempoolUrl: config.payMempoolUrl,
         payAddress: config.payAddress,
+        payToken: config.payToken,
+        payRate: config.payRate,
         mongo: config.mongo,
         mongoUrl: config.mongoUrl,
         mongoDatabase: config.mongoDatabase,
@@ -193,7 +197,10 @@ program
           }
           console.log('     Do not expose to the internet!');
         }
-        if (config.pay) console.log(`  Pay: ${config.payCost} sat/req (402 enabled)`);
+        if (config.pay) {
+          console.log(`  Pay: ${config.payCost} sat/req (402 enabled)`);
+          if (config.payToken) console.log(`  Token: ${config.payToken} @ ${config.payRate} sat/token`);
+        }
         if (config.mongo) console.log(`  MongoDB: ${config.mongoUrl} (${config.mongoDatabase})`);
         if (config.readOnly) console.log('  Read-only: enabled (PUT/DELETE/PATCH disabled)');
         console.log('\n  Press Ctrl+C to stop\n');
@@ -477,6 +484,128 @@ quotaCmd
     }
   });
 
+/**
+ * Token command - manage MRC20 tokens
+ */
+const tokenCmd = program
+  .command('token')
+  .description('Manage MRC20 tokens anchored to Bitcoin');
+
+tokenCmd
+  .command('mint')
+  .description('Create a new MRC20 token')
+  .requiredOption('-t, --ticker <ticker>', 'Token ticker symbol')
+  .requiredOption('-s, --supply <n>', 'Total supply', parseInt)
+  .requiredOption('-v, --voucher <txo>', 'Funded TXO URI (txo:btc:txid:vout?amount=N&key=hex)')
+  .option('-n, --name <name>', 'Token name (defaults to ticker)')
+  .option('-r, --root <path>', 'Data directory')
+  .option('--mempool-url <url>', 'Mempool API URL', 'https://mempool.space/testnet4')
+  .option('--network <net>', 'Bitcoin network (testnet4 or mainnet)', 'testnet4')
+  .action(async (options) => {
+    try {
+      if (options.root) process.env.DATA_ROOT = path.resolve(options.root);
+      const { mintToken } = await import('../src/token.js');
+      console.log(`\nMinting ${options.supply} ${options.ticker}...`);
+      const result = await mintToken({
+        ticker: options.ticker,
+        name: options.name,
+        supply: options.supply,
+        voucher: options.voucher,
+        mempoolUrl: options.mempoolUrl,
+        network: options.network
+      });
+      console.log(`\nToken minted!`);
+      console.log(`  Ticker:  ${options.ticker}`);
+      console.log(`  Supply:  ${options.supply}`);
+      console.log(`  Issuer:  ${result.trail.pubkeyBase}`);
+      console.log(`  TX:      ${result.txid}`);
+      console.log(`  Address: ${result.address}`);
+      console.log('');
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+tokenCmd
+  .command('transfer')
+  .description('Transfer tokens to an address')
+  .requiredOption('-t, --ticker <ticker>', 'Token ticker symbol')
+  .requiredOption('--to <address>', 'Recipient address (pubkey hex)')
+  .requiredOption('-a, --amount <n>', 'Amount to transfer', parseInt)
+  .option('-r, --root <path>', 'Data directory')
+  .option('--mempool-url <url>', 'Mempool API URL', 'https://mempool.space/testnet4')
+  .action(async (options) => {
+    try {
+      if (options.root) process.env.DATA_ROOT = path.resolve(options.root);
+      const { transferToken } = await import('../src/token.js');
+      console.log(`\nTransferring ${options.amount} ${options.ticker} to ${options.to.slice(0, 16)}...`);
+      const result = await transferToken({
+        ticker: options.ticker,
+        to: options.to,
+        amount: options.amount,
+        mempoolUrl: options.mempoolUrl
+      });
+      console.log(`\nTransfer complete!`);
+      console.log(`  TX:      ${result.txid}`);
+      console.log(`  Address: ${result.address}`);
+      console.log(`  Balance: ${JSON.stringify(result.trail.states[result.trail.states.length - 1].balances)}`);
+      console.log('');
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+tokenCmd
+  .command('info [ticker]')
+  .description('Show token info (or list all tokens)')
+  .option('-r, --root <path>', 'Data directory')
+  .action(async (ticker, options) => {
+    try {
+      if (options.root) process.env.DATA_ROOT = path.resolve(options.root);
+      const { tokenInfo, listTrails } = await import('../src/token.js');
+
+      if (!ticker) {
+        // List all tokens
+        const trails = await listTrails();
+        if (trails.length === 0) {
+          console.log('\nNo tokens found.\n');
+          return;
+        }
+        console.log('\n  TICKER   SUPPLY   SEQ   SATS       CREATED');
+        console.log('  ' + '-'.repeat(55));
+        for (const t of trails) {
+          const state = t.states[t.states.length - 1];
+          console.log(`  ${t.ticker.padEnd(8)} ${String(t.supply).padEnd(8)} ${String(state.seq).padEnd(5)} ${String(t.currentAmount).padEnd(10)} ${t.dateCreated.split('T')[0]}`);
+        }
+        console.log('');
+        return;
+      }
+
+      const info = await tokenInfo(ticker);
+      console.log(`\n  ${info.ticker} — ${info.name}`);
+      console.log('  ' + '-'.repeat(40));
+      console.log(`  Supply:    ${info.supply}`);
+      console.log(`  Seq:       ${info.seq}`);
+      console.log(`  Issuer:    ${info.pubkeyBase}`);
+      console.log(`  Network:   ${info.network}`);
+      console.log(`  TX:        ${info.currentTxid}`);
+      console.log(`  Address:   ${info.currentAddress}`);
+      console.log(`  UTXO sats: ${info.currentAmount}`);
+      console.log(`  Created:   ${info.dateCreated}`);
+      console.log('  Balances:');
+      for (const [addr, bal] of Object.entries(info.balances)) {
+        const label = addr === info.pubkeyBase ? `${addr.slice(0, 16)}... (issuer)` : `${addr.slice(0, 16)}...`;
+        console.log(`    ${label}: ${bal}`);
+      }
+      console.log('');
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
 /**
  * Helper: Prompt for input
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.101",
+  "version": "0.0.103",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",

package/src/config.js

@@ -88,6 +88,8 @@ export const defaults = {
   payCost: 1,
   payMempoolUrl: 'https://mempool.space/testnet4',
   payAddress: null,
+  payToken: null,
+  payRate: 1,
 
   // MongoDB-backed /db/ route
   mongo: false,
@@ -148,6 +150,8 @@ const envMap = {
   JSS_PAY_COST: 'payCost',
   JSS_PAY_MEMPOOL_URL: 'payMempoolUrl',
   JSS_PAY_ADDRESS: 'payAddress',
+  JSS_PAY_TOKEN: 'payToken',
+  JSS_PAY_RATE: 'payRate',
   JSS_MONGO: 'mongo',
   JSS_MONGO_URL: 'mongoUrl',
   JSS_MONGO_DATABASE: 'mongoDatabase',
@@ -177,7 +181,7 @@ function parseEnvValue(value, key) {
   if (value.toLowerCase() === 'false') return false;
 
   // Numeric values for known numeric keys
-  if ((key === 'port' || key === 'nostrMaxEvents' || key === 'payCost') && !isNaN(value)) {
+  if ((key === 'port' || key === 'nostrMaxEvents' || key === 'payCost' || key === 'payRate') && !isNaN(value)) {
     return parseInt(value, 10);
   }
 
@@ -315,7 +319,10 @@ export function printConfig(config) {
   console.log(`  Subdomains:    ${config.subdomains ? (config.baseDomain || 'enabled') : 'disabled'}`);
   console.log(`  Mashlib:       ${config.mashlibModule ? `module (${config.mashlibModule})` : config.mashlibCdn ? `CDN v${config.mashlibVersion}` : config.mashlib ? 'local' : 'disabled'}`);
   console.log(`  SolidOS UI:    ${config.solidosUi ? 'enabled' : 'disabled'}`);
-  if (config.pay) console.log(`  Pay:           ${config.payCost} sat/req`);
+  if (config.pay) {
+    console.log(`  Pay:           ${config.payCost} sat/req`);
+    if (config.payToken) console.log(`  Token:         ${config.payToken} @ ${config.payRate} sat/token`);
+  }
   if (config.mongo) console.log(`  MongoDB:       ${config.mongoUrl} (${config.mongoDatabase})`);
   console.log('─'.repeat(40));
 }

package/src/handlers/pay.js

@@ -21,10 +21,36 @@
 
 import { getNostrPubkey, pubkeyToDidNostr } from '../auth/nostr.js';
 import { readLedger, writeLedger, getBalance, credit, debit } from '../webledger.js';
-import { verifyMrc20Deposit } from '../mrc20.js';
+import { verifyMrc20Deposit, verifyMrc20Anchor, jcs, sha256Hex } from '../mrc20.js';
+import { loadTrail, transferToken } from '../token.js';
+import fs from 'fs-extra';
+import path from 'path';
 
 const DEFAULT_COST = 1; // satoshis per request
 
+// --- Replay protection ---
+const replayFile = () => path.join(process.env.DATA_ROOT || './data', '.well-known/webledgers/replay.json');
+
+async function loadReplaySet() {
+  try {
+    const data = await fs.readFile(replayFile(), 'utf8');
+    return new Set(JSON.parse(data));
+  } catch { return new Set(); }
+}
+
+async function saveReplaySet(set) {
+  await fs.ensureDir(path.dirname(replayFile()));
+  await fs.writeFile(replayFile(), JSON.stringify([...set]));
+}
+
+async function checkAndRecordState(stateHash) {
+  const seen = await loadReplaySet();
+  if (seen.has(stateHash)) return false; // replay!
+  seen.add(stateHash);
+  await saveReplaySet(seen);
+  return true;
+}
+
 // --- Deposit verification via mempool API ---
 
 async function verifySatsDeposit(txoUri, mempoolUrl) {
@@ -88,11 +114,11 @@ function parseDepositBody(body) {
 function classifyDepositObject(obj) {
   // Explicit type field
   if (obj.type === 'mrc20' && obj.state && obj.prevState) {
-    return { type: 'mrc20', state: obj.state, prevState: obj.prevState };
+    return { type: 'mrc20', state: obj.state, prevState: obj.prevState, anchor: obj.anchor };
   }
   // Auto-detect: if it has state + prevState with MRC20 profile
   if (obj.state?.profile === 'mono.mrc20.v0.1' && obj.prevState) {
-    return { type: 'mrc20', state: obj.state, prevState: obj.prevState };
+    return { type: 'mrc20', state: obj.state, prevState: obj.prevState, anchor: obj.anchor };
   }
   // Fall back to TXO URI in .txo field
   if (obj.txo) {
@@ -122,6 +148,8 @@ export function createPayHandler(options = {}) {
   const cost = options.cost ?? DEFAULT_COST;
   const mempoolUrl = options.mempoolUrl ?? 'https://mempool.space/testnet4';
   const payAddress = options.payAddress ?? null;
+  const payToken = options.payToken ?? null;
+  const payRate = options.payRate ?? 1;
 
   return async function payHandler(request, reply) {
     const url = request.url.split('?')[0];
@@ -160,11 +188,34 @@ export function createPayHandler(options = {}) {
           });
         }
 
-        const result = verifyMrc20Deposit({
-          state: deposit.state,
-          prevState: deposit.prevState,
-          toAddress: payAddress
-        });
+        // Replay protection: reject duplicate state hashes
+        const stateHash = jcs(deposit.state);
+        const isNew = await checkAndRecordState(stateHash);
+        if (!isNew) {
+          return reply.code(400).send({ error: 'Replay: this state has already been used for a deposit' });
+        }
+
+        let result;
+
+        // Anchor verification (if anchor data provided)
+        if (deposit.anchor && deposit.anchor.pubkey && deposit.anchor.stateStrings) {
+          result = await verifyMrc20Anchor({
+            state: deposit.state,
+            prevState: deposit.prevState,
+            toAddress: payAddress,
+            pubkey: deposit.anchor.pubkey,
+            stateStrings: deposit.anchor.stateStrings,
+            mempoolUrl,
+            network: deposit.anchor.network || 'testnet4'
+          });
+        } else {
+          // Fallback: verify chain integrity only (no anchor check)
+          result = verifyMrc20Deposit({
+            state: deposit.state,
+            prevState: deposit.prevState,
+            toAddress: payAddress
+          });
+        }
 
         if (!result.valid) {
           return reply.code(400).send({ error: result.error });
@@ -180,7 +231,8 @@ export function createPayHandler(options = {}) {
           deposited: result.amount,
           ticker: result.ticker,
           balance: newBalance,
-          unit: 'token'
+          unit: 'token',
+          ...(result.address ? { anchor: result.address } : {})
         });
       }
 
@@ -213,6 +265,104 @@ export function createPayHandler(options = {}) {
       });
     }
 
+    // --- POST /pay/.buy — primary market: buy tokens with sats ---
+    if (url === '/pay/.buy' && request.method === 'POST') {
+      const pubkey = await getNostrPubkey(request);
+      if (!pubkey) {
+        return reply.code(401).send({ error: 'NIP-98 authentication required' });
+      }
+
+      if (!payToken) {
+        return reply.code(400).send({ error: 'Primary market not configured (no --pay-token set)' });
+      }
+
+      // Parse buy request
+      let body = request.body;
+      if (Buffer.isBuffer(body)) body = JSON.parse(body.toString('utf8'));
+      if (typeof body === 'string') body = JSON.parse(body);
+
+      const ticker = body?.ticker || payToken;
+      if (ticker !== payToken) {
+        return reply.code(400).send({ error: `This pod only sells ${payToken}` });
+      }
+
+      // Calculate amount and cost
+      let tokenAmount, satCost;
+      if (body?.amount) {
+        tokenAmount = Math.floor(body.amount);
+        satCost = tokenAmount * payRate;
+      } else if (body?.sats) {
+        satCost = Math.floor(body.sats);
+        tokenAmount = Math.floor(satCost / payRate);
+      } else {
+        return reply.code(400).send({
+          error: 'Specify amount (tokens to buy) or sats (sats to spend)',
+          rate: payRate,
+          unit: 'sat/token'
+        });
+      }
+
+      if (tokenAmount <= 0) {
+        return reply.code(400).send({ error: 'Amount must be positive' });
+      }
+
+      // Check sat balance
+      const didUri = pubkeyToDidNostr(pubkey);
+      const ledger = await readLedger();
+      const balance = getBalance(ledger, didUri);
+      if (balance < satCost) {
+        return reply.code(402).send({
+          error: 'Insufficient sat balance',
+          balance,
+          cost: satCost,
+          rate: payRate,
+          deposit: '/pay/.deposit'
+        });
+      }
+
+      // Load token trail
+      const trail = await loadTrail(ticker);
+      if (!trail) {
+        return reply.code(500).send({ error: `Token ${ticker} not minted on this pod` });
+      }
+
+      // Transfer tokens to buyer
+      let result;
+      try {
+        result = await transferToken({
+          ticker,
+          to: pubkey,
+          amount: tokenAmount,
+          mempoolUrl
+        });
+      } catch (err) {
+        return reply.code(500).send({ error: `Transfer failed: ${err.message}` });
+      }
+
+      // Debit sats from buyer
+      debit(ledger, didUri, satCost);
+      await writeLedger(ledger);
+
+      return reply.send({
+        bought: tokenAmount,
+        ticker,
+        cost: satCost,
+        rate: payRate,
+        balance: getBalance(ledger, didUri),
+        unit: 'sat',
+        txid: result.txid,
+        proof: {
+          state: result.state,
+          prevState: result.prevState,
+          anchor: {
+            pubkey: result.trail.pubkeyBase,
+            stateStrings: result.trail.stateStrings,
+            network: result.trail.network
+          }
+        }
+      });
+    }
+
     // --- GET/HEAD /pay/* — paid resource access ---
     if (request.method === 'GET' || request.method === 'HEAD') {
       const pubkey = await getNostrPubkey(request);

package/src/mrc20.js

@@ -13,10 +13,16 @@
  */
 
 import crypto from 'crypto';
+import { secp256k1 } from '@noble/curves/secp256k1';
 
 const MRC20_PROFILE = 'mono.mrc20.v0.1';
 const TRANSFER_OP = 'urn:mono:op:transfer';
 
+// --- BIP-341 key chaining constants ---
+const SECP_N = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141');
+const BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const BECH32M = 0x2bc830a3;
+
 /**
  * JSON Canonicalization Scheme (RFC 8785)
  * Produces deterministic JSON — sorted keys, no whitespace.
@@ -144,3 +150,186 @@ export function verifyMrc20Deposit(params) {
     ticker: state.ticker || 'UNKNOWN'
   };
 }
+
+// --- BIP-341 key chaining (blocktrails anchor verification) ---
+
+function sha256Bytes(data) {
+  const buf = data instanceof Uint8Array ? Buffer.from(data) : Buffer.from(data, 'utf8');
+  return new Uint8Array(crypto.createHash('sha256').update(buf).digest());
+}
+
+function concatBytes(...arrays) {
+  const total = arrays.reduce((s, a) => s + a.length, 0);
+  const result = new Uint8Array(total);
+  let off = 0;
+  for (const a of arrays) { result.set(a, off); off += a.length; }
+  return result;
+}
+
+function bytesToBigInt(bytes) {
+  let r = 0n;
+  for (const b of bytes) r = (r << 8n) | BigInt(b);
+  return r;
+}
+
+function hexToU8(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
+}
+
+function bytesToHex(bytes) {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+function taggedHash(tag, ...msgs) {
+  const tagHash = sha256Bytes(Buffer.from(tag, 'utf8'));
+  return sha256Bytes(concatBytes(tagHash, tagHash, ...msgs));
+}
+
+function btScalar(pubkeyCompressed, state) {
+  const xOnly = pubkeyCompressed.slice(1);
+  const stateBytes = typeof state === 'string' ? Buffer.from(state, 'utf8') : state;
+  const sh = sha256Bytes(stateBytes);
+  return bytesToBigInt(taggedHash('TapTweak', xOnly, sh)) % SECP_N;
+}
+
+function btDeriveChainedPubkey(pubkeyBase, states) {
+  let P = secp256k1.ProjectivePoint.fromHex(bytesToHex(pubkeyBase));
+  let cur = pubkeyBase;
+  for (const s of states) {
+    const t = btScalar(cur, s);
+    P = P.add(secp256k1.ProjectivePoint.BASE.multiply(t));
+    cur = new Uint8Array(P.toRawBytes(true));
+  }
+  return cur;
+}
+
+// --- Bech32m encoding ---
+
+function convertBits(data, from, to, pad) {
+  let acc = 0, bits = 0;
+  const ret = [], maxv = (1 << to) - 1;
+  for (const v of data) {
+    acc = (acc << from) | v;
+    bits += from;
+    while (bits >= to) { bits -= to; ret.push((acc >> bits) & maxv); }
+  }
+  if (pad && bits > 0) ret.push((acc << (to - bits)) & maxv);
+  return ret;
+}
+
+function hrpExpand(hrp) {
+  const r = [];
+  for (const c of hrp) r.push(c.charCodeAt(0) >> 5);
+  r.push(0);
+  for (const c of hrp) r.push(c.charCodeAt(0) & 31);
+  return r;
+}
+
+function polymod(values) {
+  const GEN = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+  let chk = 1;
+  for (const v of values) {
+    const b = chk >> 25;
+    chk = ((chk & 0x1ffffff) << 5) ^ v;
+    for (let i = 0; i < 5; i++) if ((b >> i) & 1) chk ^= GEN[i];
+  }
+  return chk;
+}
+
+function bech32mEncode(hrp, version, program) {
+  const conv = convertBits(program, 8, 5, true);
+  const values = [version, ...conv];
+  const enc = [...hrpExpand(hrp), ...values, 0, 0, 0, 0, 0, 0];
+  const mod = polymod(enc) ^ BECH32M;
+  const checksum = [0, 1, 2, 3, 4, 5].map(i => (mod >> (5 * (5 - i))) & 31);
+  let result = hrp + '1';
+  for (const v of [...values, ...checksum]) result += BECH32_CHARSET[v];
+  return result;
+}
+
+/**
+ * Derive the taproot address for a state chain
+ * @param {string} pubkeyHex - Issuer's compressed pubkey (66-char hex)
+ * @param {string[]} states - JCS-encoded state strings
+ * @param {string} [network='testnet4'] - 'testnet4' or 'mainnet'
+ * @returns {string} Bech32m taproot address
+ */
+export function btAddress(pubkeyHex, states, network = 'testnet4') {
+  const pubkeyBase = hexToU8(pubkeyHex);
+  const P = btDeriveChainedPubkey(pubkeyBase, states);
+  const xOnly = P.slice(1);
+  const hrp = network === 'mainnet' ? 'bc' : 'tb';
+  return bech32mEncode(hrp, 1, xOnly);
+}
+
+/**
+ * Verify that an MRC20 state is anchored to a Bitcoin UTXO
+ * @param {object} params
+ * @param {object} params.state - Current state with transfer ops
+ * @param {object} params.prevState - Previous state (chain verification)
+ * @param {string} params.toAddress - Pod's address for transfer verification
+ * @param {string} params.pubkey - Issuer's compressed pubkey (66-char hex)
+ * @param {string[]} params.stateStrings - All JCS state strings (genesis to current)
+ * @param {string} [params.mempoolUrl] - Mempool API base URL
+ * @param {string} [params.network] - 'testnet4' or 'mainnet'
+ * @returns {Promise<{valid: boolean, amount?: number, ticker?: string, address?: string, error?: string}>}
+ */
+export async function verifyMrc20Anchor(params) {
+  const {
+    state, prevState, toAddress, pubkey, stateStrings,
+    mempoolUrl = 'https://mempool.space/testnet4',
+    network = 'testnet4'
+  } = params;
+
+  // 1. Standard deposit verification (chain integrity + transfers)
+  const depositCheck = verifyMrc20Deposit({ state, prevState, toAddress });
+  if (!depositCheck.valid) return depositCheck;
+
+  // 2. Verify stateStrings is provided and non-empty
+  if (!Array.isArray(stateStrings) || stateStrings.length === 0) {
+    return { valid: false, amount: 0, error: 'stateStrings required for anchor verification' };
+  }
+
+  // 3. Verify pubkey is provided
+  if (!pubkey || typeof pubkey !== 'string' || pubkey.length !== 66) {
+    return { valid: false, amount: 0, error: 'pubkey must be a 66-char compressed pubkey hex' };
+  }
+
+  // 4. Verify the last stateString matches the current state
+  const currentJcs = jcs(state);
+  const lastStateString = stateStrings[stateStrings.length - 1];
+  if (currentJcs !== lastStateString) {
+    return { valid: false, amount: 0, error: 'Last stateString does not match JCS(state)' };
+  }
+
+  // 5. Derive expected taproot address
+  let address;
+  try {
+    address = btAddress(pubkey, stateStrings, network);
+  } catch (err) {
+    return { valid: false, amount: 0, error: `Key derivation failed: ${err.message}` };
+  }
+
+  // 6. Query mempool for UTXO at derived address
+  try {
+    const resp = await fetch(`${mempoolUrl}/api/address/${address}/utxo`);
+    if (!resp.ok) {
+      return { valid: false, amount: 0, error: `Mempool API error: ${resp.status}` };
+    }
+    const utxos = await resp.json();
+    if (!Array.isArray(utxos) || utxos.length === 0) {
+      return { valid: false, amount: 0, error: `No UTXO at derived address ${address}` };
+    }
+  } catch (err) {
+    return { valid: false, amount: 0, error: `Mempool lookup failed: ${err.message}` };
+  }
+
+  return {
+    valid: true,
+    amount: depositCheck.amount,
+    ticker: depositCheck.ticker,
+    address
+  };
+}

package/src/server.js

@@ -100,6 +100,8 @@ export function createServer(options = {}) {
   const payCost = options.payCost ?? 1;
   const payMempoolUrl = options.payMempoolUrl ?? 'https://mempool.space/testnet4';
   const payAddress = options.payAddress ?? null; // Pod's MRC20 address for token deposits
+  const payToken = options.payToken ?? null; // Token ticker for primary market
+  const payRate = options.payRate ?? 1; // Sats per token
 
   // Set data root via environment variable if provided
   if (options.root) {
@@ -374,7 +376,7 @@ export function createServer(options = {}) {
 
   // HTTP 402 Payment Required handler for /pay/* routes
   if (payEnabled) {
-    fastify.addHook('preHandler', createPayHandler({ cost: payCost, mempoolUrl: payMempoolUrl, payAddress }));
+    fastify.addHook('preHandler', createPayHandler({ cost: payCost, mempoolUrl: payMempoolUrl, payAddress, payToken, payRate }));
   }
 
   // Authorization hook - check WAC permissions

package/src/token.js

@@ -0,0 +1,412 @@
+/**
+ * MRC20 Token Management
+ *
+ * Create, manage, and transfer MRC20 tokens anchored to Bitcoin via blocktrails.
+ * Uses BIP-341 key chaining to derive unique taproot addresses for each state.
+ *
+ * Trail state stored at: {DATA_ROOT}/.well-known/token/{ticker}.json
+ *
+ * References:
+ *   - Blocktrails: https://blocktrails.org/
+ *   - BIP-341: https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki
+ */
+
+import crypto from 'crypto';
+import fs from 'fs-extra';
+import path from 'path';
+import { secp256k1, schnorr } from '@noble/curves/secp256k1';
+import { jcs, sha256Hex, btAddress } from './mrc20.js';
+
+// --- Constants ---
+const SECP_N = BigInt('0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141');
+const MRC20_PROFILE = 'mono.mrc20.v0.1';
+
+// --- Byte helpers ---
+function hexToU8(hex) {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return bytes;
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+function bytesToBigInt(bytes) {
+  let r = 0n;
+  for (const b of bytes) r = (r << 8n) | BigInt(b);
+  return r;
+}
+function bigIntToBytes(n) {
+  return hexToU8(n.toString(16).padStart(64, '0'));
+}
+function concatBytes(...arrays) {
+  const total = arrays.reduce((s, a) => s + a.length, 0);
+  const result = new Uint8Array(total);
+  let off = 0;
+  for (const a of arrays) { result.set(a, off); off += a.length; }
+  return result;
+}
+
+// --- Serialization helpers ---
+function writeU32LE(val) {
+  const b = new Uint8Array(4);
+  b[0] = val & 0xff; b[1] = (val >> 8) & 0xff; b[2] = (val >> 16) & 0xff; b[3] = (val >> 24) & 0xff;
+  return b;
+}
+function writeU64LE(val) {
+  const b = new Uint8Array(8);
+  const n = BigInt(val);
+  for (let i = 0; i < 8; i++) b[i] = Number((n >> BigInt(i * 8)) & 0xffn);
+  return b;
+}
+function writeVarInt(val) {
+  if (val < 0xfd) return new Uint8Array([val]);
+  if (val <= 0xffff) return new Uint8Array([0xfd, val & 0xff, (val >> 8) & 0xff]);
+  throw new Error('VarInt too large');
+}
+function reverseTxid(txidHex) {
+  const bytes = hexToU8(txidHex);
+  bytes.reverse();
+  return bytes;
+}
+
+// --- Crypto ---
+function sha256Bytes(data) {
+  const buf = data instanceof Uint8Array ? Buffer.from(data) : Buffer.from(data, 'utf8');
+  return new Uint8Array(crypto.createHash('sha256').update(buf).digest());
+}
+function taggedHash(tag, ...msgs) {
+  const tagHash = sha256Bytes(Buffer.from(tag, 'utf8'));
+  return sha256Bytes(concatBytes(tagHash, tagHash, ...msgs));
+}
+
+// --- BIP-341 key chaining ---
+function btScalar(pubkeyCompressed, state) {
+  const xOnly = pubkeyCompressed.slice(1);
+  const stateBytes = typeof state === 'string' ? Buffer.from(state, 'utf8') : state;
+  const sh = sha256Bytes(stateBytes);
+  return bytesToBigInt(taggedHash('TapTweak', xOnly, sh)) % SECP_N;
+}
+
+function btDeriveChainedPubkey(pubkeyBase, states) {
+  let P = secp256k1.ProjectivePoint.fromHex(bytesToHex(pubkeyBase));
+  let cur = pubkeyBase;
+  for (const s of states) {
+    const t = btScalar(cur, s);
+    P = P.add(secp256k1.ProjectivePoint.BASE.multiply(t));
+    cur = new Uint8Array(P.toRawBytes(true));
+  }
+  return cur;
+}
+
+function btDeriveChainedPrivkey(privkeyBytes, states) {
+  let d = bytesToBigInt(privkeyBytes);
+  let cur = new Uint8Array(secp256k1.getPublicKey(privkeyBytes, true));
+  for (const s of states) {
+    const t = btScalar(cur, s);
+    d = (d + t) % SECP_N;
+    cur = new Uint8Array(secp256k1.ProjectivePoint.BASE.multiply(d).toRawBytes(true));
+  }
+  return bigIntToBytes(d);
+}
+
+function p2trScript(xonly) {
+  return concatBytes(new Uint8Array([0x51, 0x20]), xonly);
+}
+
+// --- Bitcoin transaction building ---
+function buildTransaction(inputs, outputs, privkeyBytes) {
+  const internalXOnly = new Uint8Array(secp256k1.getPublicKey(privkeyBytes, true)).slice(1);
+  const untweakedHex = '5120' + bytesToHex(internalXOnly);
+  const needsTweak = bytesToHex(inputs[0].scriptPubKey) !== untweakedHex;
+  let signingKey = privkeyBytes;
+  if (needsTweak) {
+    const tweak = taggedHash('TapTweak', internalXOnly);
+    const t = bytesToBigInt(tweak);
+    let d = bytesToBigInt(privkeyBytes);
+    const fullPub = secp256k1.getPublicKey(privkeyBytes, false);
+    if (fullPub[64] & 1) d = SECP_N - d;
+    signingKey = bigIntToBytes((d + t) % SECP_N);
+  }
+
+  const version = 2, locktime = 0, sequence = 0xfffffffd;
+  const serOutputs = outputs.map(o =>
+    concatBytes(writeU64LE(o.amount), writeVarInt(o.scriptPubKey.length), o.scriptPubKey)
+  );
+
+  const shaPrevouts = sha256Bytes(concatBytes(...inputs.map(i =>
+    concatBytes(reverseTxid(i.txid), writeU32LE(i.vout))
+  )));
+  const shaAmounts = sha256Bytes(concatBytes(...inputs.map(i => writeU64LE(i.amount))));
+  const shaScriptPubKeys = sha256Bytes(concatBytes(...inputs.map(i =>
+    concatBytes(writeVarInt(i.scriptPubKey.length), i.scriptPubKey)
+  )));
+  const shaSequences = sha256Bytes(concatBytes(...inputs.map(() => writeU32LE(sequence))));
+  const shaOutputs = sha256Bytes(concatBytes(...serOutputs));
+
+  const sigs = [];
+  for (let i = 0; i < inputs.length; i++) {
+    const sigMsg = concatBytes(
+      new Uint8Array([0x00, 0x00]),
+      writeU32LE(version), writeU32LE(locktime),
+      shaPrevouts, shaAmounts, shaScriptPubKeys, shaSequences, shaOutputs,
+      new Uint8Array([0x00]),
+      writeU32LE(i)
+    );
+    const sighash = taggedHash('TapSighash', sigMsg);
+    sigs.push(schnorr.sign(sighash, signingKey));
+  }
+
+  const parts = [
+    writeU32LE(version),
+    new Uint8Array([0x00, 0x01]),
+    writeVarInt(inputs.length)
+  ];
+  for (const inp of inputs) {
+    parts.push(reverseTxid(inp.txid), writeU32LE(inp.vout), new Uint8Array([0x00]), writeU32LE(sequence));
+  }
+  parts.push(writeVarInt(outputs.length));
+  for (const so of serOutputs) parts.push(so);
+  for (const sig of sigs) {
+    parts.push(new Uint8Array([0x01]), writeVarInt(sig.length), sig);
+  }
+  parts.push(writeU32LE(locktime));
+  return bytesToHex(concatBytes(...parts));
+}
+
+async function broadcastTx(rawTxHex, mempoolUrl) {
+  const res = await fetch(`${mempoolUrl}/api/tx`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'text/plain' },
+    body: rawTxHex
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Broadcast failed: ${err}`);
+  }
+  return res.text();
+}
+
+// --- Trail persistence ---
+function trailDir() {
+  return path.join(process.env.DATA_ROOT || './data', '.well-known', 'token');
+}
+
+function trailPath(ticker) {
+  return path.join(trailDir(), `${ticker.toLowerCase()}.json`);
+}
+
+export async function loadTrail(ticker) {
+  try {
+    const data = await fs.readFile(trailPath(ticker), 'utf8');
+    return JSON.parse(data);
+  } catch { return null; }
+}
+
+async function saveTrail(trail) {
+  await fs.ensureDir(trailDir());
+  await fs.writeFile(trailPath(trail.ticker), JSON.stringify(trail, null, 2));
+}
+
+export async function listTrails() {
+  try {
+    const files = await fs.readdir(trailDir());
+    const trails = [];
+    for (const f of files) {
+      if (f.endsWith('.json')) {
+        const data = await fs.readFile(path.join(trailDir(), f), 'utf8');
+        trails.push(JSON.parse(data));
+      }
+    }
+    return trails;
+  } catch { return []; }
+}
+
+// --- TXO URI parsing ---
+export function parseTxoUri(uri) {
+  // txo:btc:txid:vout?amount=N&key=hex
+  const match = uri.match(/(?:txo:btc:)?([0-9a-f]{64}):(\d+)\?amount=(\d+)&key=([0-9a-f]{64})/i);
+  if (!match) throw new Error('Invalid TXO URI format');
+  return {
+    txid: match[1],
+    vout: parseInt(match[2], 10),
+    amount: parseInt(match[3], 10),
+    privkey: match[4]
+  };
+}
+
+// --- Mint: create genesis MRC20 token ---
+export async function mintToken({ ticker, name, supply, voucher, mempoolUrl = 'https://mempool.space/testnet4', network = 'testnet4' }) {
+  const txo = parseTxoUri(voucher);
+  const privkeyBytes = hexToU8(txo.privkey);
+  const pubkeyBase = new Uint8Array(secp256k1.getPublicKey(privkeyBytes, true));
+  const pubkeyBaseHex = bytesToHex(pubkeyBase);
+
+  // Check if token already exists
+  const existing = await loadTrail(ticker);
+  if (existing) throw new Error(`Token ${ticker} already exists`);
+
+  // Create genesis MRC20 state
+  const genesisState = {
+    profile: MRC20_PROFILE,
+    prev: '0'.repeat(64),
+    seq: 0,
+    ticker,
+    name: name || ticker,
+    decimals: 0,
+    supply,
+    balances: { [pubkeyBaseHex]: supply },
+    ops: []
+  };
+  const genesisJcs = jcs(genesisState);
+
+  // Derive genesis taproot address
+  const genesisP = btDeriveChainedPubkey(pubkeyBase, [genesisJcs]);
+  const genesisXonly = genesisP.slice(1);
+  const genesisScript = p2trScript(genesisXonly);
+  const genesisAddr = btAddress(pubkeyBaseHex, [genesisJcs], network);
+
+  // Fetch voucher scriptPubKey
+  const txResp = await fetch(`${mempoolUrl}/api/tx/${txo.txid}`);
+  if (!txResp.ok) throw new Error('Could not fetch voucher transaction');
+  const txData = await txResp.json();
+  const prevOut = txData.vout?.[txo.vout];
+  if (!prevOut) throw new Error(`Voucher output ${txo.vout} not found`);
+  const scriptPubKey = hexToU8(prevOut.scriptpubkey);
+
+  // Build and broadcast genesis tx
+  const fee = 300;
+  const outputAmount = txo.amount - fee;
+  if (outputAmount <= 546) throw new Error('Voucher too small for fee');
+
+  const rawTx = buildTransaction(
+    [{ txid: txo.txid, vout: txo.vout, amount: txo.amount, scriptPubKey }],
+    [{ amount: outputAmount, scriptPubKey: genesisScript }],
+    privkeyBytes
+  );
+  const newTxid = await broadcastTx(rawTx, mempoolUrl);
+
+  // Save trail
+  const trail = {
+    ticker,
+    name: name || ticker,
+    supply,
+    privkey: txo.privkey,
+    pubkeyBase: pubkeyBaseHex,
+    states: [genesisState],
+    stateStrings: [genesisJcs],
+    currentTxid: newTxid,
+    currentVout: 0,
+    currentAmount: outputAmount,
+    network,
+    dateCreated: new Date().toISOString()
+  };
+  await saveTrail(trail);
+
+  return { trail, txid: newTxid, address: genesisAddr };
+}
+
+// --- Transfer: send tokens to an address ---
+export async function transferToken({ ticker, to, amount, mempoolUrl = 'https://mempool.space/testnet4' }) {
+  const trail = await loadTrail(ticker);
+  if (!trail) throw new Error(`Token ${ticker} not found`);
+
+  const privkeyBytes = hexToU8(trail.privkey);
+  const pubkeyBase = hexToU8(trail.pubkeyBase);
+
+  // Get current state
+  const currentState = trail.states[trail.states.length - 1];
+  const currentBalances = { ...currentState.balances };
+
+  // Check issuer balance
+  const issuerAddr = trail.pubkeyBase;
+  const issuerBalance = currentBalances[issuerAddr] || 0;
+  if (issuerBalance < amount) {
+    throw new Error(`Insufficient balance: ${issuerBalance} < ${amount}`);
+  }
+
+  // Create transfer state
+  currentBalances[issuerAddr] = issuerBalance - amount;
+  currentBalances[to] = (currentBalances[to] || 0) + amount;
+  // Remove zero balances
+  for (const [k, v] of Object.entries(currentBalances)) {
+    if (v === 0) delete currentBalances[k];
+  }
+
+  const prevJcs = trail.stateStrings[trail.stateStrings.length - 1];
+  const newState = {
+    profile: MRC20_PROFILE,
+    prev: sha256Hex(prevJcs),
+    seq: currentState.seq + 1,
+    ticker: trail.ticker,
+    name: trail.name,
+    decimals: 0,
+    supply: trail.supply,
+    balances: currentBalances,
+    ops: [{ op: 'urn:mono:op:transfer', from: issuerAddr, to, amt: amount }]
+  };
+  const newJcs = jcs(newState);
+
+  // Derive new address
+  const allStateStrings = [...trail.stateStrings, newJcs];
+  const newP = btDeriveChainedPubkey(pubkeyBase, allStateStrings);
+  const newXonly = newP.slice(1);
+  const newScript = p2trScript(newXonly);
+  const newAddr = btAddress(trail.pubkeyBase, allStateStrings, trail.network);
+
+  // Fetch current UTXO scriptPubKey
+  const txResp = await fetch(`${mempoolUrl}/api/tx/${trail.currentTxid}`);
+  if (!txResp.ok) throw new Error('Could not fetch current transaction');
+  const txData = await txResp.json();
+  const prevOut = txData.vout?.[trail.currentVout];
+  if (!prevOut) throw new Error('Current UTXO not found');
+  const scriptPubKey = hexToU8(prevOut.scriptpubkey);
+
+  // Derive chained privkey for signing
+  const chainedPriv = btDeriveChainedPrivkey(privkeyBytes, trail.stateStrings);
+
+  // Build and broadcast
+  const fee = 300;
+  const outputAmount = trail.currentAmount - fee;
+  if (outputAmount <= 546) throw new Error('Trail UTXO too small for fee');
+
+  const rawTx = buildTransaction(
+    [{ txid: trail.currentTxid, vout: trail.currentVout, amount: trail.currentAmount, scriptPubKey }],
+    [{ amount: outputAmount, scriptPubKey: newScript }],
+    chainedPriv
+  );
+  const newTxid = await broadcastTx(rawTx, mempoolUrl);
+
+  // Update trail
+  trail.states.push(newState);
+  trail.stateStrings.push(newJcs);
+  trail.currentTxid = newTxid;
+  trail.currentVout = 0;
+  trail.currentAmount = outputAmount;
+  await saveTrail(trail);
+
+  return { trail, txid: newTxid, address: newAddr, state: newState, prevState: currentState };
+}
+
+// --- Info: show token state ---
+export async function tokenInfo(ticker) {
+  const trail = await loadTrail(ticker);
+  if (!trail) throw new Error(`Token ${ticker} not found`);
+
+  const currentState = trail.states[trail.states.length - 1];
+  const currentAddr = btAddress(trail.pubkeyBase, trail.stateStrings, trail.network);
+
+  return {
+    ticker: trail.ticker,
+    name: trail.name,
+    supply: trail.supply,
+    seq: currentState.seq,
+    balances: currentState.balances,
+    pubkeyBase: trail.pubkeyBase,
+    currentTxid: trail.currentTxid,
+    currentAddress: currentAddr,
+    currentAmount: trail.currentAmount,
+    network: trail.network,
+    stateCount: trail.states.length,
+    dateCreated: trail.dateCreated
+  };
+}

package/test/mrc20.test.js

@@ -11,8 +11,11 @@ import {
   validateMrc20State,
   extractTransfersTo,
   totalTransferredTo,
-  verifyMrc20Deposit
+  verifyMrc20Deposit,
+  btAddress,
+  verifyMrc20Anchor
 } from '../src/mrc20.js';
+import { secp256k1 } from '@noble/curves/secp256k1';
 
 const PROFILE = 'mono.mrc20.v0.1';
 
@@ -234,4 +237,107 @@ describe('MRC20 Verification', () => {
       assert.strictEqual(result.amount, 150);
     });
   });
+
+  describe('btAddress', () => {
+    // Use a known keypair for deterministic tests
+    const testPriv = Buffer.alloc(32, 1); // 0x0101...01
+    const testPub = Buffer.from(secp256k1.getPublicKey(testPriv, true)).toString('hex');
+
+    it('should derive a valid testnet bech32m address', () => {
+      const addr = btAddress(testPub, ['state0'], 'testnet4');
+      assert.ok(addr.startsWith('tb1p'), `Expected tb1p prefix, got ${addr}`);
+      assert.ok(addr.length >= 62, `Address too short: ${addr.length}`);
+    });
+
+    it('should derive a valid mainnet bech32m address', () => {
+      const addr = btAddress(testPub, ['state0'], 'mainnet');
+      assert.ok(addr.startsWith('bc1p'), `Expected bc1p prefix, got ${addr}`);
+    });
+
+    it('should be deterministic', () => {
+      const a1 = btAddress(testPub, ['s1', 's2']);
+      const a2 = btAddress(testPub, ['s1', 's2']);
+      assert.strictEqual(a1, a2);
+    });
+
+    it('should produce different addresses for different states', () => {
+      const a1 = btAddress(testPub, ['state-a']);
+      const a2 = btAddress(testPub, ['state-b']);
+      assert.notStrictEqual(a1, a2);
+    });
+
+    it('should produce different addresses for different pubkeys', () => {
+      const priv2 = Buffer.alloc(32, 2);
+      const pub2 = Buffer.from(secp256k1.getPublicKey(priv2, true)).toString('hex');
+      const a1 = btAddress(testPub, ['state']);
+      const a2 = btAddress(pub2, ['state']);
+      assert.notStrictEqual(a1, a2);
+    });
+
+    it('should chain multiple states', () => {
+      const a1 = btAddress(testPub, ['s1']);
+      const a2 = btAddress(testPub, ['s1', 's2']);
+      assert.notStrictEqual(a1, a2);
+    });
+  });
+
+  describe('verifyMrc20Anchor', () => {
+    const testPriv = Buffer.alloc(32, 1);
+    const testPub = Buffer.from(secp256k1.getPublicKey(testPriv, true)).toString('hex');
+
+    it('should reject missing stateStrings', async () => {
+      const { prevState, state } = createStatePair(
+        [{ op: 'urn:mono:op:transfer', from: 'user', to: 'pod', amt: 100 }],
+        'pod'
+      );
+      const result = await verifyMrc20Anchor({
+        state, prevState, toAddress: 'pod',
+        pubkey: testPub, stateStrings: []
+      });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('stateStrings'));
+    });
+
+    it('should reject bad pubkey', async () => {
+      const { prevState, state } = createStatePair(
+        [{ op: 'urn:mono:op:transfer', from: 'user', to: 'pod', amt: 100 }],
+        'pod'
+      );
+      const result = await verifyMrc20Anchor({
+        state, prevState, toAddress: 'pod',
+        pubkey: 'short', stateStrings: [jcs(state)]
+      });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('pubkey'));
+    });
+
+    it('should reject mismatched last stateString', async () => {
+      const { prevState, state } = createStatePair(
+        [{ op: 'urn:mono:op:transfer', from: 'user', to: 'pod', amt: 100 }],
+        'pod'
+      );
+      const result = await verifyMrc20Anchor({
+        state, prevState, toAddress: 'pod',
+        pubkey: testPub, stateStrings: ['wrong-jcs']
+      });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('Last stateString'));
+    });
+
+    it('should reject when no UTXO exists (mempool returns empty)', async () => {
+      const { prevState, state } = createStatePair(
+        [{ op: 'urn:mono:op:transfer', from: 'user', to: 'pod', amt: 100 }],
+        'pod'
+      );
+      // Use a fake mempool URL that will fail
+      const result = await verifyMrc20Anchor({
+        state, prevState, toAddress: 'pod',
+        pubkey: testPub,
+        stateStrings: [jcs(prevState), jcs(state)],
+        mempoolUrl: 'http://127.0.0.1:1' // will fail to connect
+      });
+      assert.strictEqual(result.valid, false);
+      assert.ok(result.error.includes('Mempool') || result.error.includes('failed'));
+    });
+  });
 });