near-safe 0.4.2 → 0.5.1

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, EvmTransactionData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
+import { DecodedMultisend, EncodedTxData, EvmTransactionData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
 export interface NearSafeConfig {
     accountId: string;
     mpcContractId: string;
@@ -19,33 +19,150 @@ 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;
-    decodeTxData(data: EvmTransactionData): {
-        chainId: number;
-        costEstimate: string;
-        transactions: MetaTransaction[];
-    };
+    /**
+     * 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): DecodedMultisend;
     /**
      * Handles routing of signature requests based on the provided method, chain ID, and parameters.
      *

package/dist/cjs/near-safe.js

@@ -10,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 });
@@ -24,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;
@@ -32,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) {
@@ -59,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 {
@@ -81,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,
                 }),
@@ -96,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) {
@@ -117,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,
@@ -124,9 +228,21 @@ 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);
@@ -136,7 +252,7 @@ class NearSafe {
             abi: this.safePack.m4337.abi,
             data: userOp.callData,
         });
-        // Determine if sungular or double!
+        // Determine if singular or double!
         const transactions = (0, multisend_1.isMultisendTx)(args)
             ? (0, ethers_multisend_1.decodeMulti)(args[2])
             : [

package/dist/cjs/types.d.ts

@@ -1,113 +1,247 @@
 import { FunctionCallTransaction, SignArgs } from "near-ca";
 import { Address, Hex, ParseAbi } from "viem";
+/**
+ * Represents a collection of Safe contract deployments, each with its own address and ABI.
+ */
 export type SafeDeployments = {
+    /** Deployment for the singleton contract. */
     singleton: Deployment;
+    /** Deployment for the proxy factory contract. */
     proxyFactory: Deployment;
+    /** Deployment for the module setup contract. */
     moduleSetup: Deployment;
+    /** Deployment for the m4337 module contract. */
     m4337: Deployment;
+    /** Deployment for the entry point contract. */
     entryPoint: Deployment;
 };
+/**
+ * Represents the details of a deployed contract, including its ABI and address.
+ */
 export interface Deployment {
+    /** The ABI of the deployed contract. Can be a raw ABI array or a parsed ABI. */
     abi: unknown[] | ParseAbi<readonly string[]>;
+    /** The address of the deployed contract. */
     address: Address;
 }
+/**
+ * Represents an unsigned user operation that can be sent to the EntryPoint contract.
+ */
 export interface UnsignedUserOperation {
+    /** The sender's address initiating the user operation. */
     sender: Address;
+    /** The unique nonce associated with this user operation. */
     nonce: string;
+    /** The optional factory address to use for creating new contracts. */
     factory?: Address;
+    /** Optional additional data for the factory, typically used for contract initialization. */
     factoryData?: Hex;
+    /** The encoded data for the contract call or transaction execution. */
     callData: Hex;
+    /** Maximum priority fee per gas unit for the transaction. */
     maxPriorityFeePerGas: Hex;
+    /** Maximum fee per gas unit for the transaction. */
     maxFeePerGas: Hex;
 }
 /**
- * Supported Representation of UserOperation for EntryPoint v0.7
+ * Supported representation of a user operation for EntryPoint version 0.7, including gas limits and signature.
  */
 export interface UserOperation extends UnsignedUserOperation {
+    /** The gas limit for verification of the operation. */
     verificationGasLimit: Hex;
+    /** The gas limit for the execution of the operation call. */
     callGasLimit: Hex;
+    /** The gas used before verification begins. */
     preVerificationGas: Hex;
+    /** Optional signature for the user operation. */
     signature?: Hex;
 }
+/**
+ * Represents additional paymaster-related data for a user operation.
+ */
 export interface PaymasterData {
+    /** Optional paymaster address responsible for covering gas costs. */
     paymaster?: Address;
+    /** Optional additional data required by the paymaster. */
     paymasterData?: Hex;
+    /** The gas limit for paymaster verification. */
     paymasterVerificationGasLimit?: Hex;
+    /** The gas limit for paymaster post-operation execution. */
     paymasterPostOpGasLimit?: Hex;
+    /** The gas limit for operation verification. */
     verificationGasLimit: Hex;
+    /** The gas limit for the operation call execution. */
     callGasLimit: Hex;
+    /** The gas used before verification begins. */
     preVerificationGas: Hex;
 }
+/**
+ * User configuration options for transaction building and user operation execution.
+ */
 export interface UserOptions {
+    /** Whether to use a paymaster for gas fee coverage. */
     usePaymaster: boolean;
+    /** The unique nonce used to differentiate multiple Safe setups. */
     safeSaltNonce: string;
+    /** The NEAR contract ID for the MPC contract. */
     mpcContractId: string;
+    /** Optional recovery address in case of key compromise or other emergency situations. */
     recoveryAddress?: string;
 }
+/**
+ * Represents the possible transaction statuses.
+ */
 export type TxStatus = "success" | "reverted";
+/**
+ * Represents a log entry in a transaction receipt.
+ */
 interface Log {
+    /** The index of the log in the transaction. */
     logIndex: string;
+    /** The index of the transaction within the block. */
     transactionIndex: string;
+    /** The hash of the transaction containing the log. */
     transactionHash: string;
+    /** The hash of the block containing the transaction. */
     blockHash: string;
+    /** The number of the block containing the transaction. */
     blockNumber: string;
+    /** The address that generated the log. */
     address: string;
+    /** The raw data of the log. */
     data: string;
+    /** The topics associated with the log event. */
     topics: string[];
 }
+/**
+ * Represents a transaction receipt returned by the blockchain.
+ */
 interface Receipt {
+    /** The hash of the transaction. */
     transactionHash: Hex;
+    /** The index of the transaction within the block. */
     transactionIndex: bigint;
+    /** The hash of the block containing the transaction. */
     blockHash: Hex;
+    /** The number of the block containing the transaction. */
     blockNumber: bigint;
+    /** The address from which the transaction originated. */
     from: Address;
+    /** Optional address to which the transaction was sent (if applicable). */
     to?: Address;
+    /** The cumulative gas used in the block up to this transaction. */
     cumulativeGasUsed: bigint;
+    /** The status of the transaction (success or reverted). */
     status: TxStatus;
+    /** The total gas used by this transaction. */
     gasUsed: bigint;
+    /** Optional address of a newly deployed contract (if applicable). */
     contractAddress?: Address;
+    /** The logs bloom filter for the transaction. */
     logsBloom: Hex;
+    /** The effective gas price used in the transaction. */
     effectiveGasPrice: bigint;
 }
+/**
+ * Represents the receipt of a user operation including its details, logs, and result.
+ */
 export type UserOperationReceipt = {
+    /** The hash of the user operation. */
     userOpHash: Hex;
+    /** The address of the entry point contract handling the user operation. */
     entryPoint: Address;
+    /** The sender's address initiating the user operation. */
     sender: Address;
+    /** The nonce of the user operation. */
     nonce: bigint;
+    /** Optional paymaster address responsible for covering gas costs. */
     paymaster?: Address;
+    /** The actual gas used by the operation. */
     actualGasUsed: bigint;
+    /** The actual gas cost of the operation. */
     actualGasCost: bigint;
+    /** Whether the user operation succeeded or failed. */
     success: boolean;
+    /** Optional reason for failure if the operation was unsuccessful. */
     reason?: string;
+    /** The transaction receipt associated with the user operation. */
     receipt: Receipt;
+    /** The list of logs generated by the user operation. */
     logs: Log[];
 };
+/**
+ * Represents the different gas prices for transaction execution based on priority levels.
+ */
 export interface GasPrices {
+    /** Gas price for slower transactions. */
     slow: GasPrice;
+    /** Gas price for standard transactions. */
     standard: GasPrice;
+    /** Gas price for fast transactions. */
     fast: GasPrice;
 }
+/**
+ * Represents a specific gas price configuration for transaction execution.
+ */
 export interface GasPrice {
+    /** Maximum fee per gas unit for the transaction. */
     maxFeePerGas: Hex;
+    /** Maximum priority fee per gas unit for the transaction. */
     maxPriorityFeePerGas: Hex;
 }
+/**
+ * Enum representing the type of operation in a meta-transaction.
+ */
 export declare enum OperationType {
+    /** Standard call operation (0). */
     Call = 0,
+    /** Delegate call operation (1). */
     DelegateCall = 1
 }
+/**
+ * Represents a meta-transaction, which includes the destination address, value, data, and type of operation.
+ */
 export interface MetaTransaction {
+    /** The destination address for the meta-transaction. */
     readonly to: string;
+    /** The value to be sent with the transaction (as a string to handle large numbers). */
     readonly value: string;
+    /** The encoded data for the contract call or function execution. */
     readonly data: string;
+    /** Optional type of operation (call or delegate call). */
     readonly operation?: OperationType;
 }
+/**
+ * Represents raw transaction data for an EVM transaction.
+ */
 export interface EvmTransactionData {
+    /** The chain ID of the network where the transaction is being executed. */
     chainId: number;
+    /** The raw data of the transaction. */
     data: string;
+    /** The hash of the transaction. */
     hash: string;
 }
+/**
+ * Represents the decoded details of a multisend transaction.
+ */
+export interface DecodedMultisend {
+    /** The chain ID of the network where the multisend transaction is being executed. */
+    chainId: number;
+    /** The estimated cost of the multisend transaction in Ether.
+     *  This is an upper bound on the transaction fee (could wind up lower).
+     */
+    costEstimate: string;
+    /** The list of meta-transactions included in the multisend. */
+    transactions: MetaTransaction[];
+}
+/**
+ * Represents encoded transaction data for both NEAR and EVM networks.
+ */
 export interface EncodedTxData {
+    /** The encoded transaction data for the EVM network. */
     evmData: EvmTransactionData;
+    /** The encoded payload for a NEAR function call, including the signing arguments. */
     nearPayload: FunctionCallTransaction<{
         request: SignArgs;
     }>;

package/dist/cjs/types.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OperationType = void 0;
+/**
+ * Enum representing the type of operation in a meta-transaction.
+ */
 var OperationType;
 (function (OperationType) {
+    /** Standard call operation (0). */
     OperationType[OperationType["Call"] = 0] = "Call";
+    /** Delegate call operation (1). */
     OperationType[OperationType["DelegateCall"] = 1] = "DelegateCall";
 })(OperationType || (exports.OperationType = OperationType = {}));

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, EvmTransactionData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
+import { DecodedMultisend, EncodedTxData, EvmTransactionData, MetaTransaction, UserOperation, UserOperationReceipt } from "./types";
 export interface NearSafeConfig {
     accountId: string;
     mpcContractId: string;
@@ -19,33 +19,150 @@ 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;
-    decodeTxData(data: EvmTransactionData): {
-        chainId: number;
-        costEstimate: string;
-        transactions: MetaTransaction[];
-    };
+    /**
+     * 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): DecodedMultisend;
     /**
      * Handles routing of signature requests based on the provided method, chain ID, and parameters.
      *

package/dist/esm/near-safe.js

@@ -13,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 });
@@ -27,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;
@@ -35,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) {
@@ -62,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 {
@@ -84,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,
                 }),
@@ -99,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) {
@@ -120,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,
@@ -127,9 +231,21 @@ 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);
@@ -139,7 +255,7 @@ export class NearSafe {
             abi: this.safePack.m4337.abi,
             data: userOp.callData,
         });
-        // Determine if sungular or double!
+        // Determine if singular or double!
         const transactions = isMultisendTx(args)
             ? decodeMulti(args[2])
             : [

package/dist/esm/types.d.ts

@@ -1,113 +1,247 @@
 import { FunctionCallTransaction, SignArgs } from "near-ca";
 import { Address, Hex, ParseAbi } from "viem";
+/**
+ * Represents a collection of Safe contract deployments, each with its own address and ABI.
+ */
 export type SafeDeployments = {
+    /** Deployment for the singleton contract. */
     singleton: Deployment;
+    /** Deployment for the proxy factory contract. */
     proxyFactory: Deployment;
+    /** Deployment for the module setup contract. */
     moduleSetup: Deployment;
+    /** Deployment for the m4337 module contract. */
     m4337: Deployment;
+    /** Deployment for the entry point contract. */
     entryPoint: Deployment;
 };
+/**
+ * Represents the details of a deployed contract, including its ABI and address.
+ */
 export interface Deployment {
+    /** The ABI of the deployed contract. Can be a raw ABI array or a parsed ABI. */
     abi: unknown[] | ParseAbi<readonly string[]>;
+    /** The address of the deployed contract. */
     address: Address;
 }
+/**
+ * Represents an unsigned user operation that can be sent to the EntryPoint contract.
+ */
 export interface UnsignedUserOperation {
+    /** The sender's address initiating the user operation. */
     sender: Address;
+    /** The unique nonce associated with this user operation. */
     nonce: string;
+    /** The optional factory address to use for creating new contracts. */
     factory?: Address;
+    /** Optional additional data for the factory, typically used for contract initialization. */
     factoryData?: Hex;
+    /** The encoded data for the contract call or transaction execution. */
     callData: Hex;
+    /** Maximum priority fee per gas unit for the transaction. */
     maxPriorityFeePerGas: Hex;
+    /** Maximum fee per gas unit for the transaction. */
     maxFeePerGas: Hex;
 }
 /**
- * Supported Representation of UserOperation for EntryPoint v0.7
+ * Supported representation of a user operation for EntryPoint version 0.7, including gas limits and signature.
  */
 export interface UserOperation extends UnsignedUserOperation {
+    /** The gas limit for verification of the operation. */
     verificationGasLimit: Hex;
+    /** The gas limit for the execution of the operation call. */
     callGasLimit: Hex;
+    /** The gas used before verification begins. */
     preVerificationGas: Hex;
+    /** Optional signature for the user operation. */
     signature?: Hex;
 }
+/**
+ * Represents additional paymaster-related data for a user operation.
+ */
 export interface PaymasterData {
+    /** Optional paymaster address responsible for covering gas costs. */
     paymaster?: Address;
+    /** Optional additional data required by the paymaster. */
     paymasterData?: Hex;
+    /** The gas limit for paymaster verification. */
     paymasterVerificationGasLimit?: Hex;
+    /** The gas limit for paymaster post-operation execution. */
     paymasterPostOpGasLimit?: Hex;
+    /** The gas limit for operation verification. */
     verificationGasLimit: Hex;
+    /** The gas limit for the operation call execution. */
     callGasLimit: Hex;
+    /** The gas used before verification begins. */
     preVerificationGas: Hex;
 }
+/**
+ * User configuration options for transaction building and user operation execution.
+ */
 export interface UserOptions {
+    /** Whether to use a paymaster for gas fee coverage. */
     usePaymaster: boolean;
+    /** The unique nonce used to differentiate multiple Safe setups. */
     safeSaltNonce: string;
+    /** The NEAR contract ID for the MPC contract. */
     mpcContractId: string;
+    /** Optional recovery address in case of key compromise or other emergency situations. */
     recoveryAddress?: string;
 }
+/**
+ * Represents the possible transaction statuses.
+ */
 export type TxStatus = "success" | "reverted";
+/**
+ * Represents a log entry in a transaction receipt.
+ */
 interface Log {
+    /** The index of the log in the transaction. */
     logIndex: string;
+    /** The index of the transaction within the block. */
     transactionIndex: string;
+    /** The hash of the transaction containing the log. */
     transactionHash: string;
+    /** The hash of the block containing the transaction. */
     blockHash: string;
+    /** The number of the block containing the transaction. */
     blockNumber: string;
+    /** The address that generated the log. */
     address: string;
+    /** The raw data of the log. */
     data: string;
+    /** The topics associated with the log event. */
     topics: string[];
 }
+/**
+ * Represents a transaction receipt returned by the blockchain.
+ */
 interface Receipt {
+    /** The hash of the transaction. */
     transactionHash: Hex;
+    /** The index of the transaction within the block. */
     transactionIndex: bigint;
+    /** The hash of the block containing the transaction. */
     blockHash: Hex;
+    /** The number of the block containing the transaction. */
     blockNumber: bigint;
+    /** The address from which the transaction originated. */
     from: Address;
+    /** Optional address to which the transaction was sent (if applicable). */
     to?: Address;
+    /** The cumulative gas used in the block up to this transaction. */
     cumulativeGasUsed: bigint;
+    /** The status of the transaction (success or reverted). */
     status: TxStatus;
+    /** The total gas used by this transaction. */
     gasUsed: bigint;
+    /** Optional address of a newly deployed contract (if applicable). */
     contractAddress?: Address;
+    /** The logs bloom filter for the transaction. */
     logsBloom: Hex;
+    /** The effective gas price used in the transaction. */
     effectiveGasPrice: bigint;
 }
+/**
+ * Represents the receipt of a user operation including its details, logs, and result.
+ */
 export type UserOperationReceipt = {
+    /** The hash of the user operation. */
     userOpHash: Hex;
+    /** The address of the entry point contract handling the user operation. */
     entryPoint: Address;
+    /** The sender's address initiating the user operation. */
     sender: Address;
+    /** The nonce of the user operation. */
     nonce: bigint;
+    /** Optional paymaster address responsible for covering gas costs. */
     paymaster?: Address;
+    /** The actual gas used by the operation. */
     actualGasUsed: bigint;
+    /** The actual gas cost of the operation. */
     actualGasCost: bigint;
+    /** Whether the user operation succeeded or failed. */
     success: boolean;
+    /** Optional reason for failure if the operation was unsuccessful. */
     reason?: string;
+    /** The transaction receipt associated with the user operation. */
     receipt: Receipt;
+    /** The list of logs generated by the user operation. */
     logs: Log[];
 };
+/**
+ * Represents the different gas prices for transaction execution based on priority levels.
+ */
 export interface GasPrices {
+    /** Gas price for slower transactions. */
     slow: GasPrice;
+    /** Gas price for standard transactions. */
     standard: GasPrice;
+    /** Gas price for fast transactions. */
     fast: GasPrice;
 }
+/**
+ * Represents a specific gas price configuration for transaction execution.
+ */
 export interface GasPrice {
+    /** Maximum fee per gas unit for the transaction. */
     maxFeePerGas: Hex;
+    /** Maximum priority fee per gas unit for the transaction. */
     maxPriorityFeePerGas: Hex;
 }
+/**
+ * Enum representing the type of operation in a meta-transaction.
+ */
 export declare enum OperationType {
+    /** Standard call operation (0). */
     Call = 0,
+    /** Delegate call operation (1). */
     DelegateCall = 1
 }
+/**
+ * Represents a meta-transaction, which includes the destination address, value, data, and type of operation.
+ */
 export interface MetaTransaction {
+    /** The destination address for the meta-transaction. */
     readonly to: string;
+    /** The value to be sent with the transaction (as a string to handle large numbers). */
     readonly value: string;
+    /** The encoded data for the contract call or function execution. */
     readonly data: string;
+    /** Optional type of operation (call or delegate call). */
     readonly operation?: OperationType;
 }
+/**
+ * Represents raw transaction data for an EVM transaction.
+ */
 export interface EvmTransactionData {
+    /** The chain ID of the network where the transaction is being executed. */
     chainId: number;
+    /** The raw data of the transaction. */
     data: string;
+    /** The hash of the transaction. */
     hash: string;
 }
+/**
+ * Represents the decoded details of a multisend transaction.
+ */
+export interface DecodedMultisend {
+    /** The chain ID of the network where the multisend transaction is being executed. */
+    chainId: number;
+    /** The estimated cost of the multisend transaction in Ether.
+     *  This is an upper bound on the transaction fee (could wind up lower).
+     */
+    costEstimate: string;
+    /** The list of meta-transactions included in the multisend. */
+    transactions: MetaTransaction[];
+}
+/**
+ * Represents encoded transaction data for both NEAR and EVM networks.
+ */
 export interface EncodedTxData {
+    /** The encoded transaction data for the EVM network. */
     evmData: EvmTransactionData;
+    /** The encoded payload for a NEAR function call, including the signing arguments. */
     nearPayload: FunctionCallTransaction<{
         request: SignArgs;
     }>;

package/dist/esm/types.js

@@ -1,5 +1,10 @@
+/**
+ * Enum representing the type of operation in a meta-transaction.
+ */
 export var OperationType;
 (function (OperationType) {
+    /** Standard call operation (0). */
     OperationType[OperationType["Call"] = 0] = "Call";
+    /** Delegate call operation (1). */
     OperationType[OperationType["DelegateCall"] = 1] = "DelegateCall";
 })(OperationType || (OperationType = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "near-safe",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "license": "MIT",
   "description": "An SDK for controlling Ethereum Smart Accounts via ERC4337 from a Near Account.",
   "author": "bh2smith",
@@ -44,7 +44,7 @@
     "@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",
+    "near-ca": "^0.5.7",
     "semver": "^7.6.3",
     "viem": "^2.16.5"
   },