safehands-pharos 1.5.0 → 2.6.0

package/dist/lib/pharos/rpcMethods.js.map

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

package/dist/lib/pharos/spvVerifier.d.ts

@@ -0,0 +1,47 @@
+export interface SPVProofNode {
+    proofNode: string;
+    nextBeginOffset: number;
+    nextEndOffset: number;
+}
+export interface SPVStorageProof {
+    key: string;
+    value: string;
+    isExist: boolean;
+    proof: SPVProofNode[];
+}
+export interface SPVSiblingProof {
+    slotIndex: number;
+    leftmostLeafKey: string;
+    proofPath: SPVProofNode[];
+}
+export interface SPVResponse {
+    balance: string;
+    nonce: string;
+    codeHash: string;
+    storageHash: string;
+    isExist: boolean;
+    rawValue: string;
+    accountProof: SPVProofNode[];
+    storageProof: SPVStorageProof[];
+    siblingLeftmostLeafProofs?: SPVSiblingProof[];
+}
+/**
+ * Hash a hex string using SHA-256 (Pharos uses SHA-256 for SPV, not Keccak).
+ */
+export declare function sha256Hex(hexStr: string): string;
+/**
+ * Gets a specific nibble (4 bits) from a hex hash string at the given depth.
+ * depth 0 = first nibble, depth 1 = second nibble, etc.
+ */
+export declare function getNibbleAtDepth(hashHex: string, depth: number): number;
+/**
+ * Derives the expected nextBeginOffset based on the key and the node's depth.
+ * This is CRITICAL for non-existence soundness to prevent fake slot redirection.
+ */
+export declare function deriveExpectedOffset(key: string, depth: number): number;
+/**
+ * Verifies a Pharos SPV Proof (Existence or Non-Existence).
+ * Returns true if the proof is cryptographically sound and matches the stateRoot.
+ */
+export declare function verifyPharosSPV(key: string, stateRoot: string, isExist: boolean, proof: SPVProofNode[], siblings?: SPVSiblingProof[]): boolean;
+//# sourceMappingURL=spvVerifier.d.ts.map

package/dist/lib/pharos/spvVerifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spvVerifier.d.ts","sourceRoot":"","sources":["../../../src/lib/pharos/spvVerifier.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,yBAAyB,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAcvE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,YAAY,EAAE,EACrB,QAAQ,CAAC,EAAE,eAAe,EAAE,GAC3B,OAAO,CAqET"}

package/dist/lib/pharos/spvVerifier.js

