@locuschain/lib 0.1.31 → 0.1.33

package/dist/accounts/index.esm.js

@@ -0,0 +1,304 @@
+import { _ as __awaiter } from '../chunks/tslib.es6-WQS2tr1v.js';
+import { T as TxType } from '../chunks/tx-type-BPkhMGad.js';
+import { B as BaseError } from '../chunks/base-BQXfRsuw.js';
+import { a as SignKeyBindUnsupportedError, S as SignFailedError, D as DegenerateKeyError } from '../chunks/account-FZT9LH_s.js';
+import { O as signKeyBind, N as signByMasterKey, M as sign, z as deriveKeysFromMnemonicAndPath, y as deriveKeysFromMnemonic } from '../chunks/wasm-BtPcXTR4.js';
+import '../chunks/lclib-C2eG5HzD.js';
+
+/**
+ * 메인 서명을 master 키로 생성하는 TX 타입 집합 (signByMasterKey WASM 호출).
+ * 그 외 모든 TX 는 normal 키로 서명한다 (sign WASM 호출).
+ *
+ * Source of truth: locuschain 프로토콜 — CLOSE_ACCOUNT 만 메인 tx 를 master
+ * 키로 직접 서명한다.
+ */
+const MASTER_SIGN_TX_TYPES = new Set([
+    TxType.CLOSE_ACCOUNT,
+]);
+/**
+ * Submit payload 에 SignKeyBind 결과가 포함되는 TX 타입 집합. 메인 tx 는
+ * 여전히 normal 키가 서명하고, master 키는 (새 normal pubkey, 현재 normal
+ * pubkey) 간의 binding 만 증명한다.
+ *
+ * 정확한 submit 필드는 RPC 마다 다르다:
+ *   - TX_OPEN_ACCOUNT   -> additions.keySign         (ParamsOpenAccount.keySign)
+ *   - TX_CHANGE_KEYPAIR -> additions.signByMasterKey (ParamsChangeKey.signByMasterKey)
+ *
+ * Source of truth: locuschain 프로토콜 — run/test_lclib/lclib/lclib.go 의
+ * SignKeyBind 와 nodeext/rpclocus/rpc.go 의 ParamsXxx struct 참고.
+ */
+new Set([
+    TxType.OPEN_ACCOUNT,
+    TxType.CHANGE_KEYPAIR,
+]);
+
+/** master 가 증명한 key-bind 서명을 미리 채워야 하는 RPC 메서드들. */
+const OPEN_ACCOUNT_METHOD = 'locus_openAccount';
+const CHANGE_KEY_METHOD = 'locus_changeKey';
+/**
+ * Locus dual-key account 를 만든다. 반환된 `signTransaction` 은 prepare 된
+ * TX 에 대해 master/normal 라우팅을 모두 캡슐화하므로, wallet action 들이
+ * tx.type 분기를 직접 할 필요가 없다.
+ *
+ * 2 단계 흐름 노트:
+ *
+ *   - OPEN_ACCOUNT 는 prepare RPC 에서도 master key-bind 서명이 필요하다.
+ *     `prepareParams` 는 호출자가 `keySign` 을 빈 값으로 둔 경우 자동으로
+ *     채운다. FALCON+ED25519 가 non-deterministic 이라 submit 단계에서
+ *     서명을 다시 계산하지 *않고*, `prepared.tx.keyBind.sign` 에서 prepare
+ *     단계 값을 그대로 읽어 쓴다 (노드가 prepare 파라미터를 그대로 echo).
+ *
+ *   - CHANGE_KEYPAIR 는 *자동으로 채우지 않는다*. 노드가 메인 tx 서명을
+ *     이전 키가 아닌 *새* normal pubkey 로 검증 (proof-of-possession)
+ *     하므로, 호출자가 새 normal secret 을 보유한 상태로 새 DualKeyAccount
+ *     를 만들어 호출해야 한다. account.normal.getPublicKey() 가 새 키로
+ *     바뀐 후라면 auto-compute 된 `signByMasterKey` 는 잘못된 `currentNpk`
+ *     를 쓰게 되므로 자동 계산을 비활성화한다. 호출자 측 흐름:
+ *
+ *       1. signByMasterKey = await oldAccount.master.signKeyBind({
+ *            newNpk: <새 normal pubkey>,
+ *            currentNpk: <이전 normal pubkey>,
+ *          });
+ *       2. const newAccount = keysToAccount({ address, msk, mpk,
+ *            nsk: <new>, npk: <new> });
+ *       3. await wallet.changeKey({ ..., signByMasterKey });
+ *
+ *     signByMasterKey 가 비어 있으면 prepareParams 가 throw 한다.
+ *
+ *   - 그 외 모든 TX 는 prepareParams 가 pass-through.
+ *
+ * 정책 (single source of truth — 노드 측 ParamsOpenAccount / ParamsChangeKey
+ * / ParamsChangeVKey / ParamsCloseAccount RPC struct 와 동기 유지):
+ *
+ *   TX_CLOSE_ACCOUNT   -> sign = master.signMessage(hash)
+ *   TX_OPEN_ACCOUNT    -> sign = normal.signMessage(hash) AND
+ *                         keySign         = prepared.tx.keyBind.sign
+ *   TX_CHANGE_KEYPAIR  -> sign = normal.signMessage(hash)        // normal 은 *새* 키여야 함
+ *                         signByMasterKey = prepared.tx.keyBind.sign
+ *   TX_CHANGE_VKEY     -> sign = normal.signMessage(hash)
+ *   그 외              -> sign = normal.signMessage(hash)
+ *
+ * public key 필드 (mpk/pk/mpkey/masterPkey/newNormalPkey) 는 여기서
+ * 합성하지 않는다 — 호출자가 prepare 파라미터에 직접 포함시켜 넘기고,
+ * `_sendPreparedTransaction` 이 submit 단계에서 params[0] 에 추가 필드들
+ * 을 병합할 때 원본 값을 보존한다.
+ */
+function dualKeyAccount(args) {
+    const { address, master, normal } = args;
+    const prepareParams = (_a) => __awaiter(this, [_a], void 0, function* ({ method, params, signal, }) {
+        var _b;
+        if (params.length === 0)
+            return params;
+        const first = params[0];
+        if (!first || typeof first !== 'object')
+            return params;
+        if (method === OPEN_ACCOUNT_METHOD) {
+            const p = first;
+            if (!p.keySign || p.keySign.length === 0) {
+                if (!master.signKeyBind)
+                    throw new SignKeyBindUnsupportedError(master.type);
+                const keySign = yield master.signKeyBind({
+                    newNpk: (_b = p.pk) !== null && _b !== void 0 ? _b : '',
+                    currentNpk: '',
+                    signal,
+                });
+                return [Object.assign(Object.assign({}, p), { keySign }), ...params.slice(1)];
+            }
+        }
+        else if (method === CHANGE_KEY_METHOD) {
+            const p = first;
+            if (!p.signByMasterKey || p.signByMasterKey.length === 0) {
+                throw new BaseError(`changeKey: 'signByMasterKey' must be precomputed before calling this action`, {
+                    metaMessages: [
+                        `TX_CHANGE_KEYPAIR 는 새 normal 키가 메인 tx 에 서명 (proof-of-possession) 하므로,`,
+                        `호출자가 (1) currentNpk 로 *이전* normal pubkey 를 넣어 signByMasterKey 를 미리`,
+                        `계산하고, (2) *새* normal 키를 새 DualKeyAccount 에 바인드한 뒤 submit 해야 한다.`,
+                        `자세한 흐름은 README 의 "Normal 키 교체" 섹션 참고.`,
+                    ],
+                });
+            }
+        }
+        return params;
+    });
+    const signTransaction = (_a) => __awaiter(this, [_a], void 0, function* ({ prepared, signal, }) {
+        var _b;
+        const tx = prepared.tx;
+        const txType = typeof (tx === null || tx === void 0 ? void 0 : tx.type) === 'string' ? tx.type : '';
+        const useMaster = MASTER_SIGN_TX_TYPES.has(txType);
+        const mainSigner = useMaster ? master : normal;
+        const sign = yield mainSigner.signMessage({
+            message: prepared.hash,
+            signal,
+        });
+        const additions = {
+            sign,
+            signedHeight: prepared.signedHeight,
+        };
+        const keyBindSign = (_b = tx === null || tx === void 0 ? void 0 : tx.keyBind) === null || _b === void 0 ? void 0 : _b.sign;
+        if (txType === TxType.OPEN_ACCOUNT && keyBindSign) {
+            additions.keySign = keyBindSign;
+        }
+        else if (txType === TxType.CHANGE_KEYPAIR && keyBindSign) {
+            additions.signByMasterKey = keyBindSign;
+        }
+        return additions;
+    });
+    const signMessage = ({ message, role = 'normal', signal, }) => {
+        const signer = role === 'master' ? master : normal;
+        return signer.signMessage({ message, signal });
+    };
+    return {
+        type: 'locus-dual-key',
+        address,
+        master,
+        normal,
+        prepareParams,
+        signTransaction,
+        signMessage,
+    };
+}
+// 타입 이름과 대칭을 맞추기 위한 alias — dualKeyAccount 와 동일하다.
+const toAccount = dualKeyAccount;
+
+/**
+ * 인메모리 secret-key 소스. 개발용, CLI 도구, 또는 호출자가 평문 키
+ * 자료를 보관해도 무방한 경우에 적합하다.
+ *
+ * 키를 keystore / 하드웨어 장치 / 다른 프로세스 뒤에 보관하는 지갑은
+ * raw `key` 를 라이브러리에 넘기는 대신 toKeySource() 와 자체 콜백을
+ * 주입하는 방식을 써야 한다.
+ */
+function localKeySource(args) {
+    const { key, publicKey, role } = args;
+    const publicKeyPromise = Promise.resolve(publicKey);
+    if (role === 'master') {
+        return {
+            type: 'local',
+            getPublicKey: () => publicKeyPromise,
+            signMessage: ({ message }) => {
+                try {
+                    return Promise.resolve(signByMasterKey({ msk: key, message }));
+                }
+                catch (err) {
+                    throw new SignFailedError('local master signMessage failed', { cause: err });
+                }
+            },
+            signKeyBind: ({ newNpk, currentNpk }) => {
+                try {
+                    return Promise.resolve(signKeyBind({ msk: key, newNpk, currentNpk }));
+                }
+                catch (err) {
+                    throw new SignFailedError('local master signKeyBind failed', { cause: err });
+                }
+            },
+        };
+    }
+    return {
+        type: 'local',
+        getPublicKey: () => publicKeyPromise,
+        signMessage: ({ message }) => {
+            try {
+                return Promise.resolve(sign({ sk: key, message }));
+            }
+            catch (err) {
+                throw new SignFailedError('local normal signMessage failed', { cause: err });
+            }
+        },
+    };
+}
+
+/**
+ * 평문 master/normal 키페어로부터 DualKeyAccount 를 만든다. 개발용, 테스트,
+ * CLI 도구 용도 — 프로덕션 지갑은 secret key 가 라이브러리에 들어가지
+ * 않도록 toAccount() 와 toKeySource() 콜백을 사용해야 한다.
+ */
+function keysToAccount(args) {
+    return dualKeyAccount({
+        address: args.address,
+        master: localKeySource({ key: args.msk, publicKey: args.mpk, role: 'master' }),
+        normal: localKeySource({ key: args.nsk, publicKey: args.npk, role: 'normal' }),
+    });
+}
+
+/**
+ * BIP-39 mnemonic 으로부터 WASM 을 거쳐 Locus DualKeyAccount 를 derive 한다.
+ * 라이브러리는 결과 secret key 를 반환된 localKeySource 클로저 외에는
+ * 보관하지 않는다 — 콜백 방식 키 위임이 필요한 호출자는
+ * deriveKeysFromMnemonic / deriveKeysFromMnemonicAndPath 를 직접 호출한 뒤
+ * 결과를 `toAccount({ master, normal })` 에 넘기는 게 권장.
+ */
+function mnemonicToAccount(args) {
+    const json = args.path
+        ? deriveKeysFromMnemonicAndPath({ mnemonic: args.mnemonic, path: args.path })
+        : deriveByIndex(args);
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        throw new BaseError('mnemonicToAccount: WASM returned non-JSON', { cause: err });
+    }
+    assertDerivedShape(parsed);
+    if (parsed.masterPublicKey === parsed.publicKey) {
+        throw new DegenerateKeyError({
+            source: 'mnemonicToAccount',
+            algoMaster: args.algoMaster,
+            algoNormal: args.algoNormal,
+        });
+    }
+    return dualKeyAccount({
+        address: parsed.address,
+        master: localKeySource({
+            key: parsed.masterSecretKey,
+            publicKey: parsed.masterPublicKey,
+            role: 'master',
+        }),
+        normal: localKeySource({
+            key: parsed.secretKey,
+            publicKey: parsed.publicKey,
+            role: 'normal',
+        }),
+    });
+}
+function deriveByIndex(args) {
+    var _a;
+    if (!args.algoMaster || !args.algoNormal) {
+        throw new BaseError(`mnemonicToAccount: 'algoMaster' and 'algoNormal' are required when 'path' is not supplied`);
+    }
+    return deriveKeysFromMnemonic({
+        mnemonic: args.mnemonic,
+        algoMaster: args.algoMaster,
+        algoNormal: args.algoNormal,
+        index: (_a = args.index) !== null && _a !== void 0 ? _a : 0,
+    });
+}
+function assertDerivedShape(v) {
+    if (!v || typeof v !== 'object') {
+        throw new BaseError('mnemonicToAccount: malformed WASM result');
+    }
+    const o = v;
+    for (const k of ['address', 'publicKey', 'secretKey', 'masterPublicKey', 'masterSecretKey']) {
+        if (typeof o[k] !== 'string' || o[k].length === 0) {
+            throw new BaseError(`mnemonicToAccount: WASM result missing '${k}'`);
+        }
+    }
+}
+
+/**
+ * 호출자가 제공한 콜백으로 KeySource 를 만든다. keystore 기반 지갑,
+ * 하드웨어 지갑, 외부 지갑 앱이 통합되는 진입점 — 라이브러리는 secret key
+ * 를 보지 않는다.
+ */
+function toKeySource(args) {
+    var _a;
+    const source = {
+        type: (_a = args.type) !== null && _a !== void 0 ? _a : 'custom',
+        getPublicKey: args.getPublicKey,
+        signMessage: args.signMessage,
+    };
+    if (args.signKeyBind)
+        source.signKeyBind = args.signKeyBind;
+    return source;
+}
+
+export { dualKeyAccount, keysToAccount, localKeySource, mnemonicToAccount, toAccount, toKeySource };

