@reefclaw/openclaw-plugin 0.1.19 → 0.1.21

package/security/sealed-credentials.js

@@ -0,0 +1,180 @@
+// Sealed credential transport — the box side of the dashboard→box envelope.
+//
+// Why: exchange credentials entered in the dashboard transit browser → relay
+// (PartyKit/Cloudflare) → bridge → plugin. They were already never STORED and
+// never LOGGED off-box, but they were readable in memory by every hop. This
+// module removes that: the browser encrypts the credential payload to a
+// public key only this box holds, so the relay and the webapp carry
+// ciphertext they cannot open. The private half never leaves
+// ~/.reefclaw/credential-transport-key.json (0600).
+//
+// Scheme (ECIES, deliberately boring):
+//   recipient: static ECDH P-256 keypair (P-256 over X25519 for WebCrypto
+//     availability in every browser).
+//   sender:    ephemeral ECDH P-256 keypair per message.
+//   KDF:       HKDF-SHA256(ikm = ECDH x-coordinate, salt = 32 zero bytes,
+//              info = "reefclaw-credential-sealbox-v1" || recipientPub ||
+//              ephemeralPub) → 32-byte AES key. Binding both public keys into
+//              `info` ties the key to this exact pair.
+//   cipher:    AES-256-GCM, 12-byte IV, AAD "reefclaw-credentials-v1",
+//              16-byte tag appended to the ciphertext (WebCrypto's layout).
+//   envelope:  { v:1, kid, epk, iv, ct } — kid = first 16 hex of
+//              SHA-256(recipient public key, uncompressed), epk/iv/ct base64.
+//
+// The webapp sealer (webapp/src/lib/crypto/seal-credentials.ts) implements the
+// exact mirror in WebCrypto; a shared fixed test vector in BOTH packages pins
+// the wire format so the two implementations can never drift silently.
+//
+// SECURITY: this module holds the transport PRIVATE key and the decrypted
+// plaintext in memory only. It never logs either, never returns the private
+// key, and the public key is the ONLY thing published (via the readiness
+// report — that is its purpose).
+import { createECDH, createDecipheriv, createHash, hkdfSync } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { logger } from '../logger.js';
+const TAG = 'sealed-credentials';
+const CURVE = 'prime256v1'; // P-256
+const KDF_CONTEXT = 'reefclaw-credential-sealbox-v1';
+const AAD = 'reefclaw-credentials-v1';
+const KEY_FILE = 'credential-transport-key.json';
+export class SealedEnvelopeError extends Error {
+    reason;
+    constructor(message, 
+    /** 'key_mismatch' → the browser sealed to a stale/foreign key (refresh the
+     *  dashboard so it refetches this box's current key); 'malformed' → not a
+     *  v1 envelope; 'decrypt_failed' → tampered or corrupted in transit. */
+    reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'SealedEnvelopeError';
+    }
+}
+function keyFilePath(dir) {
+    return join(dir ?? join(homedir(), '.reefclaw'), KEY_FILE);
+}
+export function computeKeyId(publicKeyRaw) {
+    return createHash('sha256').update(publicKeyRaw).digest('hex').slice(0, 16);
+}
+function loadKeyFile(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(keyFilePath(dir), 'utf-8'));
+        if (raw?.v === 1 &&
+            raw.curve === 'p256' &&
+            typeof raw.privateKeyHex === 'string' &&
+            /^[0-9a-f]{64}$/i.test(raw.privateKeyHex) &&
+            typeof raw.publicKeyHex === 'string' &&
+            /^04[0-9a-f]{128}$/i.test(raw.publicKeyHex)) {
+            return raw;
+        }
+    }
+    catch {
+        // Missing or unreadable — caller generates.
+    }
+    return null;
+}
+/** Ensure the box's static transport keypair exists (generate + persist 0600 on
+ *  first run) and return the PUBLIC half for the readiness report. Never
+ *  returns or logs the private half. */
+export function ensureCredentialTransportKey(dir) {
+    const existing = loadKeyFile(dir);
+    if (existing) {
+        const pub = Buffer.from(existing.publicKeyHex, 'hex');
+        return { publicKeyBase64: pub.toString('base64'), keyId: computeKeyId(pub) };
+    }
+    const ecdh = createECDH(CURVE);
+    ecdh.generateKeys();
+    const pub = ecdh.getPublicKey(); // uncompressed 65 bytes
+    const file = {
+        v: 1,
+        curve: 'p256',
+        privateKeyHex: ecdh.getPrivateKey().toString('hex').padStart(64, '0'),
+        publicKeyHex: pub.toString('hex'),
+    };
+    const path = keyFilePath(dir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(file), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600); // writeFileSync mode is ignored on some platforms
+    }
+    catch {
+        // Windows dev box — best effort; prod boxes are Linux.
+    }
+    logger.info(TAG, `Generated credential transport key (keyId ${computeKeyId(pub)})`);
+    return { publicKeyBase64: pub.toString('base64'), keyId: computeKeyId(pub) };
+}
+/** The PUBLIC half for the readiness report, or null when no key exists yet
+ *  (never generates — boot calls ensureCredentialTransportKey first). */
+export function getCredentialTransportPublicKey(dir) {
+    const file = loadKeyFile(dir);
+    if (!file)
+        return null;
+    const pub = Buffer.from(file.publicKeyHex, 'hex');
+    return { publicKeyBase64: pub.toString('base64'), keyId: computeKeyId(pub) };
+}
+function b64(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new SealedEnvelopeError(`sealed envelope missing ${name}`, 'malformed');
+    }
+    const buf = Buffer.from(value, 'base64');
+    if (buf.length === 0)
+        throw new SealedEnvelopeError(`sealed envelope ${name} is not base64`, 'malformed');
+    return buf;
+}
+/** Derive the AES key exactly as the browser sealer does — pinned by the
+ *  cross-package fixed vector. */
+function deriveAesKey(shared, recipientPub, ephemeralPub) {
+    const info = Buffer.concat([Buffer.from(KDF_CONTEXT, 'utf8'), recipientPub, ephemeralPub]);
+    return Buffer.from(hkdfSync('sha256', shared, Buffer.alloc(32), info, 32));
+}
+/** Open a sealed credential envelope with this box's private transport key.
+ *  Returns the decrypted JSON payload (plain object). Throws
+ *  SealedEnvelopeError with a caller-renderable reason on any failure. */
+export function unsealCredentials(envelope, dir) {
+    if (!envelope || typeof envelope !== 'object') {
+        throw new SealedEnvelopeError('sealed payload must be an object', 'malformed');
+    }
+    const env = envelope;
+    if (env.v !== 1)
+        throw new SealedEnvelopeError('unsupported sealed envelope version', 'malformed');
+    const file = loadKeyFile(dir);
+    if (!file) {
+        throw new SealedEnvelopeError('this box has no credential transport key yet — restart the agent, then refresh the dashboard', 'key_mismatch');
+    }
+    const ourPub = Buffer.from(file.publicKeyHex, 'hex');
+    if (typeof env.kid !== 'string' || env.kid !== computeKeyId(ourPub)) {
+        throw new SealedEnvelopeError('the dashboard encrypted to a different key than this box holds — refresh the dashboard page and try again', 'key_mismatch');
+    }
+    const epk = b64(env.epk, 'epk');
+    const iv = b64(env.iv, 'iv');
+    const ct = b64(env.ct, 'ct');
+    if (epk.length !== 65 || epk[0] !== 0x04) {
+        throw new SealedEnvelopeError('sealed envelope epk is not an uncompressed P-256 point', 'malformed');
+    }
+    if (iv.length !== 12 || ct.length <= 16) {
+        throw new SealedEnvelopeError('sealed envelope iv/ct malformed', 'malformed');
+    }
+    try {
+        const ecdh = createECDH(CURVE);
+        ecdh.setPrivateKey(Buffer.from(file.privateKeyHex, 'hex'));
+        const shared = ecdh.computeSecret(epk);
+        const key = deriveAesKey(shared, ourPub, epk);
+        const tag = ct.subarray(ct.length - 16);
+        const body = ct.subarray(0, ct.length - 16);
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAAD(Buffer.from(AAD, 'utf8'));
+        decipher.setAuthTag(tag);
+        const plain = Buffer.concat([decipher.update(body), decipher.final()]).toString('utf8');
+        const parsed = JSON.parse(plain);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new SealedEnvelopeError('sealed payload did not contain an object', 'decrypt_failed');
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof SealedEnvelopeError)
+            throw err;
+        throw new SealedEnvelopeError('could not decrypt the sealed credentials — the payload was corrupted in transit; try again', 'decrypt_failed');
+    }
+}

