@opeqlabs/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Sercan0x
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @opeqlabs/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Quantum-resistant accounts for Solana, Ethereum, Base, Arbitrum and Robinhood Chain.
+
+An OPEQ account is controlled by hash-based one-time keys (WOTS+ in a Merkle tree of 1024 keys) instead of an elliptic-curve key. A quantum computer that breaks Ed25519 or secp256k1 does not break it. This SDK lets you create those accounts, sign with them and verify their signatures from your own code.
+
+It is the same code the OPEQ wallet runs. `src/` is copied byte for byte from the wallet's library by `build_sdk.py`, and the test suite fails if the two ever differ. It has no dependencies.
+
+## Status
+
+**Beta, not yet externally audited.** The audits planned for the wallet will cover this SDK too. Until then, use small amounts.
+
+**Upgrade authority.** The Solana program (`HL598vrersxS5AUUV6NyzHgpSyK31xAmqMsqUhxzeKm8`) can still be upgraded by the OPEQ team. The plan is to give that up after the audits. The program cannot move funds on its own: every transfer needs a one-time signature from the account's own key tree. The EVM account and factory contracts are not upgradeable.
+
+## Install
+
+```
+npm install @opeqlabs/sdk
+```
+
+Node.js 20 or later, or any current browser. In Node, use `FileStore`; in a browser, `IdbStore`. Both refuse to move a key counter backwards.
+
+## The one rule
+
+**A one-time key must never sign twice.** The SDK enforces this for you:
+
+- Every store refuses to move a key counter backwards.
+- `FileStore` locks its folder, so two processes cannot use the same wallet at once. The folder must be on a local disk, owned by you and closed to other users (`chmod 700`); a shared, network or synced folder defeats the lock.
+- Signing jobs inside one process run one at a time.
+
+What the SDK cannot see is a second copy somewhere else. If the same 24 words are used on another device, that device must call `useHere()` first. It moves the account to a fresh key tree, and the old copy stops signing. Never restore a store from a backup to continue signing; recover from the words and call `useHere()` instead.
+
+## Solana
+
+```js
+import { Vault } from "@opeqlabs/sdk";
+import { FileStore } from "@opeqlabs/sdk/filestore";
+
+const store = await FileStore.open("./opeq-wallet");
+const vault = new Vault({ rpcUrl: "https://your-solana-rpc", checkRpcUrl: "https://a-second-provider", network: "mainnet", store });
+
+const { id, words } = await vault.create(password);
+const acct = await vault.open(id, password);
+
+await acct.feeKey();
+await acct.activate();
+await acct.send(to, 1_000_000n);
+await acct.execute([instruction]);
+await acct.rekey();
+
+acct.close();
+await store.close();
+```
+
+- `acct.address` is the quantum account. Keep funds there.
+- `await acct.feeKey()` returns the fee key's address. It only pays Solana network fees, signs with Ed25519 and is not quantum-safe, so keep only a little SOL on it.
+- `activate()` writes the account's key root on chain once. The fee key pays for it.
+- `checkRpcUrl` is required on mainnet and must be another provider. Before the wallet ever reuses a key slot after a failure, both RPCs must agree the old transaction can no longer land.
+- `execute()` takes web3.js-style instructions (`{ programId, keys, data }`) or `[program, [[key, signer, writable]], data]`. The account signs as the wallet address; no other key may be marked as a signer. Data must be a `Uint8Array`/`Buffer`, a hex string or an array of bytes 0-255; anything else is refused rather than guessed.
+- Amounts are whole numbers in base units (lamports, wei) as bigint, integer or digit string.
+- `status()` reports how many one-time keys are left. Call `rekey()` before they run out; it moves the account to a new tree.
+- `recover(words, password)` brings an existing account into a new store. Then call `useHere()` (see the rule above).
+
+## EVM
+
+```js
+const acct = await vault.open(id, password);
+const base = await acct.evm(8453, { rpcUrl: "https://your-base-rpc", checkUrl: "https://a-second-base-rpc" });
+
+console.log(base.address, base.feeAddress);
+await base.setup();
+await base.send(to, 10n ** 16n);
+await base.execute([{ to: token, value: 0n, data: "0xa9059cbb..." }]);
+
+acct.close();
+```
+
+- Chains: 1 (Ethereum), 8453 (Base), 42161 (Arbitrum), 4663 (Robinhood Chain), 99901 (Elysium, gas in HYPE).
+- `checkUrl` must be a second, independent RPC. Before signing, the SDK checks the account state on both and refuses if they disagree.
+- The same words give the same account address on every chain.
+- The fee key (`feeAddress`) pays gas. It is an ordinary secp256k1 key, so keep only gas money on it.
+- `setup()` deploys the account contract and moves it to a key tree only this device knows. It needs gas on the fee key.
+
+## Verify without trusting anyone
+
+```js
+import { verifySolanaInstruction, verifyEvmExecute } from "@opeqlabs/sdk";
+
+verifySolanaInstruction(data, accountKeys, { pubSeed, root, aid, epoch });
+verifyEvmExecute(calldata, { chainId, account, epoch, pubSeed, root });
+```
+
+Both return the one-time key index, or `null` if the signature does not match or the input is malformed. They make no network calls. `verifyEvmExecute` only accepts calldata in the exact form the account contract decodes. `verifyWots` checks every length (16-byte digest, full signature and path, leaf inside the tree) before verifying. `examples/verify.mjs` checks a landed Solana transaction against the account's key root on chain.
+
+## Speed
+
+Building a key tree takes about 2 seconds on Solana and about 10 seconds on EVM in Node on a laptop. Signing takes under a second. EVM `setup()` builds three trees, so it takes about a minute. In a browser, pass `new Vault({ compute })` with a `run(op, args)` that hands the job to a Web Worker running `OPS` from `@opeqlabs/sdk/compute`, so the page does not freeze.
+
+## RPC
+
+Bring your own, two per network from different providers, over https. `rpc.opeq.io` only serves the OPEQ apps.
+
+## Known limits
+
+- On EVM, a takeover (`useHere()`) picks its one-time key from the local record. If two devices take over the same account at the same moment, or a store is lost and restored, they can pick the same key. Take over from one device at a time and never restore a store from a backup.
+
+## Tests
+
+```
+python3 build_sdk.py
+node sdk/test/run.mjs
+node sdk/test/e2e_anvil.mjs
+node sdk/test/e2e_devnet.mjs <funded devnet keypair json>
+node sdk/test/attack.mjs
+```
+
+- `run.mjs` checks the JS code against vectors from the Python reference implementation (`sdk/test/gen_vectors.py`): words, key trees, addresses, signatures and the exact signed message. Every result must be byte-identical.
+- `e2e_anvil.mjs` runs a full EVM account on a local chain: setup, sends, offline verification, and a takeover from a second device.
+- `e2e_devnet.mjs` does the same on Solana devnet: activate, send, verify, rekey.
+- `attack.mjs` runs the attacks from the security review: lock races between processes, symlink and permission tricks on the wallet folder, signature forgeries against the verifiers, malformed amounts and data, shared fee keys, and packing a stray wallet file.
+
+## License
+
+Apache-2.0

