javascript-solid-server 0.0.102 → 0.0.104

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.102",
+  "version": "0.0.104",
   "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

@@ -5,10 +5,12 @@
  * Authentication via NIP-98. Balance tracking via Web Ledgers spec.
  *
  * Routes:
- *   GET  /pay/.balance  — check your balance
- *   POST /pay/.deposit  — deposit sats (TXO URI) or tokens (MRC20 state proof)
- *   GET  /pay/*         — paid resource access (requires balance >= cost)
- *   PUT  /pay/*         — upload resources (standard auth)
+ *   GET  /pay/.balance   — check your balance
+ *   POST /pay/.deposit   — deposit sats (TXO URI) or tokens (MRC20 state proof)
+ *   POST /pay/.buy       — buy tokens with sat balance (primary market)
+ *   POST /pay/.withdraw  — withdraw balance as tokens (portable MRC20 proof)
+ *   GET  /pay/*          — paid resource access (requires balance >= cost)
+ *   PUT  /pay/*          — upload resources (standard auth)
  *
  * Ledger: /.well-known/webledgers/webledgers.json (webledgers.org spec)
  *
@@ -21,7 +23,8 @@
 
 import { getNostrPubkey, pubkeyToDidNostr } from '../auth/nostr.js';
 import { readLedger, writeLedger, getBalance, credit, debit } from '../webledger.js';
-import { verifyMrc20Deposit, verifyMrc20Anchor, jcs } 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';
 
@@ -147,6 +150,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];
@@ -262,6 +267,200 @@ 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
+          }
+        }
+      });
+    }
+
+    // --- POST /pay/.withdraw — withdraw balance as tokens ---
+    if (url === '/pay/.withdraw' && 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: 'Withdrawal not configured (no --pay-token set)' });
+      }
+
+      // Parse withdraw request
+      let body = request.body;
+      if (Buffer.isBuffer(body)) body = JSON.parse(body.toString('utf8'));
+      if (typeof body === 'string') body = JSON.parse(body);
+
+      const didUri = pubkeyToDidNostr(pubkey);
+      const ledger = await readLedger();
+      const balance = getBalance(ledger, didUri);
+
+      // Calculate withdrawal amount
+      let satCost, tokenAmount;
+      if (body?.all) {
+        satCost = balance;
+        tokenAmount = Math.floor(balance / payRate);
+      } else if (body?.sats) {
+        satCost = Math.floor(body.sats);
+        tokenAmount = Math.floor(satCost / payRate);
+      } else if (body?.tokens) {
+        tokenAmount = Math.floor(body.tokens);
+        satCost = tokenAmount * payRate;
+      } else {
+        return reply.code(400).send({
+          error: 'Specify tokens, sats, or all: true',
+          balance,
+          rate: payRate,
+          unit: 'sat/token'
+        });
+      }
+
+      if (tokenAmount <= 0) {
+        return reply.code(400).send({ error: 'Nothing to withdraw', balance, rate: payRate });
+      }
+
+      if (balance < satCost) {
+        return reply.code(402).send({
+          error: 'Insufficient balance',
+          balance,
+          cost: satCost,
+          rate: payRate
+        });
+      }
+
+      // Load token trail
+      const trail = await loadTrail(payToken);
+      if (!trail) {
+        return reply.code(500).send({ error: `Token ${payToken} not minted on this pod` });
+      }
+
+      // Transfer tokens to user
+      let result;
+      try {
+        result = await transferToken({
+          ticker: payToken,
+          to: pubkey,
+          amount: tokenAmount,
+          mempoolUrl
+        });
+      } catch (err) {
+        return reply.code(500).send({ error: `Transfer failed: ${err.message}` });
+      }
+
+      // Debit balance
+      debit(ledger, didUri, satCost);
+      await writeLedger(ledger);
+
+      return reply.send({
+        withdrawn: tokenAmount,
+        ticker: payToken,
+        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/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
+  };
+}