package/tools/clear-exchange-credentials.js

@@ -11,7 +11,7 @@
 //   - Always de-escalates to PAPER on mode rollback; never stays in a
 //     live mode without credentials (would crash the adapter on first
 //     order anyway).
-import { updatePluginConfig } from '../config/plugin-config-io.js';
+import { readPluginConfig, updatePluginConfig } from '../config/plugin-config-io.js';
 import { logger } from '../logger.js';
 const TAG = 'clear-exchange-credentials';
 export async function clearExchangeCredentialsTool(args, deps) {
@@ -26,6 +26,16 @@ export async function clearExchangeCredentialsTool(args, deps) {
             readiness: deps.runtime.adapter.readiness,
         };
     }
+    // Clearing removes the whole `exchange` block INCLUDING `venue` — a
+    // hyperliquid box reverts to the binance default paper stack on its next
+    // restart, so the outcome message says so (the paper wiring is boot-time).
+    let clearedVenueWasHyperliquid = false;
+    try {
+        clearedVenueWasHyperliquid = readPluginConfig(deps.configPath).exchange?.venue === 'hyperliquid';
+    }
+    catch {
+        // Unreadable config — nothing venue-specific to report.
+    }
     try {
         updatePluginConfig({ exchange: undefined }, deps.configPath);
     }