package/dist/accounts/keys/index.d.mts

@@ -0,0 +1,2 @@
+export * from './localKeySource.mjs';
+export * from './toKeySource.mjs';

package/dist/accounts/keys/localKeySource.d.mts

@@ -0,0 +1,23 @@
+import type { KeySource } from '../types.mjs';
+export type LocalKeySourceArgs = {
+    /** 평문 secret key (normal 소스이면 nsk, master 소스이면 msk). */
+    key: string;
+    /** 짝이 되는 public key (npk 또는 mpk). 호출자가 직접 넘겨야 한다. */
+    publicKey: string;
+    /**
+     * 어느 WASM signer 를 호출할지:
+     *   - 'normal' 은 `sign(sk, message)` 를 사용하며 signKeyBind 를 노출하지 않는다.
+     *   - 'master' 는 `signByMasterKey(msk, message)` 를 사용하고
+     *     signKeyBind(msk, newNpk, currentNpk) 도 함께 노출한다.
+     */
+    role: 'master' | 'normal';
+};
+/**
+ * 인메모리 secret-key 소스. 개발용, CLI 도구, 또는 호출자가 평문 키
+ * 자료를 보관해도 무방한 경우에 적합하다.
+ *
+ * 키를 keystore / 하드웨어 장치 / 다른 프로세스 뒤에 보관하는 지갑은
+ * raw `key` 를 라이브러리에 넘기는 대신 toKeySource() 와 자체 콜백을
+ * 주입하는 방식을 써야 한다.
+ */
+export declare function localKeySource(args: LocalKeySourceArgs): KeySource;

