@gol/sdk 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for GOL Network bounded mandates with hosted, owner-reimbursed gas on Base Sepolia testnet (chain `84532`).
 
-A developer's agent sends bounded USDC transfers from an end user's existing smart account. GOL's relayer pays the network gas first. After the action is finalized, GOL claims the actual gas back in native ETH from the same account, within caps the owner signed. The owner signs every authority in their own wallet and can revoke at any time without GOL.
+A developer's agent sends bounded USDC transfers from an end user's existing smart account. GOL's relayer pays the network gas first. After the action reaches the hosted profile's selected Base head, GOL claims the actual gas back in native ETH from the same account, within caps the owner signed. The owner signs every authority in their own wallet and can pause, resume, or revoke without GOL.
 
 Supported accounts are four exact configurations: Safe 1.4.1, Biconomy Nexus 1.0.0, ZeroDev Kernel v0.3.1, and Alchemy Modular Account v2. The transfer asset is Circle USDC on Base Sepolia. Read deployed addresses and limits from `getGasConfiguration`; do not hard-code them.
 
@@ -21,10 +21,11 @@ Create a test project and an API key with `project:read`, `accounts:read`, `mand
 1. **Install the core on the owner's account.** `getAccountStatus` reports the detected family and whether the core is installed. If not, build the owner operation in the browser with `prepareOwnerInstallation` and `prepareOwnerOperation`, have the owner sign it with `signOwnerOperation`, and submit the returned transaction (a Safe transaction, or an EntryPoint v0.7 user operation for Nexus, Kernel, and Alchemy).
 2. **Prepare the approval on your server.** `prepareGasPolicy` compiles the exact mandate policy (allowed recipients, per-action and total USDC caps) and gas policy (per-action and total ETH reimbursement caps, expiry, chargeable outcomes).
 3. **Have the owner sign in the browser.** `signPreparedGasPolicy(ownerWallet, prepared, expectations)` independently recomputes every ID, digest, and wallet payload, asks the wallet for one `eth_signTypedData_v4` signature, and returns a `createMandateWithGas` call. Any address may send it; authority comes only from the owner's signature.
-4. **Confirm.** `confirmGasPolicy` (or `waitForGasPolicyConfirmation`) returns the policy once the approval is finalized on Base, which usually takes 15 to 30 minutes.
+4. **Confirm.** `confirmGasPolicy` (or `waitForGasPolicyConfirmation`) returns the policy once both receipt providers observe the approval at the hosted profile's selected Base head. Profile 3 uses the lower `safe` head, usually tens of seconds behind the latest head on Base Sepolia. This is earlier than Ethereum finality, and timing varies with network conditions.
 5. **Submit actions from your agent.** `prepareGasExecution` returns EIP-712 typed data; your agent signs it and you call `submitGasExecution` with the same 32-byte action ID as the idempotency key. A retry with the same ID and signature returns the original execution and moves no additional value.
 6. **Observe.** Poll `getGasExecution` or `waitForGasExecution`, or receive signed webhooks. Network cost, owner reimbursement, and GOL cost are reported separately.
-7. **Revoke.** `prepareGasPolicyRevocation` returns both owner paths: a relayed owner signature (`signPreparedRevocation`) and a direct account call. Either works without GOL or the agent.
+7. **Pause or resume.** On your server, call `prepareGasPolicySafetyAction(projectId, gasPolicyId, { action: "pause" })` or use `"resume"`. In the owner's browser, `signPreparedSafetyAction(walletClient, prepared)` verifies the digest and wallet payload before signing and returns a core call that any address may relay. Alternatively, submit `prepared.directOwnerCall` through the owner's account. Confirm the transaction with `waitForGasPolicySafetyAction`. A paused policy refuses new submissions. An accepted action waiting to be sent remains held while paused, proceeds if the owner resumes before its quote expires, or closes without owner liability at quote expiry.
+8. **Revoke.** `prepareGasPolicyRevocation` returns both owner paths: a relayed owner signature (`signPreparedRevocation`) and a direct account call. Either works without GOL or the agent.
 
 ```ts
 // Server
