@spirobel/monero-wallet-api 0.2.0 → 0.3.0

package/dist/io/indexedDB.js

@@ -0,0 +1,221 @@
+import { writeEnvLineToDotEnvRefresh } from "../keypairs-seeds/writeKeypairs";
+class IndexedDBBun {
+    stdin = new IndexedDBFile();
+    stdout = new IndexedDBFile();
+    stderr = new IndexedDBFile();
+    file(path, options) {
+        return new IndexedDBFile(getFileFromIndexedDB(path.toString()), path.toString());
+    }
+    async write(destination, input) {
+        return await putFileIntoIndexedDB(destination.toString(), input);
+    }
+    env = {};
+}
+class IndexedDBFile {
+    content;
+    path;
+    size = 0;
+    type = "";
+    constructor(content, path) {
+        this.content = content;
+        this.path = path;
+    }
+    async text() {
+        const result = (await this.content);
+        if (!result)
+            throw new Error(`no such file or directory, open '${this.path}'`);
+        return result;
+    }
+    stream() {
+        throw new Error("not implemented");
+        return new ReadableStream();
+    }
+    async arrayBuffer() {
+        const result = (await this.content);
+        if (!result)
+            throw new Error(`no such file or directory, open '${this.path}'`);
+        return result;
+    }
+    json() {
+        throw new Error("not implemented");
+        return Promise.resolve({});
+    }
+    writer(params) {
+        throw new Error("not implemented");
+        return new BunFileSink();
+    }
+    exists() {
+        throw new Error("not implemented");
+        return Promise.resolve(false);
+    }
+    delete() {
+        return deleteFileFromIndexedDB(this.path);
+    }
+}
+class BunFileSink {
+    write(chunk) {
+        throw new Error("not implemented");
+        return 0;
+    }
+    flush() {
+        throw new Error("not implemented");
+        return 0;
+    }
+    end(error) {
+        throw new Error("not implemented");
+        return 0;
+    }
+    start(options) {
+        throw new Error("not implemented");
+    }
+    ref() {
+        throw new Error("not implemented");
+    }
+    unref() {
+        throw new Error("not implemented");
+    }
+}
+export async function getItemLength(input) {
+    if (typeof input === "string") {
+        return [input, new TextEncoder().encode(input).length];
+    }
+    if (input instanceof Blob) {
+        return [input, input.size];
+    }
+    if (ArrayBuffer.isView(input)) {
+        return [input.buffer, input.byteLength];
+    }
+    if ("arrayBuffer" in input) {
+        const bytes = await input.arrayBuffer();
+        return [bytes, bytes.byteLength];
+    }
+    // SharedArrayBuffer/ArrayBuffer fallback
+    if ("byteLength" in input) {
+        return [input, input.byteLength];
+    }
+    throw new Error(`ENOSPC: unsupported input type`);
+}
+export async function putFileIntoIndexedDB(path, content) {
+    if (!browserGlobal.filesDb) {
+        throw new Error("IndexedDB not initialized");
+    }
+    const [dbContent, byteLength] = await getItemLength(content);
+    const tx = browserGlobal.filesDb.transaction(fileStoreName, "readwrite");
+    const store = tx.objectStore(fileStoreName);
+    const request = store.put(dbContent, path);
+    return await new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(byteLength);
+        request.onerror = () => reject(request.error);
+    });
+}
+export function getFileFromIndexedDB(path) {
+    if (!browserGlobal.filesDb) {
+        throw new Error("IndexedDB not initialized");
+    }
+    else {
+        const tx = browserGlobal.filesDb.transaction(fileStoreName, "readonly");
+        const store = tx.objectStore(fileStoreName);
+        const request = store.get(path);
+        return new Promise((resolve, reject) => {
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+}
+export async function deleteFileFromIndexedDB(path) {
+    if (!browserGlobal.filesDb) {
+        throw new Error("IndexedDB not initialized");
+    }
+    const tx = browserGlobal.filesDb.transaction(fileStoreName, "readwrite");
+    const store = tx.objectStore(fileStoreName);
+    const request = store.delete(path.trim());
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+    });
+}
+export const fileStoreName = "files";
+async function initFilesDB() {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(fileStoreName);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+        request.onupgradeneeded = () => request.result.createObjectStore(fileStoreName);
+    });
+}
+// In browsers: window in main thread, self in workers
+const hasWindow = typeof window !== "undefined";
+const hasSelf = typeof self !== "undefined";
+//@ts-ignore
+const browserGlobal = hasWindow ? window : hasSelf ? self : {}; // non-browser -> no shimming
+if (typeof globalThis.Bun === "undefined") {
+    browserGlobal.filesDb = await initFilesDB();
+    browserGlobal.Bun = new IndexedDBBun();
+    browserGlobal.Bun.env = await readEnvIndexedDB();
+    browserGlobal.areWeInTheBrowser = true;
+}
+else {
+    browserGlobal.areWeInTheBrowser = false;
+}
+export async function refreshEnvIndexedDB() {
+    browserGlobal.Bun.env = await readEnvIndexedDB();
+}
+// we need this to change the env at runtime from inside the Browser extension,
+// or react native app. Or to persist view keys in bun web backend.
+// this one is specifically for indexedDB (convention of treating .env as Bun.env)
+export async function writeEnvIndexedDB(key, value) {
+    // this file should be treated as ephemeral
+    // private spendkeys + viewkeys are deterministically derived from seedphrase and password
+    // we have to go through indexedDB just so the background worker has access to this.
+    // (after waking up from an alarm or onmessage event)
+    await writeEnvLineToDotEnvRefresh(key, value, ".env");
+}
+export async function readEnvIndexedDB() {
+    const file = Bun.file(".env");
+    const content = await file
+        .text()
+        .catch(() => { })
+        .then((c) => c || "");
+    const lines = content.split("\n");
+    const result = {};
+    for (const line of lines) {
+        const keyValue = line.split("=");
+        const key = keyValue[0];
+        if (!key)
+            continue;
+        const value = keyValue[1];
+        result[key.trim()] = value?.trim();
+    }
+    return result;
+}
+/**
+ * useless function
+ * you can just do process.env[key] instead. Look at the code above.
+ * @param key
+ * @returns value
+ */
+export async function readEnvIndexedDBLine(key) {
+    const file = Bun.file(".env");
+    const content = await file.text();
+    const lines = content.split("\n");
+    const idx = lines.findIndex((line) => line.startsWith(key.trim()));
+    return lines[idx].split("=")[1].trim();
+}
+export async function readdir(dirpath) {
+    if (!browserGlobal.filesDb) {
+        throw new Error("IndexedDB not initialized");
+    }
+    let prefix = dirpath.trim();
+    if (prefix && !prefix.endsWith("/")) {
+        prefix += "/";
+    }
+    const tx = browserGlobal.filesDb.transaction(fileStoreName, "readonly");
+    const store = tx.objectStore(fileStoreName);
+    const range = IDBKeyRange.bound(prefix, prefix + "\uffff", false, true);
+    const keys = await new Promise((resolve, reject) => {
+        const request = store.getAllKeys(range);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+    return keys.map((key) => key.slice(prefix.length));
+}

package/dist/io/readDir.d.ts

@@ -0,0 +1 @@
+export declare function readDir(path: string): Promise<string[]>;

package/dist/io/readDir.js

@@ -0,0 +1,7 @@
+import { readdir as indexedDBreaddir } from "./indexedDB";
+export async function readDir(path) {
+    if (areWeInTheBrowser)
+        return await indexedDBreaddir(path);
+    const { readdir } = await import("node:fs/promises");
+    return await readdir(path);
+}

package/dist/io/sleep.d.ts

@@ -0,0 +1 @@
+export declare const sleep: (ms: number) => Promise<unknown>;

package/dist/io/sleep.js

@@ -0,0 +1 @@
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/dist/keypairs-seeds/keypairs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * "So when we first decided to create a mnemonic system the spec we
+ * came up with was: take the seed from the mnemonic, hash it for the
+ * spend key, hash it twice for the view key. Somewhere during the
+ * simplewallet implementation we forgot about that, and just used the
+ * mnemonic seed as the spendkey directly.
+ *
+ * This proved to be a blessing in disguise, though, as we'd not realised
+ * that people might want to retrieve their seed. Using our original
+ * design this wouldn't have been possible, as we didn't store the seed
+ * in the wallet file.
+ *
+ * Much later on when we were creating MyMonero (a different group of
+ * developers, I'm the only common link between the two) we decided that
+ * a 13 word seed would be much easier for people to remember, but
+ * because we wanted it to match simplewallet's implementation we made
+ * sure that we followed the spec... as it was originally... before we
+ * duffed the implementation."
+ */
+export type SpendKey = string;
+export declare function makeSpendKey(): Promise<SpendKey>;
+export declare function makeSpendKeyFromSeed(wallet_secret: string): Promise<SpendKey>;
+export type ViewPairJson = {
+    view_key: string;
+    mainnet_primary: string;
+    stagenet_primary: string;
+    testnet_primary: string;
+};
+export declare function makeViewKey(spend_private_key: string): Promise<ViewPairJson>;

package/dist/keypairs-seeds/keypairs.js

@@ -0,0 +1,207 @@
+/**
+ * "So when we first decided to create a mnemonic system the spec we
+ * came up with was: take the seed from the mnemonic, hash it for the
+ * spend key, hash it twice for the view key. Somewhere during the
+ * simplewallet implementation we forgot about that, and just used the
+ * mnemonic seed as the spendkey directly.
+ *
+ * This proved to be a blessing in disguise, though, as we'd not realised
+ * that people might want to retrieve their seed. Using our original
+ * design this wouldn't have been possible, as we didn't store the seed
+ * in the wallet file.
+ *
+ * Much later on when we were creating MyMonero (a different group of
+ * developers, I'm the only common link between the two) we decided that
+ * a 13 word seed would be much easier for people to remember, but
+ * because we wanted it to match simplewallet's implementation we made
+ * sure that we followed the spec... as it was originally... before we
+ * duffed the implementation."
+ */
+// Source: https://old.reddit.com/r/Monero/comments/3s80l2/why_mymonero_key_derivation_is_different_than_for/cwv5lzs/
+// rpc create new wallet command handling code calls generate() method on wallet2 object instance
+// 3653:       wal->generate(wallet_file, req.password, dummy_key, false, false);
+//https://github.com/monero-project/monero/blob/48ad374b0d6d6e045128729534dc2508e6999afe/src/wallet/wallet_rpc_server.cpp#L3653
+// wallet2.cpp generate method definition last few lines, notice it returns retval which is the result of m_account.generate():
+/**
+ *  crypto::secret_key retval = m_account.generate(recovery_param, recover, two_random);
+
+  [ ... ommitted irrelevant wallet key file saving lines... ]
+  return retval;
+}
+ */
+// https://github.com/monero-project/monero/blob/48ad374b0d6d6e045128729534dc2508e6999afe/src/wallet/wallet2.cpp#L5683
+// the account.generate() method is defined in account.cpp.
+// Relevant lines show it calls the crypto.cpp generate_keys() method twice.
+// 1. the first call uses a random number generator to make the spend private key
+//    (and calls sc_reduce32 on it to make sure it is a valid ed25519 scalar)
+// 2. then it hashes that spend private key with keccak to make the view private key
+// 3. then it calls generate_keys() again on this hashed value to make the view private key
+//   (to make sure via sc_reduce32 that the view private key is a valid ed25519 scalar)
+//
+// another side effect of this generate_keys function is that it creates the respective public keys from the private keys
+/**
+ *   crypto::secret_key first = generate_keys(m_keys.m_account_address.m_spend_public_key, m_keys.m_spend_secret_key, recovery_key, recover);
+
+    // rng for generating second set of keys is hash of first rng.  means only one set of electrum-style words needed for recovery
+    crypto::secret_key second;
+    keccak((uint8_t *)&m_keys.m_spend_secret_key, sizeof(crypto::secret_key), (uint8_t *)&second, sizeof(crypto::secret_key));
+
+    generate_keys(m_keys.m_account_address.m_view_public_key, m_keys.m_view_secret_key, second, two_random ? false : true);
+    [ ... ommitted irrelevant timestamp lines... ]
+     return first; [... returns first which is the spend private key ... ]
+ */
+// https://github.com/monero-project/monero/blob/48ad374b0d6d6e045128729534dc2508e6999afe/src/cryptonote_basic/account.cpp#L166-L195
+// generate_keys() method definition shows it calls sc_reduce32 on the input key material to make sure it is a valid ed25519 scalar
+// https://github.com/monero-project/monero/blob/master/src/crypto/crypto.cpp#L153
+// side note: simplewallet cpp codepath is similar to the walletrpc server codepath shown above
+// cryptonote_basic/account.cpp  generate() method returns first (also known as the spend private key) which becomes recovery_val:
+// 4832 recovery_val = m_wallet->generate(m_wallet_file, std::move(rc.second).password(), recovery_key, recover, two_random, create_address_file);
+// https://github.com/monero-project/monero/blob/48ad374b0d6d6e045128729534dc2508e6999afe/src/simplewallet/simplewallet.cpp#L4832
+// simple wallet turns spend private key (recovery_val) into mnemonic words with this call:
+// 4849   crypto::ElectrumWords::bytes_to_words(recovery_val, electrum_words, mnemonic_language);
+// https://github.com/monero-project/monero/blob/48ad374b0d6d6e045128729534dc2508e6999afe/src/simplewallet/simplewallet.cpp#L4849
+import { WasmProcessor } from "../wasm-processing/wasmProcessor";
+export async function makeSpendKey() {
+    const wasmProcessor = await WasmProcessor.init();
+    let result = undefined;
+    wasmProcessor.readFromWasmMemory = (ptr, len) => {
+        result = String(wasmProcessor.readString(ptr, len));
+    };
+    //@ts-ignore
+    wasmProcessor.tinywasi.instance.exports.make_spendkey();
+    if (!result) {
+        throw new Error("Failed to make spend key");
+    }
+    return result;
+}
+export async function makeSpendKeyFromSeed(wallet_secret) {
+    if (wallet_secret.length !== 128) {
+        throw new Error(`Invalid wallet secret length: ${wallet_secret.length}.
+       Expected 128 hex characters (64 bytes).`);
+    }
+    const wasmProcessor = await WasmProcessor.init();
+    wasmProcessor.writeToWasmMemory = (ptr, len) => {
+        wasmProcessor.writeString(ptr, len, wallet_secret);
+    };
+    let result = undefined;
+    wasmProcessor.readFromWasmMemory = (ptr, len) => {
+        result = String(wasmProcessor.readString(ptr, len));
+    };
+    //@ts-ignore
+    wasmProcessor.tinywasi.instance.exports.make_spendkey_from_seed(wallet_secret.length);
+    if (!result) {
+        throw new Error("Failed to obtain spend_key from seed.");
+    }
+    return result;
+}
+export async function makeViewKey(spend_private_key) {
+    if (spend_private_key.length !== 64) {
+        throw new Error(`Invalid spendkey length: ${spend_private_key.length}.
+       Expected 64 hex characters (32 bytes).`);
+    }
+    const wasmProcessor = await WasmProcessor.init();
+    wasmProcessor.writeToWasmMemory = (ptr, len) => {
+        wasmProcessor.writeString(ptr, len, spend_private_key);
+    };
+    let result = undefined;
+    wasmProcessor.readFromWasmMemory = (ptr, len) => {
+        result = JSON.parse(wasmProcessor.readString(ptr, len));
+    };
+    //@ts-ignore
+    wasmProcessor.tinywasi.instance.exports.make_viewkey(spend_private_key.length);
+    if (!result) {
+        throw new Error("Failed to obtain view key from spend key.");
+    }
+    return result;
+}
+/**
+ *
+ * unlike crypto-ops.c sc_reduce32, this is not unrolled
+ * we run this once at wallet creation, no timing side channel expected,
+ * goal is to be as clear as possible.
+ *
+ * crypto-ops.c source: https://github.com/monero-project/monero/blob/master/src/crypto/crypto-ops.c#L2432-L2544
+ * @param input - random 32 bytes used as seed, private key
+ * @returns - reduced 32 bytes that are a valid ed25519 scalar
+ */
+function sc_reduce32(input) {
+    if (input.length !== 32)
+        throw new Error("Input must be 32 bytes");
+    const x = bytesToBigInt(input);
+    const l = 2n ** 252n + 27742317777372353535851937790883648493n;
+    const reduced = x % l;
+    return bigIntToBytes(reduced);
+}
+// l source: https://datatracker.ietf.org/doc/html/rfc8032#section-5.1
+/**
+ * This function turns a list of bytes into one big number.
+ * It uses a loop to add up each byte after moving it to the right spot.
+ * Each byte is like a digit in a number where positions grow by 256 each time.
+ * Shifting left by 8 bits per position multiplies by 256 to place it correctly.
+ * This builds the full number step by step without mistakes.
+ */
+function bytesToBigInt(bytes) {
+    return bytes.reduce((acc, byte, i) => acc + (BigInt(byte) << BigInt(i * 8)), 0n);
+}
+/**
+ * The function starts with 0 as the total.
+ * It takes the first byte and adds it as is.
+ * For the next byte, it moves it left by 8 bits before adding.
+ * This move makes room for the previous byte below it.
+ * Each further byte shifts more to stack on top.
+ */
+// Other direction:
+/**
+ * This function breaks a big number into a list of small bytes.
+ * It creates a list of fixed size and fills each spot with one byte from the number.
+ * Shifting right brings the right part down to grab it.
+ * Masking keeps only that one byte and ignores the rest.
+ * It does this for each position to get the full list.
+ */
+function bigIntToBytes(value, length = 32) {
+    return Uint8Array.from({ length }, (_, i) => Number((value >> BigInt(i * 8)) & 0xffn));
+}
+/**
+ * The function makes an empty list of the given length.
+ * For the first spot, it takes the lowest byte.
+ * It shifts the number right by 0 bits at start.
+ * Masking with 255 grabs just 8 bits.
+ * For the next spot, it shifts right by 8 bits first.
+ */
+function testBigIntUint8Conversion(originalBigInt, length = 32) {
+    const bytes = bigIntToBytes(originalBigInt, length);
+    const reconstructedBigInt = bytesToBigInt(bytes);
+    console.log("Original BigInt:", originalBigInt);
+    console.log("Bytes:", bytes);
+    console.log("Reconstructed BigInt:", reconstructedBigInt);
+    return originalBigInt === reconstructedBigInt;
+}
+// usage
+// const testValue = 123456789012345678901234567890n; // A BigInt fitting < 32 bytes
+// console.log("Test result:", testBigIntUint8Conversion(testValue)); // Should log true
+function testScReduce32() {
+    const secret_key = new Uint8Array(32);
+    crypto.getRandomValues(secret_key);
+    const reduced = sc_reduce32(secret_key);
+    const reducedBigInt = bytesToBigInt(reduced);
+    const l = 2n ** 252n + 27742317777372353535851937790883648493n;
+    const isValid = reducedBigInt >= 0n && reducedBigInt < l && reduced.length === 32;
+    console.log("Random input:", secret_key);
+    console.log("Reduced output:", reduced);
+    console.log("Reduced as BigInt:", reducedBigInt);
+    console.log("Is valid Ed25519 scalar:", isValid);
+    // non random example (do not use not cryptographically secure values in production. use crypto.getRandomValues for real keys)
+    const deadbeef = new Uint8Array(32).fill(0xde);
+    const reducedDeadbeef = sc_reduce32(deadbeef);
+    const reducedDeadbeefBigInt = bytesToBigInt(reducedDeadbeef);
+    const isValidDeadbeef = reducedDeadbeefBigInt >= 0n &&
+        reducedDeadbeefBigInt < l &&
+        reducedDeadbeef.length === 32;
+    console.log("Deadbeef input:", deadbeef);
+    console.log("Reduced deadbeef output:", reducedDeadbeef);
+    console.log("Reduced deadbeef as BigInt:", reducedDeadbeefBigInt);
+    console.log("Is valid Ed25519 scalar (deadbeef):", isValidDeadbeef);
+    return isValid && isValidDeadbeef;
+}
+// usage
+// console.log("Test result:", testScReduce32()); // Should log true

package/dist/keypairs-seeds/writeKeypairs.d.ts

@@ -0,0 +1,11 @@
+export declare const stagenet_pk_path = ".env";
+export declare const testnet_pk_path = ".env.local";
+export declare const regtest_pk_path = ".env.local";
+export declare function writeStagenetSpendViewKeysToDotEnv(spend_key?: string): Promise<string>;
+export declare function writeRegtestSpendViewKeysToDotEnvTestLocal(spend_key?: string): Promise<string>;
+export declare function writeTestnetSpendViewKeysToDotEnvLocal(spend_key?: string): Promise<string>;
+export declare function writeWalletSecretsToDotEnv(wallet_secret: Uint8Array): Promise<string>;
+export declare function writeEnvLineToDotEnvRefresh(key: string, value: string, path?: string): Promise<void>;
+export declare function writeEnvLineToDotEnv(key: string, value: string, path?: string): Promise<void>;
+export declare const STAGENET_FRESH_WALLET_HEIGHT_DEFAULT = 2014841;
+export declare const REGTEST_FRESH_WALLET_HEIGHT_DEFAULT = 1;

package/dist/keypairs-seeds/writeKeypairs.js

@@ -0,0 +1,75 @@
+// write testnet keys .env.local
+// write stagenet keys .env
+// write mainnet keys to stdout can > redirect to the place of your desires
+// (but you really shouldnt, use a seedphrase instead)
+import { atomicWrite } from "../io/atomicWrite";
+import { makeSpendKey, makeSpendKeyFromSeed, makeViewKey } from "./keypairs";
+export const stagenet_pk_path = ".env";
+export const testnet_pk_path = ".env.local";
+export const regtest_pk_path = ".env.local";
+// writes "vkPRIMARY_KEY=<view_key> \n skPRIMARY_KEY=<spend_key>" to .env for stagenet
+export async function writeStagenetSpendViewKeysToDotEnv(spend_key) {
+    spend_key = spend_key || (await makeSpendKey());
+    let view_pair = await makeViewKey(spend_key);
+    let primary_address = view_pair.stagenet_primary;
+    await writeEnvLineToDotEnvRefresh(`vk${primary_address}`, view_pair.view_key, stagenet_pk_path);
+    await writeEnvLineToDotEnvRefresh(`sk${primary_address}`, spend_key, stagenet_pk_path);
+    return primary_address;
+}
+// writes "vkPRIMARY_KEY=<view_key> \n skPRIMARY_KEY=<spend_key>" to .env.local for regtest
+export async function writeRegtestSpendViewKeysToDotEnvTestLocal(spend_key) {
+    spend_key = spend_key || (await makeSpendKey());
+    let view_pair = await makeViewKey(spend_key);
+    let primary_address = view_pair.mainnet_primary; // regtest uses mainet style addresses
+    await writeEnvLineToDotEnvRefresh(`vk${primary_address}`, view_pair.view_key, regtest_pk_path);
+    await writeEnvLineToDotEnvRefresh(`sk${primary_address}`, spend_key, regtest_pk_path);
+    return primary_address;
+}
+// writes "vkPRIMARY_KEY=<view_key> \n skPRIMARY_KEY=<spend_key>" to .env.local for testnet
+export async function writeTestnetSpendViewKeysToDotEnvLocal(spend_key) {
+    spend_key = spend_key || (await makeSpendKey());
+    let view_pair = await makeViewKey(spend_key);
+    let primary_address = view_pair.testnet_primary;
+    await writeEnvLineToDotEnvRefresh(`vk${primary_address}`, view_pair.view_key, testnet_pk_path);
+    await writeEnvLineToDotEnvRefresh(`sk${primary_address}`, spend_key, testnet_pk_path);
+    return primary_address;
+}
+// writes "vkPRIMARY_KEY=<view_key> \n skPRIMARY_KEY=<spend_key>" to .env
+// use seedphrase package to get wallet secret from seed + passphrase: getWalletSecret function
+export async function writeWalletSecretsToDotEnv(wallet_secret) {
+    let spend_key = await makeSpendKeyFromSeed(wallet_secret.toHex());
+    let view_pair = await makeViewKey(spend_key);
+    let primary_address = view_pair.mainnet_primary;
+    await writeEnvLineToDotEnvRefresh(`vk${primary_address}`, view_pair.view_key);
+    await writeEnvLineToDotEnvRefresh(`sk${primary_address}`, spend_key);
+    return primary_address;
+}
+// this should be used in a web backend that does (non custodial) scanning
+// to add new view / spend keys, received from the users without a restart.
+export async function writeEnvLineToDotEnvRefresh(key, value, path = ".env") {
+    await writeEnvLineToDotEnv(key, value, path);
+    Bun.env[key.trim()] = value.trim();
+}
+// assuming Bun.file + Bun.write are filled in or available natively,
+// this is also used by io/indexedDB.ts
+export async function writeEnvLineToDotEnv(key, value, path = ".env") {
+    // this file should be treated as ephemeral
+    // private spendkeys + viewkeys are deterministically derived from seedphrase and password
+    // specific to indexedDB, browser extentension use case: Bun.env = .env contents
+    //
+    // we have to go through indexedDB just so the background worker has access to this.
+    // (after waking up from an alarm or onmessage event)
+    const file = Bun.file(path);
+    const content = await file
+        .text()
+        .catch(() => { })
+        .then((c) => c || "");
+    const lines = content.split("\n");
+    const idx = lines.findIndex((line) => line.startsWith(key));
+    const updatedLines = idx === -1
+        ? [...lines, `${key.trim()}=${value.trim()}`]
+        : lines.with(idx, `${key.trim()}=${value.trim()}`);
+    await atomicWrite(path, updatedLines.join("\n"));
+}
+export const STAGENET_FRESH_WALLET_HEIGHT_DEFAULT = 2014841; // current height of stagenet dec 18 2025,
+export const REGTEST_FRESH_WALLET_HEIGHT_DEFAULT = 1;