package/dist/accounts/keys/toKeySource.d.mts

@@ -0,0 +1,14 @@
+import type { KeySource } from '../types.mjs';
+export type ToKeySourceArgs = {
+    /** 디버그/UI 라벨. 도구가 사용할 수 있도록 반환되는 소스에 저장된다. */
+    type?: string;
+    getPublicKey: KeySource['getPublicKey'];
+    signMessage: KeySource['signMessage'];
+    signKeyBind?: KeySource['signKeyBind'];
+};
+/**
+ * 호출자가 제공한 콜백으로 KeySource 를 만든다. keystore 기반 지갑,
+ * 하드웨어 지갑, 외부 지갑 앱이 통합되는 진입점 — 라이브러리는 secret key
+ * 를 보지 않는다.
+ */
+export declare function toKeySource(args: ToKeySourceArgs): KeySource;

package/dist/accounts/keysToAccount.d.mts

@@ -0,0 +1,19 @@
+import type { Address } from '../types/primitives.mjs';
+import type { DualKeyAccount } from './types.mjs';
+export type KeysToAccountArgs = {
+    address: Address;
+    /** Master secret key. */
+    msk: string;
+    /** Master public key. Locus 의 PQ 알고리즘은 msk 로부터 mpk 를 derive 하지 않으므로 함께 받는다. */
+    mpk: string;
+    /** Normal secret key. */
+    nsk: string;
+    /** Normal public key. */
+    npk: string;
+};
+/**
+ * 평문 master/normal 키페어로부터 DualKeyAccount 를 만든다. 개발용, 테스트,
+ * CLI 도구 용도 — 프로덕션 지갑은 secret key 가 라이브러리에 들어가지
+ * 않도록 toAccount() 와 toKeySource() 콜백을 사용해야 한다.
+ */
+export declare function keysToAccount(args: KeysToAccountArgs): DualKeyAccount;

