near-safe 0.4.2 → 0.5.0

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

@@ -19,28 +19,149 @@ 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;

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/esm/near-safe.d.ts

@@ -19,28 +19,149 @@ 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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "near-safe",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "An SDK for controlling Ethereum Smart Accounts via ERC4337 from a Near Account.",
   "author": "bh2smith",