near-safe 0.4.1 → 0.5.0

package/dist/cjs/lib/multisend.d.ts

@@ -1,3 +1,4 @@
 import { MetaTransaction } from "../types";
 export declare const MULTI_SEND_ABI: string[];
 export declare function encodeMulti(transactions: readonly MetaTransaction[], multiSendContractAddress?: string): MetaTransaction;
+export declare function isMultisendTx(args: readonly unknown[]): boolean;

package/dist/cjs/lib/multisend.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MULTI_SEND_ABI = void 0;
 exports.encodeMulti = encodeMulti;
+exports.isMultisendTx = isMultisendTx;
 const viem_1 = require("viem");
 const types_1 = require("../types");
 exports.MULTI_SEND_ABI = ["function multiSend(bytes memory transactions)"];
@@ -38,3 +39,8 @@ function encodeMulti(transactions, multiSendContractAddress = transactions.some(
         }),
     };
 }
+function isMultisendTx(args) {
+    const to = args[0].toLowerCase();
+    return (to === MULTISEND_141.toLowerCase() ||
+        to === MULTISEND_CALLONLY_141.toLowerCase());
+}

package/dist/cjs/near-safe.d.ts

@@ -3,7 +3,7 @@ import { FinalExecutionOutcome } from "near-api-js/lib/providers";
 import { NearEthAdapter, SignRequestData } from "near-ca";
 import { Address, Hash, Hex } from "viem";
 import { SafeContractSuite } from "./lib/safe";