package/dist/accounts/mnemonicToAccount.d.mts

@@ -0,0 +1,25 @@
+import type { DualKeyAccount } from './types.mjs';
+export type MnemonicToAccountArgs = {
+    mnemonic: string;
+    /**
+     * 완전히 형성된 BIP-44 path. 이 값을 넘기면 deriveKeysFromMnemonicAndPath
+     * 가 사용되고 master KeyAlgorithm 은 path 에서 추론된다. normal
+     * KeyAlgorithm 은 노드 측 헬퍼가 ed25519 로 고정한다. 이 모드에서는
+     * `algoMaster`, `algoNormal`, `index` 가 무시된다.
+     */
+    path?: string;
+    /** `path` 가 없을 때 필수. */
+    algoMaster?: string;
+    /** `path` 가 없을 때 필수. */
+    algoNormal?: string;
+    /** BIP-44 account index. 기본값 0. `path` 가 있으면 무시된다. */
+    index?: number;
+};
+/**
+ * BIP-39 mnemonic 으로부터 WASM 을 거쳐 Locus DualKeyAccount 를 derive 한다.
+ * 라이브러리는 결과 secret key 를 반환된 localKeySource 클로저 외에는
+ * 보관하지 않는다 — 콜백 방식 키 위임이 필요한 호출자는
+ * deriveKeysFromMnemonic / deriveKeysFromMnemonicAndPath 를 직접 호출한 뒤
+ * 결과를 `toAccount({ master, normal })` 에 넘기는 게 권장.
+ */
+export declare function mnemonicToAccount(args: MnemonicToAccountArgs): DualKeyAccount;