package/examples/evm-send.mjs

@@ -0,0 +1,27 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Vault } from "@opeqlabs/sdk";
+import { FileStore } from "@opeqlabs/sdk/filestore";
+
+const [, , cmd, ...rest] = process.argv;
+const chainId = Number(process.env.OPEQ_CHAIN || 8453);
+const password = process.env.OPEQ_PASSWORD;
+const rpcUrl = process.env.OPEQ_EVM_RPC, checkUrl = process.env.OPEQ_EVM_CHECK;
+if (!password || !rpcUrl || !checkUrl) throw new Error("set OPEQ_PASSWORD, OPEQ_EVM_RPC and OPEQ_EVM_CHECK (two independent RPCs)");
+
+const store = await FileStore.open(process.env.OPEQ_DIR || join(homedir(), ".opeq-sdk-wallet"));
+const vault = new Vault({ rpcUrl: process.env.OPEQ_RPC || "https://api.mainnet-beta.solana.com", checkRpcUrl: process.env.OPEQ_CHECK_RPC || "https://solana-rpc.publicnode.com", network: process.env.OPEQ_NETWORK || "mainnet", store });
+try {
+  const [w] = await vault.list();
+  if (!w) throw new Error("no wallet yet, create one with solana-send.mjs create");
+  const acct = await vault.open(w.id, password);
+  try {
+    const evm = await acct.evm(chainId, { rpcUrl, checkUrl });
+    console.log("account", evm.address, "fee key", evm.feeAddress);
+    if (cmd === "status") console.log(await evm.status());
+    else if (cmd === "setup") console.log(await evm.setup(null, (s) => console.log("-", s)));
+    else if (cmd === "send") console.log(await evm.send(rest[0], BigInt(rest[1]), (h) => console.log("tx", h)));
+    else if (cmd === "rekey") console.log(await evm.rekey());
+    else console.log("commands: status, setup, send <to> <wei>, rekey");
+  } finally { acct.close(); }
+} finally { await store.close(); }

