@terrariumlabs/core 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrariumlabs/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A complete EVM chain inside the page, presented to your dapp as a wallet. revm in WebAssembly, real receipts, byte-identical to Anvil.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "access": "public"
   },
   "bin": {
-    "terrarium": "./bin/terrarium.mjs"
+    "terrarium": "bin/terrarium.mjs"
   },
   "exports": {
     ".": "./src/engine.js",
@@ -60,7 +60,7 @@
     "@ethereumjs/util": "^10.1.3",
     "@ethereumjs/mpt": "^10.1.3",
     "@ethereumjs/rlp": "^10.0.0",
-    "@terrariumlabs/evm": "^0.3.0"
+    "@terrariumlabs/evm": "^0.4.0"
   },
   "peerDependencies": {
     "viem": "^2.0.0",

package/src/devbar.ts

@@ -1,9 +1,13 @@
 // devbar.ts — the dev overlay. Plain DOM, own styles, talks to the chain only through provider.request(), so it works
-// on top of any dapp (React or not) and never touches the dapp's code.
+// on top of any dapp (React or not) and never touches the dapp's code. Two parts: the bar (controls) and the transaction
+// explorer, a panel above it listing every transaction with its receipt, decoded call, events and revert reason
+// (`terrarium_transactions`: the scenario runtime decodes with the scenario's `abis` and names addresses with `labels`).
 type Provider = { request(a: { method: string; params?: unknown[] }): Promise<any> };
 
+const HIDDEN_KEY = 'terrarium:devbar-hidden';
 const CSS = `
 #terrarium-devbar { position: fixed; left: 0; right: 0; bottom: 0; z-index: 2147483000; display: flex; align-items: center; gap: 8px; flex-wrap: wrap; padding: 10px 24px; background: #14231b; color: #dfe9e3; font: 13px/1.4 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif; font-variant-numeric: tabular-nums; }
+#terrarium-devbar[hidden], #terrarium-explorer[hidden], #terrarium-devbar-show[hidden] { display: none; }
 #terrarium-devbar .tag { background: #e8c547; color: #14231b; font-weight: 700; padding: 2px 8px; border-radius: 6px; }
 #terrarium-devbar .muted { color: rgba(223, 233, 227, 0.7); }
 #terrarium-devbar .muted b { color: #fff; font-weight: 600; }
@@ -13,8 +17,45 @@ const CSS = `
 #terrarium-devbar button.on { background: #1f6f5c; border-color: #1f6f5c; }
 #terrarium-devbar button.armed { background: #7a3b2a; border-color: #b3452c; }
 #terrarium-devbar button.danger { border-color: rgba(255,140,110,0.4); color: #ffb5a0; }
+#terrarium-devbar button.quiet { background: transparent; border-color: transparent; color: rgba(223,233,227,0.7); }
+#terrarium-devbar-show { position: fixed; right: 12px; bottom: 12px; z-index: 2147483000; width: 36px; height: 36px; border-radius: 50%; border: 1px solid rgba(255,255,255,0.2); background: #14231b; color: #e8c547; font: 16px/1 ui-sans-serif, system-ui, sans-serif; cursor: pointer; box-shadow: 0 2px 8px rgba(0,0,0,0.35); }
+#terrarium-explorer { position: fixed; left: 0; right: 0; z-index: 2147483000; max-height: 60vh; overflow: auto; background: #0f1a14; color: #dfe9e3; border-top: 1px solid rgba(255,255,255,0.12); font: 12px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-variant-numeric: tabular-nums; }
+#terrarium-explorer .head { display: flex; align-items: center; gap: 12px; padding: 8px 24px; font: 13px ui-sans-serif, system-ui, sans-serif; color: rgba(223,233,227,0.8); position: sticky; top: 0; background: #0f1a14; border-bottom: 1px solid rgba(255,255,255,0.08); }
+#terrarium-explorer .head b { color: #fff; }
+#terrarium-explorer table { width: 100%; border-collapse: collapse; }
+#terrarium-explorer th { text-align: left; font-weight: 600; color: rgba(223,233,227,0.6); padding: 6px 12px; border-bottom: 1px solid rgba(255,255,255,0.08); white-space: nowrap; }
+#terrarium-explorer th:first-child, #terrarium-explorer td:first-child { padding-left: 24px; }
+#terrarium-explorer td { padding: 6px 12px; border-bottom: 1px solid rgba(255,255,255,0.05); white-space: nowrap; vertical-align: top; }
+#terrarium-explorer tr.tx { cursor: pointer; }
+#terrarium-explorer tr.tx:hover td { background: rgba(255,255,255,0.04); }
+#terrarium-explorer tr.tx.open td { background: rgba(255,255,255,0.06); border-bottom-color: transparent; }
+#terrarium-explorer .ok { color: #7fd3a8; } #terrarium-explorer .bad { color: #ff9c80; } #terrarium-explorer .wait { color: #e8c547; }
+#terrarium-explorer .hash, #terrarium-explorer .addr { color: #9ecbff; }
+#terrarium-explorer .name { color: #e8c547; }
+#terrarium-explorer .dim { color: rgba(223,233,227,0.55); }
+#terrarium-explorer .detail td { padding: 10px 24px 14px 48px; white-space: normal; background: rgba(0,0,0,0.25); }
+#terrarium-explorer dl { display: grid; grid-template-columns: max-content 1fr; gap: 3px 16px; margin: 0; }
+#terrarium-explorer dt { color: rgba(223,233,227,0.6); } #terrarium-explorer dd { margin: 0; word-break: break-all; }
+#terrarium-explorer .events { margin: 10px 0 0; padding: 0; list-style: none; }
+#terrarium-explorer .events li { padding: 6px 0 6px 10px; border-left: 2px solid rgba(232,197,71,0.5); margin-bottom: 4px; word-break: break-all; }
+#terrarium-explorer .args { color: #dfe9e3; }
+#terrarium-explorer .empty { padding: 24px; text-align: center; color: rgba(223,233,227,0.55); font: 13px ui-sans-serif, system-ui, sans-serif; }
 `;
 
+const esc = (s: unknown) => String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+const short = (h: string) => (h && h.length > 14 ? `${h.slice(0, 8)}…${h.slice(-6)}` : h);
+const num = (hex: string | null | undefined) => (hex ? BigInt(hex).toString() : '');
+/** wei (hex) as ETH with up to 6 decimals, trailing zeros trimmed */
+export const formatEth = (hex: string | null | undefined) => {
+  if (!hex) return '0';
+  const wei = BigInt(hex), whole = wei / 10n ** 18n, frac = (wei % 10n ** 18n).toString().padStart(18, '0').slice(0, 6).replace(/0+$/, '');
+  return frac ? `${whole}.${frac}` : whole.toString();
+};
+/** wei (hex) as gwei with up to 3 decimals */
+const formatGwei = (hex: string | null | undefined) => { if (!hex) return '0'; const wei = BigInt(hex), whole = wei / 10n ** 9n, frac = (wei % 10n ** 9n).toString().padStart(9, '0').slice(0, 3).replace(/0+$/, ''); return frac ? `${whole}.${frac}` : whole.toString(); };
+const fmtArgs = (args: any): string => Array.isArray(args) ? args.map(fmtArgs).join(', ') : args && typeof args === 'object' ? Object.entries(args).map(([k, v]) => `${k}: ${fmtArgs(v)}`).join(', ') : String(args);
+const time = (hex: string | null) => (hex ? new Date(Number(BigInt(hex)) * 1000).toLocaleTimeString() : '');
+
 export function mountDevBar(provider: Provider) {
   if (document.getElementById('terrarium-devbar')) return;
   const rpc = (method: string, params: unknown[] = []) => provider.request({ method, params });
@@ -43,15 +84,77 @@ export function mountDevBar(provider: Provider) {
   const bReset = btn('Reset pond', 'reset', 'Wipe the chain and redeploy everything', async () => { await rpc('terrarium_reset'); location.reload(); });
   bReset.classList.add('danger');
 
+  // ---- the transaction explorer -----------------------------------------------------------------------------------
+  const panel = el(`<section id="terrarium-explorer" data-testid="explorer" hidden></section>`);
+  const open = new Set<string>();   // expanded rows, by hash, kept across refreshes
+  let lastRender = '';
+  const bTxs = btn('Transactions', 'txs', 'Every transaction on this chain, like a block explorer: receipt, decoded call, events, revert reason', async () => {
+    panel.hidden = !panel.hidden; bTxs.classList.toggle('on', !panel.hidden); lastRender = '';
+    if (!panel.hidden) await refreshTxs();
+  });
+  const place = () => { panel.style.bottom = `${bar.offsetHeight}px`; };
+  const statusCell = (s: string) => s === 'success' ? '<span class="ok" title="success">✓</span>' : s === 'pending' ? '<span class="wait" title="pending">⏳</span>' : `<span class="bad" title="${s}">✗</span>`;
+  const who = (labels: Record<string, string>, a: string | null) => a ? `<span class="addr" title="${a}">${esc(labels[a.toLowerCase()] ?? short(a))}</span>` : '<span class="dim">contract creation</span>';
+  const render = (data: { total: number; labels: Record<string, string>; transactions: any[] }) => {
+    const key = JSON.stringify([data.total, data.transactions.map((t) => [t.hash, t.status]), [...open]]);
+    if (key === lastRender) return; lastRender = key;
+    const L = data.labels ?? {};
+    const rows = data.transactions.map((t) => {
+      const method = t.method ? (t.method.name ? `<span class="name">${esc(t.method.name)}</span>` : `<span class="dim">${esc(t.method.selector)}</span>`) : '<span class="dim">transfer</span>';
+      const isOpen = open.has(t.hash);
+      const detail = !isOpen ? '' : `<tr class="detail" data-testid="tx-detail"><td colspan="10"><dl>
+        <dt>hash</dt><dd class="hash">${esc(t.hash)}</dd>
+        <dt>status</dt><dd>${esc(t.status)}${t.status === 'reverted' || t.status === 'dropped' ? ` <span class="bad">· ${t.revert ? esc(t.revert.name) + '(' + esc(fmtArgs(t.revert.args)) + ')' : esc(t.error ?? '')}</span>` : ''}</dd>
+        <dt>block</dt><dd>${t.receipt ? `${num(t.receipt.blockNumber)} · ${esc(time(t.timestamp))} · index ${num(t.receipt.transactionIndex)}` : 'pending'}</dd>
+        <dt>from</dt><dd>${who(L, t.from)} <span class="dim">${esc(t.from)}</span></dd>
+        <dt>to</dt><dd>${t.to ? `${who(L, t.to)} <span class="dim">${esc(t.to)}</span>` : `<span class="dim">created</span> ${esc(t.receipt?.contractAddress ?? '')}`}</dd>
+        <dt>value</dt><dd>${formatEth(t.value)} ETH</dd>
+        <dt>nonce</dt><dd>${num(t.nonce)}</dd>
+        <dt>gas</dt><dd>${t.receipt ? `${num(t.receipt.gasUsed)} used` : ''} of ${num(t.gas)} limit${t.receipt ? ` · ${esc(formatGwei(t.receipt.effectiveGasPrice))} gwei/gas · fee ${esc(formatEth('0x' + (BigInt(t.receipt.gasUsed) * BigInt(t.receipt.effectiveGasPrice)).toString(16)))} ETH` : ''}</dd>
+        <dt>input</dt><dd>${t.method?.name ? `<span class="name">${esc(t.method.name)}</span>(<span class="args">${esc(fmtArgs(t.method.args))}</span>)<br>` : ''}<span class="dim">${esc(t.input === '0x' ? '0x (no data)' : t.input)}</span></dd>
+        ${t.revertData && t.revertData !== '0x' ? `<dt>revert data</dt><dd class="dim">${esc(t.revertData)}</dd>` : ''}
+      </dl>
+      ${t.logs?.length ? `<ul class="events" data-testid="tx-events">${t.logs.map((l: any) => `<li><span class="dim">#${num(l.logIndex)}</span> ${who(L, l.address)} ${l.decoded ? `<span class="name">${esc(l.decoded.name)}</span>(<span class="args">${esc(fmtArgs(l.decoded.args))}</span>)` : `<span class="dim">topics ${l.topics.map(esc).join(' ')}<br>data ${esc(l.data)}</span>`}</li>`).join('')}</ul>` : `<div class="dim" style="margin-top:8px">no events</div>`}
+      </td></tr>`;
+      return `<tr class="tx${isOpen ? ' open' : ''}" data-testid="tx-row" data-hash="${t.hash}" data-status="${t.status}">
+        <td>${statusCell(t.status)}</td><td>${t.receipt ? num(t.receipt.blockNumber) : '<span class="dim">pending</span>'}</td><td class="dim">${esc(time(t.timestamp))}</td>
+        <td class="hash" title="${t.hash}">${short(t.hash)}</td><td>${method}</td><td>${who(L, t.from)}</td><td>${who(L, t.to)}</td>
+        <td>${formatEth(t.value)} ETH</td><td class="dim">${t.receipt ? num(t.receipt.gasUsed) : ''}</td><td class="dim">${t.logs?.length ? `${t.logs.length} event${t.logs.length === 1 ? '' : 's'}` : ''}</td></tr>${detail}`;
+    }).join('');
+    panel.innerHTML = `<div class="head"><b>Transactions</b> <span>${data.total} on this chain, newest first${data.total > data.transactions.length ? ` (showing ${data.transactions.length})` : ''}</span><span class="spacer" style="flex:1"></span><span class="dim">click a row for the receipt, the decoded call and the events</span></div>`
+      + (rows ? `<table><thead><tr><th></th><th>block</th><th>time</th><th>hash</th><th>method</th><th>from</th><th>to</th><th>value</th><th>gas used</th><th>events</th></tr></thead><tbody>${rows}</tbody></table>` : `<div class="empty">No transactions yet. Do something in the dapp and it appears here.</div>`);
+    place();
+  };
+  panel.addEventListener('click', (e) => {
+    const row = (e.target as HTMLElement).closest<HTMLElement>('tr.tx'); if (!row) return;
+    const h = row.dataset.hash!; open.has(h) ? open.delete(h) : open.add(h); lastRender = ''; refreshTxs();
+  });
+  const refreshTxs = async () => { const data = await rpc('terrarium_transactions', [{ limit: 200 }]).catch(() => null); if (data) render(data); };
+
+  // ---- hide / show --------------------------------------------------------------------------------------------------
+  const pill = el(`<button id="terrarium-devbar-show" data-testid="show" title="Show the Terrarium dev bar" hidden>🌱</button>`);
+  const remember = (hidden: boolean) => { try { hidden ? localStorage.setItem(HIDDEN_KEY, '1') : localStorage.removeItem(HIDDEN_KEY); } catch {} };
+  const setHidden = (hidden: boolean) => {
+    bar.hidden = hidden; pill.hidden = !hidden;
+    if (hidden) { panel.hidden = true; bTxs.classList.remove('on'); }
+    document.body.style.paddingBottom = hidden ? '' : '64px';
+    remember(hidden);
+  };
+  const bHide = btn('Hide', 'hide', 'Hide the dev bar (the chain keeps running); the leaf at the bottom right brings it back', () => setHidden(true));
+  bHide.classList.add('quiet');
+  pill.onclick = () => setHidden(false);
+
   const controls = el('<span class="controls" style="display:contents"></span>'); let controlsKey = '';
   bar.append(el('<span class="tag">Terrarium</span>'), info, el('<span class="spacer"></span>'), controls,
     btn('Mine a block', 'mine', 'Mine one empty block', () => rpc('evm_mine')),
     btn('+1 hour', 'plus-hour', 'Move the chain clock forward one hour', async () => { await rpc('evm_increaseTime', [3600]); await rpc('evm_mine'); }),
-    bMining, bSnap, bActors, bReject, bLatency, bLag, bReset);
-  document.body.append(bar);
-  document.body.style.paddingBottom = '64px';
+    bMining, bSnap, bActors, bReject, bLatency, bLag, bTxs, bReset, bHide, panel);
+  document.body.append(bar, pill);
+  let startHidden = false; try { startHidden = localStorage.getItem(HIDDEN_KEY) === '1'; } catch {}
+  setHidden(startHidden);
 
   const refresh = async () => {
+    if (!document.getElementById('terrarium-devbar')) return;   // unmounted: stop polling
     const s = await rpc('terrarium_status').catch(() => null); if (!s) return;
     info.querySelector('[data-f=chain]')!.textContent = String(s.chainId);
     info.querySelector('[data-f=block]')!.textContent = String(parseInt(s.block, 16));
@@ -64,6 +167,14 @@ export function mountDevBar(provider: Provider) {
     bReject.textContent = s.wallet.rejectNext > 0 ? `Reject next tx · armed (${s.wallet.rejectNext})` : 'Reject next tx'; bReject.classList.toggle('armed', s.wallet.rejectNext > 0);
     bLatency.textContent = s.wallet.latencyMs ? `Wallet: ${s.wallet.latencyMs / 1000}s delay` : 'Wallet: instant'; bLatency.classList.toggle('on', !!s.wallet.latencyMs);
     bLag.textContent = s.wallet.receiptLagMs ? `Receipts: ${s.wallet.receiptLagMs / 1000}s late` : 'Receipts: instant'; bLag.classList.toggle('on', !!s.wallet.receiptLagMs);
+    if (!panel.hidden) await refreshTxs();
   };
-  refresh(); setInterval(refresh, 500);
+  refresh(); const timer = setInterval(() => { if (document.getElementById('terrarium-devbar')) refresh(); else clearInterval(timer); }, 500);
+}
+
+/** Remove the dev bar, its explorer and the show pill; restore the page's bottom padding. Idempotent. */
+export function unmountDevBar() {
+  document.getElementById('terrarium-devbar')?.remove();
+  document.getElementById('terrarium-devbar-show')?.remove();
+  document.body?.style.removeProperty('padding-bottom');
 }

package/src/engine.js

@@ -364,11 +364,12 @@ export async function createTerrarium(opts = {}) {
           r = await exec({ tx: entry.tx, block, flags: { blockGasUsed: cumulative } });
         } catch (e) { // invalid tx (nonce too low, insufficient funds...): a node would drop it silently and the dapp
           // would wait for a receipt forever. Record a failed receipt instead so waiters resolve and the reason is visible.
-          const t = txs.get(entry.hash); t.error = String(e.message);
+          const t = txs.get(entry.hash); t.error = String(e.message); t.dropped = true;
           receipts.push({ transactionHash: entry.hash, transactionIndex: hex(idx), from: entry.from, to: entry.rpc.to, cumulativeGasUsed: hex(cumulative), gasUsed: '0x0', effectiveGasPrice: hex(baseFee), contractAddress: null, logs: [], logsBloom: '0x' + '00'.repeat(256), status: '0x0', type: '0x2', droppedReason: t.error });
           hashes.push(entry.hash); sealTxs.push(entry.tx); sealReceipts.push({ status: 0, cumulativeBlockGasUsed: cumulative, bitvector: new Uint8Array(256), logs: [] }); continue;
         }
         cumulative += r.gasUsed;
+        if (!r.success) { const t = txs.get(entry.hash); t.error = r.error ?? 'execution reverted'; t.revertData = bytesToHex(r.returnValue); }
         if (globalThis.process?.env?.TERRARIUM_DEBUG && !r.success) console.log('[tx reverted]', entry.hash, r.error, bytesToHex(r.returnValue), 'gasUsed', r.gasUsed, 'gasLimit', entry.tx.gasLimit);
         const bloom = bloomOf(r.logs);
         const logs = r.logs.map(([addr, topics, data]) => ({ address: bytesToHex(addr), topics: topics.map(bytesToHex), data: bytesToHex(data), blockNumber: hex(header.number), transactionHash: entry.hash, transactionIndex: hex(idx), logIndex: hex(logIndex++), removed: false }));
@@ -447,6 +448,19 @@ export async function createTerrarium(opts = {}) {
     return hi;
   }
 
+  /** Transactions newest first, as an explorer lists them: the RPC tx merged with its receipt, a `status` word, the
+   *  revert reason and data of a failed one, and the block timestamp. Pending (interval mining) come first. */
+  function listTransactions({ limit = 50, before } = {}) {
+    const all = [...txs.values()].reverse().map((t) => {
+      const mined = !!t.receipt, n = mined ? hexToBigInt(t.receipt.blockNumber) : null;
+      const b = mined ? blocks.find((b) => BigInt(b.number) === n) : null;
+      const status = !mined ? 'pending' : t.receipt.status === '0x1' ? 'success' : t.dropped ? 'dropped' : 'reverted';
+      return { ...t.rpc, status, receipt: t.receipt, timestamp: b ? hex(b.timestamp) : null, error: t.error ?? null, revertData: t.revertData ?? null };
+    });
+    const from = before ? all.findIndex((t) => t.hash === before) + 1 : 0;
+    return { total: all.length, transactions: all.slice(from, from + Math.max(0, limit)) };
+  }
+
   // ---- RPC formatting ----------------------------------------------------------------------------
   function rpcBlock(b, full) {
     const transactions = full ? b.transactions.map((h) => txs.get(h).rpc) : b.transactions;
@@ -540,6 +554,7 @@ export async function createTerrarium(opts = {}) {
         case 'eth_sendRawTransaction': { const tx = createTxFromRLP(hexToBytes(params[0]), { common }); return submit(tx, tx.getSenderAddress().toString()); }
         case 'eth_getTransactionReceipt': { const t = txs.get(params[0]); if (!t?.receipt) return null; if (walletKnobs.receiptLagMs > 0 && Date.now() - (t.minedAt ?? 0) < walletKnobs.receiptLagMs) return null; return t.receipt; }
         case 'eth_getTransactionByHash': return txs.get(params[0])?.rpc ?? null;
+        case 'terrarium_transactions': return listTransactions(params[0] ?? {});
         case 'eth_getLogs': return getLogs(params[0] ?? {});
         case 'eth_newFilter': filters.set(hex(nextFilterId), { type: 'logs', f: params[0] ?? {}, cursor: latest().number + 1n }); return hex(nextFilterId++);
         case 'eth_newBlockFilter': filters.set(hex(nextFilterId), { type: 'blocks', cursor: latest().number + 1n }); return hex(nextFilterId++);
@@ -706,7 +721,7 @@ export async function createTerrarium(opts = {}) {
     const remote = sm.remote ? { accounts: Object.fromEntries([...sm.remote.accounts].map(([a, acct]) => [a, acct ? { nonce: hex(acct.nonce), balance: hex(acct.balance), codeHash: bytesToHex(acct.codeHash) } : null])), code: Object.fromEntries([...sm.remote.code].map(([a, c]) => [a, bytesToHex(c)])), storage: Object.fromEntries([...sm.remote.storage].map(([k, v]) => [k, bytesToHex(v)])) } : undefined;
     return { version: 1, chainId, savedAt: Date.now(), state: { accounts: accountsOut, code: codeOut, storage: storageOut }, remote,
       // tx bodies: only the most recent blocks' worth (like a pruned node), and without their logs (rebuilt from block logs on load)
-      chain: { blocks: blocks.map(serBlock), txs: Object.fromEntries([...txs].filter(([, t]) => !t.receipt || hexToBigInt(t.receipt.blockNumber) >= keepFrom).map(([h, t]) => [h, { rpc: t.rpc, receipt: t.receipt ? { ...t.receipt, logs: undefined } : null, error: t.error }])), timeOffset: hex(timeOffset), baseFee: hex(baseFee), mining, impersonated: [...impersonated], dealtSlots: Object.fromEntries(dealtSlots) },
+      chain: { blocks: blocks.map(serBlock), txs: Object.fromEntries([...txs].filter(([, t]) => !t.receipt || hexToBigInt(t.receipt.blockNumber) >= keepFrom).map(([h, t]) => [h, { rpc: t.rpc, receipt: t.receipt ? { ...t.receipt, logs: undefined } : null, error: t.error, revertData: t.revertData, dropped: t.dropped }])), timeOffset: hex(timeOffset), baseFee: hex(baseFee), mining, impersonated: [...impersonated], dealtSlots: Object.fromEntries(dealtSlots) },
       journal: { entries: journal, timestamps: blocks.slice(1).map((b) => hex(b.timestamp)) } };
   }
   async function seedState({ accounts: accs = {}, code = {}, storage = {} }) {
@@ -763,6 +778,8 @@ export async function createTerrarium(opts = {}) {
     dumpState: () => exclusive(dumpState), loadState: (d) => exclusive(() => loadState(d)), replayJournal: (j) => exclusive(() => replayJournal(j)),
     get journal() { return journal.slice(); }, flush: () => { clearTimeout(persistTimer); return persister ? exclusive(async () => persister.setItem(persistKey, JSON.stringify(await dumpState()))) : Promise.resolve(); },
     get blockNumber() { return latest().number; },
+    /** transactions newest first ({ total, transactions }): tx + receipt + status word + revert reason/data + block timestamp */
+    transactions: (o) => listTransactions(o),
     /** React to on-chain events with scripted actors (keepers, oracles, other users, bridges...). */
     onLog(filter, handler) { const l = { filter, handler }; logListeners.push(l); return () => logListeners.splice(logListeners.indexOf(l), 1); },
     /** Cheat: send a tx "from" any address without keys (impersonation), e.g. to simulate another user. */

package/src/inject.ts

@@ -2,7 +2,7 @@
 // wallet (so the dapp's own connect modal lists "Terrarium Wallet") and mount the dev bar. Nothing here is imported by
 // the dapp; this is the analogue of a browser extension's injected script.
 import { createWorkerProvider } from './bridge.ts';
-import { mountDevBar } from './devbar.ts';
+import { mountDevBar, unmountDevBar } from './devbar.ts';
 import { installHttpInterceptor, type WireRoute } from './http.ts';
 
 const ICON = 'data:image/svg+xml,' + encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#1F6F5C"/><path d="M6 25.5c2-6 5.5-8.5 10-8.5s8 2.5 10 8.5" fill="none" stroke="#E8C547" stroke-width="2.5" stroke-linecap="round"/><path d="M16 17.5V9" stroke="#E8C547" stroke-width="2.5" stroke-linecap="round"/><path d="M16 12c0-4.5 3-7 7-7 0 4.5-3 7-7 7Z M16 14.5c0-4.5-3-7-7-7 0 4.5 3 7 7 7Z" fill="#E8C547"/></svg>');
@@ -38,7 +38,6 @@ export function stopTerrarium() {
   window.removeEventListener('eip6963:requestProvider', current.announce);
   current.worker.terminate();
   current = null;
-  document.getElementById('terrarium-devbar')?.remove();
-  document.body?.style.removeProperty('padding-bottom');
+  unmountDevBar();
   delete (window as any).terrarium;
 }

package/src/scenario.ts

@@ -6,7 +6,7 @@
 //     actors: [{ every: 5000, run: (ctx) => ... }, { on: { address, topics }, run: (ctx, log) => ... }],
 //     status: (ctx) => ({ addresses: ctx.state }),
 //   });
-import type { Account, Address, Chain, Hex, PublicClient, TransactionReceipt, Transport, WalletClient } from 'viem';
+import type { Abi, Account, Address, Chain, Hex, PublicClient, TransactionReceipt, Transport, WalletClient } from 'viem';
 import type { HttpRoute } from './http.ts';
 export { reply } from './http.ts';
 export type { HttpRoute, HttpRequest, HttpReply, GraphqlQuery, GraphqlResolver } from './http.ts';
@@ -89,6 +89,12 @@ export interface ScenarioConfig {
    *  intercepted for matching URLs, the handler runs here in the Worker with `ctx`, everything else goes to the network.
    *  http: [{ match: 'https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2', graphql: { swaps: (ctx, q) => … } }] */
   http?: HttpRoute[];
+  /** ABIs used to decode calls, events and revert reasons in `terrarium_transactions` (the dev bar's transaction explorer);
+   *  anything they do not cover is shown raw (selector, topics, data) */
+  abis?: Abi[];
+  /** names for addresses in the explorer (`{ [address]: 'Uniswap V2 Router' }`), or a function of ctx for addresses only
+   *  known after setup. The sim's accounts are labelled `Account #i` unless you name them */
+  labels?: Record<string, string> | ((ctx: ScenarioContext) => Record<string, string>);
 }
 
 export function defineScenario(config: ScenarioConfig): ScenarioConfig { return config; }

package/src/worker-runtime.ts

@@ -1,6 +1,6 @@
 // worker-runtime.ts — runs a scenario inside the Worker: boot the chain, run setup(), wire the actors, expose the
 // generic terrarium_* controls, and serve the provider to the page over postMessage.
-import { createPublicClient, createWalletClient, custom, defineChain, toHex, type Address, type Hex } from 'viem';
+import { createPublicClient, createWalletClient, custom, defineChain, decodeErrorResult, decodeEventLog, decodeFunctionData, toHex, type Abi, type Address, type Hex } from 'viem';
 // @ts-ignore — the engine is plain ESM JavaScript
 import { createTerrarium, indexedDBStorage } from './engine.js';
 import { serveProvider } from './bridge.ts';
@@ -61,6 +61,28 @@ export async function runScenario(config: ScenarioConfig) {
   // ---- generic controls, reachable through the provider like any RPC method -----------------------------------
   sim.addMethod('terrarium_actors', async (on?: boolean) => { await actors.toggle(on ?? !actors.enabled); return actors.enabled; });
   sim.addMethod('terrarium_status', async () => ({ chainId, engine: sim.engine, block: toHex(sim.blockNumber), accounts: ctx.accounts, actors: actors.enabled, actorsLabel: config.actorsLabel ?? 'Actors', hasActors: (config.actors?.length ?? 0) > 0, wallet: { ...sim.wallet }, controls: config.controls ?? [], restoredFromPersistence: sim.restoredFromPersistence, localBlocks: Number(sim.blockNumber) - (config.fork ? config.fork.blockNumber + 1 : 0), http: { routes: httpRoutes.length, hits: httpHits }, fork: config.fork ? { blockNumber: config.fork.blockNumber, offline: !!config.fork.offline, misses: sim.offlineMisses.length } : null, ...(await config.status?.(ctx)) }));
+  // ---- the transaction explorer: the engine's list, decoded with the scenario's ABIs and labelled -------------------
+  const abi = (config.abis ?? []).flat() as Abi;
+  const labelsOf = () => {
+    const out: Record<string, string> = {};
+    ctx.accounts.forEach((a, i) => { out[a.toLowerCase()] = `Account #${i}`; });
+    const own = typeof config.labels === 'function' ? config.labels(ctx) : config.labels ?? {};
+    for (const [a, name] of Object.entries(own)) if (a) out[a.toLowerCase()] = name;
+    return out;
+  };
+  const plain = (v: any): any => typeof v === 'bigint' ? v.toString() : Array.isArray(v) ? v.map(plain) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, plain(x)])) : v;
+  const attempt = <T,>(fn: () => T): T | null => { try { return fn(); } catch { return null; } };
+  sim.addMethod('terrarium_transactions', (opts?: { limit?: number; before?: string }) => {
+    const { total, transactions } = sim.transactions(opts ?? {});
+    const labels = labelsOf();
+    return { total, labels, transactions: transactions.map((t: any) => {
+      const call = t.to && t.input && t.input.length >= 10 && abi.length ? attempt(() => decodeFunctionData({ abi, data: t.input })) : null;
+      const method = !t.to ? { name: 'create', args: [] } : call ? { name: call.functionName, args: plain(call.args ?? []) } : t.input && t.input.length >= 10 ? { name: null, selector: t.input.slice(0, 10) } : null;
+      const revert = t.status === 'reverted' && t.revertData && t.revertData !== '0x' ? attempt(() => { const d = decodeErrorResult({ abi, data: t.revertData }); return { name: d.errorName, args: plain(d.args ?? []) }; }) : null;
+      const logs = (t.receipt?.logs ?? []).map((l: any) => { const d = abi.length ? attempt(() => decodeEventLog({ abi, data: l.data, topics: l.topics })) : null; return { ...l, decoded: d ? { name: d.eventName, args: plain(d.args ?? {}) } : null }; });
+      return { ...t, method, revert, logs };
+    }) };
+  });
   sim.addMethod('terrarium_reset', async () => { await actors.toggle(false); sim.stop(); await storage?.clear(); return true; });
   for (const [name, fn] of Object.entries(config.methods ?? {})) sim.addMethod(name, (...args: any[]) => fn(ctx, ...args));