package/dist/accounts/signing/txKeyPolicy.d.mts

@@ -0,0 +1,21 @@
+/**
+ * 메인 서명을 master 키로 생성하는 TX 타입 집합 (signByMasterKey WASM 호출).
+ * 그 외 모든 TX 는 normal 키로 서명한다 (sign WASM 호출).
+ *
+ * Source of truth: locuschain 프로토콜 — CLOSE_ACCOUNT 만 메인 tx 를 master
+ * 키로 직접 서명한다.
+ */
+export declare const MASTER_SIGN_TX_TYPES: ReadonlySet<string>;
+/**
+ * Submit payload 에 SignKeyBind 결과가 포함되는 TX 타입 집합. 메인 tx 는
+ * 여전히 normal 키가 서명하고, master 키는 (새 normal pubkey, 현재 normal
+ * pubkey) 간의 binding 만 증명한다.
+ *
+ * 정확한 submit 필드는 RPC 마다 다르다:
+ *   - TX_OPEN_ACCOUNT   -> additions.keySign         (ParamsOpenAccount.keySign)
+ *   - TX_CHANGE_KEYPAIR -> additions.signByMasterKey (ParamsChangeKey.signByMasterKey)
+ *
+ * Source of truth: locuschain 프로토콜 — run/test_lclib/lclib/lclib.go 의
+ * SignKeyBind 와 nodeext/rpclocus/rpc.go 의 ParamsXxx struct 참고.
+ */
+export declare const SIGN_KEY_BIND_TX_TYPES: ReadonlySet<string>;

package/dist/accounts/types.d.mts