package/examples/solana-send.mjs

@@ -0,0 +1,34 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Vault, NETWORKS } from "@opeqlabs/sdk";
+import { FileStore } from "@opeqlabs/sdk/filestore";
+
+const [, , cmd, ...rest] = process.argv;
+const network = process.env.OPEQ_NETWORK || "devnet";
+const password = process.env.OPEQ_PASSWORD;
+if (!password) throw new Error("set OPEQ_PASSWORD");
+if (!process.env.OPEQ_RPC) throw new Error(`set OPEQ_RPC to a Solana ${network} RPC URL`);
+if (network === "mainnet" && !process.env.OPEQ_CHECK_RPC) throw new Error("set OPEQ_CHECK_RPC to a second Solana RPC from another provider");
+
+const store = await FileStore.open(process.env.OPEQ_DIR || join(homedir(), ".opeq-sdk-wallet"));
+const vault = new Vault({ rpcUrl: process.env.OPEQ_RPC, checkRpcUrl: process.env.OPEQ_CHECK_RPC, network, store });
+try {
+  if (cmd === "create") {
+    const { id, words } = await vault.create(password);
+    console.log("wallet", id);
+    console.log("write these 24 words down and keep them offline:\n" + words);
+  } else {
+    const [w] = await vault.list();
+    if (!w) throw new Error("no wallet yet, run: create");
+    const acct = await vault.open(w.id, password);
+    try {
+      console.log("wallet", acct.address, "fee key", await acct.feeKey());
+      if (cmd === "activate") console.log(await acct.activate());
+      else if (cmd === "status") console.log(await acct.status(), "balance", await acct.balance());
+      else if (cmd === "send") console.log("signature", await acct.send(rest[0], BigInt(rest[1])));
+      else if (cmd === "rekey") console.log(await acct.rekey());
+      else console.log("commands: create, activate, status, send <to> <lamports>, rekey");
+    } finally { acct.close(); }
+  }
+} finally { await store.close(); }
+console.log("program", NETWORKS[network].program);

package/examples/verify.mjs

