@shieldedtech/moth-wallet 0.2.0

package/dist/wallet/address.js

@@ -0,0 +1,107 @@
+// Address derivation for Midnight wallets.
+// Uses the same derivation as mn-tui and the official wallet SDK.
+// See NOTICE for attribution to mn-tui (Apache-2.0).
+import { HDWallet, Roles } from '@midnightntwrk/wallet-sdk/hd';
+import { ZswapSecretKeys, DustSecretKey } from '@midnight-ntwrk/ledger-v8';
+import { ShieldedAddress, ShieldedCoinPublicKey, ShieldedEncryptionPublicKey, DustAddress, MidnightBech32m, } from '@midnightntwrk/wallet-sdk/address-format';
+import { createKeystore } from '@midnightntwrk/wallet-sdk/unshielded';
+import { setNetworkId } from '@midnight-ntwrk/midnight-js/network-id';
+const ALL_NETWORKS = ['mainnet', 'devnet', 'preview', 'preprod', 'qanet', 'stagenet', 'local', 'undeployed'];
+export { Roles };
+/**
+ * Derive raw HD keys from a hex seed using the wallet SDK's HDWallet.
+ */
+export function deriveRawKeys(seedHex) {
+    const hdWallet = HDWallet.fromSeed(Buffer.from(seedHex, 'hex'));
+    if (hdWallet.type !== 'seedOk')
+        throw new Error('Invalid seed');
+    const result = hdWallet.hdWallet
+        .selectAccount(0)
+        .selectRoles([Roles.NightExternal, Roles.NightInternal, Roles.Dust, Roles.Zswap, Roles.Metadata])
+        .deriveKeysAt(0);
+    if (result.type !== 'keysDerived')
+        throw new Error('Key derivation failed');
+    hdWallet.hdWallet.clear();
+    return result.keys;
+}
+function toHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Derive proper Midnight addresses for a specific network.
+ *
+ * - Unshielded: createKeystore(secretKey) → Ed25519 public key → bech32m
+ * - Shielded: ZswapSecretKeys.fromSeed() → coin + encryption public keys
+ * - DUST: DustSecretKey.fromSeed() → public key → DustAddress
+ */
+function deriveForNetwork(keys, network) {
+    setNetworkId(network);
+    const unshielded = createKeystore(keys[Roles.NightExternal], network).getBech32Address().toString();
+    const unshieldedInternal = createKeystore(keys[Roles.NightInternal], network).getBech32Address().toString();
+    const zswapKeys = ZswapSecretKeys.fromSeed(keys[Roles.Zswap]);
+    const shielded = MidnightBech32m.encode(network, new ShieldedAddress(ShieldedCoinPublicKey.fromHexString(zswapKeys.coinPublicKey), ShieldedEncryptionPublicKey.fromHexString(zswapKeys.encryptionPublicKey))).toString();
+    const dustKey = DustSecretKey.fromSeed(keys[Roles.Dust]);
+    const dust = DustAddress.encodePublicKey(network, dustKey.publicKey);
+    const metadata = createKeystore(keys[Roles.Metadata], network).getBech32Address().toString();
+    return { unshielded, unshieldedInternal, shielded, dust, metadata };
+}
+/**
+ * Derive all Midnight addresses from a hex seed, for all networks.
+ */
+export function deriveAllAddressesFromSeed(seedHex) {
+    const keys = deriveRawKeys(seedHex);
+    const ne = {};
+    const ni = {};
+    const du = {};
+    const zs = {};
+    const md = {};
+    for (const network of ALL_NETWORKS) {
+        const addrs = deriveForNetwork(keys, network);
+        ne[network] = addrs.unshielded;
+        ni[network] = addrs.unshieldedInternal;
+        du[network] = addrs.dust;
+        zs[network] = addrs.shielded;
+        md[network] = addrs.metadata;
+    }
+    // SECURITY: Do NOT expose raw role key bytes as hex — those are private keys.
+    // Only public address encodings (bech32m) are safe to display/store/transmit.
+    return {
+        nightExternal: { hex: '', bech32m: ne },
+        nightInternal: { hex: '', bech32m: ni },
+        dust: { hex: '', bech32m: du },
+        zswap: { hex: '', bech32m: zs },
+        metadata: { hex: '', bech32m: md },
+    };
+}
+/**
+ * Derive the shielded (Zswap) coin + encryption PUBLIC keys from a hex seed,
+ * as canonical hex strings. These are public keys (network-independent, the
+ * same across all networks) and are safe to expose to a connected dApp — unlike
+ * the raw role key bytes. The combined, network-scoped shielded address is
+ * available separately via {@link deriveAllAddressesFromSeed} (`zswap`).
+ */
+export function deriveShieldedPublicKeys(seedHex) {
+    const keys = deriveRawKeys(seedHex);
+    const zswapKeys = ZswapSecretKeys.fromSeed(keys[Roles.Zswap]);
+    return {
+        coinPublicKey: zswapKeys.coinPublicKey,
+        encryptionPublicKey: zswapKeys.encryptionPublicKey,
+    };
+}
+/**
+ * @deprecated Use deriveAllAddressesFromSeed with the hex seed.
+ */
+export function deriveAllAddresses() {
+    throw new Error('deriveAllAddresses is deprecated — use deriveAllAddressesFromSeed(seedHex)');
+}
+export function decodeBech32mAddress(address) {
+    const parsed = MidnightBech32m.parse(address);
+    return {
+        type: parsed.type,
+        network: typeof parsed.network === 'symbol' ? 'mainnet' : String(parsed.network),
+        data: new Uint8Array(parsed.data),
+    };
+}
+//# sourceMappingURL=address.js.map

