Skip to content

Commit 4a8663b

Browse files
jdevcsjdevcs
authored
read me doc (#6)
1 parent 38c350c commit 4a8663b

File tree

1 file changed

+305
-18
lines changed

1 file changed

+305
-18
lines changed

‎README.md‎

Lines changed: 305 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,322 @@
11
# Web3.js EIP4337 Plugin
22

3-
This plugin is developed and maintained by [Blocto](https://blocto.io/) .
3+
( This plugin is developed and maintained by [Blocto](https://blocto.io/) ).
4+
5+
Web3.js EIP4337 is a [web3.js](https://github.com/web3/web3.js) `4.x` plugin for Account Abstraction functionality.
6+
7+
8+
```ts
9+
import { Web3 } from 'web3';
10+
import { EIP4337Plugin } from 'web3-plugin-eip4337';
11+
12+
const web3 = new Web3('http://127.0.0.1:8545');
13+
web3.registerPlugin(new EIP4337Plugin());
14+
15+
web3.EIP4337.sendUserOperation('...');
16+
```
17+
18+
## Functionality
19+
20+
### sendUserOperation
21+
Sends a UserOperation to the bundler. If accepted, the bundler will add it to the UserOperation mempool and return a userOpHash.
22+
23+
#### Parameters
24+
- `UserOperation` - represents the structure of a transaction initiated by the user. It contains the sender, receiver, call data, maximum fee per unit of Gas, maximum priority fee, signature, nonce, and other specific elements.
25+
26+
- `entryPoint` - a singleton contract to execute bundles of UserOperations. Bundlers/Clients whitelist the supported entrypoint.
27+
28+
#### Returns
29+
- userOperation hash or throws error instead of balance.
30+
31+
#### Example
32+
```ts
33+
web3.EIP4337.sendUserOperation({
34+
sender: "0x9fd042a18e90ce326073fa70f111dc9d798d9a52",
35+
nonce: "123",
36+
initCode: "0x68656c6c6f",
37+
callData: "0x776F726C64",
38+
callGasLimit: "1000",
39+
verificationGasLimit: "2300",
40+
preVerificationGas: "3100",
41+
maxFeePerGas: "8500",
42+
maxPriorityFeePerGas: "1",
43+
paymasterAndData: "0x626c6f63746f",
44+
signature: "0x636c656d656e74"
45+
},"0x636c656d656e74").then(console.log);
46+
> 0xe554d0701f7fdc734f84927d109537f1ac4ee4ebfa3670c71d224a4fa15dbcd1
47+
```
48+
49+
### estimateUserOperationGas
50+
Estimate the gas values for a UserOperation. Given UserOperation optionally without gas limits and gas prices, return the needed gas limits. The signature field is ignored by the wallet, so that the operation will not require user's approval. Still, it might require putting a "semi-valid" signature (e.g. a signature in the right length)
51+
52+
#### Parameters
53+
- `UserOperation` - represents the structure of a transaction initiated by the user. It contains the sender, receiver, call data, maximum fee per unit of Gas, maximum priority fee, signature, nonce, and other specific elements.
54+
55+
- `entryPoint` - a singleton contract to execute bundles of UserOperations. Bundlers/Clients whitelist the supported entrypoint.
56+
57+
#### Returns
58+
- Object having:
59+
- `preVerificationGas` gas overhead of this UserOperation
60+
- `verificationGasLimit` actual gas used by the validation of this UserOperation
61+
- `callGasLimit` value used by inner account execution
62+
63+
#### Example
64+
```ts
65+
web3.EIP4337.estimateUserOperationGas({
66+
sender: "0x9fd042a18e90ce326073fa70f111dc9d798d9a52",
67+
nonce: "123",
68+
initCode: "0x68656c6c6f",
69+
callData: "0x776F726C64",
70+
callGasLimit: "1000",
71+
verificationGasLimit: "2300",
72+
preVerificationGas: "3100",
73+
maxFeePerGas: "0",
74+
maxPriorityFeePerGas: "0",
75+
paymasterAndData: "0x626c6f63746f",
76+
signature: "0x636c656d656e74"
77+
},"0x636c656d656e74").then(console.log);
78+
> {
79+
callGasLimit : "0x18b33",
80+
preVerificationGas: "0xdf17",
81+
verificationGasLimit:"0x128c4"
82+
}
83+
```
84+
85+
### getUserOperationByHash
86+
Return a UserOperation based on a hash (userOpHash) returned by eth_sendUserOperation
87+
88+
#### Parameters
89+
- `hash` - a userOpHash value returned by `eth_sendUserOperation`
90+
91+
#### Returns
92+
- Null in case the UserOperation is not yet included in a block, or a full UserOperation, with the addition of entryPoint, blockNumber, blockHash and transactionHash
93+
94+
#### Example
95+
```ts
96+
web3.EIP4337.getUserOperationByHash("0xxxxx").then(console.log);
97+
> {
98+
userOperation: {
99+
sender: "xxxx",
100+
nonce: "xxxx",
101+
initCode: "0xxxxxxxxxxxxxxx",
102+
callData: "0xxxxxxxxxxxxxxx",
103+
callGasLimit: "xxxx",
104+
verificationGasLimit: "xxxx",
105+
preVerificationGas: "xxxx",
106+
maxFeePerGas: "0",
107+
maxPriorityFeePerGas: "0",
108+
paymasterAndData: "0xxxxxxxxxxxxxxx",
109+
signature: "0xxxxxxxxxxxxxxx"
110+
},
111+
entryPoint: '0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789',
112+
blockNumber: 39642225,
113+
blockHash: '0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f',
114+
transactionHash: '0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4',
115+
}
116+
```
117+
118+
### getUserOperationReceipt
119+
Return null in case the UserOperation is not yet included in a block, or
120+
- userOpHash the request hash
121+
- entryPoint
122+
- sender
123+
- nonce
124+
- paymaster the paymaster used for this userOp (or empty)
125+
- actualGasCost - actual amount paid (by account or paymaster) for this UserOperation
126+
- actualGasUsed - total gas used by this UserOperation (including preVerification, creation, validation and execution)
127+
- success boolean - did this execution completed without revert
128+
- reason in case of revert, this is the revert reason
129+
- logs the logs generated by this UserOperation (not including logs of other UserOperations in the same bundle)
130+
- receipt the TransactionReceipt object. Note that the returned TransactionReceipt is for the entire bundle, not only for this UserOperation.
131+
132+
#### Parameters
133+
- `hash` - hash a userOpHash value returned by `eth_sendUserOperation`
134+
135+
#### Returns
136+
- Null in case the UserOperation is not yet included in a block, or UserOperation receipt
137+
138+
#### Example
139+
```ts
140+
web3.EIPI4337.getUserOperationReceipt("0xa890d7c0dccfd6cebc025919f4857ab97953ae218e82f5e24c297f02ceea5b21").then(console.log);
141+
>"userOpHash": "0xa890d7c0dccfd6cebc025919f4857ab97953ae218e82f5e24c297f02ceea5b21",
142+
"entryPoint": "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
143+
"sender": "0x026B37A09aF3ceB346c39999c5738F86A1a48f4d",
144+
"nonce": "0x7",
145+
"paymaster": "0xa312d8D37Be746BD09cBD9e9ba2ef16bc7Da48FF",
146+
"actualGasCost": "0x1a036c1638be0",
147+
"actualGasUsed": "0x2e8d8",
148+
"success": true,
149+
"reason": "",
150+
"logs": [
151+
{
152+
"address": "0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789",
153+
"topics": [
154+
"0xbb47ee3e183a558b1a2ff0874b079f3fc5478b7454eacf2bfc5af2ff5878f972"
155+
],
156+
"data": "0x",
157+
"blockHash": "0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f",
158+
"blockNumber": "0x25ce471",
159+
"transactionHash": "0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4",
160+
"transactionIndex": "0x44",
161+
"logIndex": "0x12d",
162+
"removed": false
163+
},
164+
{
165+
"address": "0xfd8ec18d48ac1f46b600e231da07d1da8209ceef",
166+
"topics": [
167+
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
168+
"0x0000000000000000000000000000000000000000000000000000000000000000",
169+
"0x000000000000000000000000026b37a09af3ceb346c39999c5738f86a1a48f4d",
170+
"0x000000000000000000000000000000000000000000000000000000000000007f"
171+
],
172+
"data": "0x",
173+
"blockHash": "0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f",
174+
"blockNumber": "0x25ce471",
175+
"transactionHash": "0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4",
176+
"transactionIndex": "0x44",
177+
"logIndex": "0x12e",
178+
"removed": false
179+
},
180+
{
181+
"address": "0x00005ea00ac477b1030ce78506496e8c2de24bf5",
182+
"topics": [
183+
"0xe90cf9cc0a552cf52ea6ff74ece0f1c8ae8cc9ad630d3181f55ac43ca076b7d6",
184+
"0x000000000000000000000000fd8ec18d48ac1f46b600e231da07d1da8209ceef",
185+
"0x000000000000000000000000026b37a09af3ceb346c39999c5738f86a1a48f4d",
186+
"0x0000000000000000000000000000a26b00c1f0df003000390027140000faa719"
187+
],
188+
"data": "0x000000000000000000000000026b37a09af3ceb346c39999c5738f86a1a48f4d0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003e80000000000000000000000000000000000000000000000000000000000000000",
189+
"blockHash": "0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f",
190+
"blockNumber": "0x25ce471",
191+
"transactionHash": "0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4",
192+
"transactionIndex": "0x44",
193+
"logIndex": "0x12f",
194+
"removed": false
195+
},
196+
{
197+
"address": "0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789",
198+
"topics": [
199+
"0x49628fd1471006c1482da88028e9ce4dbb080b815c9b0344d39e5a8e6ec1419f",
200+
"0xa890d7c0dccfd6cebc025919f4857ab97953ae218e82f5e24c297f02ceea5b21",
201+
"0x000000000000000000000000026b37a09af3ceb346c39999c5738f86a1a48f4d",
202+
"0x000000000000000000000000a312d8d37be746bd09cbd9e9ba2ef16bc7da48ff"
203+
],
204+
"data": "0x000000000000000000000000000000000000000000000000000000000000000700000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000001a036c1638be0000000000000000000000000000000000000000000000000000000000002e8d8",
205+
"blockHash": "0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f",
206+
"blockNumber": "0x25ce471",
207+
"transactionHash": "0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4",
208+
"transactionIndex": "0x44",
209+
"logIndex": "0x130",
210+
"removed": false
211+
}
212+
],
213+
"receipt": {
214+
"transactionHash": "0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4",
215+
"transactionIndex": "0x44",
216+
"blockHash": "0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f",
217+
"blockNumber": "0x25ce471",
218+
"from": "0x1e6754b227c6ae4b0ca61d82f79d60660737554a",
219+
"to": "0x5ff137d4b0fdcd49dca30c7cf57e578a026d2789",
220+
"cumulativeGasUsed": "0x1716d3b",
221+
"gasUsed": "0x2b6c6",
222+
"contractAddress": null,
223+
"logs": [
224+
{
225+
"address": "0xfd8ec18d48ac1f46b600e231da07d1da8209ceef",
226+
"topics": [
227+
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
228+
"0x0000000000000000000000000000000000000000000000000000000000000000",
229+
"0x000000000000000000000000026b37a09af3ceb346c39999c5738f86a1a48f4d",
230+
"0x000000000000000000000000000000000000000000000000000000000000007f"
231+
],
232+
"data": "0x",
233+
"blockHash": "0x638a175940cacb33f35e265961b164b14aa77477438340e635b227752f31981f",
234+
"blockNumber": "0x25ce471",
235+
"transactionHash": "0xc3e64ac247ae2343335596e106d1b97e35637656e1b99b37977a4165b34aeeb4",
236+
"transactionIndex": "0x44",
237+
"logIndex": "0x12e",
238+
"removed": false
239+
},
240+
],
241+
"status": "0x1",
242+
"logsBloom": "0x000000000000000000000000000000000008000000000000000000000000000000080000000000000002001108040020001080000000000000000200004000000000000000000000000800080000008000000000000000000001000208400040000000000a0008000000000000000800000000000000004080800010020100040000000000000000100000000000010000000000200080000000000000000000210000000000000000400080000000000000000000000000108002000004004008000002000000000001001000800000000001000000800000148040020020000000000000000000000001000000000100000000000000000000002000100000",
243+
"type": "0x2",
244+
"effectiveGasPrice": "0x59682f2e"
245+
}
246+
```
247+
248+
### supportedEntryPoints
249+
Returns an array of the entryPoint addresses supported by the client. The first element of the array SHOULD be the entryPoint addressed preferred by the client.
250+
251+
#### Parameters
252+
- None
253+
254+
#### Returns
255+
- an array of the entryPoint addresses supported by the client. The first element of the array SHOULD be the entryPoint addressed preferred by the client.
256+
257+
#### Example
258+
```ts
259+
web3.EIP4337.supportedEntryPoints().then(console.log);
260+
> ["0xcd01C8aa8995A59eB7B2627E69b40e0524B5ecf8", "0x7A0A0d159218E6a2f407B99173A2b12A6DDfC2a6"]
261+
```
262+
263+
264+
### generateUserOpHash
265+
calculate UserOperationHash
266+
267+
#### Parameters
268+
- `userOp` - a structure that describes a transaction to be sent on behalf of a user.
269+
270+
- `entryPoint` - a singleton contract to execute bundles of UserOperations. Bundlers/Clients whitelist the supported entrypoint.
271+
272+
#### Returns
273+
- An array of the entryPoint addresses supported by the client. The first element of the array SHOULD be the entryPoint addressed preferred by the client.
274+
275+
#### Example
276+
```ts
277+
web3.EIP4337.generateUserOpHash({
278+
sender: "0x9fd042a18e90ce326073fa70f111dc9d798d9a52",
279+
nonce: "123",
280+
initCode: "0x68656c6c6f",
281+
callData: "0x776F726C64",
282+
callGasLimit: "1000",
283+
verificationGasLimit: "2300",
284+
preVerificationGas: "3100",
285+
maxFeePerGas: "0",
286+
maxPriorityFeePerGas: "0",
287+
paymasterAndData: "0x626c6f63746f",
288+
signature: "0x636c656d656e74"
289+
},"0x636c656d656e74", '0x1').then(console.log);
290+
> 0xxxx
291+
```
4292

5-
This is a [web3.js](https://github.com/web3/web3.js) `4.x` plugin for Account Abstraction functionality.
6293

7294
## Run the tests
8295

9296
1. Clone the repo
10297
2. Run `yarn` to install dependencies
11-
- If you receive the following warning, please remove the file `package-lock.json` and make sure to run `yarn` to install dependencies instead of `npm i`:
298+
- If you receive the following warning, please remove the file `package-lock.json` and make sure to run `yarn` to install dependencies instead of `npm i`:
12299

13300
```console
14301
warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.
15302
```
16303

17304
3. Run the tests:
18-
- `yarn test:unit`: Runs the mocked tests that do not make a network request using the [Jest](https://jestjs.io/) framework
19-
- End-to-end tests: Runs Webpack bundled tests that make a network request to the RPC provider `https://rpc.ankr.com/eth` and returns an actual response from `MainnetPriceFeeds.LinkEth` smart contract using the [Cypress](https://www.cypress.io/) framework
20-
- `yarn test:e2e:chrome`: Runs the tests using Chrome
21-
- `yarn test:e2e:electron`: Runs the tests using Electron
22-
- `yarn test:e2e:firefox`: Runs the tests using Firefox
23-
- Black box tests: Uses a published version of the plugin from [Verdaccio](https://verdaccio.org/) to run tests that make a network request to the RPC provider `https://rpc.ankr.com/eth` and returns an actual response from `MainnetPriceFeeds.LinkEth` smart contract using the [Jest](https://jestjs.io/) framework
24-
- NOTE The black box tests are setup to run within Github actions environment, but can be ran locally. The [black_box_test_helpers.sh](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/scripts/black_box_test_helpers.sh) script can be used to:
25-
- `start`: Start Verdaccio using a Docker container
26-
- `stop`: Kill the Docker container
27-
- `startBackgroundAndPublish`: Starts a headless Docker container and publishes the plugin package
28-
- `runTests`: `cd`s into the `test/black_box` directory, installs the black box package dependencies, and runs `yarn test` which will use Jest to run the tests
29-
- In addition to the `black_box_test_helpers.sh` script, the black box tests can be ran using the following `package.json` scripts:
30-
1. `yarn pre-black-box`: Calls `startBackgroundAndPublish` from the `black_box_test_helpers.sh` script
31-
2. `yarn test:black-box`: Calls `yarn pre-black-box` and `runTests` from the from the `black_box_test_helpers.sh` script
32-
3. `yarn post-black-box`: Calls `stop` from the `black_box_test_helpers.sh` script
305+
- `yarn test:unit`: Runs the mocked tests that do not make a network request using the [Jest](https://jestjs.io/) framework
306+
- End-to-end tests: Runs Webpack bundled tests that make a network request to the RPC provider `https://rpc.ankr.com/eth` and returns an actual response from `MainnetPriceFeeds.LinkEth` smart contract using the [Cypress](https://www.cypress.io/) framework
307+
- `yarn test:e2e:chrome`: Runs the tests using Chrome
308+
- `yarn test:e2e:electron`: Runs the tests using Electron
309+
- `yarn test:e2e:firefox`: Runs the tests using Firefox
310+
- Black box tests: Uses a published version of the plugin from [Verdaccio](https://verdaccio.org/) to run tests that make a network request to the RPC provider `https://rpc.ankr.com/eth` and returns an actual response from `MainnetPriceFeeds.LinkEth` smart contract using the [Jest](https://jestjs.io/) framework
311+
- NOTE The black box tests are setup to run within Github actions environment, but can be ran locally. The [black_box_test_helpers.sh](https://github.com/ChainSafe/web3.js-plugin-chainlink/blob/master/scripts/black_box_test_helpers.sh) script can be used to:
312+
- `start`: Start Verdaccio using a Docker container
313+
- `stop`: Kill the Docker container
314+
- `startBackgroundAndPublish`: Starts a headless Docker container and publishes the plugin package
315+
- `runTests`: `cd`s into the `test/black_box` directory, installs the black box package dependencies, and runs `yarn test` which will use Jest to run the tests
316+
- In addition to the `black_box_test_helpers.sh` script, the black box tests can be ran using the following `package.json` scripts:
317+
1. `yarn pre-black-box`: Calls `startBackgroundAndPublish` from the `black_box_test_helpers.sh` script
318+
2. `yarn test:black-box`: Calls `yarn pre-black-box` and `runTests` from the from the `black_box_test_helpers.sh` script
319+
3. `yarn post-black-box`: Calls `stop` from the `black_box_test_helpers.sh` script
33320

34321
## License
35322

0 commit comments

Comments
 (0)