@prismnetwork/agent-sdk 0.7.11 → 0.8.0

package/README.md

@@ -191,10 +191,27 @@ with `host_key_unpublished`.
 
 `lease()` (and the lower-level `fund()`) reproduce the escrow's quote binding: `clientReference = keccak256(quote_id)`, `approve(escrow, maximum_escrow)`, then `createLease(...)`, waiting 12 confirmations.
 
+Pass `decision` and `policy` to `lease()` to authorise the spend first. The decision is checked against the policy before a quote is taken, and its hash is bound into the deposit: `clientReference = keccak256(keccak256(quote_id) ‖ decision_hash)`. Anyone holding the decision can recompute the reference and see it existed before the money moved. It does not show the decision was right. The helpers live in `@prismnetwork/agent-sdk/decision`.
+
 ## Funding
 
 The wallet needs two balances on Robinhood Chain (id 4663): USDG (`0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`, 6 decimals) for the lease deposit, and native ETH for gas. Bridge from L1 to fund a fresh wallet. `authenticate()`, `offers()`, and `quote()` need neither, so the read paths work before you fund anything.
 
+## Prism Chain
+
+Prism Chain (id 77476) is the Layer 3 for GPU compute, settled on Robinhood Chain. `@prismnetwork/agent-sdk/chain` exports the chain for viem and the bridge helpers:
+
+```js
+import { depositToken, prismChain, withdraw } from "@prismnetwork/agent-sdk/chain";
+
+// Robinhood Chain → Prism Chain, arrives in about a minute.
+await depositToken(robinhoodWallet, USDG, 5_000_000n);
+// Prism Chain → Robinhood Chain, claimable there after about a day.
+await withdraw(prismWallet, 1_000_000n, { token: USDG });
+```
+
+`depositEth` moves ETH the same way. Claim a finished withdrawal at [bridge.prismnetwork.tech](https://bridge.prismnetwork.tech). Leases still fund and settle on Robinhood Chain.
+
 ## Requirements
 
 Node >= 20, `viem` ^2 (peer), and `ssh`, `ssh-keygen` and `ssh-keyscan` on PATH

package/chain.d.mts

@@ -0,0 +1,32 @@
+import type { Address, Chain, Hash, WalletClient } from "viem";
+
+export declare const prismChain: Chain;
+export declare const PRISM_CHAIN_BRIDGE_URL: string;
+export declare const prismChainContracts: {
+  rollup: Address;
+  inbox: Address;
+  outbox: Address;
+  parentRouter: Address;
+  parentStandardGateway: Address;
+  childRouter: Address;
+  arbSys: Address;
+};
+
+export interface TokenDepositFees {
+  maxGas: bigint;
+  gasPriceBid: bigint;
+  maxSubmissionCost: bigint;
+  /** Wei of ETH sent with the deposit; the unused part is refunded on Prism Chain. */
+  value: bigint;
+}
+
+interface RpcOptions {
+  parentRpcUrl?: string;
+  childRpcUrl?: string;
+}
+
+export declare function prismChainToken(token: Address, options?: { rpcUrl?: string }): Promise<Address>;
+export declare function tokenDepositFees(token: Address, options?: RpcOptions): Promise<TokenDepositFees>;
+export declare function depositEth(wallet: WalletClient, amount: bigint): Promise<Hash>;
+export declare function depositToken(wallet: WalletClient, token: Address, amount: bigint, options?: RpcOptions): Promise<Hash>;
+export declare function withdraw(wallet: WalletClient, amount: bigint, options?: { token?: Address | null }): Promise<Hash>;

package/chain.mjs

@@ -0,0 +1,163 @@
+/// Prism Chain: the Layer 3 for GPU compute, settled on Robinhood Chain.
+///
+/// Assets reach it through the canonical Arbitrum token bridge. A deposit lands
+/// on Prism Chain in about a minute. A withdrawal starts on Prism Chain,
+/// finalizes on Robinhood Chain after the rollup's confirmation window (about a
+/// day), and is then claimed there; https://bridge.prismnetwork.tech does the
+/// claim. Leases still settle on Robinhood Chain today.
+import { createPublicClient, defineChain, encodeAbiParameters, erc20Abi, http, parseAbi } from "viem";
+
+// Kept here rather than imported from prism.mjs, which pulls in Node modules;
+// this file stays usable in a browser.
+const robinhoodChain = defineChain({
+  id: 4663,
+  name: "Robinhood Chain",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+  rpcUrls: { default: { http: ["https://rpc.mainnet.chain.robinhood.com"] } },
+});
+
+export const prismChain = defineChain({
+  id: 77476,
+  name: "Prism Chain",
+  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+  rpcUrls: {
+    default: { http: ["https://rpc.prismnetwork.tech"], webSocket: ["wss://ws.prismnetwork.tech"] },
+  },
+  blockExplorers: { default: { name: "Prism Chain explorer", url: "https://explorer.prismnetwork.tech" } },
+  sourceId: robinhoodChain.id,
+});
+
+export const PRISM_CHAIN_BRIDGE_URL = "https://bridge.prismnetwork.tech";
+
+/// The rollup on Robinhood Chain and both halves of the token bridge.
+export const prismChainContracts = {
+  rollup: "0x8232Ce617E7F1031F5B7bdcD72678dbdF2fDafeB",
+  inbox: "0x2FbD2fF90f56C58A8789Fc56e8b31F26e660438f",
+  outbox: "0x8cC14bF09cE7a1bf2415C70E5E4B9f50cD4a889d",
+  parentRouter: "0x52f5aF48C1DF13E0e1ABbe04F99622aabF6B2CD2",
+  parentStandardGateway: "0x1274b56aE5566014bB73dfE0A2247ab5BbC96470",
+  childRouter: "0x12d1c6c0b4b97278A7E2961eF16105Ba2dd2e859",
+  arbSys: "0x0000000000000000000000000000000000000064",
+};
+
+const inboxAbi = parseAbi([
+  "function depositEth() payable returns (uint256)",
+  "function calculateRetryableSubmissionFee(uint256 dataLength, uint256 baseFee) view returns (uint256)",
+]);
+const parentRouterAbi = parseAbi([
+  "function getGateway(address token) view returns (address)",
+  "function outboundTransferCustomRefund(address token, address refundTo, address to, uint256 amount, uint256 maxGas, uint256 gasPriceBid, bytes data) payable returns (bytes)",
+]);
+const childRouterAbi = parseAbi([
+  "function calculateL2TokenAddress(address l1Token) view returns (address)",
+  "function outboundTransfer(address l1Token, address to, uint256 amount, bytes data) payable returns (bytes)",
+]);
+const arbSysAbi = parseAbi(["function withdrawEth(address destination) payable returns (uint256)"]);
+
+const parent = (rpcUrl) => createPublicClient({ chain: robinhoodChain, transport: http(rpcUrl) });
+const child = (rpcUrl) => createPublicClient({ chain: prismChain, transport: http(rpcUrl) });
+
+/// Where a Robinhood Chain token lives on Prism Chain. Its contract exists once
+/// the first deposit of that token has landed.
+export function prismChainToken(token, { rpcUrl } = {}) {
+  return child(rpcUrl).readContract({
+    address: prismChainContracts.childRouter,
+    abi: childRouterAbi,
+    functionName: "calculateL2TokenAddress",
+    args: [token],
+  });
+}
+
+/// What a token deposit prepays for its call on Prism Chain, in wei of ETH on
+/// Robinhood Chain. The first deposit of a token also deploys its contract
+/// there, which needs more gas. Whatever goes unused is refunded to the sender
+/// on Prism Chain, so this is a ceiling, not a price.
+export async function tokenDepositFees(token, { parentRpcUrl, childRpcUrl } = {}) {
+  const [block, childGasPrice, deployed] = await Promise.all([
+    parent(parentRpcUrl).getBlock(),
+    child(childRpcUrl).getGasPrice(),
+    prismChainToken(token, { rpcUrl: childRpcUrl }).then((address) => child(childRpcUrl).getCode({ address })),
+  ]);
+  const maxGas = deployed && deployed !== "0x" ? 300_000n : 1_200_000n;
+  const gasPriceBid = childGasPrice * 2n;
+  const submission = await parent(parentRpcUrl).readContract({
+    address: prismChainContracts.inbox,
+    abi: inboxAbi,
+    functionName: "calculateRetryableSubmissionFee",
+    args: [2_000n, block.baseFeePerGas ?? 0n],
+  });
+  const maxSubmissionCost = submission * 4n;
+  return { maxGas, gasPriceBid, maxSubmissionCost, value: maxSubmissionCost + maxGas * gasPriceBid };
+}
+
+/// Move ETH from Robinhood Chain to the same address on Prism Chain. `wallet`
+/// is a viem wallet client on Robinhood Chain. Returns the Robinhood Chain
+/// transaction hash.
+export function depositEth(wallet, amount) {
+  return wallet.writeContract({
+    chain: robinhoodChain,
+    address: prismChainContracts.inbox,
+    abi: inboxAbi,
+    functionName: "depositEth",
+    value: amount,
+  });
+}
+
+/// Move an ERC-20 such as USDG from Robinhood Chain to the same address on
+/// Prism Chain. Approves the token's gateway first when the allowance is short.
+export async function depositToken(wallet, token, amount, { parentRpcUrl, childRpcUrl } = {}) {
+  const account = wallet.account.address;
+  const reader = parent(parentRpcUrl);
+  const gateway = await reader.readContract({
+    address: prismChainContracts.parentRouter,
+    abi: parentRouterAbi,
+    functionName: "getGateway",
+    args: [token],
+  });
+  const allowance = await reader.readContract({ address: token, abi: erc20Abi, functionName: "allowance", args: [account, gateway] });
+  if (allowance < amount) {
+    const approval = await wallet.writeContract({
+      chain: robinhoodChain,
+      address: token,
+      abi: erc20Abi,
+      functionName: "approve",
+      args: [gateway, amount],
+    });
+    await reader.waitForTransactionReceipt({ hash: approval });
+  }
+  const fees = await tokenDepositFees(token, { parentRpcUrl, childRpcUrl });
+  const data = encodeAbiParameters([{ type: "uint256" }, { type: "bytes" }], [fees.maxSubmissionCost, "0x"]);
+  return wallet.writeContract({
+    chain: robinhoodChain,
+    address: prismChainContracts.parentRouter,
+    abi: parentRouterAbi,
+    functionName: "outboundTransferCustomRefund",
+    args: [token, account, account, amount, fees.maxGas, fees.gasPriceBid, data],
+    value: fees.value,
+  });
+}
+
+/// Start moving ETH, or a bridged token given by its Robinhood Chain address,
+/// back to Robinhood Chain. `wallet` is a viem wallet client on Prism Chain.
+/// The withdrawal is claimable on Robinhood Chain after about a day, at
+/// PRISM_CHAIN_BRIDGE_URL. Returns the Prism Chain transaction hash.
+export function withdraw(wallet, amount, { token = null } = {}) {
+  const account = wallet.account.address;
+  if (!token) {
+    return wallet.writeContract({
+      chain: prismChain,
+      address: prismChainContracts.arbSys,
+      abi: arbSysAbi,
+      functionName: "withdrawEth",
+      args: [account],
+      value: amount,
+    });
+  }
+  return wallet.writeContract({
+    chain: prismChain,
+    address: prismChainContracts.childRouter,
+    abi: childRouterAbi,
+    functionName: "outboundTransfer",
+    args: [token, account, amount, "0x"],
+  });
+}

package/decision.mjs

@@ -124,6 +124,13 @@ export function leaseReference(quoteId, d) {
   return keccak256(concatBytes([hexToBytes(quoteDigest), hexToBytes(keccak256(canonical(d)))]));
 }
 
+/// The hex digest the control plane needs to know which derivation to expect.
+/// It is the decision's hash, not the decision: the service can check that the
+/// funding log commits to something, and cannot read what that something says.
+export function decisionDigest(d) {
+  return d ? keccak256(canonical(d)) : null;
+}
+
 /// Whether this decision is the one that funded that lease.
 export function referenceMatches(quoteId, d, reference) {
   return leaseReference(quoteId, d).toLowerCase() === String(reference).toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismnetwork/agent-sdk",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "description": "Headless GPU leasing and renter-encrypted storage on Prism Network for wallet-holding agents.",
   "type": "module",
   "main": "prism.mjs",
@@ -9,6 +9,10 @@
       "types": "./prism.d.mts",
       "default": "./prism.mjs"
     },
+    "./chain": {
+      "types": "./chain.d.mts",
+      "default": "./chain.mjs"
+    },
     "./decision": {
       "default": "./decision.mjs"
     },
@@ -40,6 +44,8 @@
   "files": [
     "prism.mjs",
     "prism.d.mts",
+    "chain.mjs",
+    "chain.d.mts",
     "attest.mjs",
     "attest.d.mts",
     "decision.mjs",

package/prism.d.mts

@@ -1,6 +1,7 @@
 import type { AttestationResult, VerifyConfidentialOptions, WorkloadPin } from "./attest.d.mts";
 
 export declare const robinhoodChain: unknown;
+export { PRISM_CHAIN_BRIDGE_URL, prismChain, prismChainContracts } from "./chain.d.mts";
 export declare const USDG: string;
 export declare const DEFAULT_IMAGE: string;
 export declare const TRUST_CLASSES: readonly ["open", "isolated", "attested", "confidential"];

package/prism.mjs

@@ -1,7 +1,7 @@
 // Prism Network agent SDK: headless GPU leasing for wallet-holding agents.
 // No browser, no Privy. Authenticate with a wallet signature, pay on-chain, run.
 import { execFileSync, spawn } from "node:child_process";
-import { authorise, leaseReference } from "./decision.mjs";
+import { authorise, decisionDigest, leaseReference } from "./decision.mjs";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -15,6 +15,7 @@ import {
   stringToBytes,
 } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
+export { PRISM_CHAIN_BRIDGE_URL, prismChain, prismChainContracts } from "./chain.mjs";
 import { appraiseWorkload, DEFAULT_CONFIDENTIAL_BASE, EXPECTED_WORKLOAD, verifyConfidential } from "./attest.mjs";
 import { decryptResponse, encryptChatRequest } from "./e2ee.mjs";
 import { hostKeyArgs, HostKeyError } from "./hostkey.mjs";
@@ -334,12 +335,17 @@ export class PrismAgent {
     }
   }
 
-  async confirm({ quoteId, transactionHash, sshAuthorizedKey }) {
+  /// `decisionHash` travels when the lease was authorised: the client
+  /// reference on chain is derived from it, and the control plane cannot check
+  /// the funding log without knowing which derivation to expect. The digest is
+  /// all it gets; the decision stays here.
+  async confirm({ quoteId, transactionHash, sshAuthorizedKey, decisionHash = null }) {
     return this.#proxy("POST", ["leases", "confirm"], {
       body: {
         quote_id: quoteId,
         transaction_hash: transactionHash,
         ssh_authorized_key: sshAuthorizedKey,
+        ...(decisionHash ? { decision_hash: decisionHash } : {}),
       },
     });
   }
@@ -426,7 +432,12 @@ export class PrismAgent {
     maxDeposit = null,
     minTrustClass = "open",
     command = null,
+    decision = null,
+    policy = null,
   } = {}) {
+    // Checked before a quote is taken, so a refusal costs nothing and does not
+    // hold capacity against other renters while it expires.
+    if (policy) authorise(policy, decision ?? { action: "unstated", source: "none", answers: [] });
     if (!this.session) await this.authenticate();
     // A wallet with no balance at all cannot fund anything, and a doomed quote
     // still holds capacity against other renters until it expires. Refuse
@@ -463,11 +474,12 @@ export class PrismAgent {
         if (maxDeposit != null && parseBaseUnits(quote.maximum_escrow, "maximum_escrow") > BigInt(maxDeposit)) {
           throw new PrismError(402, "cost_exceeds_max", { required: quote.maximum_escrow, max: String(maxDeposit) });
         }
-        funded = await this.#fundNow(quote);
+        funded = await this.#fundNow(quote, decision);
         return this.confirm({
           quoteId: quote.quote_id,
           transactionHash: funded.hash,
           sshAuthorizedKey: key.publicKey,
+          decisionHash: decisionDigest(decision),
         });
       });
       if (!Number.isInteger(record?.lease_id)) {