@opeqlabs/sdk 0.0.0-stage → 0.1.0

package/src/lib/engine.js

@@ -0,0 +1,639 @@
+import * as M from "./mnemonic.js";
+import * as P from "./protocol.js";
+import * as V from "./vaultstore.js";
+import { LEAVES, PATH_LEN, SIG_LEN, verify as wotsVerify } from "./wots.js";
+import {
+  COMPUTE_BUDGET, SYSTEM, b58decode, b58encode, compileV0, concat, eq, hex, pubkey, u32, u64, unhex, unsignedTx,
+} from "./solana.js";
+
+export const EXPIRY_SLOTS = 150;
+export const RESTORE_GAP = 64;
+export const TAKEOVER_FLOOR = 768;
+export const SIGN_LIMIT = TAKEOVER_FLOOR;
+export const EXEC_LIMIT = TAKEOVER_FLOOR - RESTORE_GAP - 16;
+export const TX_LIMIT = 1232;
+export const BASE_FEE = 5000;
+const RENT_MIN = 1000000, RENT_MAX = 2000000;
+const CONFIRM_MS = 90000;
+const HISTORY_PAGES = 100;
+const FALLBACK_MS = 30 * 60 * 1000;
+const FAILED_MAX = 3000;
+
+const b64 = (b) => btoa(String.fromCharCode(...b));
+const rd32 = (d, o) => (d[o] | (d[o + 1] << 8) | (d[o + 2] << 16) | (d[o + 3] << 24)) >>> 0;
+const rd64 = (d, o) => { let v = 0n; for (let i = 7; i >= 0; i--) v = (v << 8n) | BigInt(d[o + i]); return v; };
+
+export function signedLeaf(d, keys, program, cur) {
+  const SIG_END = P.SIG_OFF + SIG_LEN, PATH_END = SIG_END + PATH_LEN;
+  if (d.length < PATH_END || (d[0] !== P.IX_EXEC && d[0] !== P.IX_REKEY)) return null;
+  const leaf = rd32(d, 1);
+  if (leaf >= LEAVES) return null;
+  const expiry = rd64(d, 5), salt = rd32(d, P.SALT_OFF), r = d.slice(P.R_OFF, P.R_OFF + P.R_LEN);
+  const sig = d.slice(P.SIG_OFF, SIG_END), path = d.slice(SIG_END, PATH_END);
+  let h;
+  if (d[0] === P.IX_REKEY) {
+    if (d.length !== PATH_END + 32) return null;
+    h = P.rekeyHasher(program, cur.aid, cur.epoch, leaf, expiry, d.slice(PATH_END, PATH_END + 16), d.slice(PATH_END + 16, PATH_END + 32), r);
+  } else {
+    const key = (i) => { if (i >= keys.length) throw new Error("bad key index"); return b58decode(keys[i]); };
+    let o = PATH_END;
+    const count = d[o++];
+    const inner = [];
+    for (let k = 0; k < count; k++) {
+      const prog = key(d[o++]), ml = d[o++], metas = [];
+      for (let j = 0; j < ml; j++) { const idx = d[o++], fl = d[o++]; metas.push([key(idx), !!(fl & P.F_SIGNER), !!(fl & P.F_WRITABLE)]); }
+      const dl = d[o] | (d[o + 1] << 8);
+      o += 2;
+      if (o + dl > d.length) return null;
+      inner.push([prog, metas, d.slice(o, o + dl)]);
+      o += dl;
+    }
+    if (o !== d.length) return null;
+    h = P.execHasher(program, cur.aid, cur.epoch, leaf, expiry, inner, r);
+  }
+  return wotsVerify(cur.pubSeed, cur.root, leaf, P.salted(h, salt), sig, path) ? leaf : null;
+}
+const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+
+export class Failed extends Error {}
+export class Inactive extends Error {}
+
+function describe(err) {
+  const logs = (err.data && err.data.logs) || [];
+  const m = /custom program error: (0x[0-9a-f]+)/.exec(err.message + logs.join("\n"));
+  const deepest = logs.map((l) => /Program (\w+) failed: custom program error: (0x[0-9a-f]+)/.exec(l)).find(Boolean);
+  let msg = err.message;
+  if (deepest) msg += ` (${deepest[1].slice(0, 6)}… error ${parseInt(deepest[2], 16)})`;
+  else if (m) msg += ` (error ${parseInt(m[1], 16)})`;
+  return { msg, logs, code: deepest ? parseInt(deepest[2], 16) : null, program: deepest ? deepest[1] : null };
+}
+
+export class Engine {
+  constructor({ rpc, program, store, compute, payer }) {
+    this.rpc = rpc;
+    this.program = typeof program === "string" ? pubkey(program) : program;
+    this.store = store;
+    this.compute = compute;
+    this.refRpc = null;
+    this.payer = payer;
+    this.priceFor = null;
+    this.maxPriority = 100000;
+    this.genesis = null;
+    this._genesisOk = false;
+    this.log = () => {};
+  }
+
+  async create(password, progress) {
+    const master = M.newMaster();
+    const t = await this.compute.run("treeFor", { master, epoch: 0, program: this.program }, progress);
+    const aid = P.accountId(t.pubSeed, t.root);
+    const record = await this._record(master, password, aid, 0, t, 0, true);
+    return { record, words: M.toWords(master) };
+  }
+
+  async recover(words, password, progress, existing = null) {
+    const master = M.fromWords(words);
+    const t0 = await this.compute.run("treeFor", { master, epoch: 0, program: this.program }, progress && ((p) => progress(p * 0.5)));
+    const aid = P.accountId(t0.pubSeed, t0.root);
+    const acc = await this.rpc.account(P.statePda(aid, this.program).key);
+    let epoch = 0, next = 0, t = t0;
+    if (acc) {
+      if (!eq(acc.owner, this.program)) throw new Error("state account is not owned by the opeq program");
+      const st = P.unpackState(acc.data);
+      epoch = st.epoch;
+      next = existing && existing.aid && existing.epoch === epoch ? Math.max(existing.next_leaf, st.next) : st.next;
+      if (epoch > 0) t = await this.compute.run("treeFor", { master, epoch, program: this.program, pubSeed: st.pubSeed }, progress && ((p) => progress(0.5 + p * 0.5)));
+      if (!eq(t.root, st.root)) throw new Error("these words do not control this wallet's current tree");
+    }
+    if (existing && existing.epoch > epoch) throw new Error("this browser already holds a newer copy of this wallet");
+    const keep = {};
+    if (existing && existing.epoch === epoch) for (const k of ["takeover", "inflight", "rekeying"]) if (existing[k]) keep[k] = existing[k];
+    const same = !!(existing && existing.epoch === epoch && existing.root === hex(t.root) && existing.pub_seed === hex(t.pubSeed));
+    return this._record(master, password, aid, epoch, t, next, same && existing.active === true, keep);
+  }
+
+  replace(id, words, password, progress) {
+    return V.withLock(`opeq:${id}`, async () => {
+      const rec = await this.recover(words, password, progress, await this.store.get(id));
+      await this.save(rec);
+      return rec;
+    });
+  }
+
+  remove(id) {
+    return V.withLock(`opeq:${id}`, async () => {
+      const r = await this.store.get(id);
+      if (r && (r.rekeying || r.inflight)) {
+        if (r.rekeying && !(await this.passed(Number(r.rekeying.expiry), Number(r.rekeying.at) || 0))) throw new Error("a rekey or takeover from this browser may still land; wait about a minute, then remove");
+        if (r.inflight && !(await this.passed(Number(r.inflight.expiry), Number(r.inflight.at) || 0))) throw new Error("a transaction from this browser may still land; wait about a minute, then remove");
+      }
+      await this.store.del(id);
+    });
+  }
+
+  async _record(master, password, aid, epoch, t, next, active = true, keep = {}) {
+    const { blob, macKey } = await V.seal(master, password, aid);
+    const wallet = P.walletPda(aid, this.program).key;
+    const record = {
+      id: b58encode(wallet), v: 1, program: b58encode(this.program), aid: hex(aid), epoch, next_leaf: next,
+      pub_seed: hex(t.pubSeed), root: hex(t.root), leaves: b64(t.leaves), enc: blob, created: Date.now(), active, ...keep,
+    };
+    return V.signRecord(macKey, record);
+  }
+
+  async passed(expiry, at) {
+    const a = await this.rpc.slot();
+    if (!this.refRpc) return a > expiry + 2;
+    try { return Math.min(a, await this.refRpc.slot()) > expiry + 2; }
+    catch { return a > expiry + 2 && at > 0 && Date.now() - at > FALLBACK_MS; }
+  }
+
+  async save(record) { await this.store.put(record); }
+
+  async unlock(record, password) {
+    const aid = unhex(record.aid);
+    const { master, macKey, macRaw } = await V.unlock(record.enc, password, aid);
+    await V.checkRecord(macKey, record);
+    if (record.program !== b58encode(this.program)) throw new Error("this wallet belongs to a different opeq program");
+    const seeds = M.treeSeeds(master, record.epoch, this.program, unhex(record.pub_seed));
+    if (hex(seeds.pubSeed) !== record.pub_seed) throw new Error("wallet tree does not match its master seed");
+    const session = new Session(this, record.id, master, macKey);
+    session.macRaw = macRaw;
+    return session;
+  }
+
+  initIx(record) {
+    const aid = unhex(record.aid);
+    return async () => {
+      const lamports = await this.rpc.rent(P.STATE_LEN);
+      if (!Number.isSafeInteger(lamports) || lamports < RENT_MIN || lamports > RENT_MAX) throw new Error("the RPC returned an implausible rent amount, refusing to activate");
+      return [this.program, [[this.payer.key(), true, true], [P.statePda(aid, this.program).key, false, true],
+        [pubkey(record.id), false, false], [SYSTEM, false, false]], P.buildInit(unhex(record.pub_seed), unhex(record.root), lamports)];
+    };
+  }
+
+  async init(record) {
+    await this.checkCluster();
+    const ix = await this.initIx(record)();
+    const slot = await this.rpc.slot();
+    try {
+      return await this.submit(ix, slot + EXPIRY_SLOTS, 60000, [], await this.price(60000, [this.payer.key()]));
+    } catch (e) {
+      const st = await this.chainState(record);
+      if (st && hex(st.root) === record.root) return "already-initialized";
+      throw e;
+    }
+  }
+
+  async checkCluster() {
+    if (!this.genesis || this._genesisOk) return;
+    const g = await this.rpc.call("getGenesisHash", []);
+    if (g !== this.genesis) throw new Error("the RPC is connected to a different Solana cluster than this wallet expects, refusing to sign");
+    this._genesisOk = true;
+  }
+
+  async chainState(record) {
+    const acc = await this.rpc.account(P.statePda(unhex(record.aid), this.program).key);
+    if (!acc) return null;
+    if (!eq(acc.owner, this.program)) throw new Error("state account is not owned by the opeq program");
+    return P.unpackState(acc.data);
+  }
+
+  priceCap(cuLimit) {
+    return Math.floor((this.maxPriority * 1e6) / cuLimit);
+  }
+
+  async price(cuLimit, keys) {
+    if (!this.priceFor) return 0;
+    let p = 0;
+    try { p = await this.priceFor(cuLimit, keys); } catch { p = 0; }
+    if (!Number.isSafeInteger(p) || p < 0) return 0;
+    return Math.min(p, this.priceCap(cuLimit));
+  }
+
+  feeFor(cuLimit, price) {
+    return BASE_FEE + Math.ceil((price * cuLimit) / 1e6);
+  }
+
+  async payerCovers(lamports) {
+    const bal = await this.rpc.balance(this.payer.key());
+    if (!Number.isSafeInteger(bal) || bal < lamports) {
+      const f = new Failed(`the fee wallet cannot pay the network fee (it needs ${lamports} lamports, has ${bal}); nothing was signed`);
+      f.feeEmpty = true;
+      throw f;
+    }
+  }
+
+  budget(cuLimit, price) {
+    if (!Number.isSafeInteger(price) || price < 0 || price > this.priceCap(cuLimit)) throw new Error("priority fee out of range");
+    const out = [[COMPUTE_BUDGET, [], concat(new Uint8Array([2]), u32(cuLimit))]];
+    if (price) out.push([COMPUTE_BUDGET, [], concat(new Uint8Array([3]), u64(price))]);
+    return out;
+  }
+
+  txSize(ix, cuLimit, tables = []) {
+    const { message } = compileV0(this.payer.key(), [...this.budget(cuLimit, this.priceFor ? 1 : 0), ix], new Uint8Array(32), tables);
+    return unsignedTx(message, 1).length;
+  }
+
+  async submit(ix, expiry, cuLimit, tables = [], price = 0, verify = null) {
+    await this.checkCluster();
+    const { message, signers } = compileV0(this.payer.key(), [...this.budget(cuLimit, price), ix], await this.rpc.blockhash(), tables);
+    if (signers.length !== 1) throw new Error("unexpected extra signer");
+    const signed = await this.payer.sign(unsignedTx(message, 1));
+    if (signed.length > TX_LIMIT) throw new Failed(`transaction too large: ${signed.length} bytes`);
+    if (verify) {
+      try { await verify(signed); } catch (e) { const f = new Failed(e.message); f.sent = true; f.logs = e.logs; throw f; }
+    }
+    let sig;
+    try {
+      sig = await this.rpc.sendRaw(signed);
+      if (sig !== b58encode(signed.slice(1, 65))) throw new Error("the RPC returned a signature that is not this transaction's");
+    } catch (e) {
+      const d = describe(e);
+      const f = new Failed(d.msg);
+      f.code = d.code; f.program = d.program; f.logs = d.logs; f.sent = true;
+      throw f;
+    }
+    const started = Date.now();
+    for (;;) {
+      let st = null;
+      try { st = await this.rpc.status(sig); } catch { st = null; }
+      if (st && st.err) {
+        const f = new Failed(`transaction failed: ${JSON.stringify(st.err).slice(0, 200)}`);
+        f.sent = true;
+        throw f;
+      }
+      if (st && (st.confirmationStatus === "confirmed" || st.confirmationStatus === "finalized")) return sig;
+      let gone = false;
+      try { gone = await this.passed(expiry, started); } catch { gone = false; }
+      if (gone) {
+        let again = null;
+        try { again = await this.rpc.status(sig); } catch { again = null; }
+        if (again && !again.err && (again.confirmationStatus === "confirmed" || again.confirmationStatus === "finalized")) return sig;
+        const f = new Failed("transaction expired without landing");
+        f.sent = true; f.expired = true;
+        throw f;
+      }
+      if (Date.now() - started > CONFIRM_MS) {
+        const f = new Failed("could not confirm the transaction in time");
+        f.sent = true;
+        throw f;
+      }
+      await new Promise((r) => setTimeout(r, 1500));
+    }
+  }
+}
+
+export class Session {
+  constructor(engine, id, master, macKey) {
+    this.e = engine;
+    this.id = id;
+    this.master = master;
+    this.macKey = macKey;
+    this.wallet = pubkey(id);
+  }
+
+  async load() {
+    const r = await this.e.store.get(this.id);
+    if (!r) throw new Error("wallet not found in this browser");
+    await V.checkRecord(this.macKey, r);
+    if (r.program !== b58encode(this.e.program)) throw new Error("this wallet belongs to a different opeq program");
+    return r;
+  }
+
+  async put(r) {
+    await V.signRecord(this.macKey, r);
+    await this.e.store.put(r);
+    return r;
+  }
+
+  lock(fn, wait = false) {
+    return V.withLock(`opeq:${this.id}`, fn, { wait });
+  }
+
+  ownRekey(r, st) {
+    if (!r.rekeying || Number(r.rekeying.epoch) !== st.epoch) return false;
+    if (!M.chainSeeded(this.e.program, st.epoch)) return false;
+    return typeof r.rekeying.pub_seed === "string" && r.rekeying.pub_seed === hex(st.pubSeed);
+  }
+
+  async adopt(r, st) {
+    if (st.epoch === r.epoch) return r;
+    if (st.epoch < r.epoch) throw new Error("on-chain epoch is behind this wallet, refusing to sign");
+    const own = this.ownRekey(r, st);
+    if (!own) {
+      if (r.active) { r.active = false; await this.put(r); }
+      throw new Inactive("This wallet was rekeyed from another device or browser, so this copy stopped signing. To use it here, choose Use on this device.");
+    }
+    const t = await this.e.compute.run("treeFor", { master: this.master, epoch: st.epoch, program: this.e.program, pubSeed: st.pubSeed });
+    if (!eq(t.root, st.root)) throw new Error("on-chain tree is not derived from this wallet's words");
+    Object.assign(r, { epoch: st.epoch, next_leaf: 0, pub_seed: hex(t.pubSeed), root: hex(t.root), leaves: b64(t.leaves), active: true });
+    delete r.rekeying;
+    delete r.takeover;
+    delete r.inflight;
+    this.e.log(`wallet moved to tree ${st.epoch}`);
+    return this.put(r);
+  }
+
+  async preflight(isBurn = false) {
+    await this.e.checkCluster();
+    let r = await this.load();
+    const st = await this.e.chainState(r);
+    if (!st) throw new Error("wallet is not initialized on chain yet");
+    r = await this.adopt(r, st);
+    if (!r.active) throw new Inactive("This copy of the wallet is not active here yet. Choose Use on this device first.");
+    if (hex(st.root) !== r.root || hex(st.pubSeed) !== r.pub_seed) throw new Error("on-chain root differs from this wallet, refusing to sign");
+    if (r.inflight && !isBurn) {
+      const note = await this._ack(st);
+      if (note.state !== "expired" && note.state !== "landed") throw new Error(note.message);
+    }
+    return { r: await this.load(), st };
+  }
+
+  async status() {
+    const r = await this.load();
+    const st = await this.e.chainState(r);
+    if (!st) return { state: "uninitialized", r, st };
+    if (st.epoch > r.epoch && !this.ownRekey(r, st)) return { state: "inactive", r, st };
+    if (st.epoch === r.epoch && !r.active) return { state: "inactive", r, st };
+    return { state: "active", r, st };
+  }
+
+  async ackInflight(st) {
+    try {
+      return await this.lock(() => this._ack(st));
+    } catch (e) {
+      if (/busy/.test(e.message)) return { state: "busy" };
+      throw e;
+    }
+  }
+
+  async _ack(st) {
+    const r = await this.load();
+    const f = r.inflight;
+    if (!f) return { state: "none" };
+    const leaf = Number(f.leaf), expiry = Number(f.expiry);
+    if (st && st.epoch === r.epoch && st.next > leaf) {
+      delete r.inflight;
+      await this.put(r);
+      return { state: "landed", message: `an interrupted transaction (key ${leaf}) can no longer execute, but it may have gone through; check the balance before sending again` };
+    }
+    if (!(await this.e.passed(expiry, Number(f.at) || 0))) {
+      return { state: "pending", message: `an interrupted transaction (key ${leaf}) may still go through until slot ${expiry}; wait about a minute, refresh and check the balance before sending again` };
+    }
+    delete r.inflight;
+    await this.put(r);
+    return { state: "expired", message: `an interrupted transaction (key ${leaf}) expired without landing` };
+  }
+
+  async reserve(r, st, limit) {
+    const leaf = Math.max(r.next_leaf, st.next);
+    if (leaf >= limit) {
+      throw new Error(limit === EXEC_LIMIT ? "this key tree is used up for transactions; rekey now" : "no keys left for a rekey on this tree; choose Use on this device to move to a new tree");
+    }
+    r.next_leaf = leaf + 1;
+    await this.put(r);
+    return leaf;
+  }
+
+  exec(inner, cuLimit = 400000, progress, tables = [], verify = null) {
+    return this.lock(() => this._exec(inner, cuLimit, progress, true, tables, false, verify));
+  }
+
+  async _exec(inner, cuLimit, progress, burnOnFail, tables = [], isBurn = false, verify = null) {
+    const { r, st } = await this.preflight(isBurn);
+    const aid = unhex(r.aid);
+    const state = P.statePda(aid, this.e.program).key;
+    const { outer, metas } = P.outerLayout(state, this.wallet, inner);
+    const size = await this.execSize(inner, tables);
+    if (size > TX_LIMIT) throw new Failed(`this transaction would be ${size} bytes, over the ${TX_LIMIT} byte limit; nothing was signed`);
+    const price = await this.e.price(cuLimit, metas.filter((m) => m[2]).map((m) => m[0]));
+    await this.e.payerCovers(2 * this.e.feeFor(cuLimit, price));
+    const leaf = await this.reserve(r, st, isBurn ? SIGN_LIMIT : EXEC_LIMIT);
+    const expiry = (await this.e.rpc.slot()) + EXPIRY_SLOTS;
+    const prev = r.inflight;
+    r.inflight = prev ? { leaf: Math.min(Number(prev.leaf), leaf), expiry: Math.max(Number(prev.expiry), expiry), at: Date.now() } : { leaf, expiry, at: Date.now() };
+    await this.put(r);
+    let sig;
+    try {
+      const rnd = crypto.getRandomValues(new Uint8Array(P.R_LEN));
+      const s = await this.e.compute.run("signExec", {
+        master: this.master, epoch: r.epoch, leaves: unb64(r.leaves), pubSeed: unhex(r.pub_seed), leaf, program: this.e.program, aid, expiry, inner, r: rnd,
+      }, progress);
+      const data = P.buildExec(leaf, expiry, s.salt, rnd, s.sig, s.path, inner, outer);
+      this.e.log(`leaf ${leaf}, ${s.cost} on-chain hash steps`);
+      sig = await this.e.submit([this.e.program, metas, data], expiry, cuLimit, tables, price, verify);
+    } catch (err) {
+      if (!err.sent) {
+        const back = await this.load();
+        if (prev) back.inflight = prev; else delete back.inflight;
+        await this.put(back);
+        throw err;
+      }
+      let after = null;
+      try { after = await this.e.chainState(await this.load()); } catch { after = null; }
+      if (after && after.epoch === r.epoch && after.next > leaf) {
+        await this._clearIf(leaf);
+        const f = new Failed(`${err.message}. The wallet's key counter moved past this transaction, so it may have gone through; check the balance before sending again`);
+        f.maybeLanded = true;
+        throw f;
+      }
+      if (err.expired) {
+        await this._clearIf(leaf);
+        throw new Failed("the transaction expired without landing; it can no longer execute");
+      }
+      if (burnOnFail) await this.burnIfLive(leaf);
+      throw err;
+    }
+    await this._clearIf(leaf);
+    return sig;
+  }
+
+  async _clearIf(leaf) {
+    const r = await this.load();
+    if (!r.inflight) return;
+    const st = await this.e.chainState(r).catch(() => null);
+    if (Number(r.inflight.leaf) === leaf || (st && st.epoch === r.epoch && st.next > Number(r.inflight.leaf))) {
+      delete r.inflight;
+      await this.put(r);
+    }
+  }
+
+  async burnIfLive(leaf) {
+    const st = await this.e.chainState(await this.load());
+    if (st.next > leaf) return;
+    this.e.log(`burning key ${leaf} so the failed signature can never execute`);
+    try {
+      await this._exec([], 200000, null, false, [], true);
+      this.e.log(`key ${leaf} burned`);
+    } catch (e) {
+      this.e.log(`could not burn key ${leaf} (${e.message}). Do not send again until the wallet shows this transaction as settled.`);
+    }
+  }
+
+  async execSize(inner, tables = []) {
+    const state = P.statePda(unhex((await this.load()).aid), this.e.program).key;
+    const { outer, metas } = P.outerLayout(state, this.wallet, inner);
+    const data = P.buildExec(0, 0, 0, new Uint8Array(P.R_LEN), new Uint8Array(SIG_LEN), new Uint8Array(PATH_LEN), inner, outer);
+    return this.e.txSize([this.e.program, metas, data], 400000, tables);
+  }
+
+  sendSol(to, lamports, progress) {
+    const inner = [[SYSTEM, [[this.wallet, true, true], [to, false, true]], concat(u32(2), u64(lamports))]];
+    return this.exec(inner, 400000, progress);
+  }
+
+  rekey(progress) {
+    return this.lock(async () => {
+      const { r, st } = await this.preflight();
+      await this.pendingRekey(r, st);
+      return this._rekey(r, st, await this.reserve(r, st, SIGN_LIMIT), progress);
+    });
+  }
+
+  takeover(progress, opts = {}) {
+    return this.lock(async () => {
+      await this.e.checkCluster();
+      let r = await this.load();
+      const st = await this.e.chainState(r);
+      if (!st) throw new Error("wallet is not initialized on chain yet");
+      if (st.epoch < r.epoch) throw new Error("on-chain epoch is behind this wallet, refusing to sign");
+      if (st.next + RESTORE_GAP >= LEAVES) throw new Error("the current key tree is too far used to take over safely; take over from the device that is active, or wait for it to rekey");
+      if (st.epoch !== r.epoch || r.root !== hex(st.root)) {
+        const t = await this.e.compute.run("treeFor", { master: this.master, epoch: st.epoch, program: this.e.program, pubSeed: st.pubSeed }, progress && ((p) => progress(p * 0.4)));
+        if (!eq(t.root, st.root)) throw new Error("on-chain tree is not derived from this wallet's words");
+        const keepNext = st.epoch === r.epoch ? Math.max(r.next_leaf, st.next) : st.next;
+        Object.assign(r, { epoch: st.epoch, next_leaf: keepNext, pub_seed: hex(t.pubSeed), root: hex(t.root), leaves: b64(t.leaves), active: false });
+        delete r.inflight;
+        delete r.rekeying;
+        r = await this.put(r);
+      }
+      await this.pendingRekey(r, st);
+      const tk = (await this.e.store.get(`tk:${r.aid}`)) || { id: `tk:${r.aid}`, used: {} };
+      const scan = await this.failedLeaves(P.statePda(unhex(r.aid), this.e.program).key, { epoch: st.epoch, pubSeed: unhex(r.pub_seed), root: unhex(r.root), aid: unhex(r.aid) });
+      if (!scan.complete && !opts.partialOk) {
+        const e = new Error("this wallet's history is too long, or holds too many failed transactions, to check every earlier attempt from another device");
+        e.incomplete = true;
+        throw e;
+      }
+      const seen = scan.leaves;
+      const used = [...new Set([...(r.takeover && r.takeover.epoch === st.epoch ? r.takeover.used : []), ...(tk.used[st.epoch] || []), ...seen])];
+      const lo = Math.max(TAKEOVER_FLOOR, st.next + RESTORE_GAP, r.next_leaf > TAKEOVER_FLOOR ? r.next_leaf : 0);
+      const free = [];
+      for (let l = lo; l < LEAVES; l++) if (!used.includes(l)) free.push(l);
+      if (!free.length) throw new Error("no unused takeover keys left on this tree; take over from the device that is active, or wait for it to rekey");
+      const leaf = free[crypto.getRandomValues(new Uint32Array(1))[0] % free.length];
+      tk.used = { [st.epoch]: [...used, leaf] };
+      await this.e.store.put(tk);
+      r.takeover = { epoch: st.epoch, used: [...used, leaf] };
+      await this.put(r);
+      return this._rekey(r, st, leaf, progress && ((p) => progress(0.4 + p * 0.6)));
+    });
+  }
+
+  async failedLeaves(state, cur) {
+    const out = new Set();
+    let complete = true;
+    for (const rpc of this.e.refRpc ? [this.e.rpc, this.e.refRpc] : [this.e.rpc]) {
+      const one = await this.scanFailed(rpc, state, cur);
+      one.leaves.forEach((l) => out.add(l));
+      if (!one.complete) complete = false;
+    }
+    return { leaves: [...out], complete };
+  }
+
+  async scanFailed(rpc, state, cur) {
+    const sigs = [];
+    let before = null, complete = false;
+    for (let page = 0; page < HISTORY_PAGES; page++) {
+      const got = await rpc.call("getSignaturesForAddress", [b58encode(state), { limit: 1000, commitment: "confirmed", ...(before ? { before } : {}) }]);
+      if (!Array.isArray(got)) throw new Error("the RPC returned a malformed signature list");
+      sigs.push(...got);
+      if (got.length < 1000) { complete = true; break; }
+      before = got[got.length - 1] && got[got.length - 1].signature;
+      if (typeof before !== "string") throw new Error("the RPC returned a malformed signature list");
+    }
+    let failed = sigs.filter((x) => x && x.err);
+    if (failed.length > FAILED_MAX) { failed = failed.slice(0, FAILED_MAX); complete = false; }
+    const out = new Set();
+    const prog = b58encode(this.e.program);
+    for (const s of failed) {
+      if (failed.length > 200 && this.e.pace !== 0) await new Promise((r) => setTimeout(r, this.e.pace || 250));
+      let tx = null;
+      for (let i = 0; i < 4 && !tx; i++) {
+        tx = await rpc.call("getTransaction", [s.signature, { encoding: "json", commitment: "confirmed", maxSupportedTransactionVersion: 0 }]).catch(() => null);
+        if (!tx) await new Promise((r) => setTimeout(r, 1500));
+      }
+      if (!tx || !tx.transaction) { complete = false; continue; }
+      const keys = [...tx.transaction.message.accountKeys, ...((tx.meta && tx.meta.loadedAddresses && [...tx.meta.loadedAddresses.writable, ...tx.meta.loadedAddresses.readonly]) || [])];
+      const ixs = [...tx.transaction.message.instructions, ...((tx.meta && Array.isArray(tx.meta.innerInstructions) && tx.meta.innerInstructions.flatMap((x) => (x && Array.isArray(x.instructions) ? x.instructions : []))) || [])];
+      for (const ix of ixs) {
+        if (!ix || keys[ix.programIdIndex] !== prog || typeof ix.data !== "string" || ix.data.length > 4000) continue;
+        let leaf;
+        try { leaf = signedLeaf(b58decode(ix.data), (ix.accounts || []).map((i) => keys[i]), this.e.program, cur); } catch { leaf = null; }
+        if (leaf !== null) out.add(leaf);
+      }
+    }
+    return { leaves: [...out], complete };
+  }
+
+  async pendingRekey(r, st) {
+    const m = r.rekeying;
+    if (m && Number(m.epoch) === st.epoch + 1 && !(await this.e.passed(Number(m.expiry), Number(m.at) || 0)))
+      throw new Error("an earlier rekey from this copy may still land; wait about a minute, then try again");
+  }
+
+  async _rekey(r, st, leaf, progress) {
+    const expiry = (await this.e.rpc.slot()) + EXPIRY_SLOTS;
+    const state = P.statePda(unhex(r.aid), this.e.program).key;
+    const metas = [[state, false, true], [this.wallet, false, false]];
+    const price = await this.e.price(400000, [state]);
+    await this.e.payerCovers(this.e.feeFor(400000, price));
+    const newPubSeed = M.chainSeeded(this.e.program, st.epoch + 1) ? crypto.getRandomValues(new Uint8Array(16)) : undefined;
+    r.rekeying = { epoch: st.epoch + 1, leaf, expiry, at: Date.now() };
+    if (newPubSeed) r.rekeying.pub_seed = hex(newPubSeed);
+    await this.put(r);
+    const rnd = crypto.getRandomValues(new Uint8Array(P.R_LEN));
+    const aid = unhex(r.aid);
+    const s = await this.e.compute.run("signRekey", {
+      master: this.master, epoch: r.epoch, leaves: unb64(r.leaves), pubSeed: unhex(r.pub_seed), newPubSeed, leaf, program: this.e.program, aid, expiry, r: rnd,
+    }, progress);
+    const data = P.buildRekey(leaf, expiry, s.salt, rnd, s.sig, s.path, s.newPubSeed, s.newRoot);
+    let sig;
+    try {
+      sig = await this.e.submit([this.e.program, metas, data], expiry, 400000, [], price);
+    } catch (err) {
+      if (!err.sent) {
+        const back = await this.load();
+        if (back.rekeying && Number(back.rekeying.leaf) === leaf) { delete back.rekeying; await this.put(back); }
+        throw err;
+      }
+      if (!M.chainSeeded(this.e.program, st.epoch + 1)) throw err;
+      const after = await this.e.chainState(await this.load()).catch(() => null);
+      if (!(after && after.epoch === st.epoch + 1 && eq(after.root, s.newRoot))) throw err;
+      sig = "landed";
+    }
+    if (sig !== "landed" && !M.chainSeeded(this.e.program, st.epoch + 1)) {
+      let tx = null;
+      for (let i = 0; i < 6 && !(tx && tx.meta); i++) {
+        tx = await this.e.rpc.call("getTransaction", [sig, { encoding: "json", commitment: "confirmed", maxSupportedTransactionVersion: 0 }]).catch(() => null);
+        if (!(tx && tx.meta)) await new Promise((r) => setTimeout(r, 3000));
+      }
+      if (!(tx && tx.meta && tx.meta.err === null)) throw new Error("could not confirm this rekey on chain; refresh in a minute");
+    }
+    if (sig !== "landed") {
+      const after = await this.e.chainState(await this.load()).catch(() => null);
+      if (!(after && after.epoch === st.epoch + 1 && eq(after.root, s.newRoot))) throw new Error("the rekey was reported as landed but the chain does not show the new tree yet; refresh in a minute");
+    }
+    const fresh = await this.load();
+    Object.assign(fresh, { epoch: r.epoch + 1, next_leaf: 0, pub_seed: hex(s.newPubSeed), root: hex(s.newRoot), leaves: b64(s.newLeaves), active: true });
+    delete fresh.rekeying;
+    delete fresh.inflight;
+    delete fresh.takeover;
+    await this.put(fresh);
+    return sig;
+  }
+
+  words() { return M.toWords(this.master); }
+}