openzoo 0.51.2 → 0.51.3

package/transmute/lib/deploy.js

@@ -9,8 +9,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { Keypair, PublicKey } from '@solana/web3.js';
-import { MANIFEST_PATH } from './wire.js';
+import { MANIFEST_PATH, CODE_PATH } from './wire.js';
 import { connect, deployProgram, upgradeProgram, getProgramInfo, putAsset, detectSbpfArch, pool, assetRent } from './solana.js';
+import { initSite, getSiteInfo } from './solana.js';
 import { loadWallet, rpcUrl } from './wallet.js';
 import { runCargoBuildSbf, estimateCost, formatCostTable, LAMPORTS_PER_SOL, INSTALL_HINT } from './build.js';
 import { DEFAULT_PORT } from './gateway.js';
@@ -83,6 +84,7 @@ export async function deploy(o = {}) {
   const buildInfo = readJson(path.join(zooDir, 'build.json'), {});
   const staticPlan = readJson(path.join(zooDir, 'static-plan.json'), []);
   const crateDir = path.join(zooDir, 'crate');
+  if ((buildInfo.target || manifest.target) === 'shared') return deployShared(o, { log, outDir, zooDir, manifest, buildInfo, staticPlan });
 
   const rpc = o.connection?.rpcEndpoint || rpcUrl(o.cluster);
   const cluster = clusterLabel(o.cluster);
@@ -207,3 +209,149 @@ export async function deploy(o = {}) {
 export async function assetRentSol(connection, size, contentType = '') {
   return (await assetRent(connection, size, contentType)) / LAMPORTS_PER_SOL;
 }
+
+// ---------------------------------------------------------------- shared runtime
+
+/** Load or create the site keypair: its public key is the site id (looks like a program id, costs nothing). */
+export function siteKeypairFor(zooDir, { create = true } = {}) {
+  const p = path.join(zooDir, 'site-keypair.json');
+  if (fs.existsSync(p)) return { keypair: Keypair.fromSecretKey(Uint8Array.from(readJson(p))), path: p, created: false };
+  if (!create) return null;
+  const kp = Keypair.generate();
+  fs.writeFileSync(p, JSON.stringify([...kp.secretKey]), { mode: 0o600 });
+  return { keypair: kp, path: p, created: true };
+}
+
+/**
+ * Deploy to the shared runtime: no program, only accounts — the site account,
+ * the bytecode module at /.zoo/code.bin, the static assets and the manifest,
+ * all PDAs of the runtime program namespaced by the site id.
+ */
+async function deployShared(o, { log, outDir, zooDir, manifest, buildInfo, staticPlan }) {
+  const runtime = o.runtime || process.env.OPENZOO_VM_PROGRAM || manifest.runtime || buildInfo.runtime;
+  if (!runtime) throw new Error('shared target needs the runtime program id: --runtime <id> (or OPENZOO_VM_PROGRAM)');
+  const rpc = o.connection?.rpcEndpoint || rpcUrl(o.cluster);
+  const cluster = clusterLabel(o.cluster);
+  const connection = o.connection || connect(rpc);
+  let mainnet = isMainnet(o.cluster, rpc);
+  const genesis = await genesisCluster(connection);
+  if (genesis === 'mainnet' && !mainnet) { mainnet = true; log(`note: ${rpc.replace(/\?.*$/, '')} serves mainnet (genesis hash); treating it as mainnet`); }
+  const wallet = o.wallet || loadWallet({ keypair: o.keypair });
+  const payer = wallet.keypair;
+  const codePath = buildInfo.codePath && fs.existsSync(buildInfo.codePath) ? buildInfo.codePath : path.join(zooDir, 'code.bin');
+  if (!fs.existsSync(codePath)) throw new Error(`no bytecode module at ${codePath}; run build --target shared first`);
+  const code = fs.readFileSync(codePath);
+  const siteKp = o.site ? null : siteKeypairFor(zooDir);
+  const site = o.site ? new PublicKey(o.site) : siteKp.keypair.publicKey;
+  const runtimeInfo = await getProgramInfo(connection, runtime);
+  if (!runtimeInfo.exists) throw new Error(`runtime program ${runtime} is not deployed on ${cluster}`);
+  log(`cluster ${cluster} (${rpc.replace(/\?.*$/, '')}) · payer ${payer.publicKey.toBase58()} · runtime ${new PublicKey(runtime).toBase58()} · site ${site.toBase58()}${siteKp?.created ? ' (new)' : ''}`);
+
+  // Cost: site account + code + assets + manifest, all rent-exempt accounts.
+  const manifestOut = { ...manifest, target: 'shared', runtime: new PublicKey(runtime).toBase58(), site: site.toBase58(), cluster, rpc: rpc.replace(/\?.*$/, ''), deployedAt: new Date().toISOString() };
+  const manifestBytes = Buffer.byteLength(JSON.stringify(manifestOut));
+  const items = [{ label: 'site account', bytes: 66 }, { label: `code module (${code.length.toLocaleString()} B)`, bytes: code.length + 20 }];
+  for (const f of staticPlan) items.push({ label: f.path, bytes: (f.size ?? 0) + 7 + (f.contentType || '').length });
+  items.push({ label: '/.zoo/manifest.json', bytes: manifestBytes + 40 });
+  let total = 0;
+  for (const it of items) { it.lamports = await connection.getMinimumBalanceForRentExemption(it.bytes); total += it.lamports; }
+  const fees = 5000 * (3 + staticPlan.length * 3 + Math.ceil(code.length / 900) + 4);
+  log('  item                                bytes       SOL');
+  for (const it of items) log(`  ${it.label.padEnd(34)}${String(it.bytes).padStart(8)}  ${(it.lamports / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
+  log(`  ${'rent total'.padEnd(34)}${''.padStart(8)}  ${(total / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
+  log(`  ${'+ tx fees (approx.)'.padEnd(34)}${''.padStart(8)}  ${(fees / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
+  log(`  ${'TOTAL'.padEnd(34)}${''.padStart(8)}  ${((total + fees) / LAMPORTS_PER_SOL).toFixed(4).padStart(8)}`);
+  if (mainnet && !o.yes) throw new Error('this is mainnet: pass --yes to spend the amount above');
+  const balance = await connection.getBalance(payer.publicKey);
+  if (balance < total + fees) throw new Error(`payer has ${(balance / LAMPORTS_PER_SOL).toFixed(4)} SOL, needs ~${((total + fees) / LAMPORTS_PER_SOL).toFixed(4)}`);
+
+  const t0 = Date.now();
+  const si = await initSite(connection, { authority: payer, runtime, site });
+  log(`${si.created ? 'created' : 'reusing'} site account ${si.pda.toBase58()}`);
+  const cr = await putAsset(connection, { authority: payer, programId: runtime, site, path: CODE_PATH, contentType: 'application/x-zoo-bytecode', data: code, force: o.force });
+  log(`code → ${CODE_PATH} (${cr.pda.toBase58()}, ${code.length.toLocaleString()} B${cr.skipped ? ', unchanged' : ''})`);
+  let uploaded = 0, skipped = 0, failed = 0;
+  const failures = [];
+  if (!o.skipAssets) {
+    const files = staticPlan.filter((f) => f.file || f.path);
+    let done = 0;
+    await pool(files, async (f) => {
+      try {
+        const data = fs.readFileSync(f.file);
+        const r = await putAsset(connection, { authority: payer, programId: runtime, site, path: f.path, contentType: f.contentType || 'application/octet-stream', data, force: o.force });
+        if (r.skipped) skipped++; else uploaded++;
+        log(`[${++done}/${files.length}] ${f.path} ${r.skipped ? 'unchanged' : `${data.length.toLocaleString()} B in ${r.txs} tx`}`);
+      } catch (e) { failed++; failures.push({ path: f.path, error: String(e?.message || e) }); log(`[${++done}/${files.length}] ${f.path} FAILED: ${e?.message || e}`); }
+    }, { concurrency: o.concurrency ? Number(o.concurrency) : 4 });
+    log(`assets: ${uploaded} uploaded, ${skipped} unchanged, ${failed} failed`);
+  }
+  const mr = await putAsset(connection, { authority: payer, programId: runtime, site, path: MANIFEST_PATH, contentType: MANIFEST_CONTENT_TYPE, data: Buffer.from(JSON.stringify(manifestOut)), force: true });
+  log(`manifest → ${MANIFEST_PATH} (${mr.pda.toBase58()}, ${manifestBytes.toLocaleString()} B) in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+  const out = { target: 'shared', site: site.toBase58(), programId: site.toBase58(), runtime: new PublicKey(runtime).toBase58(), sitePda: si.pda.toBase58(), manifestPda: mr.pda.toBase58(), assets: { uploaded, skipped, failed }, cluster, rpc, deployedAt: manifestOut.deployedAt, failures, url: `${process.env.OPENZOO_HUB_URL || 'https://sites.openzoo.fun'}/s/${site.toBase58()}` };
+  writeJson(path.join(zooDir, 'deploy.json'), out);
+  log(`\nserve it:  openzoo-transmute serve ${site.toBase58()} --runtime ${new PublicKey(runtime).toBase58()} --cluster ${cluster}`);
+  log(`or open    ${out.url}`);
+  return out;
+}
+
+// ---------------------------------------------------------------- runtime program
+
+const HERE_DEPLOY = path.dirname(new URL(import.meta.url).pathname);
+export const PREBUILT_DIR = path.resolve(HERE_DEPLOY, '..', 'prebuilt');
+export const RUNTIME_CRATE = path.resolve(HERE_DEPLOY, '..', 'runtime', 'zoo-vm');
+
+/** The zoo-vm .so for an SBPF arch: prebuilt (v0 = mainnet) or built from runtime/zoo-vm. */
+export async function runtimeSoFor(arch, { log = console.log, so } = {}) {
+  if (so) return { soPath: path.resolve(so), source: 'given' };
+  const pre = path.join(PREBUILT_DIR, `zoo_vm.${arch}.so`);
+  if (fs.existsSync(pre)) return { soPath: pre, source: 'prebuilt' };
+  if (!fs.existsSync(path.join(RUNTIME_CRATE, 'Cargo.toml'))) throw new Error(`no prebuilt zoo-vm for ${arch} (${pre}) and no runtime/zoo-vm crate to build it from`);
+  const r = await runCargoBuildSbf(RUNTIME_CRATE, { arch, outDir: path.join(RUNTIME_CRATE, 'target', 'deploy-' + arch), log });
+  if (!r.ok) throw new Error(r.missing ? `no prebuilt zoo-vm for ${arch}; install the toolchain to build it: ${INSTALL_HINT}` : `zoo-vm build failed: ${r.error}`);
+  return { soPath: r.soPath, source: 'built' };
+}
+
+/**
+ * Deploy (or upgrade) the shared runtime program once per cluster. Sites then
+ * cost only their accounts. Keypair kept at `programKeypair` (default
+ * ./zoo-vm-keypair.json) so a redeploy upgrades in place.
+ */
+export async function deployRuntime(o = {}) {
+  const log = o.log ?? console.log;
+  const rpc = rpcUrl(o.cluster);
+  const cluster = clusterLabel(o.cluster);
+  const connection = o.connection || connect(rpc);
+  let mainnet = isMainnet(o.cluster, rpc);
+  if ((await genesisCluster(connection)) === 'mainnet') mainnet = true;
+  const wallet = o.wallet || loadWallet({ keypair: o.keypair });
+  const payer = wallet.keypair;
+  const arch = await detectSbpfArch(connection);
+  const { soPath, source } = await runtimeSoFor(arch, { log, so: o.so });
+  const so = fs.readFileSync(soPath);
+  const kpPath = path.resolve(o.programKeypair || 'zoo-vm-keypair.json');
+  let programKeypair;
+  if (fs.existsSync(kpPath)) programKeypair = Keypair.fromSecretKey(Uint8Array.from(readJson(kpPath)));
+  else { programKeypair = Keypair.generate(); fs.writeFileSync(kpPath, JSON.stringify([...programKeypair.secretKey]), { mode: 0o600 }); log(`new runtime keypair → ${kpPath} (keep it: redeploys upgrade in place)`); }
+  const programId = programKeypair.publicKey;
+  const info = await getProgramInfo(connection, programId);
+  const upgrade = info.exists;
+  const est = await estimateCost({ staticFiles: [], soSize: so.length, manifestBytes: 0, connection, upgrade });
+  est.items = est.items.filter((i) => i.kind !== 'asset');
+  est.lamports = est.items.filter((i) => !i.transient).reduce((n, i) => n + i.lamports, 0); est.sol = est.lamports / LAMPORTS_PER_SOL;
+  est.totalLamports = est.lamports + est.transientLamports + est.feeLamports; est.totalSol = est.totalLamports / LAMPORTS_PER_SOL;
+  log(`cluster ${cluster} (${rpc.replace(/\?.*$/, '')}) · payer ${payer.publicKey.toBase58()} · runtime ${programId.toBase58()} (${upgrade ? 'upgrade' : 'new'}) · ${path.basename(soPath)} ${so.length.toLocaleString()} B ${arch} (${source})`);
+  log(formatCostTable(est));
+  const bal = await connection.getBalance(payer.publicKey);
+  if (bal < est.totalLamports) throw new Error(`payer has ${(bal / LAMPORTS_PER_SOL).toFixed(4)} SOL, needs ≈ ${est.totalSol.toFixed(4)} SOL`);
+  if (mainnet && !o.yes) throw new Error(`refusing to spend ≈ ${est.totalSol.toFixed(4)} SOL on mainnet without --yes`);
+  let done = 0; const total = Math.ceil(so.length / 900);
+  const onProgress = (n) => { done += 1; if (done % 25 === 0 || done === total) log(`  wrote ${Math.min(done, total)}/${total} chunks`); };
+  const t0 = Date.now();
+  const r = upgrade
+    ? await upgradeProgram(connection, { payer, programId, so, onProgress })
+    : await deployProgram(connection, { payer, programKeypair, so, onProgress, headroom: o.headroom ? Number(o.headroom) : 1 });
+  log(`${upgrade ? 'upgraded' : 'deployed'} runtime ${programId.toBase58()} in ${((Date.now() - t0) / 1000).toFixed(1)}s (${r.signature})`);
+  log(`\nsites now deploy against it:  openzoo-transmute build <dir> --target shared && openzoo-transmute deploy <dir> --runtime ${programId.toBase58()} --cluster ${cluster}`);
+  log(`hub: OPENZOO_VM_PROGRAM=${programId.toBase58()}`);
+  return { programId: programId.toBase58(), signature: r.signature, upgrade, arch, soPath, cluster, rpc, keypairPath: kpPath };
+}

package/transmute/lib/gateway.js

@@ -15,8 +15,8 @@
 import http from 'node:http';
 import { createHash } from 'node:crypto';
 import { PublicKey, Transaction, TransactionInstruction, ComputeBudgetProgram, SystemProgram } from '@solana/web3.js';
-import { FORWARDED_HEADERS, MANIFEST_PATH, assetPda, decodeAsset, encodeInvoke } from './wire.js';
-import { connect, invoke as chainInvoke, readManifest, getProgramInfo, DEFAULT_CU, DEFAULT_HEAP } from './solana.js';
+import { FORWARDED_HEADERS, MANIFEST_PATH, assetPda, assetPdaFor, decodeAsset, encodeInvoke } from './wire.js';
+import { connect, invoke as chainInvoke, readManifest, getProgramInfo, getSiteInfo, DEFAULT_CU, DEFAULT_HEAP } from './solana.js';
 import { rpcUrl } from './wallet.js';
 
 export const DEFAULT_PORT = 4402;
@@ -46,9 +46,14 @@ const HTML_CT = 'text/html; charset=utf-8';
 export function makeState(o) {
   const programId = new PublicKey(o.programId);
   const cluster = o.cluster || process.env.OPENZOO_CLUSTER || 'localnet';
+  // Shared runtime: `programId` is the runtime program and `site` the site id;
+  // every PDA is namespaced by it and the invoke carries it.
+  const site = o.site ? new PublicKey(o.site) : null;
   const state = {
     programId,
     programIdStr: programId.toBase58(),
+    site,
+    siteStr: site ? site.toBase58() : null,
     cluster,
     rpc: o.connection?.rpcEndpoint || safeRpcUrl(cluster),
     connection: o.connection ?? null,
@@ -103,7 +108,7 @@ export async function getAsset(state, path) {
   const cached = state.assets.get(path);
   if (cached && now - cached.at < state.cacheTtlMs) return cached;
   if (!state.connection) return cached ?? { missing: true, at: now };
-  const [pda] = assetPda(state.programId, path);
+  const [pda] = assetPdaFor(state.programId, state.site, path);
   let entry;
   try {
     const info = await state.connection.getAccountInfo(pda);
@@ -384,7 +389,7 @@ async function serveFunction(state, hit, req, pathname, query, extraHeaders = {}
   state.stats.invokes++;
   let r;
   try {
-    r = await state.invoke({ programId: state.programId, payer, event, mutate });
+    r = await state.invoke({ programId: state.programId, site: state.site, payer, event, mutate });
   } catch (e) {
     const msg = String(e?.message || e);
     if (/signing keypair is required/i.test(msg)) return json(402, { error: 'payment required', message: msg, method, path: pathname }, { 'x-zoo-program': state.programIdStr });
@@ -424,10 +429,11 @@ export async function statusOf(state) {
   let chain = null;
   if (state.connection) {
     try {
-      const [info, slot] = await Promise.all([getProgramInfo(state.connection, state.programId), state.connection.getSlot('confirmed')]);
+      const [info, slot, siteInfo] = await Promise.all([getProgramInfo(state.connection, state.programId), state.connection.getSlot('confirmed'), state.site ? getSiteInfo(state.connection, state.programId, state.site) : null]);
       chain = {
         slot,
         program: { exists: info.exists, executable: info.executable ?? null, authority: info.authority ? info.authority.toBase58() : null, deploySlot: info.slot, maxDataLen: info.maxDataLen, programData: info.programData.toBase58() },
+        site: siteInfo ? { id: state.siteStr, exists: siteInfo.exists, authority: siteInfo.authority ? siteInfo.authority.toBase58() : null, account: siteInfo.pda.toBase58() } : null,
       };
     } catch (e) { chain = { error: String(e?.message || e) }; }
   }
@@ -660,13 +666,13 @@ function readBody(req, limit) {
  * Serve a program over HTTP. Resolves once listening.
  * @returns {Promise<{server:import('node:http').Server, port:number, url:string, state:object, close:()=>Promise<void>}>}
  */
-export async function startGateway({ programId, cluster, port = DEFAULT_PORT, host = '127.0.0.1', keypair, manifest, invoke, connection, cacheTtlMs, log = console.log, quiet = false } = {}) {
+export async function startGateway({ programId, site = null, cluster, port = DEFAULT_PORT, host = '127.0.0.1', keypair, manifest, invoke, connection, cacheTtlMs, log = console.log, quiet = false } = {}) {
   const rpc = safeRpcUrl(cluster || process.env.OPENZOO_CLUSTER || 'localnet');
   connection = connection ?? (rpc ? connect(rpc) : null);
-  const state = makeState({ programId, cluster, connection, keypair, manifest, invoke, cacheTtlMs, port, log: quiet ? () => {} : log });
+  const state = makeState({ programId, site, cluster, connection, keypair, manifest, invoke, cacheTtlMs, port, log: quiet ? () => {} : log });
   if (!manifest && connection) {
     try {
-      const m = await readManifest(connection, state.programId);
+      const m = await readManifest(connection, state.programId, state.site);
       if (m) { state.manifest = normalizeManifest(m); state.manifestAt = Date.now(); }
       else if (!quiet) log(`warning: no manifest at ${MANIFEST_PATH} for ${state.programIdStr}; routing by on-chain lookup only`);
     } catch (e) { if (!quiet) log(`warning: could not read the manifest: ${e?.message || e}`); }

package/transmute/lib/hub.js

@@ -20,7 +20,7 @@
 import http from 'node:http';
 import { PublicKey } from '@solana/web3.js';
 import { makeState, normalizeManifest, handleRequest, safeResponseHeaders, PACKET_DATA_SIZE, BODY_LIMIT } from './gateway.js';
-import { connect, readManifest } from './solana.js';
+import { connect, readManifest, getSiteInfo } from './solana.js';
 import { rpcUrl } from './wallet.js';
 import { MANIFEST_PATH } from './wire.js';
 
@@ -80,6 +80,9 @@ export function makeHub(o = {}) {
     startedAt: Date.now(),
     stats: { requests: 0, sitesLoaded: 0, writes: 0, writesRefused: 0, spentLamports: 0 },
     publicUrl: o.publicUrl || null,
+    // The shared runtime program on this cluster: ids that are site accounts
+    // under it are served as shared sites; anything else as a compiled program.
+    runtime: o.runtime || process.env.OPENZOO_VM_PROGRAM || null,
     // write governor: per-IP token bucket + a daily lamport budget for the signer
     writesPerMin: o.writesPerMin ?? Number(process.env.OPENZOO_HUB_WRITES_PER_MIN || 3),
     budgetLamports: Math.round((o.writeBudgetSol ?? Number(process.env.OPENZOO_HUB_WRITE_BUDGET_SOL || 0.05)) * 1e9),
@@ -115,9 +118,15 @@ async function siteFor(hub, programId) {
   let state;
   if (hub.makeSite) state = await hub.makeSite(programId);
   else {
-    state = makeState({ programId, cluster: hub.cluster, connection: hub.connection, keypair: hub.keypair, log: hub.log, cacheTtlMs: hub.manifestTtlMs });
+    let shared = false;
+    if (hub.runtime) {
+      try { shared = (await getSiteInfo(hub.connection, hub.runtime, programId)).exists; } catch { /* fall through to program mode */ }
+    }
+    state = shared
+      ? makeState({ programId: hub.runtime, site: programId, cluster: hub.cluster, connection: hub.connection, keypair: hub.keypair, log: hub.log, cacheTtlMs: hub.manifestTtlMs })
+      : makeState({ programId, cluster: hub.cluster, connection: hub.connection, keypair: hub.keypair, log: hub.log, cacheTtlMs: hub.manifestTtlMs });
     try {
-      const m = await readManifest(hub.connection, state.programId);
+      const m = await readManifest(hub.connection, state.programId, state.site);
       if (m) { state.manifest = normalizeManifest(m); state.manifestAt = Date.now(); }
       else state.noManifest = true;
     } catch (e) { state.manifestError = String(e?.message || e); }
@@ -135,6 +144,7 @@ function siteSummary(id, entry) {
   const m = entry.state.manifest || {};
   return {
     programId: id,
+    mode: entry.state.site ? 'shared' : 'program',
     name: m.name || null,
     framework: m.framework || null,
     routes: (m.routes || []).length,

package/transmute/lib/solana.js

@@ -9,6 +9,8 @@ import {
   BPF_LOADER_UPGRADEABLE, ERR_KV_MISSING, encodeInvoke, parseLogs, decodeResponse, programDataPda,
   assetPda, encodeAssetInit, encodeAssetWrite, encodeAssetClose, decodeAsset, ASSET_FIXED_HEADER,
   ASSET_MAX_INITIAL, kvPda, decodeKv, MANIFEST_PATH,
+  sitePda, assetPdaFor, kvPdaFor, encodeSiteInit, encodeVmInvoke, encodeVmAssetInit, encodeVmAssetWrite, encodeVmAssetClose,
+  decodeSite, CODE_PATH,
 } from './wire.js';
 
 export const WRITE_CHUNK = 900;
@@ -158,10 +160,11 @@ export async function upgradeProgram(connection, { payer, authority = payer, pro
 
 // ---------------------------------------------------------------- assets
 
-function assetKeys(authority, programId, pda) {
+function assetKeys(authority, programId, pda, site = null) {
   return [
     { pubkey: authority.publicKey, isSigner: true, isWritable: true },
-    { pubkey: programDataPda(programId), isSigner: false, isWritable: false },
+    // proof of authority: the program's ProgramData (compiled site) or the site account (shared runtime)
+    { pubkey: site ? sitePda(programId, site)[0] : programDataPda(programId), isSigner: false, isWritable: false },
     { pubkey: pda, isSigner: false, isWritable: true },
     { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
   ];
@@ -176,55 +179,59 @@ export async function assetRent(connection, len, contentType = '') {
  * Upload one asset (create/re-init + chunked writes). Skips the upload when
  * the on-chain bytes already match.
  */
-export async function putAsset(connection, { authority, programId, path, contentType, data, onProgress, force = false }) {
+export async function putAsset(connection, { authority, programId, site = null, path, contentType, data, onProgress, force = false }) {
   const pid = new PublicKey(programId);
-  const [pda] = assetPda(pid, path);
+  const [pda] = assetPdaFor(pid, site, path);
+  const initData = site ? encodeVmAssetInit(site, path, data.length, contentType) : encodeAssetInit(path, data.length, contentType);
+  // The shared-runtime write carries the 32-byte site id; keep the tx ≤ 1232 B.
+  const chunk = site ? WRITE_CHUNK - 32 : WRITE_CHUNK;
+  const writeData = (off) => site ? encodeVmAssetWrite(site, path, off, data.subarray(off, off + chunk)) : encodeAssetWrite(path, off, data.subarray(off, off + chunk));
   const existing = await connection.getAccountInfo(pda);
   if (existing && !force) {
     const cur = decodeAsset(existing.data);
     if (cur && cur.complete && cur.contentType === contentType && cur.data.equals(data)) return { pda, skipped: true };
   }
-  const keys = assetKeys(authority, pid, pda);
-  await sendTx(connection, [new TransactionInstruction({ programId: pid, keys, data: encodeAssetInit(path, data.length, contentType) })], [authority], { label: `init ${path}` });
+  const keys = assetKeys(authority, pid, pda, site);
+  await sendTx(connection, [new TransactionInstruction({ programId: pid, keys, data: initData })], [authority], { label: `init ${path}` });
   const header = ASSET_FIXED_HEADER + Buffer.byteLength(contentType.slice(0, 120));
   // The first `ASSET_MAX_INITIAL - header` bytes fit in the created account;
   // later chunks grow it ≤10 KB per tx. Both are just sequential offsets.
   const chunks = [];
-  for (let off = 0; off < data.length; off += WRITE_CHUNK) chunks.push(off);
+  for (let off = 0; off < data.length; off += chunk) chunks.push(off);
   // Writes past the initial allocation resize the account, and a resize's
   // budget is measured from the length at instruction entry; keep those in
   // order so no two growing writes race each other.
   const initialCap = Math.max(0, ASSET_MAX_INITIAL - header);
-  const inPlace = chunks.filter((o) => o + WRITE_CHUNK <= initialCap);
-  const growing = chunks.filter((o) => o + WRITE_CHUNK > initialCap);
-  const write = (off) => sendTx(connection, [new TransactionInstruction({ programId: pid, keys, data: encodeAssetWrite(path, off, data.subarray(off, off + WRITE_CHUNK)) })], [authority], { label: `write ${path}@${off}` });
+  const inPlace = chunks.filter((o) => o + chunk <= initialCap);
+  const growing = chunks.filter((o) => o + chunk > initialCap);
+  const write = (off) => sendTx(connection, [new TransactionInstruction({ programId: pid, keys, data: writeData(off) })], [authority], { label: `write ${path}@${off}` });
   let done = 0;
   await pool(inPlace, async (off) => { await write(off); onProgress?.(++done, chunks.length); }, { concurrency: 8 });
   for (const off of growing) { await write(off); onProgress?.(++done, chunks.length); }
   return { pda, skipped: false, txs: 1 + chunks.length };
 }
 
-export async function closeAsset(connection, { authority, programId, path }) {
+export async function closeAsset(connection, { authority, programId, site = null, path }) {
   const pid = new PublicKey(programId);
-  const [pda] = assetPda(pid, path);
-  return sendTx(connection, [new TransactionInstruction({ programId: pid, keys: assetKeys(authority, pid, pda), data: encodeAssetClose(path) })], [authority], { label: `close ${path}` });
+  const [pda] = assetPdaFor(pid, site, path);
+  return sendTx(connection, [new TransactionInstruction({ programId: pid, keys: assetKeys(authority, pid, pda, site), data: site ? encodeVmAssetClose(site, path) : encodeAssetClose(path) })], [authority], { label: `close ${path}` });
 }
 
-export async function readAsset(connection, programId, path) {
-  const [pda] = assetPda(new PublicKey(programId), path);
+export async function readAsset(connection, programId, path, site = null) {
+  const [pda] = assetPdaFor(new PublicKey(programId), site, path);
   const info = await connection.getAccountInfo(pda);
   if (!info) return null;
   return decodeAsset(info.data);
 }
 
-export async function readManifest(connection, programId) {
-  const a = await readAsset(connection, programId, MANIFEST_PATH);
+export async function readManifest(connection, programId, site = null) {
+  const a = await readAsset(connection, programId, MANIFEST_PATH, site);
   if (!a || !a.complete) return null;
   return JSON.parse(a.data.toString('utf8'));
 }
 
-export async function readKv(connection, programId, key) {
-  const [pda] = kvPda(new PublicKey(programId), key);
+export async function readKv(connection, programId, key, site = null) {
+  const [pda] = kvPdaFor(new PublicKey(programId), site, key);
   const info = await connection.getAccountInfo(pda);
   return info ? decodeKv(info.data) : null;
 }
@@ -242,9 +249,15 @@ export async function readKv(connection, programId, key) {
  *
  * @returns {{status:number, headers:object, body:Buffer, signature?:string, logs:string[], unitsConsumed?:number, accounts:string[]}}
  */
-export async function invoke(connection, { programId, payer, event, mutate = false, computeUnits = DEFAULT_CU, heap = DEFAULT_HEAP, maxDiscovery = 6 }) {
+export async function invoke(connection, { programId, site = null, payer, event, mutate = false, computeUnits = DEFAULT_CU, heap = DEFAULT_HEAP, maxDiscovery = 6 }) {
   const pid = new PublicKey(programId);
   const payerKey = payer.publicKey ?? new PublicKey(payer);
+  // Shared runtime: the instruction names the site and hands the program its
+  // site account and code account after payer + system program.
+  const siteKeys = site ? [
+    { pubkey: sitePda(pid, site)[0], isSigner: false, isWritable: false },
+    { pubkey: assetPdaFor(pid, site, CODE_PATH)[0], isSigner: false, isWritable: false },
+  ] : [];
   if (mutate) {
     // Identical bytes inside one blockhash window dedupe as AlreadyProcessed;
     // a per-request nonce header (ignored on chain) makes every write unique
@@ -252,12 +265,13 @@ export async function invoke(connection, { programId, payer, event, mutate = fal
     const nonce = Math.random().toString(16).slice(2, 10) + Date.now().toString(16);
     event = { ...event, headers: typeof event.headers === 'string' ? event.headers + `x-zoo-nonce:${nonce}\n` : { ...(event.headers || {}), 'x-zoo-nonce': nonce } };
   }
-  const data = encodeInvoke(event);
+  const data = site ? encodeVmInvoke(site, event) : encodeInvoke(event);
   const extra = [];
   for (let round = 0; ; round++) {
     const keys = [
       { pubkey: payerKey, isSigner: true, isWritable: true },
       { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      ...siteKeys,
       ...extra.map((k) => ({ pubkey: k, isSigner: false, isWritable: true })),
     ];
     const ix = new TransactionInstruction({ programId: pid, keys, data });
@@ -339,3 +353,35 @@ export async function waitForProgram(connection, programId, { timeoutMs = 30_000
     await new Promise((r) => setTimeout(r, 400));
   }
 }
+
+// ---------------------------------------------------------------- shared runtime sites
+
+/** Create the site account (`["site", siteId]`) under the runtime, owned by `authority`. Idempotent. */
+export async function initSite(connection, { authority, runtime, site }) {
+  const pid = new PublicKey(runtime);
+  const [pda] = sitePda(pid, site);
+  const info = await connection.getAccountInfo(pda);
+  if (info) {
+    const s = decodeSite(info.data);
+    if (s && !s.authority.equals(authority.publicKey)) throw new Error(`site ${new PublicKey(site).toBase58()} belongs to ${s.authority.toBase58()}`);
+    return { pda, created: false };
+  }
+  await sendTx(connection, [new TransactionInstruction({
+    programId: pid,
+    keys: [
+      { pubkey: authority.publicKey, isSigner: true, isWritable: true },
+      { pubkey: pda, isSigner: false, isWritable: true },
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+    ],
+    data: encodeSiteInit(site),
+  })], [authority], { label: 'site init' });
+  return { pda, created: true };
+}
+
+export async function getSiteInfo(connection, runtime, site) {
+  const [pda] = sitePda(new PublicKey(runtime), site);
+  const info = await connection.getAccountInfo(pda);
+  if (!info) return { exists: false, pda };
+  const s = decodeSite(info.data);
+  return { exists: !!s, pda, authority: s?.authority || null };
+}

package/transmute/lib/wire.js

@@ -7,7 +7,9 @@
 import { createHash } from 'node:crypto';
 import { PublicKey } from '@solana/web3.js';
 
-export const TAG = { INVOKE: 0, ASSET_INIT: 1, ASSET_WRITE: 2, ASSET_CLOSE: 3 };
+export const TAG = { INVOKE: 0, ASSET_INIT: 1, ASSET_WRITE: 2, ASSET_CLOSE: 3, SITE_INIT: 16, SITE_SET_AUTHORITY: 17, VM_INVOKE: 18, VM_ASSET_INIT: 19, VM_ASSET_WRITE: 20, VM_ASSET_CLOSE: 21 };
+/** Path of a site's bytecode module under the shared runtime. */
+export const CODE_PATH = '/.zoo/code.bin';
 export const METHODS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD'];
 export const ERR_KV_MISSING = 0x4b560001;
 export const ERR_NOT_AUTHORITY = 0x4b560002;
@@ -165,3 +167,42 @@ export function decodeKv(data) {
   if (len === 0) return null;
   try { return JSON.parse(data.subarray(KV_HEADER, KV_HEADER + len).toString('utf8')); } catch { return null; }
 }
+
+// ---- shared runtime (zoo-vm): sites are accounts namespaced by a 32-byte site id
+
+export function siteIdBytes(site) { return site instanceof PublicKey ? site.toBuffer() : new PublicKey(site).toBuffer(); }
+
+export function sitePda(runtime, site) {
+  return PublicKey.findProgramAddressSync([Buffer.from('site'), siteIdBytes(site)], new PublicKey(runtime));
+}
+export function kvPdaNs(runtime, site, key) {
+  return PublicKey.findProgramAddressSync([Buffer.from('kv'), siteIdBytes(site), kvHash(key)], new PublicKey(runtime));
+}
+export function assetPdaNs(runtime, site, path) {
+  return PublicKey.findProgramAddressSync([Buffer.from('asset'), siteIdBytes(site), assetHash(path)], new PublicKey(runtime));
+}
+/** Any-mode asset PDA: program-flavour when `site` is null. */
+export function assetPdaFor(programId, site, path) {
+  return site ? assetPdaNs(programId, site, path) : assetPda(programId, path);
+}
+export function kvPdaFor(programId, site, key) {
+  return site ? kvPdaNs(programId, site, key) : kvPda(programId, key);
+}
+
+export function encodeSiteInit(site) { return Buffer.concat([Buffer.from([TAG.SITE_INIT]), siteIdBytes(site)]); }
+export function encodeSiteSetAuthority(site, newAuthority) { return Buffer.concat([Buffer.from([TAG.SITE_SET_AUTHORITY]), siteIdBytes(site), new PublicKey(newAuthority).toBuffer()]); }
+/** The VM invoke: same bridge event, prefixed by the site id. */
+export function encodeVmInvoke(site, ev) {
+  const inner = encodeInvoke(ev); // [TAG.INVOKE][...]
+  return Buffer.concat([Buffer.from([TAG.VM_INVOKE]), siteIdBytes(site), inner.subarray(1)]);
+}
+export function encodeVmAssetInit(site, path, totalLen, contentType) { return Buffer.concat([Buffer.from([TAG.VM_ASSET_INIT]), siteIdBytes(site), encodeAssetInit(path, totalLen, contentType).subarray(1)]); }
+export function encodeVmAssetWrite(site, path, offset, bytes) { return Buffer.concat([Buffer.from([TAG.VM_ASSET_WRITE]), siteIdBytes(site), encodeAssetWrite(path, offset, bytes).subarray(1)]); }
+export function encodeVmAssetClose(site, path) { return Buffer.concat([Buffer.from([TAG.VM_ASSET_CLOSE]), siteIdBytes(site), encodeAssetClose(path).subarray(1)]); }
+
+export const SITE_LEN = 66;
+/** Decode a site account: { authority, bump } or null. */
+export function decodeSite(data) {
+  if (!data || data.length < SITE_LEN || data[0] !== 1) return null;
+  return { bump: data[1], authority: new PublicKey(data.subarray(2, 34)) };
+}

package/transmute/runtime/zoo-host/examples/vmrun.rs

@@ -0,0 +1,43 @@
+//! Host-side VM harness: `vmrun <module.bin> <route> <method> <path> [query] [body] [headers]`
+//! prints the bridge response as JSON. No chain: KV calls report as missing.
+use std::io::Read;
+use zoo_host::{vm, wire::Req, Ctx};
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let mut code = Vec::new();
+    std::fs::File::open(&args[1]).unwrap().read_to_end(&mut code).unwrap();
+    let route: usize = args[2].parse().unwrap();
+    let method = zoo_host::wire::METHODS.iter().position(|m| *m == args[3]).unwrap_or(0) as u8;
+    let req = Req {
+        route: route as u8,
+        method,
+        path: args.get(4).cloned().unwrap_or_else(|| "/".into()),
+        query: args.get(5).cloned().unwrap_or_default(),
+        headers: args.get(7).cloned().unwrap_or_default().replace("\\n", "\n"),
+        body: args.get(6).cloned().unwrap_or_default().into_bytes(),
+    };
+    let program_id = pinocchio::Address::new_from_array([7u8; 32]);
+    let mut accounts: [pinocchio::AccountView; 0] = [];
+    let mut cx = Ctx::new(&program_id, &mut accounts, req, &[]);
+    let out = vm::invoke_module(&mut cx, &code, route);
+    let status_body = match out {
+        Ok(()) if cx.sent => (cx.res.status, String::from_utf8_lossy(&cx.res.body).into_owned(), cx.res.headers.clone()),
+        Ok(()) => (504, "no response".into(), vec![]),
+        Err(e) => {
+            let r = vm::error_resp(&e);
+            (r.status, String::from_utf8_lossy(&r.body).into_owned(), r.headers.clone())
+        }
+    };
+    let hdrs: Vec<String> = status_body.2.iter().map(|(k, v)| format!("\"{}\":\"{}\"", k, v.replace('"', "\\\""))).collect();
+    println!("{{\"status\":{},\"headers\":{{{}}},\"body\":{}}}", status_body.0, hdrs.join(","), serde_free(&status_body.1));
+}
+
+fn serde_free(s: &str) -> String {
+    let mut o = String::from("\"");
+    for c in s.chars() {
+        match c { '"' => o.push_str("\\\""), '\\' => o.push_str("\\\\"), '\n' => o.push_str("\\n"), _ => o.push(c) }
+    }
+    o.push('"');
+    o
+}