@@ -0,0 +1,29 @@
+import { NETWORKS, verifySolanaInstruction, b58decode, b58encode, lowLevel } from "@opeqlabs/sdk";
+
+const [, , rpcUrl, signature, network = "mainnet"] = process.argv;
+if (!rpcUrl || !signature) throw new Error("usage: node verify.mjs <solana rpc> <transaction signature> [mainnet|devnet]");
+const call = async (method, params) => {
+  const r = await fetch(rpcUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });
+  const j = await r.json();
+  if (j.error) throw new Error(j.error.message);
+  return j.result;
+};
+const program = NETWORKS[network].program;
+const tx = await call("getTransaction", [signature, { encoding: "json", maxSupportedTransactionVersion: 0 }]);
+if (!tx) throw new Error("transaction not found");
+if (tx.meta.err) console.log("note: this transaction failed on chain:", JSON.stringify(tx.meta.err));
+const m = tx.transaction.message, la = tx.meta.loadedAddresses || {};
+const keys = [...m.accountKeys, ...(la.writable || []), ...(la.readonly || [])];
+const found = m.instructions.filter((x) => keys[x.programIdIndex] === program);
+if (!found.length) throw new Error("this transaction has no top-level OPEQ instruction");
+for (const ix of found) {
+  const accounts = ix.accounts.map((a) => keys[a]);
+  const state = await call("getAccountInfo", [accounts[0], { encoding: "base64" }]);
+  if (!state.value || state.value.owner !== program) { console.log("skipped: the first account is not an OPEQ state account"); continue; }
+  const st = lowLevel.protocol.unpackState(Uint8Array.from(atob(state.value.data[0]), (c) => c.charCodeAt(0)));
+  const P = lowLevel.protocol, prog = b58decode(program);
+  const acc = { state: b58encode(P.statePda(st.id, prog).key), wallet: b58encode(P.walletPda(st.id, prog).key) };
+  if (acc.state !== accounts[0] || acc.wallet !== accounts[1]) { console.log("skipped: state and wallet accounts do not belong together"); continue; }
+  const leaf = verifySolanaInstruction(b58decode(ix.data), accounts, { pubSeed: st.pubSeed, root: st.root, aid: st.id, epoch: st.epoch }, network);
+  console.log(`wallet ${acc.wallet}:`, leaf === null ? "does not verify against the current key tree (it may have been signed before a rekey)" : `valid quantum signature, one-time key #${leaf}`);
+}

package/filestore.js

