{"_id":"@defi-wonderland/hardhat-account-abstraction","_rev":"5-6902fd9c3d3c819b73d5fb15e9831edc","name":"@defi-wonderland/hardhat-account-abstraction","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@defi-wonderland/hardhat-account-abstraction","version":"1.0.0","keywords":["ethereum","smart-contracts","sponsored-txs","hardhat","hardhat-plugin"],"author":{"name":"Wonderland"},"license":"MIT","_id":"@defi-wonderland/hardhat-account-abstraction@1.0.0","maintainers":[{"name":"wonderland-bot","email":"wonderland@defi.sucks"},{"name":"gas1cent","email":"gas1cent@defi.sucks"},{"name":"0xng","email":"ng@defi.sucks"},{"name":"0xgorilla","email":"0xGorilla@defi.sucks"},{"name":"kelvinfichter","email":"kelvinfichter@gmail.com"},{"name":"wei3erhase","email":"wei3erhase@defi.sucks"},{"name":"enderman0x","email":"enderman0x@defi.sucks"}],"dist":{"shasum":"a6f6cf77e72ea88d6b7a37957a08cd5b272815a7","tarball":"https://registry.npmjs.org/@defi-wonderland/hardhat-account-abstraction/-/hardhat-account-abstraction-1.0.0.tgz","fileCount":97,"integrity":"sha512-DmHw1+CPz4wZo860gPrlnVku8LwiW/qmoiA9RURv5g/0PfIlcwyVhirXY6dSClnKf6qsAtqQVivKG5INMVRwyQ==","signatures":[{"sig":"MEUCIA9A8YxwafZTtvjwLvFlEqVLpRbZLAwwSKw4u6DTIas+AiEAkBTutfFKzLX0/ETjdc63umgfQH1OMfU2idflYlQjVjY=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":230665},"main":"dist/src/index.js","types":"dist/src/index.d.ts","scripts":{"lint":"yarn lint:src && yarn lint:test","test":"mocha --exit --recursive 'test/**/*.test.ts'","build":"forge compile && tsc","watch":"tsc -w","format":"yarn run prettier:fix && yarn run lint:fix","prepare":"husky install","lint:fix":"yarn lint:src --fix && yarn lint:test --fix && forge fmt","lint:src":"eslint ./src","prettier":"prettier src test --check","lint:test":"eslint ./test","test:unit":"mocha --exit --recursive 'test/unit/**/*.test.ts'","prettier:fix":"yarn run prettier -- --write","prepublishOnly":"npm run build","test:integration":"mocha --exit --recursive 'test/integration/**/*.test.ts'"},"_npmUser":{"name":"wonderland-bot","email":"wonderland@defi.sucks"},"repository":{"url":"https://github.com/defi-wonderland/hardhat-account-abstraction.git","type":"git"},"description":"Hardhat TypeScript plugin for Account Abstraction","directories":{},"licenseText":"The MIT License (MIT)\nCopyright © 2024 Wonder Ltd\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n  \n  ","lint-staged":{"*.ts":"eslint --cache --fix","src/**/*.{js,ts,md}":"yarn run prettier:fix"},"dependencies":{"viem":"1.20.3","axios":"1.6.7","debug":"4.3.4","ethers":"6.9.0","permissionless":"0.0.16"},"_hasShrinkwrap":false,"devDependencies":{"chai":"4.3.10","husky":"8.0.3","mocha":"10.2.0","sinon":"15.2.0","dotenv":"16.4.1","eslint":"8.34.0","hardhat":"2.19.0","ts-node":"10.9.1","prettier":"3.1.0","typescript":"5.0.4","@types/chai":"4.3.11","lint-staged":"13.2.2","@types/debug":"4.1.12","@types/mocha":"5.2.6","@types/sinon":"10.0.15","eslint-config-prettier":"9.0.0","eslint-plugin-prettier":"5.0.1","@typescript-eslint/parser":"5.59.6","@nomicfoundation/hardhat-ethers":"3.0.5","@typescript-eslint/eslint-plugin":"5.59.6"},"peerDependencies":{"hardhat":"2.19.5"},"_npmOperationalInternal":{"tmp":"tmp/hardhat-account-abstraction_1.0.0_1707401868577_0.19873310141620926","host":"s3://npm-registry-packages"}}},"time":{"created":"2024-02-08T14:17:48.493Z","modified":"2025-07-25T08:28:19.352Z","1.0.0":"2024-02-08T14:17:48.747Z"},"author":{"name":"Wonderland"},"license":"MIT","keywords":["ethereum","smart-contracts","sponsored-txs","hardhat","hardhat-plugin"],"repository":{"url":"https://github.com/defi-wonderland/hardhat-account-abstraction.git","type":"git"},"description":"Hardhat TypeScript plugin for Account Abstraction","maintainers":[{"email":"gori@wonderland.xyz","name":"0xgorilla"},{"email":"alice@wonderland.xyz","name":"wonderland-bot"},{"email":"turtlemoji@protonmail.com","name":"turtlemoji"}],"readme":"# Hardhat Account Abstraction\n\nA plugin to send sponsored transactions utilizing account abstraction!\n\n\n## What\n\nThis plugin sponsors any transaction the user sends through the power of account abstraction. Through seemless integration after the configuration is set just submit any transaction, and you can see it get mined on the testnets without costing the signer any gas! \n\n## Installation\n\n\n```bash\nyarn install @defi-wonderland/hardhat-account-abstraction\n```\n\nImport the plugin in your `hardhat.config.js`:\n\n```js\nrequire(\"@defi-wonderland/hardhat-account-abstraction\");\n```\n\nOr if you are using TypeScript, in your `hardhat.config.ts`:\n\n```ts\nimport \"@defi-wonderland/hardhat-account-abstraction\";\n```\n\n\n## Required plugins\n\n> **NOTE: Only one of these packages is needed depending on what you are writing your scripts in**\n\n<br>\n\n- [@nomicfoundation/hardhat-ethers](https://github.com/NomicFoundation/hardhat/tree/main/packages/hardhat-ethers)\n- [@nomicfoundation/hardhat-viem](https://github.com/NomicFoundation/hardhat/tree/main/packages/hardhat-viem)\n\n## Tasks\n\n\nThis plugin creates no additional tasks.\n\n\n## Environment extensions\n\nThis plugin does not extend the hardhat runtime environment\n\n## Configuration\n> **NOTE: Currently the plugin will only use the first private key in `accounts`**\n\nThis plugin requires 2 new fields inside an `accountAbstraction` object which will be nested inside each hardhat network that is set in the config\n\nThis is an example of how to set it:\n\n```ts\nconst config: HardhatUserConfig = {\n  solidity: '0.8.19',\n  defaultNetwork: 'goerli',\n  networks: {\n    goerli: {\n      url: process.env.GOERLI_RPC_URL as string,\n      accounts: [process.env.PRIVATE_KEY as string],\n      accountAbstraction: {\n        bundlerUrl: 'https://example.com',\n        paymasterUrl: 'https://example.com',\n      }\n    }\n  }\n};\n```\n\n### Options\n\n| Option                         | Description                                                                                          | Required | Default                                     |\n| ------------------------------ | ---------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------  |\n| `bundlerUrl`                   | The bundler that the UserOperations will be sent to                                                  | Yes      | No default                                  |\n| `paymasterUrl`                 | The paymaster API that will be used for sponsoring transactions                                      | Yes      | No default                                  |\n| `simpleAccountFactoryAddress`  | The simple account factory address you want to use                                                   | No       | 0x9406cc6185a346906296840746125a0e44976454  |\n| `smartAccount`                 | Address of a smart account to use in your scripts                                                    | No       | Will deploy one for you                     |\n| `policyId`                     | The policy id to use if your paymaster has one                                                       | No       | No default                                  | \n\n### Supported Paymaster Types\n\nThe list of paymasters we currently support\n\n1. Pimlico\n1. Stackup\n1. Alchemy\n1. Base\n\n\nIf you would like to add support for a new paymaster check out the [contributors guide](./CONTRIBUTORS.md#adding-a-new-paymaster-to-the-plugin)\n\n### Supported Chains\n\n#### For a chain to be supported the conditions are:\n\n1. The SimpleAccount Factory is deployed to the address `0x9406cc6185a346906296840746125a0e44976454` or alternatively entered as an optional parameter in the config\n1. The [CreateXFactory](https://github.com/pcaversaccio/createx) needs to be deployed to its standard address\n<br>\n#### Currently the list of supported chains is, but not limited to the following:\n\n1. Ethereum Sepolia\n1. Ethereum Goerli\n1. Polygon Mumbai\n1. Base Goerli\n1. Optimism Goerli\n1. Arbitrum Goerli\n\n## Usage\n\n> **⚠ WARNING: Any non-zero msg.value call will not work as intended as paymaster's dont sponsor this value, in order to use native transfers or interact with payable functions you will need the native token of your chain in the smart account wallet beforehand**\n\nAfter you have setup the configuration for the `accountAbstraction` and you are using a network that has them enable you are good to go, you can right a simple script below and your transactions will be mined on the testnet that you have configured!\n\n```js\nconst signer = await ethers.provider.getSigner();\nconst testToken = new ethers.Contract('0x16F63C5036d3F48A239358656a8f123eCE85789C', TEST_TOKEN_ABI, signer);\nconst amountToMint = ethers.parseEther('6.9');\nawait testToken.mint(amountToMint);\n```\n\n## Deploying Contracts\n\nDeploying contracts works just as any other transaction would, however due to the nature of account abstraction we deploy all contracts through the `CreateXFactory`, The `CreateXFactory` is deployed on **most** EVM compatible chains, if you would like to learn more about it or deploy it to your new chain you can do so by checking out [their repo](https://github.com/pcaversaccio/createx)\n\n### What are the differences?\n\n- **Ownable contracts**\n\n    We do support ownable contracts and the default `owner` of your contract will be the smart account you deployed with, the only condition is you must have a `transferOwnership(address)` function to make this work, if you have a custom implementation of `Ownable` and dont instantiate `owner` as `msg.sender` in the constructor it will also work.\n\n- **Contract addresses in scripts**\n\n    Scripting with deployed contracts works pretty much out of the box with one caveat, the address that ethers provides for your address is wrong. This is because ethers predicts the deployment address by the default `CREATE` opcode standards which takes the transaction's `from` and `nonce` values, these values do not match that of our middlewares deployment so we expose a [custom method to get this address](#aa_getdeploymentfor). This issue is only present with libraries that hardcode the predicted address such as ethers. Other libraries use the receipt to retrieve the contract address such as viem, for those libraries the address returned will be correct as we modify the receipts in our middleware.\n\n    <br>\n\n    Scripting will work as expected even with this incorrect address param, this is because our middleware overwrites any transaction being sent to the incorrect predicted address and routes it to the address we deployed. As you can see from this example below.\n\n  ```js\n  const lock = await ethers.getContractFactory('Lock');\n\n  const lockContract = await lock.deploy();\n\n  const originalOwner = await lockContract.owner();\n\n  console.log('Original owner set to: ', originalOwner); // Logs the smart account address\n\n  await lockContract.transferOwnership(\"0xEB7cFd33CfEfFf98EF067F501B81D31C9a7077C3\");\n\n  const newOwner = await lockContract.owner();\n\n  console.log('New owner set to: ', newOwner); // Logs the 0xEB7... address\n  ```\n  <br>\n\n  However it is very important to remember that `lockContract` has the wrong address, however using the address the contract computes will work as a parameter as you can see below\n\n  <br>\n\n  ```js\n  const lock = await ethers.getContractFactory('Lock');\n  const lockContract = await lock.deploy();\n  \n  console.log(lockContract.target); // Wrong address\n\n  const lockContractAddress = await network.provider.request({\n    method: 'aa_getDeploymentFor',\n    params: [lockContract.target]\n  });\n\n  console.log(lockContractAddress) // Correct address\n\n  lockContract.randomFunctionWithAddressAsParam(lockContract.target) // Will use the correct address\n  ```\n\n## Custom JSON API methods\n\nThis plugin adds additional JSON-RPC methods to be able to interact and get data from our custom provider middleware.\n\n### `aa_getSmartAccountAddress`\n\n**Description:** Returns the address for the smart account that is being used by the provider.\n  - Example: \n  ```js\n  const smartAccountAddress = await network.provider.request({\n      method: 'aa_getSmartAccountAddress',\n      params: [],\n    });\n    console.log(`Smart account address: ${smartAccountAddress}`);\n  ```\n\n### `aa_getDeploymentFor`: \n\n**Description:** Returns the address of which a contract was deployed through our middleware, [to learn more about why this is needed click here](#deploying-contracts)\n  - Parameters:\n    - `contract: 0x${string}`: The contract address that you want to check the deployment for\n  - Example:\n  ```js\n  const lock = await ethers.getContractFactory('Lock');\n  const lockContract = await lock.deploy();\n\n  const lockContractAddress = await network.provider.request({\n    method: 'aa_getDeploymentFor',\n    params: [lockContract.target] \n  });\n  ```\n\n\n## Contributors\n\nIf you want to learn how to add support for your own paymaster implementation checkout our guide [here](./CONTRIBUTORS.md#adding-a-new-paymaster-to-the-plugin) to learn how to add it to the plugin!\n\n<br>\n\nHardhat Account Abstraction was built with ❤️ by [Wonderland](https://defi.sucks).\n\nWonderland the largest core development group in web3. Our commit ment is to a financial future that's open, decentralized, and accessible to all.\n\n[DeFi sucks](https://defi.sucks), but Wonderland is here to make it better.\n\n## Licensing\n\nThe primary license for Hardhat Account Abstraction is MIT, see [`LICENSE`](./LICENSE).","readmeFilename":"README.md"}