-import { EncodedTxData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
+import { EncodedTxData, EvmTransactionData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
 export interface NearSafeConfig {
     accountId: string;
     mpcContractId: string;
@@ -19,28 +19,154 @@ export declare class NearSafe {
     private setup;
     private pimlicoKey;
     private safeSaltNonce;
+    /**
+     * Creates a new instance of the `NearSafe` class using the provided configuration.
+     *
+     * @param {NearSafeConfig} config - The configuration object required to initialize the `NearSafe` instance, including the Pimlico key and safe salt nonce.
+     * @returns {Promise<NearSafe>} - A promise that resolves to a new `NearSafe` instance.
+     */
     static create(config: NearSafeConfig): Promise<NearSafe>;
+    /**
+     * Constructs a new `NearSafe` object with the provided parameters.
+     *
+     * @param {NearEthAdapter} nearAdapter - The NEAR adapter used for interacting with the NEAR blockchain.
+     * @param {SafeContractSuite} safePack - A suite of contracts and utilities for managing the Safe contract.
+     * @param {string} pimlicoKey - A key required for authenticating with the Pimlico service.
+     * @param {string} setup - The setup string generated for the Safe contract.
+     * @param {Address} safeAddress - The address of the deployed Safe contract.
+     * @param {string} safeSaltNonce - A unique nonce used to differentiate the Safe setup.
+     */
     constructor(nearAdapter: NearEthAdapter, safePack: SafeContractSuite, pimlicoKey: string, setup: string, safeAddress: Address, safeSaltNonce: string);
+    /**
+     * Retrieves the MPC (Multi-Party Computation) address associated with the NEAR adapter.
+     *
+     * @returns {Address} - The MPC address of the NEAR adapter.
+     */
     get mpcAddress(): Address;
+    /**
+     * Retrieves the contract ID of the MPC contract associated with the NEAR adapter.
+     *
+     * @returns {string} - The contract ID of the MPC contract.
+     */
     get mpcContractId(): string;
+    /**
+     * Retrieves the balance of the Safe account on the specified EVM chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @returns {Promise<bigint>} - A promise that resolves to the balance of the Safe account in wei.
+     */
     getBalance(chainId: number): Promise<bigint>;
+    /**
+     * Constructs a user operation for the specified chain, including necessary gas fees, nonce, and paymaster data.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {Object} args - The arguments for building the transaction.
+     * @param {number} args.chainId - The ID of the blockchain network where the transaction will be executed.
+     * @param {MetaTransaction[]} args.transactions - A list of meta-transactions to be included in the user operation.
+     * @param {boolean} args.usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<UserOperation>} - A promise that resolves to a complete `UserOperation` object, including gas fees, nonce, and paymaster data.
+     * @throws {Error} - Throws an error if the transaction set is empty or if any operation fails during the building process.
+     */
     buildTransaction(args: {
         chainId: number;
         transactions: MetaTransaction[];
         usePaymaster: boolean;
     }): Promise<UserOperation>;
+    /**
+     * Signs a transaction with the NEAR adapter using the provided operation hash.
+     *
+     * @param {Hex} safeOpHash - The hash of the user operation that needs to be signed.
+     * @returns {Promise<Hex>} - A promise that resolves to the packed signature in hexadecimal format.
+     */
     signTransaction(safeOpHash: Hex): Promise<Hex>;
+    /**
+     * Computes the operation hash for a given user operation.
+     *
+     * @param {UserOperation} userOp - The user operation for which the hash needs to be computed.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the provided user operation.
+     */
     opHash(userOp: UserOperation): Promise<Hash>;
+    /**
+     * Encodes a request to sign a transaction using either a paymaster or the user's own funds.
+     *
+     * @param {SignRequestData} signRequest - The data required to create the signature request. This includes information such as the chain ID and other necessary fields for the transaction.
+     * @param {boolean} usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<EncodedTxData>} - A promise that resolves to the encoded transaction data for the NEAR and EVM networks.
+     */
     encodeSignRequest(signRequest: SignRequestData, usePaymaster: boolean): Promise<EncodedTxData>;
+    /**
+     * Broadcasts a user operation to the EVM network with a provided signature.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the EVM network to which the transaction should be broadcasted.
+     * @param {FinalExecutionOutcome} outcome - The result of the NEAR transaction execution, which contains the necessary data to construct an EVM signature.
+     * @param {UserOperation} unsignedUserOp - The unsigned user operation to be broadcasted. This includes transaction data such as the destination address and data payload.
+     * @returns {Promise<{ signature: Hex; opHash: Hash }>} - A promise that resolves to an object containing the signature used and the hash of the executed user operation.
+     * @throws {Error} - Throws an error if the EVM broadcast fails, including the error message for debugging.
+     */
     broadcastEvm(chainId: number, outcome: FinalExecutionOutcome, unsignedUserOp: UserOperation): Promise<{
         signature: Hex;
-        receipt: UserOperationReceipt;
+        opHash: Hash;
     }>;
-    executeTransaction(chainId: number, userOp: UserOperation): Promise<UserOperationReceipt>;
+    /**
+     * Executes a user operation on the specified blockchain network.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network on which to execute the transaction.
+     * @param {UserOperation} userOp - The user operation to be executed, typically includes the data and signatures necessary for the transaction.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the executed transaction.
+     */
+    executeTransaction(chainId: number, userOp: UserOperation): Promise<Hash>;
+    /**
+     * Retrieves the receipt of a previously executed user operation.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network where the operation was executed.
+     * @param {Hash} userOpHash - The hash of the user operation for which to retrieve the receipt.
+     * @returns {Promise<UserOperationReceipt>} - A promise that resolves to the receipt of the user operation, which includes status and logs.
+     */
+    getOpReceipt(chainId: number, userOpHash: Hash): Promise<UserOperationReceipt>;
+    /**
+     * Checks if the Safe contract is deployed on the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe contract should be checked.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe contract is deployed, otherwise `false`.
+     */
     safeDeployed(chainId: number): Promise<boolean>;
+    /**
+     * Determines if the Safe account has sufficient funds to cover the transaction costs.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @param {MetaTransaction[]} transactions - A list of meta-transactions to be evaluated for funding.
+     * @param {bigint} gasCost - The estimated gas cost of executing the transactions.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe account has sufficient funds, otherwise `false`.
+     */
     sufficientlyFunded(chainId: number, transactions: MetaTransaction[], gasCost: bigint): Promise<boolean>;
+    /**
+     * Creates a meta-transaction for adding a new owner to the Safe contract.
+     *
+     * @param {Address} address - The address of the new owner to be added.
+     * @returns {MetaTransaction} - A meta-transaction object for adding the new owner.
+     */
     addOwnerTx(address: Address): MetaTransaction;
+    /**
+     * Creates and returns a new `Erc4337Bundler` instance for the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network for which the bundler is to be created.
+     * @returns {Erc4337Bundler} - A new instance of the `Erc4337Bundler` class configured for the specified chain.
+     */
     private bundlerForChainId;
+    /**
+     * Decodes transaction data for a given EVM transaction and extracts relevant details.
+     *
+     * @param {EvmTransactionData} data - The raw transaction data to be decoded.
+     * @returns {{ chainId: number; costEstimate: string; transactions: MetaTransaction[] }} - An object containing the chain ID, estimated cost, and a list of decoded meta-transactions.
+     */
+    decodeTxData(data: EvmTransactionData): {
+        chainId: number;
+        costEstimate: string;
+        transactions: MetaTransaction[];
+    };
     /**
      * Handles routing of signature requests based on the provided method, chain ID, and parameters.
      *

package/dist/cjs/near-safe.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NearSafe = void 0;
+const ethers_multisend_1 = require("ethers-multisend");
 const near_ca_1 = require("near-ca");
 const viem_1 = require("viem");
 const bundler_1 = require("./lib/bundler");
@@ -9,6 +10,12 @@ const safe_1 = require("./lib/safe");
 const safe_message_1 = require("./lib/safe-message");
 const util_1 = require("./util");
 class NearSafe {
+    /**
+     * Creates a new instance of the `NearSafe` class using the provided configuration.
+     *
+     * @param {NearSafeConfig} config - The configuration object required to initialize the `NearSafe` instance, including the Pimlico key and safe salt nonce.
+     * @returns {Promise<NearSafe>} - A promise that resolves to a new `NearSafe` instance.
+     */
     static async create(config) {
         const { pimlicoKey, safeSaltNonce } = config;
         const nearAdapter = await (0, near_ca_1.setupAdapter)({ ...config });
@@ -23,6 +30,16 @@ class NearSafe {
     `);
         return new NearSafe(nearAdapter, safePack, pimlicoKey, setup, safeAddress, safeSaltNonce || "0");
     }
+    /**
+     * Constructs a new `NearSafe` object with the provided parameters.
+     *
+     * @param {NearEthAdapter} nearAdapter - The NEAR adapter used for interacting with the NEAR blockchain.
+     * @param {SafeContractSuite} safePack - A suite of contracts and utilities for managing the Safe contract.
+     * @param {string} pimlicoKey - A key required for authenticating with the Pimlico service.
+     * @param {string} setup - The setup string generated for the Safe contract.
+     * @param {Address} safeAddress - The address of the deployed Safe contract.
+     * @param {string} safeSaltNonce - A unique nonce used to differentiate the Safe setup.
+     */
     constructor(nearAdapter, safePack, pimlicoKey, setup, safeAddress, safeSaltNonce) {
         this.nearAdapter = nearAdapter;
         this.address = safeAddress;
@@ -31,15 +48,42 @@ class NearSafe {
         this.pimlicoKey = pimlicoKey;
         this.safeSaltNonce = safeSaltNonce;
     }
+    /**
+     * Retrieves the MPC (Multi-Party Computation) address associated with the NEAR adapter.
+     *
+     * @returns {Address} - The MPC address of the NEAR adapter.
+     */
     get mpcAddress() {
         return this.nearAdapter.address;
     }
+    /**
+     * Retrieves the contract ID of the MPC contract associated with the NEAR adapter.
+     *
+     * @returns {string} - The contract ID of the MPC contract.
+     */
     get mpcContractId() {
         return this.nearAdapter.mpcContract.contract.contractId;
     }
+    /**
+     * Retrieves the balance of the Safe account on the specified EVM chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @returns {Promise<bigint>} - A promise that resolves to the balance of the Safe account in wei.
+     */
     async getBalance(chainId) {
         return await (0, util_1.getClient)(chainId).getBalance({ address: this.address });
     }
+    /**
+     * Constructs a user operation for the specified chain, including necessary gas fees, nonce, and paymaster data.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {Object} args - The arguments for building the transaction.
+     * @param {number} args.chainId - The ID of the blockchain network where the transaction will be executed.
+     * @param {MetaTransaction[]} args.transactions - A list of meta-transactions to be included in the user operation.
+     * @param {boolean} args.usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<UserOperation>} - A promise that resolves to a complete `UserOperation` object, including gas fees, nonce, and paymaster data.
+     * @throws {Error} - Throws an error if the transaction set is empty or if any operation fails during the building process.
+     */
     async buildTransaction(args) {
         const { transactions, usePaymaster, chainId } = args;
         if (transactions.length === 0) {
@@ -58,13 +102,32 @@ class NearSafe {
         const unsignedUserOp = { ...rawUserOp, ...paymasterData };
         return unsignedUserOp;
     }
+    /**
+     * Signs a transaction with the NEAR adapter using the provided operation hash.
+     *
+     * @param {Hex} safeOpHash - The hash of the user operation that needs to be signed.
+     * @returns {Promise<Hex>} - A promise that resolves to the packed signature in hexadecimal format.
+     */
     async signTransaction(safeOpHash) {
         const signature = await this.nearAdapter.sign(safeOpHash);
         return (0, util_1.packSignature)(signature);
     }
+    /**
+     * Computes the operation hash for a given user operation.
+     *
+     * @param {UserOperation} userOp - The user operation for which the hash needs to be computed.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the provided user operation.
+     */
     async opHash(userOp) {
         return this.safePack.getOpHash(userOp);
     }
+    /**
+     * Encodes a request to sign a transaction using either a paymaster or the user's own funds.
+     *
+     * @param {SignRequestData} signRequest - The data required to create the signature request. This includes information such as the chain ID and other necessary fields for the transaction.
+     * @param {boolean} usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<EncodedTxData>} - A promise that resolves to the encoded transaction data for the NEAR and EVM networks.
+     */
     async encodeSignRequest(signRequest, usePaymaster) {
         const { payload, evmMessage, hash } = await this.requestRouter(signRequest, usePaymaster);
         return {
@@ -80,12 +143,22 @@ class NearSafe {
             },
         };
     }
+    /**
+     * Broadcasts a user operation to the EVM network with a provided signature.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the EVM network to which the transaction should be broadcasted.
+     * @param {FinalExecutionOutcome} outcome - The result of the NEAR transaction execution, which contains the necessary data to construct an EVM signature.
+     * @param {UserOperation} unsignedUserOp - The unsigned user operation to be broadcasted. This includes transaction data such as the destination address and data payload.
+     * @returns {Promise<{ signature: Hex; opHash: Hash }>} - A promise that resolves to an object containing the signature used and the hash of the executed user operation.
+     * @throws {Error} - Throws an error if the EVM broadcast fails, including the error message for debugging.
+     */
     async broadcastEvm(chainId, outcome, unsignedUserOp) {
         const signature = (0, util_1.packSignature)((0, viem_1.serializeSignature)((0, near_ca_1.signatureFromOutcome)(outcome)));
         try {
             return {
                 signature,
-                receipt: await this.executeTransaction(chainId, {
+                opHash: await this.executeTransaction(chainId, {
                     ...unsignedUserOp,
                     signature,
                 }),
@@ -95,19 +168,45 @@ class NearSafe {
             throw new Error(`Failed EVM broadcast: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Executes a user operation on the specified blockchain network.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network on which to execute the transaction.
+     * @param {UserOperation} userOp - The user operation to be executed, typically includes the data and signatures necessary for the transaction.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the executed transaction.
+     */
     async executeTransaction(chainId, userOp) {
-        const bundler = this.bundlerForChainId(chainId);
-        const userOpHash = await bundler.sendUserOperation(userOp);
-        console.log("UserOp Hash", userOpHash);
-        const userOpReceipt = await bundler.getUserOpReceipt(userOpHash);
-        console.log("userOp Receipt", userOpReceipt);
-        // Update safeNotDeployed after the first transaction
-        this.safeDeployed(chainId);
-        return userOpReceipt;
+        return this.bundlerForChainId(chainId).sendUserOperation(userOp);
+    }
+    /**
+     * Retrieves the receipt of a previously executed user operation.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network where the operation was executed.
+     * @param {Hash} userOpHash - The hash of the user operation for which to retrieve the receipt.
+     * @returns {Promise<UserOperationReceipt>} - A promise that resolves to the receipt of the user operation, which includes status and logs.
+     */
+    async getOpReceipt(chainId, userOpHash) {
+        return this.bundlerForChainId(chainId).getUserOpReceipt(userOpHash);
     }
+    /**
+     * Checks if the Safe contract is deployed on the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe contract should be checked.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe contract is deployed, otherwise `false`.
+     */
     async safeDeployed(chainId) {
         return (0, util_1.isContract)(this.address, chainId);
     }
+    /**
+     * Determines if the Safe account has sufficient funds to cover the transaction costs.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @param {MetaTransaction[]} transactions - A list of meta-transactions to be evaluated for funding.
+     * @param {bigint} gasCost - The estimated gas cost of executing the transactions.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe account has sufficient funds, otherwise `false`.
+     */
     async sufficientlyFunded(chainId, transactions, gasCost) {
         const txValue = transactions.reduce((acc, tx) => acc + BigInt(tx.value), 0n);
         if (txValue + gasCost === 0n) {
@@ -116,6 +215,12 @@ class NearSafe {
         const safeBalance = await this.getBalance(chainId);
         return txValue + gasCost < safeBalance;
     }
+    /**
+     * Creates a meta-transaction for adding a new owner to the Safe contract.
+     *
+     * @param {Address} address - The address of the new owner to be added.
+     * @returns {MetaTransaction} - A meta-transaction object for adding the new owner.
+     */
     addOwnerTx(address) {
         return {
             to: this.address,
@@ -123,9 +228,48 @@ class NearSafe {
             data: this.safePack.addOwnerData(address),
         };
     }
+    /**
+     * Creates and returns a new `Erc4337Bundler` instance for the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network for which the bundler is to be created.
+     * @returns {Erc4337Bundler} - A new instance of the `Erc4337Bundler` class configured for the specified chain.
+     */
     bundlerForChainId(chainId) {
         return new bundler_1.Erc4337Bundler(this.safePack.entryPoint.address, this.pimlicoKey, chainId);
     }
+    /**
+     * Decodes transaction data for a given EVM transaction and extracts relevant details.
+     *
+     * @param {EvmTransactionData} data - The raw transaction data to be decoded.
+     * @returns {{ chainId: number; costEstimate: string; transactions: MetaTransaction[] }} - An object containing the chain ID, estimated cost, and a list of decoded meta-transactions.
+     */
+    decodeTxData(data) {
+        // TODO: data.data may not always parse to UserOperation. We will have to handle the other cases.
+        const userOp = JSON.parse(data.data);
+        const { callGasLimit, maxFeePerGas, maxPriorityFeePerGas } = userOp;
+        const maxGasPrice = BigInt(maxFeePerGas) + BigInt(maxPriorityFeePerGas);
+        const { args } = (0, viem_1.decodeFunctionData)({
+            abi: this.safePack.m4337.abi,
+            data: userOp.callData,
+        });
+        // Determine if singular or double!
+        const transactions = (0, multisend_1.isMultisendTx)(args)
+            ? (0, ethers_multisend_1.decodeMulti)(args[2])
+            : [
+                {
+                    to: args[0],
+                    value: args[1],
+                    data: args[2],
+                    operation: args[3],
+                },
+            ];
+        return {
+            chainId: data.chainId,
+            // This is an upper bound on the gas fees (could be lower)
+            costEstimate: (0, viem_1.formatEther)(BigInt(callGasLimit) * maxGasPrice),
+            transactions,
+        };
+    }
     /**
      * Handles routing of signature requests based on the provided method, chain ID, and parameters.
      *

package/dist/cjs/types.d.ts

@@ -1,5 +1,5 @@
 import { FunctionCallTransaction, SignArgs } from "near-ca";
-import { Address, Hash, Hex, ParseAbi, TransactionSerializable } from "viem";
+import { Address, Hex, ParseAbi } from "viem";
 export type SafeDeployments = {
     singleton: Deployment;
     proxyFactory: Deployment;
@@ -101,12 +101,13 @@ export interface MetaTransaction {
     readonly data: string;
     readonly operation?: OperationType;
 }
+export interface EvmTransactionData {
+    chainId: number;
+    data: string;
+    hash: string;
+}
 export interface EncodedTxData {
-    evmData: {
-        chainId: number;
-        data: string | TransactionSerializable;
-        hash: Hash;
-    };
+    evmData: EvmTransactionData;
     nearPayload: FunctionCallTransaction<{
         request: SignArgs;
     }>;

package/dist/esm/lib/multisend.d.ts

@@ -1,3 +1,4 @@
 import { MetaTransaction } from "../types";
 export declare const MULTI_SEND_ABI: string[];
 export declare function encodeMulti(transactions: readonly MetaTransaction[], multiSendContractAddress?: string): MetaTransaction;
+export declare function isMultisendTx(args: readonly unknown[]): boolean;

package/dist/esm/lib/multisend.js

@@ -34,3 +34,8 @@ export function encodeMulti(transactions, multiSendContractAddress = transaction
         }),
     };
 }
+export function isMultisendTx(args) {
+    const to = args[0].toLowerCase();
+    return (to === MULTISEND_141.toLowerCase() ||
+        to === MULTISEND_CALLONLY_141.toLowerCase());
+}

package/dist/esm/near-safe.d.ts

@@ -3,7 +3,7 @@ import { FinalExecutionOutcome } from "near-api-js/lib/providers";
 import { NearEthAdapter, SignRequestData } from "near-ca";
 import { Address, Hash, Hex } from "viem";
 import { SafeContractSuite } from "./lib/safe";
-import { EncodedTxData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
+import { EncodedTxData, EvmTransactionData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
 export interface NearSafeConfig {
     accountId: string;
     mpcContractId: string;
@@ -19,28 +19,154 @@ export declare class NearSafe {
     private setup;
     private pimlicoKey;
     private safeSaltNonce;
+    /**
+     * Creates a new instance of the `NearSafe` class using the provided configuration.
+     *
+     * @param {NearSafeConfig} config - The configuration object required to initialize the `NearSafe` instance, including the Pimlico key and safe salt nonce.
+     * @returns {Promise<NearSafe>} - A promise that resolves to a new `NearSafe` instance.
+     */
     static create(config: NearSafeConfig): Promise<NearSafe>;
+    /**
+     * Constructs a new `NearSafe` object with the provided parameters.
+     *
+     * @param {NearEthAdapter} nearAdapter - The NEAR adapter used for interacting with the NEAR blockchain.
+     * @param {SafeContractSuite} safePack - A suite of contracts and utilities for managing the Safe contract.
+     * @param {string} pimlicoKey - A key required for authenticating with the Pimlico service.
+     * @param {string} setup - The setup string generated for the Safe contract.
+     * @param {Address} safeAddress - The address of the deployed Safe contract.
+     * @param {string} safeSaltNonce - A unique nonce used to differentiate the Safe setup.
+     */
     constructor(nearAdapter: NearEthAdapter, safePack: SafeContractSuite, pimlicoKey: string, setup: string, safeAddress: Address, safeSaltNonce: string);
+    /**
+     * Retrieves the MPC (Multi-Party Computation) address associated with the NEAR adapter.
+     *
+     * @returns {Address} - The MPC address of the NEAR adapter.
+     */
     get mpcAddress(): Address;
+    /**
+     * Retrieves the contract ID of the MPC contract associated with the NEAR adapter.
+     *
+     * @returns {string} - The contract ID of the MPC contract.
+     */
     get mpcContractId(): string;
+    /**
+     * Retrieves the balance of the Safe account on the specified EVM chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @returns {Promise<bigint>} - A promise that resolves to the balance of the Safe account in wei.
+     */
     getBalance(chainId: number): Promise<bigint>;
+    /**
+     * Constructs a user operation for the specified chain, including necessary gas fees, nonce, and paymaster data.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {Object} args - The arguments for building the transaction.
+     * @param {number} args.chainId - The ID of the blockchain network where the transaction will be executed.
+     * @param {MetaTransaction[]} args.transactions - A list of meta-transactions to be included in the user operation.
+     * @param {boolean} args.usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<UserOperation>} - A promise that resolves to a complete `UserOperation` object, including gas fees, nonce, and paymaster data.
+     * @throws {Error} - Throws an error if the transaction set is empty or if any operation fails during the building process.
+     */
     buildTransaction(args: {
         chainId: number;
         transactions: MetaTransaction[];
         usePaymaster: boolean;
     }): Promise<UserOperation>;
+    /**
+     * Signs a transaction with the NEAR adapter using the provided operation hash.
+     *
+     * @param {Hex} safeOpHash - The hash of the user operation that needs to be signed.
+     * @returns {Promise<Hex>} - A promise that resolves to the packed signature in hexadecimal format.
+     */
     signTransaction(safeOpHash: Hex): Promise<Hex>;
+    /**
+     * Computes the operation hash for a given user operation.
+     *
+     * @param {UserOperation} userOp - The user operation for which the hash needs to be computed.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the provided user operation.
+     */
     opHash(userOp: UserOperation): Promise<Hash>;
+    /**
+     * Encodes a request to sign a transaction using either a paymaster or the user's own funds.
+     *
+     * @param {SignRequestData} signRequest - The data required to create the signature request. This includes information such as the chain ID and other necessary fields for the transaction.
+     * @param {boolean} usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<EncodedTxData>} - A promise that resolves to the encoded transaction data for the NEAR and EVM networks.
+     */
     encodeSignRequest(signRequest: SignRequestData, usePaymaster: boolean): Promise<EncodedTxData>;
+    /**
+     * Broadcasts a user operation to the EVM network with a provided signature.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the EVM network to which the transaction should be broadcasted.
+     * @param {FinalExecutionOutcome} outcome - The result of the NEAR transaction execution, which contains the necessary data to construct an EVM signature.
+     * @param {UserOperation} unsignedUserOp - The unsigned user operation to be broadcasted. This includes transaction data such as the destination address and data payload.
+     * @returns {Promise<{ signature: Hex; opHash: Hash }>} - A promise that resolves to an object containing the signature used and the hash of the executed user operation.
+     * @throws {Error} - Throws an error if the EVM broadcast fails, including the error message for debugging.
+     */
     broadcastEvm(chainId: number, outcome: FinalExecutionOutcome, unsignedUserOp: UserOperation): Promise<{
         signature: Hex;
-        receipt: UserOperationReceipt;
+        opHash: Hash;
     }>;
-    executeTransaction(chainId: number, userOp: UserOperation): Promise<UserOperationReceipt>;
+    /**
+     * Executes a user operation on the specified blockchain network.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network on which to execute the transaction.
+     * @param {UserOperation} userOp - The user operation to be executed, typically includes the data and signatures necessary for the transaction.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the executed transaction.
+     */
+    executeTransaction(chainId: number, userOp: UserOperation): Promise<Hash>;
+    /**
+     * Retrieves the receipt of a previously executed user operation.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network where the operation was executed.
+     * @param {Hash} userOpHash - The hash of the user operation for which to retrieve the receipt.
+     * @returns {Promise<UserOperationReceipt>} - A promise that resolves to the receipt of the user operation, which includes status and logs.
+     */
+    getOpReceipt(chainId: number, userOpHash: Hash): Promise<UserOperationReceipt>;
+    /**
+     * Checks if the Safe contract is deployed on the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe contract should be checked.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe contract is deployed, otherwise `false`.
+     */
     safeDeployed(chainId: number): Promise<boolean>;
+    /**
+     * Determines if the Safe account has sufficient funds to cover the transaction costs.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @param {MetaTransaction[]} transactions - A list of meta-transactions to be evaluated for funding.
+     * @param {bigint} gasCost - The estimated gas cost of executing the transactions.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe account has sufficient funds, otherwise `false`.
+     */
     sufficientlyFunded(chainId: number, transactions: MetaTransaction[], gasCost: bigint): Promise<boolean>;
+    /**
+     * Creates a meta-transaction for adding a new owner to the Safe contract.
+     *
+     * @param {Address} address - The address of the new owner to be added.
+     * @returns {MetaTransaction} - A meta-transaction object for adding the new owner.
+     */
     addOwnerTx(address: Address): MetaTransaction;
+    /**
+     * Creates and returns a new `Erc4337Bundler` instance for the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network for which the bundler is to be created.
+     * @returns {Erc4337Bundler} - A new instance of the `Erc4337Bundler` class configured for the specified chain.
+     */
     private bundlerForChainId;
+    /**
+     * Decodes transaction data for a given EVM transaction and extracts relevant details.
+     *
+     * @param {EvmTransactionData} data - The raw transaction data to be decoded.
+     * @returns {{ chainId: number; costEstimate: string; transactions: MetaTransaction[] }} - An object containing the chain ID, estimated cost, and a list of decoded meta-transactions.
+     */
+    decodeTxData(data: EvmTransactionData): {
+        chainId: number;
+        costEstimate: string;
+        transactions: MetaTransaction[];
+    };
     /**
      * Handles routing of signature requests based on the provided method, chain ID, and parameters.
      *

package/dist/esm/near-safe.js

@@ -1,7 +1,8 @@
+import { decodeMulti } from "ethers-multisend";
 import { setupAdapter, signatureFromOutcome, toPayload, } from "near-ca";
-import { serializeSignature } from "viem";
+import { decodeFunctionData, formatEther, serializeSignature, } from "viem";
 import { Erc4337Bundler } from "./lib/bundler";
-import { encodeMulti } from "./lib/multisend";
+import { encodeMulti, isMultisendTx } from "./lib/multisend";
 import { SafeContractSuite } from "./lib/safe";
 import { decodeSafeMessage } from "./lib/safe-message";
 import { getClient, isContract, metaTransactionsFromRequest, packSignature, } from "./util";
@@ -12,6 +13,12 @@ export class NearSafe {
     setup;
     pimlicoKey;
     safeSaltNonce;
+    /**
+     * Creates a new instance of the `NearSafe` class using the provided configuration.
+     *
+     * @param {NearSafeConfig} config - The configuration object required to initialize the `NearSafe` instance, including the Pimlico key and safe salt nonce.
+     * @returns {Promise<NearSafe>} - A promise that resolves to a new `NearSafe` instance.
+     */
     static async create(config) {
         const { pimlicoKey, safeSaltNonce } = config;
         const nearAdapter = await setupAdapter({ ...config });
@@ -26,6 +33,16 @@ export class NearSafe {
     `);
         return new NearSafe(nearAdapter, safePack, pimlicoKey, setup, safeAddress, safeSaltNonce || "0");
     }
+    /**
+     * Constructs a new `NearSafe` object with the provided parameters.
+     *
+     * @param {NearEthAdapter} nearAdapter - The NEAR adapter used for interacting with the NEAR blockchain.
+     * @param {SafeContractSuite} safePack - A suite of contracts and utilities for managing the Safe contract.
+     * @param {string} pimlicoKey - A key required for authenticating with the Pimlico service.
+     * @param {string} setup - The setup string generated for the Safe contract.
+     * @param {Address} safeAddress - The address of the deployed Safe contract.
+     * @param {string} safeSaltNonce - A unique nonce used to differentiate the Safe setup.
+     */
     constructor(nearAdapter, safePack, pimlicoKey, setup, safeAddress, safeSaltNonce) {
         this.nearAdapter = nearAdapter;
         this.address = safeAddress;
@@ -34,15 +51,42 @@ export class NearSafe {
         this.pimlicoKey = pimlicoKey;
         this.safeSaltNonce = safeSaltNonce;
     }
+    /**
+     * Retrieves the MPC (Multi-Party Computation) address associated with the NEAR adapter.
+     *
+     * @returns {Address} - The MPC address of the NEAR adapter.
+     */
     get mpcAddress() {
         return this.nearAdapter.address;
     }
+    /**
+     * Retrieves the contract ID of the MPC contract associated with the NEAR adapter.
+     *
+     * @returns {string} - The contract ID of the MPC contract.
+     */
     get mpcContractId() {
         return this.nearAdapter.mpcContract.contract.contractId;
     }
+    /**
+     * Retrieves the balance of the Safe account on the specified EVM chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @returns {Promise<bigint>} - A promise that resolves to the balance of the Safe account in wei.
+     */
     async getBalance(chainId) {
         return await getClient(chainId).getBalance({ address: this.address });
     }
+    /**
+     * Constructs a user operation for the specified chain, including necessary gas fees, nonce, and paymaster data.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {Object} args - The arguments for building the transaction.
+     * @param {number} args.chainId - The ID of the blockchain network where the transaction will be executed.
+     * @param {MetaTransaction[]} args.transactions - A list of meta-transactions to be included in the user operation.
+     * @param {boolean} args.usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<UserOperation>} - A promise that resolves to a complete `UserOperation` object, including gas fees, nonce, and paymaster data.
+     * @throws {Error} - Throws an error if the transaction set is empty or if any operation fails during the building process.
+     */
     async buildTransaction(args) {
         const { transactions, usePaymaster, chainId } = args;
         if (transactions.length === 0) {
@@ -61,13 +105,32 @@ export class NearSafe {
         const unsignedUserOp = { ...rawUserOp, ...paymasterData };
         return unsignedUserOp;
     }
+    /**
+     * Signs a transaction with the NEAR adapter using the provided operation hash.
+     *
+     * @param {Hex} safeOpHash - The hash of the user operation that needs to be signed.
+     * @returns {Promise<Hex>} - A promise that resolves to the packed signature in hexadecimal format.
+     */
     async signTransaction(safeOpHash) {
         const signature = await this.nearAdapter.sign(safeOpHash);
         return packSignature(signature);
     }
+    /**
+     * Computes the operation hash for a given user operation.
+     *
+     * @param {UserOperation} userOp - The user operation for which the hash needs to be computed.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the provided user operation.
+     */
     async opHash(userOp) {
         return this.safePack.getOpHash(userOp);
     }
+    /**
+     * Encodes a request to sign a transaction using either a paymaster or the user's own funds.
+     *
+     * @param {SignRequestData} signRequest - The data required to create the signature request. This includes information such as the chain ID and other necessary fields for the transaction.
+     * @param {boolean} usePaymaster - Flag indicating whether to use a paymaster for gas fees. If true, the transaction will be sponsored by the paymaster.
+     * @returns {Promise<EncodedTxData>} - A promise that resolves to the encoded transaction data for the NEAR and EVM networks.
+     */
     async encodeSignRequest(signRequest, usePaymaster) {
         const { payload, evmMessage, hash } = await this.requestRouter(signRequest, usePaymaster);
         return {
@@ -83,12 +146,22 @@ export class NearSafe {
             },
         };
     }
+    /**
+     * Broadcasts a user operation to the EVM network with a provided signature.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the EVM network to which the transaction should be broadcasted.
+     * @param {FinalExecutionOutcome} outcome - The result of the NEAR transaction execution, which contains the necessary data to construct an EVM signature.
+     * @param {UserOperation} unsignedUserOp - The unsigned user operation to be broadcasted. This includes transaction data such as the destination address and data payload.
+     * @returns {Promise<{ signature: Hex; opHash: Hash }>} - A promise that resolves to an object containing the signature used and the hash of the executed user operation.
+     * @throws {Error} - Throws an error if the EVM broadcast fails, including the error message for debugging.
+     */
     async broadcastEvm(chainId, outcome, unsignedUserOp) {
         const signature = packSignature(serializeSignature(signatureFromOutcome(outcome)));
         try {
             return {
                 signature,
-                receipt: await this.executeTransaction(chainId, {
+                opHash: await this.executeTransaction(chainId, {
                     ...unsignedUserOp,
                     signature,
                 }),
@@ -98,19 +171,45 @@ export class NearSafe {
             throw new Error(`Failed EVM broadcast: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Executes a user operation on the specified blockchain network.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network on which to execute the transaction.
+     * @param {UserOperation} userOp - The user operation to be executed, typically includes the data and signatures necessary for the transaction.
+     * @returns {Promise<Hash>} - A promise that resolves to the hash of the executed transaction.
+     */
     async executeTransaction(chainId, userOp) {
-        const bundler = this.bundlerForChainId(chainId);
-        const userOpHash = await bundler.sendUserOperation(userOp);
-        console.log("UserOp Hash", userOpHash);
-        const userOpReceipt = await bundler.getUserOpReceipt(userOpHash);
-        console.log("userOp Receipt", userOpReceipt);
-        // Update safeNotDeployed after the first transaction
-        this.safeDeployed(chainId);
-        return userOpReceipt;
+        return this.bundlerForChainId(chainId).sendUserOperation(userOp);
+    }
+    /**
+     * Retrieves the receipt of a previously executed user operation.
+     * Warning: Uses a private ethRPC with sensitive Pimlico API key (should be run server side).
+     *
+     * @param {number} chainId - The ID of the blockchain network where the operation was executed.
+     * @param {Hash} userOpHash - The hash of the user operation for which to retrieve the receipt.
+     * @returns {Promise<UserOperationReceipt>} - A promise that resolves to the receipt of the user operation, which includes status and logs.
+     */
+    async getOpReceipt(chainId, userOpHash) {
+        return this.bundlerForChainId(chainId).getUserOpReceipt(userOpHash);
     }
+    /**
+     * Checks if the Safe contract is deployed on the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe contract should be checked.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe contract is deployed, otherwise `false`.
+     */
     async safeDeployed(chainId) {
         return isContract(this.address, chainId);
     }
+    /**
+     * Determines if the Safe account has sufficient funds to cover the transaction costs.
+     *
+     * @param {number} chainId - The ID of the blockchain network where the Safe account is located.
+     * @param {MetaTransaction[]} transactions - A list of meta-transactions to be evaluated for funding.
+     * @param {bigint} gasCost - The estimated gas cost of executing the transactions.
+     * @returns {Promise<boolean>} - A promise that resolves to `true` if the Safe account has sufficient funds, otherwise `false`.
+     */
     async sufficientlyFunded(chainId, transactions, gasCost) {
         const txValue = transactions.reduce((acc, tx) => acc + BigInt(tx.value), 0n);
         if (txValue + gasCost === 0n) {
@@ -119,6 +218,12 @@ export class NearSafe {
         const safeBalance = await this.getBalance(chainId);
         return txValue + gasCost < safeBalance;
     }
+    /**
+     * Creates a meta-transaction for adding a new owner to the Safe contract.
+     *
+     * @param {Address} address - The address of the new owner to be added.
+     * @returns {MetaTransaction} - A meta-transaction object for adding the new owner.
+     */
     addOwnerTx(address) {
         return {
             to: this.address,
@@ -126,9 +231,48 @@ export class NearSafe {
             data: this.safePack.addOwnerData(address),
         };
     }
+    /**
+     * Creates and returns a new `Erc4337Bundler` instance for the specified chain.
+     *
+     * @param {number} chainId - The ID of the blockchain network for which the bundler is to be created.
+     * @returns {Erc4337Bundler} - A new instance of the `Erc4337Bundler` class configured for the specified chain.
+     */
     bundlerForChainId(chainId) {
         return new Erc4337Bundler(this.safePack.entryPoint.address, this.pimlicoKey, chainId);
     }
+    /**
+     * Decodes transaction data for a given EVM transaction and extracts relevant details.
+     *
+     * @param {EvmTransactionData} data - The raw transaction data to be decoded.
+     * @returns {{ chainId: number; costEstimate: string; transactions: MetaTransaction[] }} - An object containing the chain ID, estimated cost, and a list of decoded meta-transactions.
+     */
+    decodeTxData(data) {
+        // TODO: data.data may not always parse to UserOperation. We will have to handle the other cases.
+        const userOp = JSON.parse(data.data);
+        const { callGasLimit, maxFeePerGas, maxPriorityFeePerGas } = userOp;
+        const maxGasPrice = BigInt(maxFeePerGas) + BigInt(maxPriorityFeePerGas);
+        const { args } = decodeFunctionData({
+            abi: this.safePack.m4337.abi,
+            data: userOp.callData,
+        });
+        // Determine if singular or double!
+        const transactions = isMultisendTx(args)
+            ? decodeMulti(args[2])
+            : [
+                {
+                    to: args[0],
+                    value: args[1],
+                    data: args[2],
+                    operation: args[3],
+                },
+            ];
+        return {
+            chainId: data.chainId,
+            // This is an upper bound on the gas fees (could be lower)
+            costEstimate: formatEther(BigInt(callGasLimit) * maxGasPrice),
+            transactions,
+        };
+    }
     /**
      * Handles routing of signature requests based on the provided method, chain ID, and parameters.
      *

package/dist/esm/types.d.ts

@@ -1,5 +1,5 @@
 import { FunctionCallTransaction, SignArgs } from "near-ca";
-import { Address, Hash, Hex, ParseAbi, TransactionSerializable } from "viem";
+import { Address, Hex, ParseAbi } from "viem";
 export type SafeDeployments = {
     singleton: Deployment;
     proxyFactory: Deployment;
@@ -101,12 +101,13 @@ export interface MetaTransaction {
     readonly data: string;
     readonly operation?: OperationType;
 }
+export interface EvmTransactionData {
+    chainId: number;
+    data: string;
+    hash: string;
+}
 export interface EncodedTxData {
-    evmData: {
-        chainId: number;
-        data: string | TransactionSerializable;
-        hash: Hash;
-    };
+    evmData: EvmTransactionData;
     nearPayload: FunctionCallTransaction<{
         request: SignArgs;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "near-safe",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "An SDK for controlling Ethereum Smart Accounts via ERC4337 from a Near Account.",
   "author": "bh2smith",
@@ -42,6 +42,7 @@
   },
   "dependencies": {
     "@safe-global/safe-gateway-typescript-sdk": "^3.22.2",
+    "ethers-multisend": "^3.1.0",
     "near-api-js": "^5.0.0",
     "near-ca": "^0.5.6",
     "semver": "^7.6.3",
@@ -68,7 +69,6 @@
     "yargs": "^17.7.2"
   },
   "resolutions": {
-    "glob": "^9.0.0",
-    "base-x": "^3.0.0"
+    "glob": "^11.0.0"
   }
 }