@@ -0,0 +1,105 @@
+import { createHash } from "crypto";
+import { hexToBytes } from "viem";
+/**
+ * Hash a hex string using SHA-256 (Pharos uses SHA-256 for SPV, not Keccak).
+ */
+export function sha256Hex(hexStr) {
+    const bytes = hexToBytes(hexStr);
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    return `0x${hash}`;
+}
+/**
+ * Gets a specific nibble (4 bits) from a hex hash string at the given depth.
+ * depth 0 = first nibble, depth 1 = second nibble, etc.
+ */
+export function getNibbleAtDepth(hashHex, depth) {
+    const cleanHash = hashHex.startsWith("0x") ? hashHex.slice(2) : hashHex;
+    if (depth >= cleanHash.length)
+        return 0;
+    return parseInt(cleanHash[depth], 16);
+}
+/**
+ * Derives the expected nextBeginOffset based on the key and the node's depth.
+ * This is CRITICAL for non-existence soundness to prevent fake slot redirection.
+ */
+export function deriveExpectedOffset(key, depth) {
+    if (depth === 0) {
+        // MSU Root layer: 256 flat slots. Offset = last byte of key * 32
+        const cleanKey = key.startsWith("0x") ? key.slice(2) : key;
+        const lastByteHex = cleanKey.slice(-2);
+        const msuSlotIndex = parseInt(lastByteHex, 16);
+        return msuSlotIndex * 32;
+    }
+    else {
+        // Internal node layer: 3-byte header + 16 slots. Offset = 3 + nibble * 32
+        const keyHash = sha256Hex(key);
+        // depth - 1 because depth 0 is MSU root. Internal nodes start at trie depth 0 (which is chain depth 1)
+        const slotIdx = getNibbleAtDepth(keyHash, depth - 1);
+        return 3 + slotIdx * 32;
+    }
+}
+/**
+ * Verifies a Pharos SPV Proof (Existence or Non-Existence).
+ * Returns true if the proof is cryptographically sound and matches the stateRoot.
+ */
+export function verifyPharosSPV(key, stateRoot, isExist, proof, siblings) {
+    if (!proof || proof.length === 0)
+        return false;
+    if (isExist) {
+        // EXISTENCE PROOF VERIFICATION
+        // 1. Verify Leaf
+        const leaf = proof[proof.length - 1];
+        // In this SPV verifier, we compute the hash of the leaf directly.
+        let currentHash = sha256Hex(leaf.proofNode);
+        // 2. Walk upwards to root
+        for (let i = proof.length - 2; i >= 0; i--) {
+            const parent = proof[i];
+            const expectedOffset = deriveExpectedOffset(key, i);
+            // Security Check: Enforce key-derived offset
+            if (parent.nextBeginOffset !== expectedOffset) {
+                throw new Error(`SPV Verification Failed: Invalid slot offset at depth ${i}. Expected ${expectedOffset}, got ${parent.nextBeginOffset}`);
+            }
+            currentHash = sha256Hex(parent.proofNode);
+        }
+        // 3. Verify against State Root
+        return currentHash.toLowerCase() === stateRoot.toLowerCase();
+    }
+    else {
+        // NON-EXISTENCE PROOF VERIFICATION
+        // Step 1: Verify the main chain up to the empty slot internal node
+        const lastInternal = proof[proof.length - 1];
+        let currentHash = sha256Hex(lastInternal.proofNode);
+        for (let i = proof.length - 2; i >= 0; i--) {
+            const parent = proof[i];
+            const expectedOffset = deriveExpectedOffset(key, i);
+            if (parent.nextBeginOffset !== expectedOffset) {
+                throw new Error(`SPV Non-Existence Failed: Invalid main chain offset at depth ${i}`);
+            }
+            currentHash = sha256Hex(parent.proofNode);
+        }
+        if (currentHash.toLowerCase() !== stateRoot.toLowerCase())
+            return false;
+        // Step 2: Verify all sibling chains (Case 2)
+        if (siblings && siblings.length > 0) {
+            for (const sib of siblings) {
+                if (!sib.proofPath || sib.proofPath.length === 0)
+                    continue;
+                // Combine main chain (minus last node) with sibling path
+                const combined = [...proof.slice(0, proof.length - 1), ...sib.proofPath];
+                let sibHash = sha256Hex(combined[combined.length - 1].proofNode);
+                for (let i = combined.length - 2; i >= 0; i--) {
+                    const parent = combined[i];
+                    const expectedOffset = deriveExpectedOffset(sib.leftmostLeafKey, i);
+                    if (parent.nextBeginOffset !== expectedOffset) {
+                        throw new Error(`SPV Sibling Verification Failed for slot ${sib.slotIndex}`);
+                    }
+                    sibHash = sha256Hex(parent.proofNode);
+                }
+                if (sibHash.toLowerCase() !== stateRoot.toLowerCase())
+                    return false;
+            }
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=spvVerifier.js.map

package/dist/lib/pharos/spvVerifier.js.map

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

package/dist/lib/pharos/userSignedBroadcaster.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Gated module specifically for sending externally signed transactions.
+ * Rules:
+ * - Does not sign, hold keys, or create wallets.
+ * - Only active if SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED=true.
+ * - Only supports Pharos Pacific Mainnet (chainId 1672).
+ * - Bypasses PharosReadOnlyRpc by design to allow eth_sendRawTransaction.
+ */
+export declare function broadcastSignedTransaction(rawSignedTx: string, chainId: number): Promise<string>;
+//# sourceMappingURL=userSignedBroadcaster.d.ts.map

package/dist/lib/pharos/userSignedBroadcaster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userSignedBroadcaster.d.ts","sourceRoot":"","sources":["../../../src/lib/pharos/userSignedBroadcaster.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6CtG"}

package/dist/lib/pharos/userSignedBroadcaster.js

@@ -0,0 +1,50 @@
+import { getActiveNetwork, resolveRpcUrl } from "../networks.js";
+import { fetchWithTimeoutAndRetry } from "../http.js";
+/**
+ * Gated module specifically for sending externally signed transactions.
+ * Rules:
+ * - Does not sign, hold keys, or create wallets.
+ * - Only active if SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED=true.
+ * - Only supports Pharos Pacific Mainnet (chainId 1672).
+ * - Bypasses PharosReadOnlyRpc by design to allow eth_sendRawTransaction.
+ */
+export async function broadcastSignedTransaction(rawSignedTx, chainId) {
+    if (process.env.SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED !== "true") {
+        throw new Error("Broadcasting is disabled. Set SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED=true to enable.");
+    }
+    if (chainId !== 1672) {
+        throw new Error("Live broadcast is only supported on Pharos Pacific Mainnet (chainId 1672).");
+    }
+    const network = getActiveNetwork();
+    if (network.chainId !== 1672) {
+        throw new Error("Active network is not Pharos Pacific Mainnet (1672). Broadcast aborted.");
+    }
+    const rpcUrl = resolveRpcUrl(network);
+    try {
+        const res = await fetchWithTimeoutAndRetry(rpcUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: Date.now(),
+                method: "eth_sendRawTransaction",
+                params: [rawSignedTx],
+            }),
+            timeoutMs: 10_000,
+            retries: 1,
+            retryDelayMs: 250,
+        });
+        const json = (await res.json());
+        if (json.error) {
+            throw new Error(`eth_sendRawTransaction error: ${json.error.message || "unknown"}`);
+        }
+        if (!json.result) {
+            throw new Error("eth_sendRawTransaction returned no result");
+        }
+        return json.result;
+    }
+    catch (error) {
+        throw new Error(`Broadcast failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+//# sourceMappingURL=userSignedBroadcaster.js.map

package/dist/lib/pharos/userSignedBroadcaster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userSignedBroadcaster.js","sourceRoot":"","sources":["../../../src/lib/pharos/userSignedBroadcaster.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,WAAmB,EAAE,OAAe;IACnF,IAAI,OAAO,CAAC,GAAG,CAAC,uCAAuC,KAAK,MAAM,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IAED,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;IAChG,CAAC;IAED,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,wBAAwB,CAAC,MAAM,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;gBACd,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE,CAAC,WAAW,CAAC;aACtB,CAAC;YACF,SAAS,EAAE,MAAM;YACjB,OAAO,EAAE,CAAC;YACV,YAAY,EAAE,GAAG;SAClB,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAsD,CAAC;QAErF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;QACtF,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnH,CAAC;AACH,CAAC"}

package/dist/lib/pharosClient.d.ts

@@ -1,5 +1,5 @@
 import { type PublicClient, type WalletClient, type Transport, type Chain, type Account } from "viem";
-export declare const pharosAtlantic: {
+export declare const pharosNetwork: {
     blockExplorers: {
         readonly default: {
             readonly name: "PharosScan";
@@ -18,10 +18,10 @@ export declare const pharosAtlantic: {
     } | undefined;
     ensTlds?: readonly string[] | undefined;
     id: number;
-    name: `Pharos ${string}`;
+    name: string;
     nativeCurrency: {
-        readonly name: "PHRS";
-        readonly symbol: "PHRS";
+        readonly name: string;
+        readonly symbol: string;
         readonly decimals: 18;
     };
     experimental_preconfirmationTime?: number | undefined | undefined;
@@ -31,7 +31,7 @@ export declare const pharosAtlantic: {
         };
     };
     sourceId?: number | undefined | undefined;
-    testnet: true;
+    testnet: boolean;
     custom?: Record<string, unknown> | undefined;
     extendSchema?: Record<string, unknown> | undefined;
     fees?: import("viem").ChainFees<undefined> | undefined;
@@ -49,11 +49,6 @@ export declare const pharosAtlantic: {
     verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
 };
 export declare const publicClient: PublicClient<Transport, Chain>;
-/**
- * Creates a wallet client for signing and sending transactions.
- * Private key is passed per-request and NEVER stored.
- */
-export declare function createPharosWalletClient(privateKey: `0x${string}`): WalletClient<Transport, Chain, Account>;
 export declare function createPharosWalletClientFromAccount(account: Account): WalletClient<Transport, Chain, Account>;
 export declare function getExplorerUrl(txHash: string): string;
 //# sourceMappingURL=pharosClient.d.ts.map

package/dist/lib/pharosClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pharosClient.d.ts","sourceRoot":"","sources":["../../src/lib/pharosClient.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,OAAO,EACb,MAAM,MAAM,CAAC;AAkBd,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBzB,CAAC;AAIH,eAAO,MAAM,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAGtD,CAAC;AAIH;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,KAAK,MAAM,EAAE,GACxB,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAGzC;AAED,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,OAAO,GACf,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAMzC;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"pharosClient.d.ts","sourceRoot":"","sources":["../../src/lib/pharosClient.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,OAAO,EACb,MAAM,MAAM,CAAC;AAoBd,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBxB,CAAC;AAIH,eAAO,MAAM,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,CAGtD,CAAC;AAIH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,OAAO,GACf,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,CAMzC;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/lib/pharosClient.js

@@ -2,8 +2,9 @@
 // viem publicClient & walletClient factory for Pharos Atlantic Testnet.
 // ────────────────────────────────────────────────────────────────────────
 import { createPublicClient, createWalletClient, http, fallback, defineChain, } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { RPC_URL, CHAIN_ID, EXPLORER_BASE, PHAROS_ENVIRONMENT, IS_MAINNET } from "./constants.js";
+import { RPC_URL, CHAIN_ID, EXPLORER_BASE, IS_MAINNET } from "./constants.js";
+import { getActiveNetwork } from "./networks.js";
+const ACTIVE_NETWORK = getActiveNetwork();
 // Support multiple comma-separated RPC URLs for failover.
 // PHAROS_RPC_URLS takes priority; falls back to single PHAROS_RPC_URL.
 const RPC_URLS = (process.env.PHAROS_RPC_URLS || RPC_URL)
@@ -15,12 +16,12 @@ function buildTransport() {
     return transports.length > 1 ? fallback(transports) : transports[0];
 }
 // ─── Chain Definition ──────────────────────────────────────────────────
-export const pharosAtlantic = defineChain({
+export const pharosNetwork = defineChain({
     id: CHAIN_ID,
-    name: `Pharos ${PHAROS_ENVIRONMENT}`,
+    name: ACTIVE_NETWORK.label,
     nativeCurrency: {
-        name: "PHRS",
-        symbol: "PHRS",
+        name: ACTIVE_NETWORK.nativeToken,
+        symbol: ACTIVE_NETWORK.nativeToken,
         decimals: 18,
     },
     rpcUrls: {
@@ -38,22 +39,14 @@ export const pharosAtlantic = defineChain({
 });
 // ─── Public Client (read-only) ─────────────────────────────────────────
 export const publicClient = createPublicClient({
-    chain: pharosAtlantic,
+    chain: pharosNetwork,
     transport: buildTransport(),
 });
 // ─── Wallet Client Factory ─────────────────────────────────────────────
-/**
- * Creates a wallet client for signing and sending transactions.
- * Private key is passed per-request and NEVER stored.
- */
-export function createPharosWalletClient(privateKey) {
-    const account = privateKeyToAccount(privateKey);
-    return createPharosWalletClientFromAccount(account);
-}
 export function createPharosWalletClientFromAccount(account) {
     return createWalletClient({
         account,
-        chain: pharosAtlantic,
+        chain: pharosNetwork,
         transport: buildTransport(),
     });
 }

package/dist/lib/pharosClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"pharosClient.js","sourceRoot":"","sources":["../../src/lib/pharosClient.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,wEAAwE;AACxE,2EAA2E;AAE3E,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,IAAI,EACJ,QAAQ,EACR,WAAW,GAMZ,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAElG,0DAA0D;AAC1D,uEAAuE;AACvE,MAAM,QAAQ,GAAa,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,CAAC;KAChE,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnB,SAAS,cAAc;IACrB,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACzG,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,0EAA0E;AAE1E,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;IACxC,EAAE,EAAE,QAAQ;IACZ,IAAI,EAAE,UAAU,kBAAkB,EAAE;IACpC,cAAc,EAAE;QACd,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,EAAE;KACb;IACD,OAAO,EAAE;QACP,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,OAAO,CAAC;SAChB;KACF;IACD,cAAc,EAAE;QACd,OAAO,EAAE;YACP,IAAI,EAAE,YAAY;YAClB,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACvC;KACF;IACD,OAAO,EAAE,CAAC,UAAU;CACrB,CAAC,CAAC;AAEH,0EAA0E;AAE1E,MAAM,CAAC,MAAM,YAAY,GAAmC,kBAAkB,CAAC;IAC7E,KAAK,EAAE,cAAc;IACrB,SAAS,EAAE,cAAc,EAAE;CAC5B,CAAC,CAAC;AAEH,0EAA0E;AAE1E;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAyB;IAEzB,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAChD,OAAO,mCAAmC,CAAC,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,mCAAmC,CACjD,OAAgB;IAEhB,OAAO,kBAAkB,CAAC;QACxB,OAAO;QACP,KAAK,EAAE,cAAc;QACrB,SAAS,EAAE,cAAc,EAAE;KAC5B,CAAC,CAAC;AACL,CAAC;AAED,0EAA0E;AAE1E,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,GAAG,aAAa,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC"}
+{"version":3,"file":"pharosClient.js","sourceRoot":"","sources":["../../src/lib/pharosClient.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,wEAAwE;AACxE,2EAA2E;AAE3E,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,IAAI,EACJ,QAAQ,EACR,WAAW,GAMZ,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,cAAc,GAAG,gBAAgB,EAAE,CAAC;AAE1C,0DAA0D;AAC1D,uEAAuE;AACvE,MAAM,QAAQ,GAAa,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,CAAC;KAChE,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AAEnB,SAAS,cAAc;IACrB,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACzG,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,0EAA0E;AAE1E,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;IACvC,EAAE,EAAE,QAAQ;IACZ,IAAI,EAAE,cAAc,CAAC,KAAK;IAC1B,cAAc,EAAE;QACd,IAAI,EAAE,cAAc,CAAC,WAAW;QAChC,MAAM,EAAE,cAAc,CAAC,WAAW;QAClC,QAAQ,EAAE,EAAE;KACb;IACD,OAAO,EAAE;QACP,OAAO,EAAE;YACP,IAAI,EAAE,CAAC,OAAO,CAAC;SAChB;KACF;IACD,cAAc,EAAE;QACd,OAAO,EAAE;YACP,IAAI,EAAE,YAAY;YAClB,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACvC;KACF;IACD,OAAO,EAAE,CAAC,UAAU;CACrB,CAAC,CAAC;AAEH,0EAA0E;AAE1E,MAAM,CAAC,MAAM,YAAY,GAAmC,kBAAkB,CAAC;IAC7E,KAAK,EAAE,aAAa;IACpB,SAAS,EAAE,cAAc,EAAE;CAC5B,CAAC,CAAC;AAEH,0EAA0E;AAE1E,MAAM,UAAU,mCAAmC,CACjD,OAAgB;IAEhB,OAAO,kBAAkB,CAAC;QACxB,OAAO;QACP,KAAK,EAAE,aAAa;QACpB,SAAS,EAAE,cAAc,EAAE;KAC5B,CAAC,CAAC;AACL,CAAC;AAED,0EAA0E;AAE1E,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,GAAG,aAAa,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC"}

package/dist/lib/policy/actionPolicyEngine.d.ts

@@ -1,3 +1,5 @@
+import { type AgentPolicy } from "./agentPolicy.js";
+import type { RiskAssessment } from "../riskEngine.js";
 export type SafeHandsActionType = "send_payment" | "approve_token" | "execute_swap" | "x402_pay_and_fetch" | "publish_risk_score" | "custom_contract_call";
 export type PolicyDecision = "ALLOW" | "WARN" | "BLOCK" | "REQUIRE_CONFIRMATION" | "REQUIRE_FUNDING" | "REQUIRE_TOKEN_REVIEW";
 export type PolicyRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" | "UNKNOWN";
@@ -6,19 +8,39 @@ export interface PolicyCheck {
     status: "pass" | "warn" | "fail" | "unknown";
     message: string;
 }
+/**
+ * Advisory risk-engine output passed to the policy engine as EVIDENCE. The
+ * policy engine, not the risk engine, decides (see docs/DECISION_CONTRACT.md).
+ * Check names derived from this evidence are `risk_*` — deliberately containing
+ * neither "token" nor "funding" so the decision remap below never applies.
+ */
+export interface PolicyRiskEvidence {
+    /** 0-100 weighted risk score. */
+    score: number;
+    /** Critical risk signal could not be evaluated: never sign silently. */
+    degraded: boolean;
+    degradedReasons?: string[];
+    /** Counterparty breakdown dimension (0-100). */
+    counterpartyRisk?: number;
+    /** Structural SWAP_LIQUIDITY_NOT_CONFIGURED state (permanent, not transient). */
+    swapProviderNotConfigured?: boolean;
+}
+/** Projects a RiskAssessment into the policy-evidence shape. Single mapper — write tools must use this rather than hand-rolling the projection. */
+export declare function riskEvidenceFromAssessment(a: RiskAssessment): PolicyRiskEvidence;
 export interface ActionPolicyInput {
     actionType: SafeHandsActionType;
     environment?: string;
     chainId?: number;
     isMainnet?: boolean;
     amount?: string;
-    amountUnit?: "PHRS" | "USDC" | "USD" | "TOKEN";
+    amountUnit?: "PROS" | "USDC" | "USD" | "TOKEN";
     token?: string;
     tokenAddress?: string;
     tokenIn?: string;
     tokenOut?: string;
     recipient?: string;
     spender?: string;
+    targetContract?: string;
     approvalAmount?: string;
     approvalToken?: string;
     approvalUnlimited?: boolean;
@@ -30,11 +52,25 @@ export interface ActionPolicyInput {
     signerAvailable?: boolean;
     tokenSecurityStatus?: "ok" | "unavailable" | "unknown";
     tokenRegistryStatus?: string;
+    /**
+     * Caller CLAIM that the recipient was verified — never independently confirmed
+     * by this engine. Omitted = treated as unverified (fail-closed), never as safe.
+     */
     recipientVerified?: boolean;
+    /** Caller CLAIM (same semantics as recipientVerified). */
     spenderVerified?: boolean;
     allowUnlimitedApproval?: boolean;
     writeToolsEnabled?: boolean;
     requiresSigner?: boolean;
+    agentId?: string;
+    agentPolicy?: AgentPolicy;
+    /**
+     * Advisory risk-engine output passed as EVIDENCE (riskEvidenceFromAssessment).
+     * Write tools MUST provide this and gate with `requireRiskEvidence: true` —
+     * never gate on riskEngine output directly. Omitted by structural/preflight
+     * callers, which then get no risk_* checks.
+     */
+    risk?: PolicyRiskEvidence;
 }
 export interface ActionPolicyResult {
     decision: PolicyDecision;

package/dist/lib/policy/actionPolicyEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actionPolicyEngine.d.ts","sourceRoot":"","sources":["../../../src/lib/policy/actionPolicyEngine.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,MAAM,GACN,OAAO,GACP,sBAAsB,GACtB,iBAAiB,GACjB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,mBAAmB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mBAAmB,CAAC,EAAE,IAAI,GAAG,aAAa,GAAG,SAAS,CAAC;IACvD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,eAAe,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAuBD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAS5E;AAsCD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CA4HjF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAQtE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,GAAG,IAAI,CAMnF"}
+{"version":3,"file":"actionPolicyEngine.d.ts","sourceRoot":"","sources":["../../../src/lib/policy/actionPolicyEngine.ts"],"names":[],"mappings":"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"}