@@ -0,0 +1,149 @@
+import { promises as fs, constants as C, openSync, writeSync, closeSync, readFileSync, unlinkSync, linkSync, lstatSync, fsyncSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { checkForward } from "./src/lib/vaultstore.js";
+
+const LOCK = ".lock";
+const TAKEOVER = ".takeover";
+const NOFOLLOW = C.O_NOFOLLOW || 0;
+
+const name = (id) => createHash("sha256").update(String(id)).digest("hex") + ".json";
+
+const encode = (r) => JSON.stringify(r, (k, v) => (typeof v === "bigint" ? { $big: v.toString() } : v));
+const decode = (s) => JSON.parse(s, (k, v) => (v && typeof v === "object" && Object.keys(v).length === 1 && typeof v.$big === "string" ? BigInt(v.$big) : v));
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+function readLock(path) {
+  try { return readFileSync(path, "utf8"); } catch (e) { if (e.code === "ENOENT") return null; throw e; }
+}
+
+function pidOf(text) {
+  const m = /^(\d+) [0-9a-f]{32}$/.exec(text || "");
+  return m ? Number(m[1]) : null;
+}
+
+function exclusive(path, text) {
+  const fd = openSync(path, C.O_WRONLY | C.O_CREAT | C.O_EXCL | NOFOLLOW, 0o600);
+  try { writeSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function checkDir(dir) {
+  const st = lstatSync(dir);
+  if (st.isSymbolicLink() || !st.isDirectory()) throw new Error("the wallet folder must be a real folder, not a link");
+  if (typeof process.getuid === "function") {
+    if (st.uid !== process.getuid()) throw new Error("the wallet folder belongs to another user");
+    if (st.mode & 0o077) throw new Error(`the wallet folder can be read or changed by other users (mode ${(st.mode & 0o777).toString(8)}); run chmod 700 on it`);
+  }
+}
+
+function takeLock(dir) {
+  const path = join(dir, LOCK);
+  const mine = `${process.pid} ${randomBytes(16).toString("hex")}`;
+  const tmp = join(dir, `.lock-${randomBytes(8).toString("hex")}`);
+  exclusive(tmp, mine);
+  try {
+    try { linkSync(tmp, path); return mine; } catch (e) { if (e.code !== "EEXIST") throw e; }
+    const held = readLock(path);
+    const pid = pidOf(held);
+    if (pid === null || alive(pid)) {
+      throw new Error(`another process${pid ? ` (pid ${pid})` : ""} is using this wallet folder; one-time keys must never be used from two places at once`);
+    }
+    const tk = join(dir, TAKEOVER);
+    try { exclusive(tk, mine); } catch (e) {
+      if (e.code === "EEXIST") throw new Error(`another process is taking over this wallet folder. If none is running, delete ${tk}`);
+      throw e;
+    }
+    try {
+      const again = readLock(path);
+      if (again !== held) throw new Error("the wallet folder lock changed while taking it over; try again");
+      unlinkSync(path);
+      try { linkSync(tmp, path); } catch (e) {
+        if (e.code === "EEXIST") throw new Error("another process took this wallet folder first");
+        throw e;
+      }
+      return mine;
+    } finally { try { unlinkSync(tk); } catch {} }
+  } finally { try { unlinkSync(tmp); } catch {} }
+}
+
+export class FileStore {
+  static async open(dir) {
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    checkDir(dir);
+    return new FileStore(dir, takeLock(dir));
+  }
+
+  constructor(dir, token) {
+    if (!token) throw new Error("use FileStore.open(dir)");
+    this.dir = dir;
+    this.token = token;
+    this.lockPath = join(dir, LOCK);
+    this.closed = false;
+    this.queue = Promise.resolve();
+  }
+
+  live() {
+    if (this.closed) throw new Error("this wallet store is closed");
+    if (readLock(this.lockPath) !== this.token) {
+      this.closed = true;
+      throw new Error("this process no longer holds the wallet folder lock; stopping before any key is used");
+    }
+  }
+
+  serial(fn) {
+    const run = this.queue.then(() => { this.live(); return fn(); });
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  async read(file) {
+    let h;
+    try { h = await fs.open(join(this.dir, file), C.O_RDONLY | NOFOLLOW); }
+    catch (e) { if (e.code === "ENOENT") return null; if (e.code === "ELOOP") throw new Error("a wallet record is a link, refusing to read it"); throw e; }
+    try {
+      if (!(await h.stat()).isFile()) throw new Error("a wallet record is not a regular file");
+      return decode(await h.readFile("utf8"));
+    } finally { await h.close(); }
+  }
+
+  async all() {
+    this.live();
+    const out = [];
+    for (const f of await fs.readdir(this.dir)) if (/^[0-9a-f]{64}\.json$/.test(f)) { const r = await this.read(f); if (r) out.push(r); }
+    return out;
+  }
+
+  async get(id) { this.live(); return this.read(name(id)); }
+
+  put(r) {
+    this.live();
+    return this.serial(async () => {
+      const file = name(r.id);
+      checkForward(await this.read(file), r);
+      const tmp = join(this.dir, `.${randomBytes(12).toString("hex")}.tmp`);
+      const h = await fs.open(tmp, C.O_WRONLY | C.O_CREAT | C.O_EXCL | NOFOLLOW, 0o600);
+      try { await h.writeFile(encode(r)); await h.sync(); } finally { await h.close(); }
+      try { await fs.rename(tmp, join(this.dir, file)); } catch (e) { await fs.rm(tmp, { force: true }); throw e; }
+      const d = await fs.open(this.dir, "r");
+      try { await d.sync(); } catch {} finally { await d.close(); }
+    });
+  }
+
+  del(id) {
+    this.live();
+    return this.serial(async () => { await fs.rm(join(this.dir, name(id)), { force: true }); });
+  }
+
+  async close() {
+    if (this.closed) return;
+    const pending = this.queue;
+    this.queue = this.queue.then(() => { throw new Error("this wallet store is closed"); });
+    this.queue.catch(() => {});
+    await pending;
+    this.closed = true;
+    if (readLock(this.lockPath) === this.token) { try { unlinkSync(this.lockPath); } catch {} }
+  }
+}