@@ -0,0 +1,100 @@
+import type { RpcCreateTxResult } from '../autogen/types/rpc/rpc-create-tx-result.mjs';
+import type { Address } from '../types/primitives.mjs';
+/**
+ * 서버 측 prepare 결과 — 로컬 서명 단계의 입력이 된다. Locus 의 모든
+ * TX_CREATION RPC (예: locus_transferCoin) 가 이 값을 반환한다.
+ */
+export type PreparedTransaction = RpcCreateTxResult;
+/**
+ * 두 번째 (submit) RPC 호출의 params[0] 에 병합되는 추가 필드들.
+ *
+ * 필드명은 RPC 스키마와 글자 그대로 (와이어에서 case-sensitive) 일치한다:
+ *   - `sign` 과 `signedHeight` 는 모든 TX_CREATION submit 에 존재.
+ *   - `keySign` 은 TX_OPEN_ACCOUNT 의 SignKeyBind 결과.
+ *   - `signByMasterKey` 는 TX_CHANGE_KEYPAIR 의 SignKeyBind 결과.
+ * public key 필드 (mpk/pk/mpkey/masterPkey/newNormalPkey) 는 사용자가
+ * prepare 파라미터로 직접 넘기는 값이며 여기서 합성하지 않는다.
+ */
+export type TxSignAdditions = {
+    sign: string;
+    signedHeight: number;
+    /** TX_OPEN_ACCOUNT: 초기 key-bind 메시지에 대한 master 서명. */
+    keySign?: string;
+    /** TX_CHANGE_KEYPAIR: (newNpk, hash(currentNpk)) 에 대한 master 서명. */
+    signByMasterKey?: string;
+};
+/**
+ * 키 단위의 일반 signer. 구현체는 다음과 같다:
+ *   - localKeySource — secret key + public key 를 메모리에 보유.
+ *   - toKeySource    — 호출자가 제공한 콜백 (keystore, 하드웨어 지갑,
+ *                      외부 지갑 앱 등).
+ * 라이브러리는 secret key 를 직접 보관하지 않고, 콜백만 호출한다.
+ */
+export type KeySource = {
+    /** 디버그/UI 라벨 — 'local' | 'keystore' | 'ledger' | 'trezor' | 'json-rpc' | 'custom' | string. */
+    type: string;
+    /**
+     * public key (normal 소스이면 npk, master 소스이면 mpk). Locus 의 PQ
+     * 서명 알고리즘은 secret 으로부터 public 을 결정적으로 derive 할 수
+     * 없어, 호출자가 값을 주입해야 한다.
+     */
+    getPublicKey: (args?: {
+        signal?: AbortSignal;
+    }) => Promise<string>;
+    /** 임의의 메시지에 서명한다 (보통 tx 해시). */
+    signMessage: (args: {
+        message: string;
+        signal?: AbortSignal;
+    }) => Promise<string>;
+    /**
+     * changeKey 흐름용 서명: master KeySource 가 새 normal public key 를
+     * 이전 키에 바인드한다. 이 함수는 master 소스만 제공할 것으로 기대하며,
+     * 이를 필요로 하는 wallet action 을 signKeyBind 구현 없는 KeySource 로
+     * 호출하면 SignKeyBindUnsupportedError 가 발생한다.
+     *
+     * 최초 key bind (TX_OPEN_ACCOUNT) 의 경우 currentNpk 는 빈 문자열 — 노드는
+     * 이를 BlankShortDigest 로 해석한다.
+     */
+    signKeyBind?: (args: {
+        newNpk: string;
+        currentNpk: string;
+        signal?: AbortSignal;
+    }) => Promise<string>;
+};
+/**
+ * Locus account 모델: 두 개의 key source (master + normal). 라이브러리는
+ * TX 마다 어느 소스로 라우팅할지 accounts/signing/txKeyPolicy.mts 의
+ * TX 타입별 정책으로 결정한다.
+ */
+export type DualKeyAccount = {
+    type: 'locus-dual-key';
+    address: Address;
+    master: KeySource;
+    normal: KeySource;
+    /**
+     * _prepareTransaction 이 첫 RPC 호출 전에 부르는 선택적 훅.
+     * TX_OPEN_ACCOUNT / TX_CHANGE_KEYPAIR 의 경우 prepare RPC 단계에서도
+     * 노드가 master 가 증명한 key-bind 서명을 검증하므로 prepare 전에
+     * 미리 채워져 있어야 한다. 변환된 `params` 를 반환하면 dualKeyAccount
+     * 가 `keySign` / `signByMasterKey` 를 자동으로 채우고, 나머지 RPC 는
+     * pass-through 로 둔다.
+     */
+    prepareParams?: (args: {
+        method: string;
+        params: readonly unknown[];
+        signal?: AbortSignal;
+    }) => Promise<readonly unknown[]>;
+    /** _signLocusTransaction 이 호출한다. 사용자 코드가 직접 부르지 않는다. */
+    signTransaction: (args: {
+        prepared: PreparedTransaction;
+        signal?: AbortSignal;
+    }) => Promise<TxSignAdditions>;
+    /** TX 외 메시지 서명용 escape hatch (예: 인증 challenge). */
+    signMessage: (args: {
+        message: string;
+        role?: 'master' | 'normal';
+        signal?: AbortSignal;
+    }) => Promise<string>;
+};
+/** 라이브러리의 표준 account 타입으로 re-export. */
+export type LocusAccount = DualKeyAccount;

package/dist/actions/wallet/_deriveTxAdditions.d.mts