@@ -57,11 +67,14 @@ export async function clearExchangeCredentialsTool(args, deps) {
         await deps.runtime.reconnect({ mode: 'PAPER', exchange: null }, { adapterDeps: deps.adapterDeps });
         rolledBackToPaper = true;
     }
+    const venueNote = clearedVenueWasHyperliquid
+        ? ' (venue selection cleared too — the box reverts to Binance paper data on its next restart)'
+        : '';
     return {
         ok: true,
         message: rolledBackToPaper
-            ? `Credentials cleared and trading mode rolled back from ${modeBefore} to PAPER`
-            : 'Credentials cleared',
+            ? `Credentials cleared and trading mode rolled back from ${modeBefore} to PAPER${venueNote}`
+            : `Credentials cleared${venueNote}`,
         modeBefore,
         mode: deps.runtime.mode,
         rolledBackToPaper,

package/tools/hl-agent-wallet-status.d.ts

@@ -0,0 +1,29 @@
+import type { VenueId } from '../venues/registry.js';
+export interface HlAgentWalletStatusArgs {
+    /** Tool-discovery probe — return immediately, no config/network access. */
+    probe?: boolean;
+}
+export interface HlAgentWalletStatusResult {
+    ok: boolean;
+    message: string;
+    /** False until an HL wallet (venue + agent key) exists in plugin-config. */
+    configured: boolean;
+    masterAddress?: string;
+    /** Derived from the stored key (public). */
+    agentAddress?: string;
+    testnet?: boolean;
+    /** true/false = definitive verdict from the exchange; null = unverifiable. */
+    approved?: boolean | null;
+    /** Approval expiry (epoch ms) when the exchange reports one. */
+    validUntil?: number | null;
+    balanceUSDC?: number | null;
+    warnings?: string[];
+    /** True when the booted venue is not hyperliquid yet — restart pending. */
+    restartRequired?: boolean;
+}
+export interface HlAgentWalletStatusDeps {
+    bootVenue?: VenueId;
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function hlAgentWalletStatusTool(args: HlAgentWalletStatusArgs, deps?: HlAgentWalletStatusDeps): Promise<HlAgentWalletStatusResult>;

package/tools/hl-agent-wallet-status.js

@@ -0,0 +1,100 @@
+// hl_agent_wallet_status — operator-only plugin tool.
+//
+// The polling half of the guided Hyperliquid onboarding: after
+// hl_provision_agent_wallet mints a key and the operator signs the
+// approveAgent approval in their browser, the dashboard polls THIS tool until
+// Hyperliquid lists the box's agent address as approved. All reads are the
+// keyless shared preflight (hl-preflight.ts) — the stored private key is only
+// ever used here to DERIVE its public address, never to sign, and never
+// appears in the result.
+//
+// `{ probe: true }` short-circuits before touching config or network — the
+// bridge's tool-discovery probes every optional tool at boot, and a probe
+// that ran the real preflight would put 2 HL /info calls on every discovery
+// retry cycle (and could time the 8s probe out entirely → the tool would be
+// "missing" forever; see tool-discovery.ts).
+import { readPluginConfig } from '../config/plugin-config-io.js';
+import { deriveAddressFromPrivateKey } from '../venues/hyperliquid/hl-agent-wallet.js';
+import { hlPreflight } from '../venues/hyperliquid/hl-preflight.js';
+import { logger } from '../logger.js';
+const TAG = 'hl-agent-wallet-status';
+export async function hlAgentWalletStatusTool(args, deps = {}) {
+    if (args?.probe === true) {
+        return { ok: false, message: 'probe', configured: false };
+    }
+    let masterAddress;
+    let storedKey;
+    let testnet = false;
+    try {
+        const cfg = readPluginConfig(deps.configPath);
+        if (cfg.exchange?.venue === 'hyperliquid' && typeof cfg.exchange.agentPrivateKey === 'string') {
+            storedKey = cfg.exchange.agentPrivateKey;
+            masterAddress =
+                typeof cfg.exchange.walletAddress === 'string' ? cfg.exchange.walletAddress : undefined;
+            testnet = cfg.exchange.testnet === true;
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `config read failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!storedKey || !masterAddress) {
+        return {
+            ok: true,
+            message: 'No Hyperliquid agent wallet is provisioned on this machine yet.',
+            configured: false,
+        };
+    }
+    const restartRequired = (deps.bootVenue ?? 'binance') !== 'hyperliquid';
+    const derived = await deriveAddressFromPrivateKey(storedKey);
+    if (!derived.ok) {
+        return {
+            ok: true,
+            message: 'A wallet is stored but its address could not be derived on this host — approval not verifiable.',
+            configured: true,
+            masterAddress,
+            testnet,
+            approved: null,
+            validUntil: null,
+            restartRequired,
+            warnings: ['Could not derive the agent wallet address on this host — approval not verified.'],
+        };
+    }
+    const pre = await hlPreflight({
+        walletAddress: masterAddress,
+        agentAddress: derived.address,
+        testnet,
+        fetchImpl: deps.fetchImpl,
+    });
+    if (!pre.reachable) {
+        return {
+            ok: false,
+            message: `Could not reach Hyperliquid to check the approval: ${pre.unreachableError ?? 'unknown error'}`,
+            configured: true,
+            masterAddress,
+            agentAddress: derived.address,
+            testnet,
+            approved: null,
+            validUntil: null,
+            restartRequired,
+            warnings: pre.warnings,
+        };
+    }
+    const approvedText = pre.agentApproved === true
+        ? 'approved'
+        : pre.agentApproved === false
+            ? 'NOT approved yet'
+            : 'approval not verifiable';
+    return {
+        ok: true,
+        message: `Agent wallet ${derived.address.slice(0, 8)}… is ${approvedText}.`,
+        configured: true,
+        masterAddress,
+        agentAddress: derived.address,
+        testnet,
+        approved: pre.agentApproved,
+        validUntil: pre.agentValidUntil,
+        balanceUSDC: pre.balanceUSDC,
+        warnings: pre.warnings,
+        restartRequired,
+    };
+}

package/tools/hl-provision-agent-wallet.d.ts

@@ -0,0 +1,35 @@
+import type { PluginRuntime } from '../onboarding/runtime.js';
+import type { TradingMode } from '../types.js';
+import type { VenueId } from '../venues/registry.js';
+export interface HlProvisionAgentWalletArgs {
+    /** MASTER account address (public, 0x…) the agent wallet will trade for. */
+    walletAddress?: string;
+    testnet?: boolean;
+    /** Mint a fresh key even when one exists (PAPER mode only). */
+    regenerate?: boolean;
+}
+export interface HlProvisionAgentWalletResult {
+    ok: boolean;
+    message: string;
+    venue: 'hyperliquid';
+    /** Derived agent address (public) — what the operator approves on HL. */
+    agentAddress?: string;
+    /** Master address the stored credentials are bound to. */
+    masterAddress?: string;
+    testnet?: boolean;
+    /** True when an already-provisioned wallet was returned instead of minting. */
+    existing?: boolean;
+    /** Existing path only: does the stored master match the requested one? */
+    masterMatches?: boolean;
+    /** True when the boot venue differs — restart applies the venue. */
+    restartRequired?: boolean;
+    mode: TradingMode;
+}
+export interface HlProvisionAgentWalletDeps {
+    runtime: PluginRuntime;
+    /** The venue this process booted with. */
+    bootVenue?: VenueId;
+    /** Override the config file path — tests use this. */
+    configPath?: string;
+}
+export declare function hlProvisionAgentWalletTool(args: HlProvisionAgentWalletArgs, deps: HlProvisionAgentWalletDeps): Promise<HlProvisionAgentWalletResult>;

package/tools/hl-provision-agent-wallet.js

@@ -0,0 +1,144 @@
+// hl_provision_agent_wallet — operator-only plugin tool.
+//
+// The zero-secret-handling Hyperliquid onboarding path: the agent-wallet
+// PRIVATE KEY IS BORN ON THIS BOX. This tool generates a fresh secp256k1
+// keypair locally, persists it straight into ~/.reefclaw/plugin-config.json
+// (venue=hyperliquid, wholesale exchange-block write — same contract as
+// set_exchange_credentials), and returns ONLY the derived PUBLIC address.
+// The dashboard then walks the operator through approving that address with
+// one wallet signature (Hyperliquid `approveAgent` — user-signed, submitted
+// from the browser straight to HL); hl_agent_wallet_status polls until the
+// approval lands. Nobody — not the browser, not the relay, not ReefClaw, not
+// even the operator — ever sees the private key.
+//
+// Semantics:
+//   - IDEMPOTENT by default: if an HL agent key already exists in config the
+//     tool returns its derived address (existing:true) instead of minting a
+//     new one — a closed-and-reopened dashboard resumes where it left off.
+//   - `regenerate:true` mints a fresh key (the old one's approval becomes
+//     orphaned on HL; the UI warns first). REFUSED while trading mode is not
+//     PAPER — replacing the signing key under a live book breaks the next
+//     restart until the new key is approved.
+//   - A venue CHANGE (boot venue ≠ hyperliquid) is restart-required, exactly
+//     like set_exchange_credentials — provisioning + approval both work
+//     pre-restart (approval polling is keyless), so the restart is the LAST
+//     step of the guided flow, not a blocker in the middle.
+//
+// Security: the private key exists only in this process's memory between
+// generation and the config write. It is never logged, never in the result,
+// never egressed (credential-no-egress.test.ts pins this module).
+import { readPluginConfig, updatePluginConfig, redactCredential } from '../config/plugin-config-io.js';
+import { deriveAddressFromPrivateKey, generateAgentPrivateKey, isHexAddress, } from '../venues/hyperliquid/hl-agent-wallet.js';
+import { logger } from '../logger.js';
+const TAG = 'hl-provision-agent-wallet';
+export async function hlProvisionAgentWalletTool(args, deps) {
+    const bootVenue = deps.bootVenue ?? 'binance';
+    const mode = deps.runtime.mode;
+    const restartRequired = bootVenue !== 'hyperliquid';
+    if (!isHexAddress(args?.walletAddress)) {
+        return {
+            ok: false,
+            message: 'walletAddress must be your MASTER account address: 0x followed by 40 hex characters',
+            venue: 'hyperliquid',
+            mode,
+        };
+    }
+    const walletAddress = args.walletAddress.trim();
+    const testnet = args.testnet === true;
+    // Existing-wallet path: resume, don't clobber.
+    let existingKey = null;
+    let existingMaster = null;
+    let existingTestnet = false;
+    try {
+        const cfg = readPluginConfig(deps.configPath);
+        if (cfg.exchange?.venue === 'hyperliquid' && typeof cfg.exchange.agentPrivateKey === 'string') {
+            existingKey = cfg.exchange.agentPrivateKey;
+            existingMaster = typeof cfg.exchange.walletAddress === 'string' ? cfg.exchange.walletAddress : null;
+            existingTestnet = cfg.exchange.testnet === true;
+        }
+    }
+    catch {
+        // Unreadable config — treat as fresh.
+    }
+    if (existingKey && args.regenerate !== true) {
+        const derived = await deriveAddressFromPrivateKey(existingKey);
+        if (derived.ok) {
+            const masterMatches = existingMaster != null && existingMaster.toLowerCase() === walletAddress.toLowerCase();
+            return {
+                ok: true,
+                message: masterMatches
+                    ? 'An agent wallet is already provisioned for this master account — approve it if you have not yet.'
+                    : `An agent wallet is already provisioned for a DIFFERENT master account (${redactCredential(existingMaster ?? '')}). ` +
+                        'Pass regenerate: true to replace it (its approval will be orphaned).',
+                venue: 'hyperliquid',
+                agentAddress: derived.address,
+                masterAddress: existingMaster ?? undefined,
+                testnet: existingTestnet,
+                existing: true,
+                masterMatches,
+                restartRequired,
+                mode,
+            };
+        }
+        // Stored key is corrupt/underivable — fall through to mint a fresh one
+        // (regenerate semantics: the stored key was never usable anyway).
+        logger.warn(TAG, 'Stored agent key is not derivable — provisioning a fresh one');
+    }
+    if (existingKey && args.regenerate === true && mode !== 'PAPER') {
+        return {
+            ok: false,
+            message: `Refusing to replace the agent key while trading mode is ${mode} — go to PAPER first ` +
+                '(a fresh key is unapproved and would leave the next restart unable to sign).',
+            venue: 'hyperliquid',
+            mode,
+        };
+    }
+    // Mint. The key exists in memory only between these two statements.
+    const agentPrivateKey = generateAgentPrivateKey();
+    const derived = await deriveAddressFromPrivateKey(agentPrivateKey);
+    if (!derived.ok) {
+        // Without the derived address the guided flow cannot proceed (nothing to
+        // approve). Fail cleanly toward the manual path.
+        return {
+            ok: false,
+            message: 'Could not derive the agent wallet address on this host — use the manual setup instead ' +
+                '(generate the agent wallet on the Hyperliquid API page and paste the two values).',
+            venue: 'hyperliquid',
+            mode,
+        };
+    }
+    const exchange = {
+        venue: 'hyperliquid',
+        walletAddress,
+        agentPrivateKey,
+        testnet,
+    };
+    try {
+        updatePluginConfig({ exchange }, deps.configPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `Failed to persist provisioned wallet: ${msg}`);
+        return {
+            ok: false,
+            message: `Failed to persist the provisioned wallet: ${msg}`,
+            venue: 'hyperliquid',
+            mode,
+        };
+    }
+    logger.info(TAG, `Provisioned agent wallet ${derived.address} for master ${redactCredential(walletAddress)} ` +
+        `(testnet: ${testnet}${restartRequired ? ', restart required to apply venue' : ''})`);
+    return {
+        ok: true,
+        message: restartRequired
+            ? 'Agent wallet created on this machine. Approve it on Hyperliquid, then restart your agent to switch the venue.'
+            : 'Agent wallet created on this machine. Approve it on Hyperliquid to finish.',
+        venue: 'hyperliquid',
+        agentAddress: derived.address,
+        masterAddress: walletAddress,
+        testnet,
+        existing: false,
+        restartRequired,
+        mode,
+    };
+}

package/tools/set-exchange-credentials.d.ts

@@ -1,11 +1,30 @@
 import type { PluginRuntime } from '../onboarding/runtime.js';
 import type { IExchangeAdapter } from '../exchange-adapter.js';
 import type { TradingMode } from '../types.js';
+import { type VenueId } from '../venues/registry.js';
 export interface SetExchangeCredentialsArgs {
-    apiKey: string;
-    secret: string;
+    /** Absent → 'binance' (legacy callers unchanged). */
+    venue?: string;
+    apiKey?: string;
+    secret?: string;
+    walletAddress?: string;
+    agentPrivateKey?: string;
     testnet?: boolean;
+    /** End-to-end encrypted envelope from the dashboard (sealed-credentials.ts).
+     *  When present it is the SOLE source of the credential fields — any
+     *  plaintext siblings are ignored, so a mixed payload can't smuggle values
+     *  past the encryption. */
+    sealed?: unknown;
 }
+/** Open a sealed envelope into plain args, or return a renderable error. */
+export declare function resolveSealedArgs<T extends {
+    sealed?: unknown;
+}>(args: T, configDir?: string): {
+    args: T;
+    sealed: boolean;
+} | {
+    error: string;
+};
 export interface SetExchangeCredentialsResult {
     ok: boolean;
     message: string;
@@ -13,13 +32,23 @@ export interface SetExchangeCredentialsResult {
     reconnected: boolean;
     mode: TradingMode;
     readiness: string;
+    /** Venue the credentials were stored for. */
+    venue?: VenueId;
+    /** True when the stored venue differs from the booted venue — the operator
+     *  must restart the agent before the change takes effect. */
+    restartRequired?: boolean;
 }
 export interface SetExchangeCredentialsDeps {
     runtime: PluginRuntime;
     adapterDeps: {
         adapter: IExchangeAdapter;
     };
+    /** The venue this process booted with (register()-time). Venue changes are
+     *  restart-required; absent (legacy tests) → 'binance'. */
+    bootVenue?: VenueId;
     /** Override the config file path — tests use this. */
     configPath?: string;
+    /** Override the transport-key directory (sealed envelopes) — tests use this. */
+    transportKeyDir?: string;
 }
-export declare function setExchangeCredentialsTool(args: SetExchangeCredentialsArgs, deps: SetExchangeCredentialsDeps): Promise<SetExchangeCredentialsResult>;
+export declare function setExchangeCredentialsTool(rawArgs: SetExchangeCredentialsArgs, deps: SetExchangeCredentialsDeps): Promise<SetExchangeCredentialsResult>;