near-safe 0.0.0

package/README.md

@@ -0,0 +1,57 @@
+# Near-Safe
+
+**TLDR;** This project provides a TypeScript implementation for controling Ethereum Smart Accounts via ERC4337 standard from a Near Account. 
+It includes utilities for packing data, managing transactions, and interacting with a bundler.
+
+The account structure is defined as follows:
+
+1. **Near Account** produces signatures for a deterministic EOA via Near's MPC Contract for [Chain Signatures](https://docs.near.org/concepts/abstraction/chain-signatures)
+2. This EOA (controled by the Near Account) is the owner of a deterministic [Safe](https://safe.global/) with configured support for [ERC4337](https://www.erc4337.io/) standard.
+
+## Features
+
+1. Users first transaction is bundled together with the Safe's deployement (i.e. Safe does not need to be created before it is used). This is achived as multisend transaction.
+2. No need to fund the EOA Account (it is only used for signatures).
+3. Account Recovery: Near's MPC service provides signatures for accounts that users control, but do not hold the private key for. Provide a "recoveryAddress" that will be added as an additional owner of the Safe.
+4. Paymaster Support for an entirely gasless experience!
+5. Same address on all chains!
+
+## Installation & Configuration
+
+To get started, clone the repository and install the dependencies:
+
+```sh
+yarn install
+```
+
+Create a `.env` (or use our `.env.sample`) file in the root of the project and add the following environment variables:
+
+```sh
+ETH_RPC=https://rpc2.sepolia.org
+
+NEAR_ACCOUNT_ID=
+NEAR_ACCOUNT_PRIVATE_KEY=
+
+# Head to https://www.pimlico.io/ for an API key
+ERC4337_BUNDLER_URL=
+```
+
+
+## Usage
+
+### Running the Example
+
+The example script `examples/send-tx.ts` demonstrates how to use the transaction manager. You can run it with the following command:
+
+```sh
+yarn start --usePaymaster --recoveryAddress <recovery_address> --safeSaltNonce <safe_salt_nonce>
+```
+
+### Example Arguments
+
+The example script accepts the following arguments:
+
+- `--usePaymaster`: Boolean flag to indicate if the transaction should be sponsored by a paymaster service.
+- `--recoveryAddress`: The recovery address to be attached as the owner of the Safe (immediately after deployment).
+- `--safeSaltNonce`: The salt nonce used for the Safe deployment.
+

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./tx-manager"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./util"), exports);

package/dist/cjs/lib/bundler.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Erc4337Bundler = void 0;
+const ethers_1 = require("ethers");
+const util_1 = require("../util");
+class Erc4337Bundler {
+    constructor(bundlerUrl, entryPointAddress) {
+        this.entryPointAddress = entryPointAddress;
+        this.provider = new ethers_1.ethers.JsonRpcProvider(bundlerUrl);
+    }
+    async getPaymasterData(rawUserOp, usePaymaster, safeNotDeployed) {
+        // TODO: Keep this option out of the bundler
+        if (usePaymaster) {
+            console.log("Requesting paymaster data...");
+            const data = this.provider.send("pm_sponsorUserOperation", [
+                { ...rawUserOp, signature: util_1.PLACEHOLDER_SIG },
+                this.entryPointAddress,
+            ]);
+            return data;
+        }
+        return defaultPaymasterData(safeNotDeployed);
+    }
+    async sendUserOperation(userOp) {
+        try {
+            const userOpHash = await this.provider.send("eth_sendUserOperation", [
+                userOp,
+                this.entryPointAddress,
+            ]);
+            return userOpHash;
+        }
+        catch (err) {
+            const error = err.error;
+            throw new Error(`Failed to send user op with: ${error.message}`);
+        }
+    }
+    async getGasPrice() {
+        return this.provider.send("pimlico_getUserOperationGasPrice", []);
+    }
+    async _getUserOpReceiptInner(userOpHash) {
+        return this.provider.send("eth_getUserOperationReceipt", [userOpHash]);
+    }
+    async getUserOpReceipt(userOpHash) {
+        let userOpReceipt = null;
+        while (!userOpReceipt) {
+            // Wait 2 seconds before checking the status again
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            userOpReceipt = await this._getUserOpReceiptInner(userOpHash);
+        }
+        return userOpReceipt;
+    }
+}
+exports.Erc4337Bundler = Erc4337Bundler;
+// TODO(bh2smith) Should probably get reasonable estimates here:
+const defaultPaymasterData = (safeNotDeployed) => {
+    return {
+        verificationGasLimit: ethers_1.ethers.toBeHex(safeNotDeployed ? 500000 : 100000),
+        callGasLimit: ethers_1.ethers.toBeHex(100000),
+        preVerificationGas: ethers_1.ethers.toBeHex(100000),
+    };
+};

package/dist/cjs/lib/near.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNearSignature = getNearSignature;
+const ethers_1 = require("ethers");
+async function getNearSignature(adapter, hash) {
+    const viemHash = typeof hash === "string" ? hash : hash;
+    // MPC Contract produces two possible signatures.
+    const signature = await adapter.sign(viemHash);
+    if (ethers_1.ethers.recoverAddress(hash, signature).toLocaleLowerCase() ===
+        adapter.address.toLocaleLowerCase()) {
+        return signature;
+    }
+    throw new Error("Invalid signature!");
+}