@@ -0,0 +1,18 @@
+import type { PreparedTransaction } from '../../accounts/types.mjs';
+/**
+ * prepared.tx 의 type 으로부터 submit RPC 호출 params[0] 에 echo 해야 할 부가
+ * 필드들을 추출한다.
+ *
+ * 노드는 prepare 단계에서 일부 필드를 직접 생성하거나 확정한 뒤 1차 응답의
+ * `tx` 안에 담아 돌려준다. 이어지는 submit 호출은 *동일 method* 를 다시
+ * 호출하기 때문에, 호출자가 보낸 params 에 이 값들을 다시 채워 넣지 않으면
+ * 노드 검증 단계에서 hash 불일치 또는 빈 필드로 실패한다.
+ *
+ *   TX_CREATE_CONTRACT  -> contractAccount   = tx.target
+ *   TX_CREATE_SA        -> synthAccount      = tx.target
+ *   TX_CREATE_VME       -> sysId             = tx.sysId
+ *   TX_CHANGE_VKEY      -> newValidationPkey = tx.newKey
+ *
+ * prefix 매칭이라 `*_FEE` 변종 (TX_CREATE_CONTRACT_FEE 등) 도 같이 잡힌다.
+ */
+export declare function _deriveTxAdditions(prepared: PreparedTransaction): Record<string, unknown>;

package/dist/actions/wallet/_prepareTransaction.d.mts

@@ -0,0 +1,15 @@
+import type { Client } from '../../clients/types.mjs';
+import type { PrepareTransactionArgs, PreparedTransactionEnvelope } from './types.mjs';
+/**
+ * Locus TX 2-step 흐름의 1 단계.
+ *
+ * TX_CREATION RPC 를 호출자 params 로 호출하고, 응답이 `hash` 와 `tx` 를
+ * 모두 포함하는지 (즉 일반 read 응답이 아니라 진짜 prepare 결과인지)
+ * 검증한다. _signLocusTransaction 과 _sendPreparedTransaction 이 소비할
+ * envelope 를 반환한다.
+ *
+ * 클라이언트가 `prepareParams` 를 제공하는 DualKeyAccount 에 바인드되어
+ * 있으면 params 는 그 훅을 먼저 거친다. OPEN_ACCOUNT / CHANGE_KEYPAIR 가
+ * 노드 검증 전에 master 가 증명한 key-bind 서명을 채우는 경로가 이것.
+ */
+export declare function _prepareTransaction(client: Client, args: PrepareTransactionArgs): Promise<PreparedTransactionEnvelope>;

package/dist/actions/wallet/_sendPreparedTransaction.d.mts

@@ -0,0 +1,9 @@
+import type { Client } from '../../clients/types.mjs';
+import type { SignedTransactionEnvelope } from './types.mjs';
+/**
+ * Locus TX 2-step 흐름의 3 단계.
+ *
+ * sign 단계 결과를 params[0] 에 병합한 뒤 같은 RPC 메서드를 다시 호출한다.
+ * 노드는 이제 완성된 payload 를 받아 최종 결과를 반환한다.
+ */
+export declare function _sendPreparedTransaction<T = unknown>(client: Client, signed: SignedTransactionEnvelope): Promise<T>;

package/dist/actions/wallet/_signLocusTransaction.d.mts

@@ -0,0 +1,14 @@
+import type { DualKeyAccount } from '../../accounts/types.mjs';
+import type { PreparedTransactionEnvelope, SignedTransactionEnvelope } from './types.mjs';
+/**
+ * Locus TX 2-step 흐름의 2 단계.
+ *
+ * prepared envelope 를 account 에 넘기고, account 가 master / normal /
+ * signKeyBind 라우팅을 한 곳에서 수행한다 (accounts/account.mts 참고).
+ *
+ * 동시에 `_deriveTxAdditions` 로 prepared.tx 에서 echo 해야 할 TX-type 별
+ * 필드 (contractAccount / synthAccount / sysId / newValidationPkey) 를
+ * 추출해 sign 결과와 함께 submit 단계 (`_sendPreparedTransaction`) 의
+ * params[0] 머지 대상에 포함시킨다.
+ */
+export declare function _signLocusTransaction(account: DualKeyAccount | undefined, envelope: PreparedTransactionEnvelope): Promise<SignedTransactionEnvelope>;

package/dist/actions/wallet/index.d.mts

@@ -0,0 +1,5 @@
+export * from './types.mjs';
+export * from './_prepareTransaction.mjs';
+export * from './_signLocusTransaction.mjs';
+export * from './_sendPreparedTransaction.mjs';
+export * from './_deriveTxAdditions.mjs';

