Skip to content

Commit 2075c79

Browse files
ajhodgesajhodges
authored
docs: Add ERC-8132 gasLimitOverride capability documentation (#1237)
* Add ERC-8132 gasLimitOverride capability docs * Add gasLimitOverride callout to batch transactions guide
1 parent 6d79f48 commit 2075c79

6 files changed

Lines changed: 270 additions & 3 deletions

File tree

‎docs/base-account/improve-ux/batch-transactions.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,13 @@ async function trackBatchTransaction(
334334

335335
You can learn more about `wallet_getCallsStatus` in the [reference documentation](/base-account/reference/core/provider-rpc-methods/wallet_getCallsStatus).
336336

337+
<Tip>
338+
**Need more control over gas?**
339+
340+
You can override the gas limit for individual calls in a batch using the [`gasLimitOverride`](/base-account/reference/core/capabilities/gasLimitOverride) capability. This is useful for calls with nondeterministic gas consumption, such as swaps. See the [capabilities overview](/base-account/reference/core/capabilities/overview) for the full list of supported capabilities.
341+
342+
</Tip>
343+
337344
## Video Guide
338345

339346
<iframe

‎docs/base-account/reference/core/capabilities/gasLimitOverride.mdx‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: "gasLimitOverride"
3+
description: "Override gas limits for individual calls in a wallet_sendCalls batch"
4+
---
5+
6+
Defined in [ERC-8132](https://github.com/ethereum/ERCs/pull/1485)
7+
8+
<Info>
9+
The gasLimitOverride capability allows apps to specify gas limits for individual calls within a `wallet_sendCalls` batch. Gas limits can be partially specified — you can provide overrides for only the calls you have context about, and the wallet estimates gas for the rest. Apps often have more context about the gas requirements of their own contract calls than the wallet, making app-provided gas limits more accurate.
10+
</Info>
11+
12+
## Parameters
13+
14+
This is a **call-level capability**, meaning it is specified on individual calls within a `wallet_sendCalls` batch rather than at the top level.
15+
16+
<ParamField body="value" type="`0x${string}`" required>
17+
Hex-encoded gas limit for the call. Must be a non-zero value that does not exceed the block gas limit of the target chain.
18+
</ParamField>
19+
20+
## Returns
21+
22+
<ResponseField name="gasLimitOverride" type="object">
23+
The gasLimitOverride capability configuration.
24+
25+
<Expandable title="gasLimitOverride capability properties">
26+
<ResponseField name="supported" type="boolean">
27+
Indicates whether the wallet supports app-provided gas limit overrides. Reported for all chains (`0x0`) when supported.
28+
</ResponseField>
29+
</Expandable>
30+
</ResponseField>
31+
32+
## Example usage
33+
34+
<RequestExample>
35+
```typescript Check gasLimitOverride support
36+
const capabilities = await provider.request({
37+
method: 'wallet_getCapabilities',
38+
params: [userAddress]
39+
});
40+
41+
const gasLimitOverrideSupport = capabilities["0x0"]?.gasLimitOverride;
42+
```
43+
44+
```typescript Send calls with a gas limit override
45+
const result = await provider.request({
46+
method: "wallet_sendCalls",
47+
params: [{
48+
version: "1.0",
49+
chainId: "0x2105",
50+
from: userAddress,
51+
atomicRequired: true,
52+
calls: [
53+
{
54+
// Approval — no override, wallet estimates gas
55+
to: tokenAddress,
56+
value: "0x0",
57+
data: approveCallData
58+
},
59+
{
60+
// Swap — app provides a known gas limit
61+
to: swapContractAddress,
62+
value: "0x0",
63+
data: swapCallData,
64+
capabilities: {
65+
gasLimitOverride: {
66+
value: "0x30D40" // 200,000 gas
67+
}
68+
}
69+
}
70+
]
71+
}]
72+
});
73+
```
74+
</RequestExample>
75+
76+
<ResponseExample>
77+
```json Capability response (supported)
78+
{
79+
"0x0": {
80+
"gasLimitOverride": {
81+
"supported": true
82+
}
83+
}
84+
}
85+
```
86+
87+
```json Capability response (unsupported)
88+
{
89+
"0x0": {
90+
"gasLimitOverride": {
91+
"supported": false
92+
}
93+
}
94+
}
95+
```
96+
</ResponseExample>
97+
98+
## Error handling
99+
100+
| Code | Message | Description |
101+
| ------ | -------------------- | --------------------------------------------------------------------------- |
102+
| -32602 | Invalid params | Gas limit is zero or exceeds the block gas limit of the target chain |
103+
| 5700 | Capability required | Call includes gasLimitOverride but wallet doesn't support it |
104+
105+
## How it works
106+
107+
When a wallet receives calls with `gasLimitOverride` capabilities:
108+
109+
1. The wallet uses the app-provided gas limit for that call's portion of the batch gas limit.
110+
2. For calls **without** a `gasLimitOverride`, the wallet estimates gas as usual.
111+
3. The wallet may add additional gas to account for batch processing overhead (such as smart account execution or EIP-7702 delegation).
112+
113+
This is a call-level capability, so you can specify gas limits for only some calls in a batch. The wallet handles estimation for the rest.
114+
115+
## Use cases
116+
117+
### Nondeterministic gas usage
118+
119+
Some contract calls have nondeterministic gas costs that are difficult for wallets to estimate accurately. Apps with deep knowledge of their contracts can provide better gas limits:
120+
121+
```typescript
122+
// A complex DeFi operation where gas usage depends on pool state
123+
const result = await provider.request({
124+
method: "wallet_sendCalls",
125+
params: [{
126+
version: "1.0",
127+
chainId: "0x2105",
128+
from: userAddress,
129+
atomicRequired: true,
130+
calls: [
131+
{
132+
to: routerAddress,
133+
value: "0x0",
134+
data: swapCallData,
135+
capabilities: {
136+
gasLimitOverride: {
137+
value: "0x7A120" // 500,000 gas — app knows the swap is complex
138+
}
139+
}
140+
}
141+
]
142+
}]
143+
});
144+
```
145+
146+
### Partial gas limit specification
147+
148+
You can specify gas limits for only the calls you have context about and let the wallet estimate the rest:
149+
150+
```typescript
151+
const result = await provider.request({
152+
method: "wallet_sendCalls",
153+
params: [{
154+
version: "1.0",
155+
chainId: "0x2105",
156+
from: userAddress,
157+
atomicRequired: true,
158+
calls: [
159+
{
160+
// Approval — let the wallet estimate gas
161+
to: tokenAddress,
162+
value: "0x0",
163+
data: approveCallData
164+
},
165+
{
166+
// Swap — app provides a known gas limit
167+
to: swapContractAddress,
168+
value: "0x0",
169+
data: swapCallData,
170+
capabilities: {
171+
gasLimitOverride: {
172+
value: "0x30D40" // 200,000 gas
173+
}
174+
}
175+
}
176+
]
177+
}]
178+
});
179+
```
180+
181+
## Best practices
182+
183+
1. **Check capabilities first**: Verify `gasLimitOverride` support via `wallet_getCapabilities` before including it in calls
184+
2. **Use `optional: true` for compatibility**: Mark the capability as optional if your app can function without it, so wallets that don't support it can still process the batch
185+
3. **Provide accurate limits**: Use gas limits based on your contract's actual requirements — overly tight limits cause reverts, overly generous limits waste block space
186+
4. **Let the wallet handle overhead**: Only specify gas for the call itself. The wallet accounts for batch processing overhead separately
187+
188+
<Warning>
189+
The wallet returns an invalid params error (`-32602`) if a provided gas limit is zero or exceeds the block gas limit of the target chain.
190+
</Warning>
191+
192+
## Related capabilities
193+
194+
- [atomic](/base-account/reference/core/capabilities/atomic) - Use with atomic batch transactions
195+
- [paymasterService](/base-account/reference/core/capabilities/paymasterService) - Combine with sponsored transactions
196+
197+
import PolicyBanner from "/snippets/PolicyBanner.mdx";
198+
199+
<PolicyBanner />

‎docs/base-account/reference/core/capabilities/overview.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ const baseCapabilities = capabilities["0x2105"]; // Base mainnet chain ID
3333
| [flowControl](/base-account/reference/core/capabilities/flowControl) | `wallet_sendCalls` | Flow control |
3434
| [datacallback](/base-account/reference/core/capabilities/datacallback) | `wallet_sendCalls` | Data callback |
3535
| [dataSuffix](/base-account/reference/core/capabilities/dataSuffix) | `wallet_sendCalls` | Transaction attribution |
36+
| [gasLimitOverride](/base-account/reference/core/capabilities/gasLimitOverride) | `wallet_sendCalls` | Call-level gas limit overrides |
3637

3738
## Using with wallet_connect
3839

@@ -201,6 +202,7 @@ For detailed information on each capability:
201202
- [auxiliaryFunds](/base-account/reference/core/capabilities/auxiliaryFunds) - Auxiliary funding support
202203
- [atomic](/base-account/reference/core/capabilities/atomic) - Atomic batch transactions
203204
- [paymasterService](/base-account/reference/core/capabilities/paymasterService) - Gasless transactions
205+
- [gasLimitOverride](/base-account/reference/core/capabilities/gasLimitOverride) - Call-level gas limit overrides
204206

205207
## Related Methods
206208

‎docs/base-account/reference/core/provider-rpc-methods/wallet_getCapabilities.mdx‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,16 @@ Whether data callbacks are supported for this account on this chain.
7575
</ResponseField>
7676
</Expandable>
7777
</ResponseField>
78+
79+
<ResponseField name="gasLimitOverride" type="object">
80+
Indicates support for app-provided gas limit overrides on individual calls. Defined in [ERC-8132](https://github.com/ethereum/ERCs/pull/1485). Reported for all chains (`0x0`).
81+
82+
<Expandable title="gasLimitOverride properties">
83+
<ResponseField name="supported" type="boolean">
84+
Whether gas limit overrides are supported.
85+
</ResponseField>
86+
</Expandable>
87+
</ResponseField>
7888
</Expandable>
7989
</ResponseField>
8090
</Expandable>
@@ -108,11 +118,13 @@ const baseCapabilities = capabilities["0x2105"]; // Base Mainnet
108118
const hasAuxiliaryFunds = baseCapabilities?.auxiliaryFunds?.supported;
109119
const supportsAtomic = baseCapabilities?.atomic?.supported === "supported";
110120
const hasPaymaster = baseCapabilities?.paymasterService?.supported;
121+
const hasGasLimitOverride = capabilities["0x0"]?.gasLimitOverride?.supported;
111122

112123
console.log('Capabilities:', {
113124
hasAuxiliaryFunds,
114125
supportsAtomic,
115-
hasPaymaster
126+
hasPaymaster,
127+
hasGasLimitOverride
116128
});
117129
```
118130
</RequestExample>
@@ -140,6 +152,11 @@ console.log('Capabilities:', {
140152
"supported": false
141153
}
142154
},
155+
"0x0": {
156+
"gasLimitOverride": {
157+
"supported": true
158+
}
159+
},
143160
"0x14A34": {
144161
"auxiliaryFunds": {
145162
"supported": false
@@ -212,7 +229,8 @@ async function getWalletCapabilities(userAddress: string) {
212229
hasAtomicBatch: baseCapabilities.atomic?.supported === "supported",
213230
hasPaymaster: !!baseCapabilities.paymasterService?.supported,
214231
hasFlowControl: !!baseCapabilities.flowControl?.supported,
215-
hasDataCallback: !!baseCapabilities.datacallback?.supported
232+
hasDataCallback: !!baseCapabilities.datacallback?.supported,
233+
hasGasLimitOverride: !!capabilities["0x0"]?.gasLimitOverride?.supported
216234
};
217235
}
218236
```

‎docs/base-account/reference/core/provider-rpc-methods/wallet_sendCalls.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,10 @@ The value to send with the call (in wei, hex format).
4848
<ParamField body="data" type="string">
4949
The call data (optional, hex format).
5050
</ParamField>
51+
52+
<ParamField body="capabilities" type="object">
53+
Optional call-level capabilities. For example, [`gasLimitOverride`](/base-account/reference/core/capabilities/gasLimitOverride) allows you to specify a gas limit for an individual call.
54+
</ParamField>
5155
</Expandable>
5256
</ParamField>
5357

@@ -87,6 +91,42 @@ An object containing information about the sent batch, including transaction det
8791
}]
8892
}
8993
```
94+
95+
```json Request with call-level gas limit overrides
96+
{
97+
"id": 1,
98+
"jsonrpc": "2.0",
99+
"method": "wallet_sendCalls",
100+
"params": [{
101+
"version": "2.0.0",
102+
"from": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
103+
"chainId": "0x2105",
104+
"atomicRequired": true,
105+
"calls": [
106+
{
107+
"to": "0x54f1C1965B355e1AB9ec3465616136be35bb5Ff7",
108+
"value": "0x0",
109+
"data": "0x095ea7b3...",
110+
"capabilities": {
111+
"gasLimitOverride": {
112+
"value": "0x13880"
113+
}
114+
}
115+
},
116+
{
117+
"to": "0x2D48e6f5Ae053e4E918d2be53570961D880905F2",
118+
"value": "0x0",
119+
"data": "0x38ed1739...",
120+
"capabilities": {
121+
"gasLimitOverride": {
122+
"value": "0x30D40"
123+
}
124+
}
125+
}
126+
]
127+
}]
128+
}
129+
```
90130
</RequestExample>
91131

92132
<ResponseExample>

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -402,7 +402,8 @@
402402
"base-account/reference/core/capabilities/paymasterService",
403403
"base-account/reference/core/capabilities/auxiliaryFunds",
404404
"base-account/reference/core/capabilities/datacallback",
405-
"base-account/reference/core/capabilities/dataSuffix"
405+
"base-account/reference/core/capabilities/dataSuffix",
406+
"base-account/reference/core/capabilities/gasLimitOverride"
406407
]
407408
}
408409
]

0 commit comments

Comments
 (0)