package/dist/cjs/lib/safe.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContractSuite = void 0;
+const ethers_1 = require("ethers");
+const safe_deployments_1 = require("@safe-global/safe-deployments");
+const safe_modules_deployments_1 = require("@safe-global/safe-modules-deployments");
+const util_1 = require("../util");
+/**
+ * All contracts used in account creation & execution
+ */
+class ContractSuite {
+    constructor(provider, singleton, proxyFactory, m4337, moduleSetup, entryPoint) {
+        this.provider = provider;
+        this.singleton = singleton;
+        this.proxyFactory = proxyFactory;
+        this.m4337 = m4337;
+        this.moduleSetup = moduleSetup;
+        this.entryPoint = entryPoint;
+    }
+    static async init(provider) {
+        const safeDeployment = (fn) => getDeployment(fn, { provider, version: "1.4.1" });
+        const m4337Deployment = (fn) => getDeployment(fn, { provider, version: "0.3.0" });
+        // Need this first to get entryPoint address
+        const m4337 = await m4337Deployment(safe_modules_deployments_1.getSafe4337ModuleDeployment);
+        const [singleton, proxyFactory, moduleSetup, supportedEntryPoint] = await Promise.all([
+            safeDeployment(safe_deployments_1.getSafeL2SingletonDeployment),
+            safeDeployment(safe_deployments_1.getProxyFactoryDeployment),
+            m4337Deployment(safe_modules_deployments_1.getSafeModuleSetupDeployment),
+            m4337.SUPPORTED_ENTRYPOINT(),
+        ]);
+        const entryPoint = new ethers_1.ethers.Contract(supportedEntryPoint, ["function getNonce(address, uint192 key) view returns (uint256 nonce)"], provider);
+        return new ContractSuite(provider, singleton, proxyFactory, m4337, moduleSetup, entryPoint);
+    }
+    async addressForSetup(setup, saltNonce) {
+        // bytes32 salt = keccak256(abi.encodePacked(keccak256(initializer), saltNonce));
+        // cf: https://github.com/safe-global/safe-smart-account/blob/499b17ad0191b575fcadc5cb5b8e3faeae5391ae/contracts/proxies/SafeProxyFactory.sol#L58
+        const salt = ethers_1.ethers.keccak256(ethers_1.ethers.solidityPacked(["bytes32", "uint256"], [ethers_1.ethers.keccak256(setup), saltNonce || 0]));
+        // abi.encodePacked(type(SafeProxy).creationCode, uint256(uint160(_singleton)));
+        // cf: https://github.com/safe-global/safe-smart-account/blob/499b17ad0191b575fcadc5cb5b8e3faeae5391ae/contracts/proxies/SafeProxyFactory.sol#L29
+        const initCode = ethers_1.ethers.solidityPacked(["bytes", "uint256"], [
+            await this.proxyFactory.proxyCreationCode(),
+            await this.singleton.getAddress(),
+        ]);
+        return ethers_1.ethers.getCreate2Address(await this.proxyFactory.getAddress(), salt, ethers_1.ethers.keccak256(initCode));
+    }
+    async getSetup(owners) {
+        const setup = await this.singleton.interface.encodeFunctionData("setup", [
+            owners,
+            1, // We use sign threshold of 1.
+            this.moduleSetup.target,
+            this.moduleSetup.interface.encodeFunctionData("enableModules", [
+                [this.m4337.target],
+            ]),
+            this.m4337.target,
+            ethers_1.ethers.ZeroAddress,
+            0,
+            ethers_1.ethers.ZeroAddress,
+        ]);
+        return setup;
+    }
+    async getOpHash(unsignedUserOp, paymasterData) {
+        return this.m4337.getOperationHash({
+            ...unsignedUserOp,
+            initCode: unsignedUserOp.factory
+                ? ethers_1.ethers.solidityPacked(["address", "bytes"], [unsignedUserOp.factory, unsignedUserOp.factoryData])
+                : "0x",
+            accountGasLimits: (0, util_1.packGas)(unsignedUserOp.verificationGasLimit, unsignedUserOp.callGasLimit),
+            gasFees: (0, util_1.packGas)(unsignedUserOp.maxPriorityFeePerGas, unsignedUserOp.maxFeePerGas),
+            paymasterAndData: (0, util_1.packPaymasterData)(paymasterData),
+            signature: util_1.PLACEHOLDER_SIG,
+        });
+    }
+    factoryDataForSetup(safeNotDeployed, setup, safeSaltNonce) {
+        return safeNotDeployed
+            ? {
+                factory: this.proxyFactory.target,
+                factoryData: this.proxyFactory.interface.encodeFunctionData("createProxyWithNonce", [this.singleton.target, setup, safeSaltNonce]),
+            }
+            : {};
+    }
+    async buildUserOp(txData, safeAddress, feeData, setup, safeNotDeployed, safeSaltNonce) {
+        const rawUserOp = {
+            sender: safeAddress,
+            nonce: ethers_1.ethers.toBeHex(await this.entryPoint.getNonce(safeAddress, 0)),
+            ...this.factoryDataForSetup(safeNotDeployed, setup, safeSaltNonce),
+            // <https://github.com/safe-global/safe-modules/blob/9a18245f546bf2a8ed9bdc2b04aae44f949ec7a0/modules/4337/contracts/Safe4337Module.sol#L172>
+            callData: this.m4337.interface.encodeFunctionData("executeUserOp", [
+                txData.to,
+                BigInt(txData.value),
+                txData.data,
+                txData.operation || 0,
+            ]),
+            ...feeData,
+        };
+        return rawUserOp;
+    }
+}
+exports.ContractSuite = ContractSuite;
+async function getDeployment(fn, { provider, version }) {
+    const { chainId } = await provider.getNetwork();
+    const deployment = fn({ version });
+    if (!deployment || !deployment.networkAddresses[`${chainId}`]) {
+        throw new Error(`Deployment not found for version ${version} and chainId ${chainId}`);
+    }
+    return new ethers_1.ethers.Contract(deployment.networkAddresses[`${chainId}`], deployment.abi, provider);
+}