package/dist/wallet/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../src/wallet/address.ts"],"names":[],"mappings":"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"}

package/dist/wallet/app-secret.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive a 32-byte hex app secret for `(seedHex, origin, domain)`. Same inputs
+ * always yield the same secret.
+ *
+ * SECURITY:
+ * - `origin` MUST be supplied by the wallet from the connection session, never
+ *   from DApp params — that is what stops one site deriving another's secret.
+ * - IKM is the Metadata role key: non-spending and used elsewhere only to
+ *   derive a *public* identity address, so a leaked app secret can never expose
+ *   the seed, the unshielded signing key, or the Zswap/Dust spend keys. HKDF's
+ *   one-way extract-then-expand over the private role key also makes the output
+ *   independent of (and non-correlatable to) that public address.
+ */
+export declare function deriveAppSecret(seedHex: string, origin: string, domain: string): Promise<string>;
+//# sourceMappingURL=app-secret.d.ts.map

package/dist/wallet/app-secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-secret.d.ts","sourceRoot":"","sources":["../../src/wallet/app-secret.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAkBjB"}

package/dist/wallet/app-secret.js

@@ -0,0 +1,45 @@
+// Deterministic per-(origin, domain) app secret for DApps — the wallet-side
+// primitive behind the connector's `deriveAppSecret`. HKDF-SHA-256 over a
+// non-spending HD role key gives a secret that is simultaneously:
+//   (1) private-key-bound  — not recomputable from any public value,
+//   (2) deterministic/portable — reproducible from the seed on any device,
+//   (3) stateless — nothing to back up beyond the seed.
+// See specs/003-derive-app-secret/spec.md.
+//
+// The v1 salt/info strings are NORMATIVE and vendor-neutral ("midnight:", not
+// "moth:") on purpose: this prototype and a future @midnightntwrk/wallet-sdk
+// version must produce BYTE-IDENTICAL secrets so adopters never re-derive. Do
+// NOT change any of them within v1 — a change is a new version tag (v2), never
+// an in-place edit. See specs/003-derive-app-secret/wallet-sdk-upstream.md §3.
+import { Roles, deriveRawKeys } from './address.js';
+/** Normative v1 domain-separation tag. Pinned — see file header. */
+const APP_SECRET_V1 = 'midnight:dapp-app-secret:v1';
+const APP_SECRET_SALT = new TextEncoder().encode(APP_SECRET_V1);
+/**
+ * Derive a 32-byte hex app secret for `(seedHex, origin, domain)`. Same inputs
+ * always yield the same secret.
+ *
+ * SECURITY:
+ * - `origin` MUST be supplied by the wallet from the connection session, never
+ *   from DApp params — that is what stops one site deriving another's secret.
+ * - IKM is the Metadata role key: non-spending and used elsewhere only to
+ *   derive a *public* identity address, so a leaked app secret can never expose
+ *   the seed, the unshielded signing key, or the Zswap/Dust spend keys. HKDF's
+ *   one-way extract-then-expand over the private role key also makes the output
+ *   independent of (and non-correlatable to) that public address.
+ */
+export async function deriveAppSecret(seedHex, origin, domain) {
+    const keys = deriveRawKeys(seedHex);
+    // Copy into a fresh ArrayBuffer-backed view: deriveRawKeys returns
+    // Uint8Array<ArrayBufferLike>, which WebCrypto's BufferSource type rejects.
+    const ikm = new Uint8Array(keys[Roles.Metadata]);
+    // origin + domain fold into `info` so different sites and different labels
+    // yield independent, non-correlatable secrets.
+    const info = new TextEncoder().encode(`${APP_SECRET_V1}|${origin}|${domain}`);
+    const key = await crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+    const bits = await crypto.subtle.deriveBits({ name: 'HKDF', hash: 'SHA-256', salt: APP_SECRET_SALT, info }, key, 256);
+    return Array.from(new Uint8Array(bits))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+//# sourceMappingURL=app-secret.js.map

package/dist/wallet/app-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-secret.js","sourceRoot":"","sources":["../../src/wallet/app-secret.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,0EAA0E;AAC1E,kEAAkE;AAClE,qEAAqE;AACrE,2EAA2E;AAC3E,wDAAwD;AACxD,2CAA2C;AAC3C,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAE/E,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEpD,oEAAoE;AACpE,MAAM,aAAa,GAAG,6BAA6B,CAAC;AACpD,MAAM,eAAe,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,MAAc,EACd,MAAc;IAEd,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,mEAAmE;IACnE,4EAA4E;IAC5E,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,2EAA2E;IAC3E,+CAA+C;IAC/C,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,aAAa,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC;IAE9E,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IACrF,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,UAAU,CACzC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,EAC9D,GAAG,EACH,GAAG,CACJ,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;SACpC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/wallet/balance-format.d.ts

@@ -0,0 +1,12 @@
+/** STAR per NIGHT: 1 NIGHT = 10^6 STAR. */
+export declare const NIGHT_DENOMINATION: bigint;
+/** SPECK per DUST: 1 DUST = 10^15 SPECK. */
+export declare const DUST_DENOMINATION: bigint;
+/**
+ * Generic balance formatter. Divides by the supplied denomination and
+ * applies decimal-place + scale-suffix (K/M/B/T) formatting.
+ */
+export declare function formatBalance(balance: bigint, denomination?: bigint): string;
+/** SPECK → DUST display. 1 DUST = 10^15 SPECK. */
+export declare function formatDustBalance(speckBalance: bigint): string;
+//# sourceMappingURL=balance-format.d.ts.map

package/dist/wallet/balance-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance-format.d.ts","sourceRoot":"","sources":["../../src/wallet/balance-format.ts"],"names":[],"mappings":"AAUA,2CAA2C;AAC3C,eAAO,MAAM,kBAAkB,EAAE,MAAwB,CAAC;AAE1D,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,EAAE,MAAyB,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,MAA2B,GAAG,MAAM,CAkBhG;AAaD,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/wallet/balance-format.js

@@ -0,0 +1,51 @@
+// Pure formatting helpers for wallet balances. Shared between the TUI
+// (for dashboard rendering) and the daemon handlers (for L3 modal
+// summaries).
+//
+// Midnight denominations:
+//   1 NIGHT = 10^6 STAR  (the smallest NIGHT unit)
+//   1 DUST  = 10^15 SPECK (the smallest DUST unit; DUST is non-transferable)
+// All other (contract-issued) tokens have no protocol-level decimals and
+// are displayed as raw integers.
+/** STAR per NIGHT: 1 NIGHT = 10^6 STAR. */
+export const NIGHT_DENOMINATION = BigInt(10 ** 6);
+/** SPECK per DUST: 1 DUST = 10^15 SPECK. */
+export const DUST_DENOMINATION = BigInt(10 ** 15);
+/**
+ * Generic balance formatter. Divides by the supplied denomination and
+ * applies decimal-place + scale-suffix (K/M/B/T) formatting.
+ */
+export function formatBalance(balance, denomination = NIGHT_DENOMINATION) {
+    const value = balance / denomination;
+    const fractionalPart = balance % denomination;
+    const trillion = 1000000000000n;
+    const billion = 1000000000n;
+    const million = 1000000n;
+    if (value >= trillion)
+        return formatScaled(value, fractionalPart, trillion, 'T');
+    if (value >= billion)
+        return formatScaled(value, fractionalPart, billion, 'B');
+    if (value >= million)
+        return formatScaled(value, fractionalPart, million, 'M');
+    const wholeStr = value.toLocaleString('en-US');
+    if (fractionalPart > 0n) {
+        const fractionalStr = fractionalPart.toString().padStart(6, '0').replace(/0+$/, '');
+        return `${wholeStr}.${fractionalStr}`;
+    }
+    return wholeStr;
+}
+function formatScaled(value, fractionalPart, scale, suffix) {
+    const whole = value / scale;
+    const remainder = value % scale;
+    const decimalPart = Number((remainder * 100n) / scale);
+    if (decimalPart === 0 && fractionalPart === 0n) {
+        return `${whole.toLocaleString('en-US')}${suffix}`;
+    }
+    const decimalStr = (decimalPart / 100).toFixed(2).substring(1).replace(/\.?0+$/, '');
+    return `${whole.toLocaleString('en-US')}${decimalStr}${suffix}`;
+}
+/** SPECK → DUST display. 1 DUST = 10^15 SPECK. */
+export function formatDustBalance(speckBalance) {
+    return formatBalance(speckBalance, DUST_DENOMINATION);
+}
+//# sourceMappingURL=balance-format.js.map

package/dist/wallet/balance-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance-format.js","sourceRoot":"","sources":["../../src/wallet/balance-format.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,kEAAkE;AAClE,cAAc;AACd,EAAE;AACF,0BAA0B;AAC1B,mDAAmD;AACnD,6EAA6E;AAC7E,yEAAyE;AACzE,iCAAiC;AAEjC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAW,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;AAE1D,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAW,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,eAAuB,kBAAkB;IACtF,MAAM,KAAK,GAAG,OAAO,GAAG,YAAY,CAAC;IACrC,MAAM,cAAc,GAAG,OAAO,GAAG,YAAY,CAAC;IAE9C,MAAM,QAAQ,GAAG,cAAkB,CAAC;IACpC,MAAM,OAAO,GAAG,WAAc,CAAC;IAC/B,MAAM,OAAO,GAAG,QAAU,CAAC;IAE3B,IAAI,KAAK,IAAI,QAAQ;QAAE,OAAO,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACjF,IAAI,KAAK,IAAI,OAAO;QAAE,OAAO,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAC/E,IAAI,KAAK,IAAI,OAAO;QAAE,OAAO,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAE/E,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,cAAc,GAAG,EAAE,EAAE,CAAC;QACxB,MAAM,aAAa,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACpF,OAAO,GAAG,QAAQ,IAAI,aAAa,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,cAAsB,EAAE,KAAa,EAAE,MAAc;IACxF,MAAM,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;IAC5B,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;IAChC,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC;IACvD,IAAI,WAAW,KAAK,CAAC,IAAI,cAAc,KAAK,EAAE,EAAE,CAAC;QAC/C,OAAO,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACrD,CAAC;IACD,MAAM,UAAU,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACrF,OAAO,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,UAAU,GAAG,MAAM,EAAE,CAAC;AAClE,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,OAAO,aAAa,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;AACxD,CAAC"}

package/dist/wallet/batch-transfer.d.ts

@@ -0,0 +1,36 @@
+import { type TxStage, type WalletKeys } from '../sync/operations.js';
+export interface BatchTransferEntry {
+    to: string;
+    amount: string;
+    shielded?: boolean;
+}
+export interface BatchTransferResult {
+    index: number;
+    to: string;
+    amount: string;
+    status: 'success' | 'error';
+    txHash?: string;
+    error?: string;
+}
+export interface BatchTransferSummary {
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: BatchTransferResult[];
+}
+/**
+ * Load batch transfer list from a JSON file.
+ * Expected format: array of { to, amount, shielded? }
+ */
+export declare function loadBatchFile(path: string): BatchTransferEntry[];
+/**
+ * Execute batch transfers sequentially.
+ * Returns summary with per-item results and three-tier exit code:
+ *   0 = all succeeded, 1 = some failed, 2 = all failed
+ */
+export declare function executeBatchTransfer(facade: any, walletKeys: WalletKeys, networkId: string, entries: BatchTransferEntry[], onProgress?: (index: number, stage: TxStage) => void): Promise<BatchTransferSummary>;
+/**
+ * Three-tier exit code from batch results.
+ */
+export declare function batchExitCode(summary: BatchTransferSummary): 0 | 1 | 2;
+//# sourceMappingURL=batch-transfer.d.ts.map

package/dist/wallet/batch-transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-transfer.d.ts","sourceRoot":"","sources":["../../src/wallet/batch-transfer.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwC,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAG5G,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAgBhE;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,GAAG,EACX,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,kBAAkB,EAAE,EAC7B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GACnD,OAAO,CAAC,oBAAoB,CAAC,CAqD/B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAItE"}

package/dist/wallet/batch-transfer.js

@@ -0,0 +1,93 @@
+// Batch transfer — load transfer list from JSON, execute sequentially, collect results.
+// Supports file input or direct array input.
+import { readFileSync } from 'node:fs';
+import { sendTokensWithKeys } from '../sync/operations.js';
+import { NIGHT_TOKEN_ID } from '../sync/wallet-sync.js';
+/**
+ * Load batch transfer list from a JSON file.
+ * Expected format: array of { to, amount, shielded? }
+ */
+export function loadBatchFile(path) {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        throw new Error('Batch file must contain a JSON array of transfer entries');
+    }
+    for (let i = 0; i < parsed.length; i++) {
+        const entry = parsed[i];
+        if (!entry.to || typeof entry.to !== 'string') {
+            throw new Error(`Entry ${i}: missing or invalid "to" address`);
+        }
+        if (!entry.amount || typeof entry.amount !== 'string') {
+            throw new Error(`Entry ${i}: missing or invalid "amount" (must be string)`);
+        }
+    }
+    return parsed;
+}
+/**
+ * Execute batch transfers sequentially.
+ * Returns summary with per-item results and three-tier exit code:
+ *   0 = all succeeded, 1 = some failed, 2 = all failed
+ */
+export async function executeBatchTransfer(facade, walletKeys, networkId, entries, onProgress) {
+    const results = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const parsed = parseFloat(entry.amount);
+        if (Number.isNaN(parsed) || parsed <= 0) {
+            results.push({
+                index: i,
+                to: entry.to,
+                amount: entry.amount,
+                status: 'error',
+                error: `Invalid amount: ${entry.amount}`,
+            });
+            continue;
+        }
+        const req = {
+            type: entry.shielded ? 'shielded' : 'unshielded',
+            tokenId: NIGHT_TOKEN_ID,
+            amount: BigInt(Math.round(parsed * 1_000_000)),
+            to: entry.to,
+        };
+        try {
+            const txHash = await sendTokensWithKeys(facade, walletKeys, networkId, [req], (stage) => {
+                onProgress?.(i, stage);
+            });
+            results.push({
+                index: i,
+                to: entry.to,
+                amount: entry.amount,
+                status: 'success',
+                txHash,
+            });
+        }
+        catch (err) {
+            results.push({
+                index: i,
+                to: entry.to,
+                amount: entry.amount,
+                status: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const succeeded = results.filter(r => r.status === 'success').length;
+    return {
+        total: entries.length,
+        succeeded,
+        failed: entries.length - succeeded,
+        results,
+    };
+}
+/**
+ * Three-tier exit code from batch results.
+ */
+export function batchExitCode(summary) {
+    if (summary.failed === 0)
+        return 0;
+    if (summary.succeeded === 0)
+        return 1;
+    return 2;
+}
+//# sourceMappingURL=batch-transfer.js.map

package/dist/wallet/batch-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-transfer.js","sourceRoot":"","sources":["../../src/wallet/batch-transfer.ts"],"names":[],"mappings":"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"}

package/dist/wallet/keystore.d.ts

@@ -0,0 +1,16 @@
+export interface EncryptedKeystore {
+    readonly version: number;
+    readonly algorithm: string;
+    readonly salt: Uint8Array;
+    readonly nonce: Uint8Array;
+    readonly ciphertext: Uint8Array;
+    readonly tag: Uint8Array;
+}
+declare const KEYSTORE_VERSION = 2;
+export declare function encryptKeystore(mnemonic: string, passphrase: string): Promise<EncryptedKeystore>;
+/** Current keystore version — new keystores are always created at this version */
+export { KEYSTORE_VERSION };
+/** Check if a keystore needs re-encryption with stronger KDF parameters */
+export declare function keystoreNeedsUpgrade(keystore: EncryptedKeystore): boolean;
+export declare function decryptKeystore(keystore: EncryptedKeystore, passphrase: string): Promise<string>;
+//# sourceMappingURL=keystore.d.ts.map

package/dist/wallet/keystore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.d.ts","sourceRoot":"","sources":["../../src/wallet/keystore.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED,QAAA,MAAM,gBAAgB,IAAI,CAAC;AA+B3B,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAwB5B;AAED,kFAAkF;AAClF,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAEzE;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CA2BjB"}

package/dist/wallet/keystore.js

@@ -0,0 +1,76 @@
+import { chacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { randomBytes } from '@noble/ciphers/utils.js';
+import { scrypt } from '@noble/hashes/scrypt.js';
+const KEYSTORE_VERSION = 2;
+const ALGORITHM = 'chacha20-poly1305';
+const SALT_LENGTH = 32;
+const NONCE_LENGTH = 12;
+const KEY_LENGTH = 32;
+// scrypt parameters per keystore version.
+// V1: N=2^15 (~8 MiB, ~50ms) — too weak for offline key storage.
+// V2: N=2^18 (~256 MiB, ~300ms) — meets NIST SP 800-132 interactive threshold.
+const SCRYPT_PARAMS = {
+    1: { N: 2 ** 15, r: 8, p: 1 },
+    2: { N: 2 ** 18, r: 8, p: 1 },
+};
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function deriveEncryptionKey(passphrase, salt, version = KEYSTORE_VERSION) {
+    const params = SCRYPT_PARAMS[version] ?? SCRYPT_PARAMS[KEYSTORE_VERSION];
+    return scrypt(encoder.encode(passphrase), salt, {
+        N: params.N,
+        r: params.r,
+        p: params.p,
+        dkLen: KEY_LENGTH,
+    });
+}
+export async function encryptKeystore(mnemonic, passphrase) {
+    const salt = randomBytes(SALT_LENGTH);
+    const nonce = randomBytes(NONCE_LENGTH);
+    const key = deriveEncryptionKey(passphrase, salt);
+    const cipher = chacha20poly1305(key, nonce);
+    const plaintext = encoder.encode(mnemonic);
+    const sealed = cipher.encrypt(plaintext);
+    // ChaCha20-Poly1305 appends 16-byte tag to ciphertext
+    const ciphertext = sealed.subarray(0, sealed.length - 16);
+    const tag = sealed.subarray(sealed.length - 16);
+    // Zero the key from memory
+    key.fill(0);
+    return {
+        version: KEYSTORE_VERSION,
+        algorithm: ALGORITHM,
+        salt,
+        nonce,
+        ciphertext,
+        tag,
+    };
+}
+/** Current keystore version — new keystores are always created at this version */
+export { KEYSTORE_VERSION };
+/** Check if a keystore needs re-encryption with stronger KDF parameters */
+export function keystoreNeedsUpgrade(keystore) {
+    return keystore.version < KEYSTORE_VERSION;
+}
+export async function decryptKeystore(keystore, passphrase) {
+    if (!SCRYPT_PARAMS[keystore.version]) {
+        throw new Error(`Unsupported keystore version: ${keystore.version} (supported: ${Object.keys(SCRYPT_PARAMS).join(', ')})`);
+    }
+    // Derive key using the version-specific scrypt parameters
+    const key = deriveEncryptionKey(passphrase, keystore.salt, keystore.version);
+    // Reconstruct sealed message (ciphertext + tag)
+    const sealed = new Uint8Array(keystore.ciphertext.length + keystore.tag.length);
+    sealed.set(keystore.ciphertext);
+    sealed.set(keystore.tag, keystore.ciphertext.length);
+    const cipher = chacha20poly1305(key, keystore.nonce);
+    try {
+        const plaintext = cipher.decrypt(sealed);
+        return decoder.decode(plaintext);
+    }
+    catch {
+        throw new Error('Decryption failed: invalid passphrase or corrupted keystore');
+    }
+    finally {
+        key.fill(0);
+    }
+}
+//# sourceMappingURL=keystore.js.map

package/dist/wallet/keystore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystore.js","sourceRoot":"","sources":["../../src/wallet/keystore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAWjD,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,SAAS,GAAG,mBAAmB,CAAC;AACtC,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,0CAA0C;AAC1C,iEAAiE;AACjE,+EAA+E;AAC/E,MAAM,aAAa,GAAwD;IACzE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;IAC7B,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE;CAC9B,CAAC;AAEF,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,SAAS,mBAAmB,CAC1B,UAAkB,EAClB,IAAgB,EAChB,UAAkB,gBAAgB;IAElC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACzE,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE;QAC9C,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,KAAK,EAAE,UAAU;KAClB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,UAAkB;IAElB,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,mBAAmB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEzC,sDAAsD;IACtD,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAEhD,2BAA2B;IAC3B,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAEZ,OAAO;QACL,OAAO,EAAE,gBAAgB;QACzB,SAAS,EAAE,SAAS;QACpB,IAAI;QACJ,KAAK;QACL,UAAU;QACV,GAAG;KACJ,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,2EAA2E;AAC3E,MAAM,UAAU,oBAAoB,CAAC,QAA2B;IAC9D,OAAO,QAAQ,CAAC,OAAO,GAAG,gBAAgB,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAA2B,EAC3B,UAAkB;IAElB,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,iCAAiC,QAAQ,CAAC,OAAO,gBAAgB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1G,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,MAAM,GAAG,GAAG,mBAAmB,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAE7E,gDAAgD;IAChD,MAAM,MAAM,GAAG,IAAI,UAAU,CAC3B,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CACjD,CAAC;IACF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAErD,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;IAErD,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/wallet/manager.d.ts

@@ -0,0 +1,77 @@
+import type { StorageAdapter } from '../storage/adapter.js';
+import type { WalletInfo, UnlockedWallet } from '../types/wallet.js';
+export declare class WalletManager {
+    private readonly storage;
+    constructor(storage: StorageAdapter);
+    private loadConfig;
+    private saveConfig;
+    private saveMeta;
+    private loadMeta;
+    private validateName;
+    private seedToHex;
+    private deriveAddressesFromSeed;
+    /** Public night receive address, preferring the wallet's own network. */
+    private primaryAddress;
+    generate(name: string, passphrase: string, network?: string, birthday?: number, mnemonic?: string): Promise<WalletInfo & {
+        mnemonic: string;
+    }>;
+    import(name: string, mnemonic: string, passphrase: string, network?: string): Promise<WalletInfo>;
+    importFromSeed(name: string, hexSeed: string, passphrase: string, network?: string): Promise<WalletInfo>;
+    /** Read and revive a wallet's keystore from storage (JSON round-trips
+     *  Uint8Array fields as index-keyed objects). */
+    private readKeystore;
+    unlock(name: string, passphrase: string): Promise<UnlockedWallet>;
+    /**
+     * Recover the raw BIP-39 hex seed for a wallet.
+     *
+     * This is the ONE deliberate exception to Option A's derive-and-drop
+     * (D-KM-3): the common `unlock()` path derives `walletKeys` and drops the
+     * seed so `UnlockedWallet` is seed-free, and the daemon/CLI/multi-tenant
+     * host never see raw seed material. But the browser extension's offscreen
+     * document is the key-holder, and Chrome tears it down and recreates it at
+     * will — the WASM `walletKeys` cannot cross the runtime-message boundary, so
+     * the offscreen needs a *serializable* secret the background can re-supply to
+     * rebuild the key bundle after each restart. That secret is the seed.
+     *
+     * Kept off `unlock()` on purpose so the seed-free invariant holds for every
+     * caller that doesn't explicitly opt in here.
+     * See docs/spec/wallet-service/05-key-management.md D-KM-3.
+     */
+    exportSeedHex(name: string, passphrase: string): Promise<string>;
+    /**
+     * Recover the wallet's backup secret for a user-facing reveal: the original
+     * BIP-39 mnemonic when the wallet has one, or the raw hex seed for wallets
+     * imported from hex (no mnemonic ever existed). Passphrase-gated by the
+     * keystore decrypt itself — a wrong passphrase rejects. Same deliberate
+     * D-KM-3 opt-in rationale as exportSeedHex above.
+     */
+    exportPhrase(name: string, passphrase: string): Promise<{
+        kind: 'mnemonic' | 'seed';
+        value: string;
+    }>;
+    remove(name: string): Promise<void>;
+    /**
+     * List wallets. Returns the name, network and public receive address (stored
+     * in the clear at create/import time). The full per-role address set and any
+     * key material still require unlock — only the primary night address is here.
+     */
+    list(): Promise<WalletInfo[]>;
+    getActive(): Promise<string | null>;
+    setActive(name: string): Promise<void>;
+    /**
+     * Set or clear a wallet's display label. Labels are presentation-only
+     * metadata: the wallet keeps its immutable `name` (the storage key), so
+     * keystores, sync caches and sessions all stay valid across renames.
+     * An empty (or whitespace-only) label reverts to showing the name.
+     */
+    setLabel(name: string, label: string): Promise<void>;
+    /**
+     * Move a wallet to another network. Only this wallet's metadata changes —
+     * other wallets keep their own networks. The public address and chain
+     * birthday are network-scoped, so the old values are discarded. A caller
+     * that already has the unlocked seed may provide the newly derived public
+     * address to keep the locked account list immediately useful.
+     */
+    setNetwork(name: string, network: string, address?: string, birthday?: number): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/wallet/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/wallet/manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAiD,MAAM,oBAAoB,CAAC;AAmGpH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;gBAE7B,OAAO,EAAE,cAAc;YAIrB,UAAU;YAUV,UAAU;YAIV,QAAQ;YAIR,QAAQ;IAMtB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,uBAAuB;IAI/B,yEAAyE;IACzE,OAAO,CAAC,cAAc;IAWhB,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,SAAW,EAClB,QAAQ,CAAC,EAAE,MAAM,EAIjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAuCvC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,SAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgCnG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,SAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAuBhH;qDACiD;YACnC,YAAY;IAepB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA4GvE;;;;;;;;;;;;;;;OAeG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUtE;;;;;;OAMG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAOlD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCzC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAwB7B,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKnC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU1D;;;;;;OAMG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA6CpG"}