package/dist/actions/wallet/types.d.mts

@@ -0,0 +1,38 @@
+import type { PreparedTransaction, TxSignAdditions } from '../../accounts/types.mjs';
+export type PrepareTransactionArgs = {
+    /** 호출할 RPC 메서드 (예: 'locus_transferCoin'). */
+    method: string;
+    /** 원본 RPC params. 첫 원소가 3 단계에서 sign 추가 필드를 받는다. */
+    params: readonly unknown[];
+};
+export type PreparedTransactionEnvelope = {
+    method: string;
+    params: readonly unknown[];
+    /** 1 단계에서 노드가 반환한 결과. hash + tx + signedHeight 를 담는다. */
+    prepared: PreparedTransaction;
+};
+/**
+ * submit 호출 (`_sendPreparedTransaction`) 이 params[0] 에 병합하는 부가 필드.
+ *
+ * 두 출처의 합집합:
+ *  - sign 단계 결과 (`TxSignAdditions`) — sign / signedHeight / keySign /
+ *    signByMasterKey.
+ *  - prepared.tx 에서 echo 해야 하는 TX-type 별 필드 (`_deriveTxAdditions`):
+ *    contractAccount / synthAccount / sysId / newValidationPkey.
+ */
+export type SubmitAdditions = TxSignAdditions & {
+    /** TX_CREATE_CONTRACT — 노드가 생성한 컨트랙트 주소를 echo. */
+    contractAccount?: string;
+    /** TX_CREATE_SA — 노드가 생성한 synth account 주소를 echo. */
+    synthAccount?: string;
+    /** TX_CREATE_VME — 노드가 확정한 sysId 를 echo. */
+    sysId?: string;
+    /** TX_CHANGE_VKEY — 노드가 echo 한 새 validation pubkey. */
+    newValidationPkey?: string;
+};
+export type SignedTransactionEnvelope = {
+    method: string;
+    params: readonly unknown[];
+    /** 2 단계 결과 — 3 단계에서 params[0] 에 병합된다. */
+    additions: SubmitAdditions;
+};

package/dist/autogen/actions/debug/index.d.mts

@@ -0,0 +1,2 @@
+export * from './public/index.mjs';
+export * from './wallet/index.mjs';

package/dist/autogen/actions/debug/public/allHeights.d.mts

@@ -0,0 +1,3 @@
+import { RpcAccountHeight } from '../../../types/common/rpc-account-height.mjs';
+import type { Client } from '../../../../clients/types.mjs';
+export declare function allHeights(client: Client): Promise<RpcAccountHeight[]>;

package/dist/autogen/actions/debug/public/balanceGrantList.d.mts

@@ -0,0 +1,2 @@
+import type { Client } from '../../../../clients/types.mjs';
+export declare function balanceGrantList(client: Client): Promise<string[]>;

package/dist/autogen/actions/debug/public/balanceList.d.mts

@@ -0,0 +1,2 @@
+import type { Client } from '../../../../clients/types.mjs';
+export declare function balanceList(client: Client): Promise<string[]>;

package/dist/autogen/actions/debug/public/createAccount.d.mts

@@ -0,0 +1,3 @@
+import { RpcCreateAccountResult } from '../../../types/rpc/rpc-create-account-result.mjs';
+import type { Client } from '../../../../clients/types.mjs';
+export declare function createAccount(client: Client): Promise<RpcCreateAccountResult>;

package/dist/autogen/actions/debug/public/createNode.d.mts

@@ -0,0 +1,4 @@
+import { ParamsCreateNode } from '../../../types/rpc/params-create-node.mjs';
+import { RpcCreateNodeResult } from '../../../types/rpc/rpc-create-node-result.mjs';
+import type { Client } from '../../../../clients/types.mjs';
+export declare function createNode(client: Client, param: ParamsCreateNode): Promise<RpcCreateNodeResult>;

package/dist/autogen/actions/debug/public/dumpAllAccounts.d.mts

@@ -0,0 +1,3 @@
+import { ResultDumpAccounts } from '../../../types/rpc/result-dump-accounts.mjs';
+import type { Client } from '../../../../clients/types.mjs';
+export declare function dumpAllAccounts(client: Client): Promise<ResultDumpAccounts>;

package/dist/autogen/actions/debug/public/echo.d.mts

@@ -0,0 +1,2 @@
+import type { Client } from '../../../../clients/types.mjs';
+export declare function echo(client: Client, str: string): Promise<string>;