package/dist/cjs/tx-manager.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionManager = void 0;
+const ethers_1 = require("ethers");
+const near_ca_1 = require("near-ca");
+const bundler_1 = require("./lib/bundler");
+const util_1 = require("./util");
+const near_1 = require("./lib/near");
+const ethers_multisend_1 = require("ethers-multisend");
+const safe_1 = require("./lib/safe");
+class TransactionManager {
+    constructor(provider, nearAdapter, safePack, bundler, setup, safeAddress, safeSaltNonce, safeNotDeployed) {
+        this.provider = provider;
+        this.nearAdapter = nearAdapter;
+        this.safePack = safePack;
+        this.bundler = bundler;
+        this.setup = setup;
+        this.safeAddress = safeAddress;
+        this.safeSaltNonce = safeSaltNonce;
+        this._safeNotDeployed = safeNotDeployed;
+    }
+    static async create(config) {
+        const provider = new ethers_1.ethers.JsonRpcProvider(config.ethRpc);
+        const [nearAdapter, safePack] = await Promise.all([
+            near_ca_1.NearEthAdapter.fromConfig({
+                mpcContract: new near_ca_1.MpcContract(config.nearAccount, config.mpcContractId),
+            }),
+            safe_1.ContractSuite.init(provider),
+        ]);
+        console.log(`Near Adapter: ${nearAdapter.nearAccountId()} <> ${nearAdapter.address}`);
+        const bundler = new bundler_1.Erc4337Bundler(config.erc4337BundlerUrl, await safePack.entryPoint.getAddress());
+        const setup = await safePack.getSetup([nearAdapter.address]);
+        const safeAddress = await safePack.addressForSetup(setup, config.safeSaltNonce);
+        const safeNotDeployed = (await provider.getCode(safeAddress)) === "0x";
+        console.log(`Safe Address: ${safeAddress} - deployed? ${!safeNotDeployed}`);
+        return new TransactionManager(provider, nearAdapter, safePack, bundler, setup, safeAddress, config.safeSaltNonce || "0", safeNotDeployed);
+    }
+    get safeNotDeployed() {
+        return this._safeNotDeployed;
+    }
+    get nearEOA() {
+        return this.nearAdapter.address;
+    }
+    async getSafeBalance() {
+        return await this.provider.getBalance(this.safeAddress);
+    }
+    async buildTransaction(args) {
+        const { transactions, options } = args;
+        const gasFees = (await this.bundler.getGasPrice()).fast;
+        // const gasFees = await this.provider.getFeeData();
+        // Build Singular MetaTransaction for Multisend from transaction list.
+        if (transactions.length === 0) {
+            throw new Error("Empty transaction set!");
+        }
+        const tx = transactions.length > 1 ? (0, ethers_multisend_1.encodeMulti)(transactions) : transactions[0];
+        const rawUserOp = await this.safePack.buildUserOp(tx, this.safeAddress, gasFees, this.setup, this.safeNotDeployed, this.safeSaltNonce);
+        const paymasterData = await this.bundler.getPaymasterData(rawUserOp, options.usePaymaster, this.safeNotDeployed);
+        const unsignedUserOp = { ...rawUserOp, ...paymasterData };
+        const safeOpHash = await this.safePack.getOpHash(unsignedUserOp, paymasterData);
+        return {
+            safeOpHash,
+            unsignedUserOp,
+        };
+    }
+    async signTransaction(safeOpHash) {
+        const signature = await (0, near_1.getNearSignature)(this.nearAdapter, safeOpHash);
+        return (0, util_1.packSignature)(signature);
+    }
+    async executeTransaction(userOp) {
+        const userOpHash = await this.bundler.sendUserOperation(userOp);
+        console.log("UserOp Hash", userOpHash);
+        const userOpReceipt = await this.bundler.getUserOpReceipt(userOpHash);
+        console.log("userOp Receipt", userOpReceipt);
+        // Update safeNotDeployed after the first transaction
+        this._safeNotDeployed =
+            (await this.provider.getCode(this.safeAddress)) === "0x";
+        return userOpReceipt;
+    }
+    addOwnerTx(address) {
+        return {
+            to: this.safeAddress,
+            value: "0",
+            data: this.safePack.singleton.interface.encodeFunctionData("addOwnerWithThreshold", [address, 1]),
+        };
+    }
+    async safeSufficientlyFunded(transactions, gasCost) {
+        const txValue = transactions.reduce((acc, tx) => acc + BigInt(tx.value), 0n);
+        if (txValue + gasCost === 0n) {
+            return true;
+        }
+        const safeBalance = await this.getSafeBalance();
+        return txValue + gasCost < safeBalance;
+    }
+}
+exports.TransactionManager = TransactionManager;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/util.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packGas = exports.PLACEHOLDER_SIG = void 0;
+exports.packSignature = packSignature;
+exports.packPaymasterData = packPaymasterData;
+exports.containsValue = containsValue;
+const ethers_1 = require("ethers");
+exports.PLACEHOLDER_SIG = ethers_1.ethers.solidityPacked(["uint48", "uint48"], [0, 0]);
+const packGas = (hi, lo) => ethers_1.ethers.solidityPacked(["uint128", "uint128"], [hi, lo]);
+exports.packGas = packGas;
+function packSignature(signature, validFrom = 0, validTo = 0) {
+    return ethers_1.ethers.solidityPacked(["uint48", "uint48", "bytes"], [validFrom, validTo, signature]);
+}
+function packPaymasterData(data) {
+    return data.paymaster
+        ? ethers_1.ethers.hexlify(ethers_1.ethers.concat([
+            data.paymaster,
+            ethers_1.ethers.toBeHex(data.paymasterVerificationGasLimit || "0x", 16),
+            ethers_1.ethers.toBeHex(data.paymasterPostOpGasLimit || "0x", 16),
+            data.paymasterData || "0x",
+        ]))
+        : "0x";
+}
+function containsValue(transactions) {
+    return transactions.some((tx) => tx.value !== "0");
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./tx-manager";
+export * from "./types";
+export * from "./util";

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export * from "./tx-manager";
+export * from "./types";
+export * from "./util";

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

@@ -0,0 +1,12 @@
+import { ethers } from "ethers";
+import { GasPrices, PaymasterData, UnsignedUserOperation, UserOperation, UserOperationReceipt } from "../types";
+export declare class Erc4337Bundler {
+    provider: ethers.JsonRpcProvider;
+    entryPointAddress: string;
+    constructor(bundlerUrl: string, entryPointAddress: string);
+    getPaymasterData(rawUserOp: UnsignedUserOperation, usePaymaster: boolean, safeNotDeployed: boolean): Promise<PaymasterData>;
+    sendUserOperation(userOp: UserOperation): Promise<string>;
+    getGasPrice(): Promise<GasPrices>;
+    _getUserOpReceiptInner(userOpHash: string): Promise<UserOperationReceipt | null>;
+    getUserOpReceipt(userOpHash: string): Promise<UserOperationReceipt>;
+}

package/dist/esm/lib/bundler.js

@@ -0,0 +1,58 @@
+import { ethers } from "ethers";
+import { PLACEHOLDER_SIG } from "../util";
+export class Erc4337Bundler {
+    provider;
+    entryPointAddress;
+    constructor(bundlerUrl, entryPointAddress) {
+        this.entryPointAddress = entryPointAddress;
+        this.provider = new ethers.JsonRpcProvider(bundlerUrl);
+    }
+    async getPaymasterData(rawUserOp, usePaymaster, safeNotDeployed) {
+        // TODO: Keep this option out of the bundler
+        if (usePaymaster) {
+            console.log("Requesting paymaster data...");
+            const data = this.provider.send("pm_sponsorUserOperation", [
+                { ...rawUserOp, signature: PLACEHOLDER_SIG },
+                this.entryPointAddress,
+            ]);
+            return data;
+        }
+        return defaultPaymasterData(safeNotDeployed);
+    }
+    async sendUserOperation(userOp) {
+        try {
+            const userOpHash = await this.provider.send("eth_sendUserOperation", [
+                userOp,
+                this.entryPointAddress,
+            ]);
+            return userOpHash;
+        }
+        catch (err) {
+            const error = err.error;
+            throw new Error(`Failed to send user op with: ${error.message}`);
+        }
+    }
+    async getGasPrice() {
+        return this.provider.send("pimlico_getUserOperationGasPrice", []);
+    }
+    async _getUserOpReceiptInner(userOpHash) {
+        return this.provider.send("eth_getUserOperationReceipt", [userOpHash]);
+    }
+    async getUserOpReceipt(userOpHash) {
+        let userOpReceipt = null;
+        while (!userOpReceipt) {
+            // Wait 2 seconds before checking the status again
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+            userOpReceipt = await this._getUserOpReceiptInner(userOpHash);
+        }
+        return userOpReceipt;
+    }
+}
+// TODO(bh2smith) Should probably get reasonable estimates here:
+const defaultPaymasterData = (safeNotDeployed) => {
+    return {
+        verificationGasLimit: ethers.toBeHex(safeNotDeployed ? 500000 : 100000),
+        callGasLimit: ethers.toBeHex(100000),
+        preVerificationGas: ethers.toBeHex(100000),
+    };
+};

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

@@ -0,0 +1,3 @@
+import { ethers } from "ethers";
+import { NearEthAdapter } from "near-ca";
+export declare function getNearSignature(adapter: NearEthAdapter, hash: ethers.BytesLike): Promise<string>;

package/dist/esm/lib/near.js

@@ -0,0 +1,11 @@
+import { ethers } from "ethers";
+export async function getNearSignature(adapter, hash) {
+    const viemHash = typeof hash === "string" ? hash : hash;
+    // MPC Contract produces two possible signatures.
+    const signature = await adapter.sign(viemHash);
+    if (ethers.recoverAddress(hash, signature).toLocaleLowerCase() ===
+        adapter.address.toLocaleLowerCase()) {
+        return signature;
+    }
+    throw new Error("Invalid signature!");
+}

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

@@ -0,0 +1,24 @@
+import { ethers } from "ethers";
+import { GasPrice, PaymasterData, UnsignedUserOperation, UserOperation } from "../types";
+import { MetaTransaction } from "ethers-multisend";
+/**
+ * All contracts used in account creation & execution
+ */
+export declare class ContractSuite {
+    provider: ethers.JsonRpcProvider;
+    singleton: ethers.Contract;
+    proxyFactory: ethers.Contract;
+    m4337: ethers.Contract;
+    moduleSetup: ethers.Contract;
+    entryPoint: ethers.Contract;
+    constructor(provider: ethers.JsonRpcProvider, singleton: ethers.Contract, proxyFactory: ethers.Contract, m4337: ethers.Contract, moduleSetup: ethers.Contract, entryPoint: ethers.Contract);
+    static init(provider: ethers.JsonRpcProvider): Promise<ContractSuite>;
+    addressForSetup(setup: ethers.BytesLike, saltNonce?: string): Promise<string>;
+    getSetup(owners: string[]): Promise<string>;
+    getOpHash(unsignedUserOp: UserOperation, paymasterData: PaymasterData): Promise<string>;
+    factoryDataForSetup(safeNotDeployed: boolean, setup: string, safeSaltNonce: string): {
+        factory?: ethers.AddressLike;
+        factoryData?: string;
+    };
+    buildUserOp(txData: MetaTransaction, safeAddress: ethers.AddressLike, feeData: GasPrice, setup: string, safeNotDeployed: boolean, safeSaltNonce: string): Promise<UnsignedUserOperation>;
+}

package/dist/esm/lib/safe.js

@@ -0,0 +1,108 @@
+import { ethers } from "ethers";
+import { getProxyFactoryDeployment, getSafeL2SingletonDeployment, } from "@safe-global/safe-deployments";
+import { getSafe4337ModuleDeployment, getSafeModuleSetupDeployment, } from "@safe-global/safe-modules-deployments";
+import { PLACEHOLDER_SIG, packGas, packPaymasterData } from "../util";
+/**
+ * All contracts used in account creation & execution
+ */
+export class ContractSuite {
+    provider;
+    singleton;
+    proxyFactory;
+    m4337;
+    moduleSetup;
+    entryPoint;
+    constructor(provider, singleton, proxyFactory, m4337, moduleSetup, entryPoint) {
+        this.provider = provider;
+        this.singleton = singleton;
+        this.proxyFactory = proxyFactory;
+        this.m4337 = m4337;
+        this.moduleSetup = moduleSetup;
+        this.entryPoint = entryPoint;
+    }
+    static async init(provider) {
+        const safeDeployment = (fn) => getDeployment(fn, { provider, version: "1.4.1" });
+        const m4337Deployment = (fn) => getDeployment(fn, { provider, version: "0.3.0" });
+        // Need this first to get entryPoint address
+        const m4337 = await m4337Deployment(getSafe4337ModuleDeployment);
+        const [singleton, proxyFactory, moduleSetup, supportedEntryPoint] = await Promise.all([
+            safeDeployment(getSafeL2SingletonDeployment),
+            safeDeployment(getProxyFactoryDeployment),
+            m4337Deployment(getSafeModuleSetupDeployment),
+            m4337.SUPPORTED_ENTRYPOINT(),
+        ]);
+        const entryPoint = new ethers.Contract(supportedEntryPoint, ["function getNonce(address, uint192 key) view returns (uint256 nonce)"], provider);
+        return new ContractSuite(provider, singleton, proxyFactory, m4337, moduleSetup, entryPoint);
+    }
+    async addressForSetup(setup, saltNonce) {
+        // bytes32 salt = keccak256(abi.encodePacked(keccak256(initializer), saltNonce));
+        // cf: https://github.com/safe-global/safe-smart-account/blob/499b17ad0191b575fcadc5cb5b8e3faeae5391ae/contracts/proxies/SafeProxyFactory.sol#L58
+        const salt = ethers.keccak256(ethers.solidityPacked(["bytes32", "uint256"], [ethers.keccak256(setup), saltNonce || 0]));
+        // abi.encodePacked(type(SafeProxy).creationCode, uint256(uint160(_singleton)));
+        // cf: https://github.com/safe-global/safe-smart-account/blob/499b17ad0191b575fcadc5cb5b8e3faeae5391ae/contracts/proxies/SafeProxyFactory.sol#L29
+        const initCode = ethers.solidityPacked(["bytes", "uint256"], [
+            await this.proxyFactory.proxyCreationCode(),
+            await this.singleton.getAddress(),
+        ]);
+        return ethers.getCreate2Address(await this.proxyFactory.getAddress(), salt, ethers.keccak256(initCode));
+    }
+    async getSetup(owners) {
+        const setup = await this.singleton.interface.encodeFunctionData("setup", [
+            owners,
+            1, // We use sign threshold of 1.
+            this.moduleSetup.target,
+            this.moduleSetup.interface.encodeFunctionData("enableModules", [
+                [this.m4337.target],
+            ]),
+            this.m4337.target,
+            ethers.ZeroAddress,
+            0,
+            ethers.ZeroAddress,
+        ]);
+        return setup;
+    }
+    async getOpHash(unsignedUserOp, paymasterData) {
+        return this.m4337.getOperationHash({
+            ...unsignedUserOp,
+            initCode: unsignedUserOp.factory
+                ? ethers.solidityPacked(["address", "bytes"], [unsignedUserOp.factory, unsignedUserOp.factoryData])
+                : "0x",
+            accountGasLimits: packGas(unsignedUserOp.verificationGasLimit, unsignedUserOp.callGasLimit),
+            gasFees: packGas(unsignedUserOp.maxPriorityFeePerGas, unsignedUserOp.maxFeePerGas),
+            paymasterAndData: packPaymasterData(paymasterData),
+            signature: PLACEHOLDER_SIG,
+        });
+    }
+    factoryDataForSetup(safeNotDeployed, setup, safeSaltNonce) {
+        return safeNotDeployed
+            ? {
+                factory: this.proxyFactory.target,
+                factoryData: this.proxyFactory.interface.encodeFunctionData("createProxyWithNonce", [this.singleton.target, setup, safeSaltNonce]),
+            }
+            : {};
+    }
+    async buildUserOp(txData, safeAddress, feeData, setup, safeNotDeployed, safeSaltNonce) {
+        const rawUserOp = {
+            sender: safeAddress,
+            nonce: ethers.toBeHex(await this.entryPoint.getNonce(safeAddress, 0)),
+            ...this.factoryDataForSetup(safeNotDeployed, setup, safeSaltNonce),
+            // <https://github.com/safe-global/safe-modules/blob/9a18245f546bf2a8ed9bdc2b04aae44f949ec7a0/modules/4337/contracts/Safe4337Module.sol#L172>
+            callData: this.m4337.interface.encodeFunctionData("executeUserOp", [
+                txData.to,
+                BigInt(txData.value),
+                txData.data,
+                txData.operation || 0,
+            ]),
+            ...feeData,
+        };
+        return rawUserOp;
+    }
+}
+async function getDeployment(fn, { provider, version }) {
+    const { chainId } = await provider.getNetwork();
+    const deployment = fn({ version });
+    if (!deployment || !deployment.networkAddresses[`${chainId}`]) {
+        throw new Error(`Deployment not found for version ${version} and chainId ${chainId}`);
+    }
+    return new ethers.Contract(deployment.networkAddresses[`${chainId}`], deployment.abi, provider);
+}

package/dist/esm/tx-manager.d.ts

@@ -0,0 +1,39 @@
+import { ethers } from "ethers";
+import { NearEthAdapter } from "near-ca";
+import { Erc4337Bundler } from "./lib/bundler";
+import { UserOperation, UserOperationReceipt, UserOptions } from "./types";
+import { MetaTransaction } from "ethers-multisend";
+import { ContractSuite } from "./lib/safe";
+import { Account } from "near-api-js";
+export declare class TransactionManager {
+    readonly provider: ethers.JsonRpcProvider;
+    readonly nearAdapter: NearEthAdapter;
+    private safePack;
+    private bundler;
+    private setup;
+    readonly safeAddress: string;
+    private safeSaltNonce;
+    private _safeNotDeployed;
+    constructor(provider: ethers.JsonRpcProvider, nearAdapter: NearEthAdapter, safePack: ContractSuite, bundler: Erc4337Bundler, setup: string, safeAddress: string, safeSaltNonce: string, safeNotDeployed: boolean);
+    static create(config: {
+        ethRpc: string;
+        erc4337BundlerUrl: string;
+        nearAccount: Account;
+        mpcContractId: string;
+        safeSaltNonce?: string;
+    }): Promise<TransactionManager>;
+    get safeNotDeployed(): boolean;
+    get nearEOA(): `0x${string}`;
+    getSafeBalance(): Promise<bigint>;
+    buildTransaction(args: {
+        transactions: MetaTransaction[];
+        options: UserOptions;
+    }): Promise<{
+        safeOpHash: string;
+        unsignedUserOp: UserOperation;
+    }>;
+    signTransaction(safeOpHash: string): Promise<string>;
+    executeTransaction(userOp: UserOperation): Promise<UserOperationReceipt>;
+    addOwnerTx(address: string): MetaTransaction;
+    safeSufficientlyFunded(transactions: MetaTransaction[], gasCost: bigint): Promise<boolean>;
+}

package/dist/esm/tx-manager.js

@@ -0,0 +1,99 @@
+import { ethers } from "ethers";
+import { NearEthAdapter, MpcContract } from "near-ca";
+import { Erc4337Bundler } from "./lib/bundler";
+import { packSignature } from "./util";
+import { getNearSignature } from "./lib/near";
+import { encodeMulti } from "ethers-multisend";
+import { ContractSuite } from "./lib/safe";
+export class TransactionManager {
+    provider;
+    nearAdapter;
+    safePack;
+    bundler;
+    setup;
+    safeAddress;
+    safeSaltNonce;
+    _safeNotDeployed;
+    constructor(provider, nearAdapter, safePack, bundler, setup, safeAddress, safeSaltNonce, safeNotDeployed) {
+        this.provider = provider;
+        this.nearAdapter = nearAdapter;
+        this.safePack = safePack;
+        this.bundler = bundler;
+        this.setup = setup;
+        this.safeAddress = safeAddress;
+        this.safeSaltNonce = safeSaltNonce;
+        this._safeNotDeployed = safeNotDeployed;
+    }
+    static async create(config) {
+        const provider = new ethers.JsonRpcProvider(config.ethRpc);
+        const [nearAdapter, safePack] = await Promise.all([
+            NearEthAdapter.fromConfig({
+                mpcContract: new MpcContract(config.nearAccount, config.mpcContractId),
+            }),
+            ContractSuite.init(provider),
+        ]);
+        console.log(`Near Adapter: ${nearAdapter.nearAccountId()} <> ${nearAdapter.address}`);
+        const bundler = new Erc4337Bundler(config.erc4337BundlerUrl, await safePack.entryPoint.getAddress());
+        const setup = await safePack.getSetup([nearAdapter.address]);
+        const safeAddress = await safePack.addressForSetup(setup, config.safeSaltNonce);
+        const safeNotDeployed = (await provider.getCode(safeAddress)) === "0x";
+        console.log(`Safe Address: ${safeAddress} - deployed? ${!safeNotDeployed}`);
+        return new TransactionManager(provider, nearAdapter, safePack, bundler, setup, safeAddress, config.safeSaltNonce || "0", safeNotDeployed);
+    }
+    get safeNotDeployed() {
+        return this._safeNotDeployed;
+    }
+    get nearEOA() {
+        return this.nearAdapter.address;
+    }
+    async getSafeBalance() {
+        return await this.provider.getBalance(this.safeAddress);
+    }
+    async buildTransaction(args) {
+        const { transactions, options } = args;
+        const gasFees = (await this.bundler.getGasPrice()).fast;
+        // const gasFees = await this.provider.getFeeData();
+        // Build Singular MetaTransaction for Multisend from transaction list.
+        if (transactions.length === 0) {
+            throw new Error("Empty transaction set!");
+        }
+        const tx = transactions.length > 1 ? encodeMulti(transactions) : transactions[0];
+        const rawUserOp = await this.safePack.buildUserOp(tx, this.safeAddress, gasFees, this.setup, this.safeNotDeployed, this.safeSaltNonce);
+        const paymasterData = await this.bundler.getPaymasterData(rawUserOp, options.usePaymaster, this.safeNotDeployed);
+        const unsignedUserOp = { ...rawUserOp, ...paymasterData };
+        const safeOpHash = await this.safePack.getOpHash(unsignedUserOp, paymasterData);
+        return {
+            safeOpHash,
+            unsignedUserOp,
+        };
+    }
+    async signTransaction(safeOpHash) {
+        const signature = await getNearSignature(this.nearAdapter, safeOpHash);
+        return packSignature(signature);
+    }
+    async executeTransaction(userOp) {
+        const userOpHash = await this.bundler.sendUserOperation(userOp);
+        console.log("UserOp Hash", userOpHash);
+        const userOpReceipt = await this.bundler.getUserOpReceipt(userOpHash);
+        console.log("userOp Receipt", userOpReceipt);
+        // Update safeNotDeployed after the first transaction
+        this._safeNotDeployed =
+            (await this.provider.getCode(this.safeAddress)) === "0x";
+        return userOpReceipt;
+    }
+    addOwnerTx(address) {
+        return {
+            to: this.safeAddress,
+            value: "0",
+            data: this.safePack.singleton.interface.encodeFunctionData("addOwnerWithThreshold", [address, 1]),
+        };
+    }
+    async safeSufficientlyFunded(transactions, gasCost) {
+        const txValue = transactions.reduce((acc, tx) => acc + BigInt(tx.value), 0n);
+        if (txValue + gasCost === 0n) {
+            return true;
+        }
+        const safeBalance = await this.getSafeBalance();
+        return txValue + gasCost < safeBalance;
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,85 @@
+import { ethers } from "ethers";
+export interface UnsignedUserOperation {
+    sender: ethers.AddressLike;
+    nonce: string;
+    factory?: ethers.AddressLike;
+    factoryData?: ethers.BytesLike;
+    callData: string;
+    maxPriorityFeePerGas: string;
+    maxFeePerGas: string;
+}
+/**
+ * Supported Representation of UserOperation for EntryPoint v0.7
+ */
+export interface UserOperation extends UnsignedUserOperation {
+    verificationGasLimit: string;
+    callGasLimit: string;
+    preVerificationGas: string;
+    signature?: string;
+}
+export interface PaymasterData {
+    paymaster?: string;
+    paymasterData?: string;
+    paymasterVerificationGasLimit?: string;
+    paymasterPostOpGasLimit?: string;
+    verificationGasLimit: string;
+    callGasLimit: string;
+    preVerificationGas: string;
+}
+export interface UserOptions {
+    usePaymaster: boolean;
+    safeSaltNonce: string;
+    mpcContractId: string;
+    recoveryAddress?: string;
+}
+export type TStatus = "success" | "reverted";
+export type Address = ethers.AddressLike;
+export type Hex = `0x${string}`;
+export type Hash = `0x${string}`;
+interface Log {
+    logIndex: string;
+    transactionIndex: string;
+    transactionHash: string;
+    blockHash: string;
+    blockNumber: string;
+    address: string;
+    data: string;
+    topics: string[];
+}
+interface Receipt {
+    transactionHash: Hex;
+    transactionIndex: bigint;
+    blockHash: Hash;
+    blockNumber: bigint;
+    from: Address;
+    to: Address | null;
+    cumulativeGasUsed: bigint;
+    status: TStatus;
+    gasUsed: bigint;
+    contractAddress: Address | null;
+    logsBloom: Hex;
+    effectiveGasPrice: bigint;
+}
+export type UserOperationReceipt = {
+    userOpHash: Hash;
+    entryPoint: Address;
+    sender: Address;
+    nonce: bigint;
+    paymaster?: Address;
+    actualGasUsed: bigint;
+    actualGasCost: bigint;
+    success: boolean;
+    reason?: string;
+    receipt: Receipt;
+    logs: Log[];
+};
+export interface GasPrices {
+    slow: GasPrice;
+    standard: GasPrice;
+    fast: GasPrice;
+}
+export interface GasPrice {
+    maxFeePerGas: Hex;
+    maxPriorityFeePerGas: Hex;
+}
+export {};

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/util.d.ts

@@ -0,0 +1,8 @@
+import { ethers } from "ethers";
+import { PaymasterData } from "./types";
+import { MetaTransaction } from "ethers-multisend";
+export declare const PLACEHOLDER_SIG: string;
+export declare const packGas: (hi: ethers.BigNumberish, lo: ethers.BigNumberish) => string;
+export declare function packSignature(signature: string, validFrom?: number, validTo?: number): string;
+export declare function packPaymasterData(data: PaymasterData): string;
+export declare function containsValue(transactions: MetaTransaction[]): boolean;

package/dist/esm/util.js

@@ -0,0 +1,19 @@
+import { ethers } from "ethers";
+export const PLACEHOLDER_SIG = ethers.solidityPacked(["uint48", "uint48"], [0, 0]);
+export const packGas = (hi, lo) => ethers.solidityPacked(["uint128", "uint128"], [hi, lo]);
+export function packSignature(signature, validFrom = 0, validTo = 0) {
+    return ethers.solidityPacked(["uint48", "uint48", "bytes"], [validFrom, validTo, signature]);
+}
+export function packPaymasterData(data) {
+    return data.paymaster
+        ? ethers.hexlify(ethers.concat([
+            data.paymaster,
+            ethers.toBeHex(data.paymasterVerificationGasLimit || "0x", 16),
+            ethers.toBeHex(data.paymasterPostOpGasLimit || "0x", 16),
+            data.paymasterData || "0x",
+        ]))
+        : "0x";
+}
+export function containsValue(transactions) {
+    return transactions.some((tx) => tx.value !== "0");
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "near-safe",
+  "version": "0.0.0",
+  "license": "MIT",
+  "main": "dist/cjs/index.js",
+  "module": "dist/cjs/index.js",
+  "types": "dist/esm/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "rm -fr dist/* && yarn build:esm && yarn build:cjs",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "start": "yarn example",
+    "example": "tsx examples/send-tx.ts",
+    "lint": "eslint . --ignore-pattern dist/",
+    "fmt": "prettier --write '{src,examples,tests}/**/*.{js,jsx,ts,tsx}'",
+    "all": "yarn fmt && yarn lint && yarn build"
+  },
+  "dependencies": {
+    "@safe-global/safe-deployments": "^1.37.0",
+    "@safe-global/safe-modules-deployments": "^2.2.0",
+    "ethers": "^6.13.1",
+    "ethers-multisend": "^3.1.0",
+    "near-api-js": "^4.0.3",
+    "near-ca": "^0.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.3.0",
+    "@types/yargs": "^17.0.32",
+    "@typescript-eslint/eslint-plugin": "^8.1.0",
+    "@typescript-eslint/parser": "^8.1.0",
+    "dotenv": "^16.4.5",
+    "eslint": "^9.6.0",
+    "prettier": "^3.3.2",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.2",
+    "yargs": "^17.7.2"
+  }
+}