@@ -81,7 +82,7 @@ const event = verifyWebhook(
 
 Each family's owner path is fixed: Safe `SafeMessage` under the account's domain, Nexus ERC-7739 `PersonalSign` with the K1 validator prefix, Kernel `Kernel(bytes32 hash)` with the root locator, and Alchemy `ReplaySafeHash` with the entity-zero prefix. `buildWalletSigningPayload` and `verifyWalletSigningPayload` expose them. The SDK never signs a raw hash with `personal_sign` for an approval, and never receives an owner key. Owner user operations for Nexus, Kernel, and Alchemy are signed with `personal_sign` over the EntryPoint v0.7 user operation hash. An Alchemy account can hold one GOL validation at entity 1; remove an earlier GOL core with `preparePermanentRemoval` before installing this one.
 
-The encoders are checked against the independent Python reference vectors in `contracts/tools/encoding/gol_encoding.py`, and `pnpm verify:owner-fork` drives installation, approval, and both revocation paths for the four families on an anvil fork of Base Sepolia.
+The encoders are checked against the independent Python reference vectors in `contracts/tools/encoding/gol_encoding.py`, and `pnpm verify:owner-fork` drives installation, approval, relayed and direct pause and resume, and both revocation paths for the four families on an anvil fork of Base Sepolia.
 
 ## API key authentication
 
@@ -136,7 +137,7 @@ pnpm verify:account-dialects
 pnpm format:check
 ```
 
-`pnpm upstream:check` and `pnpm verify:gas-encoding` need sibling `platform` and `contracts` checkouts. `pnpm verify:account-dialects` reads Base Sepolia over RPC, using `BASE_SEPOLIA_RPC_URL` or the public endpoint. CI runs `generate:check`, `typecheck`, `lint`, `test`, `format:check`, and `verify:pack` on Node.js 22; it does not run the sibling or RPC checks.
+`pnpm upstream:check` and `pnpm verify:gas-encoding` need sibling `platform` and `contracts` checkouts. `pnpm verify:account-dialects` reads Base Sepolia over RPC, using `BASE_SEPOLIA_RPC_URL`, else an Alchemy endpoint built from `ALCHEMY_API_KEY`, else the public endpoint. CI runs `generate:check`, `typecheck`, `lint`, `test`, `format:check`, and `verify:pack` on Node.js 22; it does not run the sibling or RPC checks.
 
 `openapi/platform.json` is a versioned snapshot of the platform contract. `pnpm sync:openapi` refreshes the snapshot from `../platform/openapi/openapi.json` by default and regenerates TypeScript declarations. Set `GOL_PLATFORM_OPENAPI_PATH` when the platform repository is elsewhere.
 

package/dist/generated/platform.d.ts

@@ -358,6 +358,38 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/projects/{projectId}/gas-policies/{gasPolicyId}/safety-actions/prepare": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["prepareGasPolicySafetyAction"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/projects/{projectId}/gas-policies/{gasPolicyId}/safety-actions/confirm": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["confirmGasPolicySafetyAction"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/projects/{projectId}/gas-executions/{executionId}/disputes": {
         parameters: {
             query?: never;
@@ -648,7 +680,7 @@ export interface components {
             account: string;
             family: ("safe" | "nexus" | "kernel" | "alchemy") | null;
             agent: string;
-            status: "active" | "revoked" | "expired" | "unavailable";
+            status: "active" | "paused" | "revoked" | "expired" | "unavailable";
             maxPerActionWei: string;
             maxTotalWei: string;
             spentWei: string;
@@ -769,6 +801,8 @@ export interface operations {
                         status: "ready";
                         version: string;
                         sourceCommit: string;
+                        /** @description Whether operational alerting reported within the last five minutes. It does not change readiness. */
+                        alerting?: "ok" | "stale";
                     };
                 };
             };
@@ -4908,6 +4942,361 @@ export interface operations {
             };
         };
     };
+    prepareGasPolicySafetyAction: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: string;
+                gasPolicyId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    action: "pause" | "resume";
+                    deadline?: number;
+                };
+            };
+        };
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        gasPolicyId: string;
+                        mandateId: string;
+                        account: string;
+                        family: "safe" | "nexus" | "kernel" | "alchemy";
+                        /** @enum {number} */
+                        chainId: 84532;
+                        core: string;
+                        action: "pause" | "resume";
+                        actionCode: 1 | 2;
+                        nonce: string;
+                        deadline: number;
+                        digest: string;
+                        directOwnerCall: {
+                            to: string;
+                            data: string;
+                        };
+                        relayed: {
+                            signing: components["schemas"]["def-5"];
+                            /** @enum {string} */
+                            functionName: "safetyAction";
+                        };
+                        observedBlockNumber: string;
+                    };
+                };
+            };
+            /** @description Default Response */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    confirmGasPolicySafetyAction: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                projectId: string;
+                gasPolicyId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    action: "pause" | "resume";
+                    transactionHash: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["def-6"];
+                };
+            };
+            /** @description Default Response */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @enum {string} */
+                        status: "observing";
+                        transactionHash: string;
+                        /** Format: uuid */
+                        draftId?: string;
+                        gasPolicyId?: string;
+                    };
+                };
+            };
+            /** @description Default Response */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+            /** @description Default Response */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error: {
+                            code: string;
+                            message: string;
+                            /** Format: uuid */
+                            correlationId: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
     openGasExecutionDispute: {
         parameters: {
             query?: never;
@@ -5238,7 +5627,7 @@ export interface operations {
                 "application/json": {
                     url: string;
                     description?: string;
-                    eventTypes?: ("gas_execution.updated" | "gas_policy.confirmed" | "gas_policy.revoked" | "webhook.test")[];
+                    eventTypes?: ("gas_execution.updated" | "gas_policy.confirmed" | "gas_policy.revoked" | "gas_policy.paused" | "gas_policy.resumed" | "webhook.test")[];
                 };
             };
         };