Skip to content

Commit 2526dec

Browse files
spencerstockspencerstock
authored
Add fetchPermission utility documentation (#330)
* Add fetchPermission documentation and update spend permissions * add fetchPermission example
1 parent 99d358d commit 2526dec

File tree

5 files changed

+179
-25
lines changed

5 files changed

+179
-25
lines changed

‎docs/base-account/improve-ux/spend-permissions.mdx‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -180,13 +180,15 @@ await provider.request({
180180
- [requestRevoke](/base-account/reference/spend-permission-utilities/requestRevoke)
181181
- [prepareRevokeCallData](/base-account/reference/spend-permission-utilities/prepareRevokeCallData)
182182
- [fetchPermissions](/base-account/reference/spend-permission-utilities/fetchPermissions)
183+
- [fetchPermission](/base-account/reference/spend-permission-utilities/fetchPermission)
183184
- [getPermissionStatus](/base-account/reference/spend-permission-utilities/getPermissionStatus)
184185

185186
## Complete Integration Example
186187

187188
```typescript
188189
import {
189190
fetchPermissions,
191+
fetchPermission,
190192
getPermissionStatus,
191193
prepareSpendCallData,
192194
requestSpendPermission,
@@ -205,22 +207,30 @@ const sdk = createBaseAccountSDK({
205207

206208
const spender = "0xAppSpenderAddress";
207209

208-
// 1) Fetch available permissions
209-
const permissions = await fetchPermissions({
210-
account: "0xUserBaseAccountAddress",
211-
chainId: 84532,
212-
spender,
210+
// 1) Fetch a specific permission by its hash
211+
// Use fetchPermission when you already know the permission hash
212+
// (e.g., stored from a previous session or passed as a parameter)
213+
const permission = await fetchPermission({
214+
permissionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
213215
provider: sdk.getProvider(),
214216
});
215217

218+
// Alternative: Fetch all permissions for a spender
219+
// Use fetchPermissions when you need to see all available permissions
220+
// and want to choose which one to use
221+
// const permissions = await fetchPermissions({
222+
// account: "0xUserBaseAccountAddress",
223+
// chainId: 84532,
224+
// spender,
225+
// provider: sdk.getProvider(),
226+
// });
227+
// const permission = permissions.at(0);
228+
216229
// ========================================
217230
// When there IS an existing permission
218231
// ========================================
219232

220-
// 2. find the permission to use, potentially filtering by token
221-
const permission = permissions.at(0);
222-
223-
// 3. check the status of permission
233+
// 2. check the status of permission
224234
try {
225235
const { isActive, remainingSpend } = await getPermissionStatus(permission);
226236
const amount = 1000n;
@@ -232,13 +242,13 @@ try {
232242
throw new Error("No spend permission available");
233243
}
234244

235-
// 4. prepare the calls
245+
// 3. prepare the calls
236246
const [approveCall, spendCall] = await prepareSpendCallData({
237247
permission,
238248
amount,
239249
});
240250

241-
// 5. execute the calls using your app's spender account
251+
// 4. execute the calls using your app's spender account
242252
// this is an example using wallet_sendCalls, in production it could be using eth_sendTransaction.
243253
await provider.request({
244254
method: "wallet_sendCalls",

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

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
title: "coinbase_fetchPermissions"
3-
description: "Retrieve permissions associated with a specific account, chain, and spender"
3+
description: "Retrieve permissions associated with a specific account and chain, optionally filtered by spender"
44
---
55

66
Coinbase-specific RPC method
77

88
<Info>
9-
Retrieves permissions associated with a specific account, chain, and spender. This method excludes permissions that have expired or been revoked, returning only active spend permissions.
9+
Retrieves permissions associated with a specific account and chain. If a spender is provided, returns only permissions for that spender. Otherwise, returns all permissions for the account. This method excludes permissions that have expired or been revoked, returning only active spend permissions.
1010
</Info>
1111

1212
## Parameters
@@ -19,8 +19,8 @@ The address of the account whose permissions are being queried.
1919
The ID of the blockchain, in hexadecimal format.
2020
</ParamField>
2121

22-
<ParamField body="spender" type="string" required>
23-
The entity granted with the permission to spend the account's funds.
22+
<ParamField body="spender" type="string">
23+
Optional. The entity granted with the permission to spend the account's funds. If not provided, returns all permissions for the account.
2424
</ParamField>
2525

2626
<ParamField body="pageOptions" type="object">
@@ -54,7 +54,7 @@ Pagination information for the response.
5454
</ResponseField>
5555

5656
<RequestExample>
57-
```json Request
57+
```json Request with spender
5858
{
5959
"id": 1,
6060
"jsonrpc": "2.0",
@@ -66,6 +66,18 @@ Pagination information for the response.
6666
}]
6767
}
6868
```
69+
70+
```json Request without spender (all permissions)
71+
{
72+
"id": 1,
73+
"jsonrpc": "2.0",
74+
"method": "coinbase_fetchPermissions",
75+
"params": [{
76+
"account": "0xfB2adc8629FC9F54e243377ffcECEb437a42934C",
77+
"chainId": "0x14A34"
78+
}]
79+
}
80+
```
6981
</RequestExample>
7082

7183
<ResponseExample>
@@ -110,5 +122,5 @@ Pagination information for the response.
110122
| -32602 | Invalid params | Invalid account, chainId, or spender parameters |
111123

112124
<Warning>
113-
Ensure the `chainId`, `account`, and `spender` parameters are correctly formatted and valid for the blockchain you are querying.
125+
Ensure the `chainId` and `account` parameters are correctly formatted and valid for the blockchain you are querying. If provided, the `spender` parameter must also be a valid address.
114126
</Warning>

‎docs/base-account/reference/spend-permission-utilities/fetchPermission.mdx‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: "fetchPermission"
3+
description: "Retrieve a single Spend Permission by its hash"
4+
---
5+
6+
Defined in the [Base Account SDK](https://github.com/base/account-sdk)
7+
8+
<Info>
9+
Returns a single spend permission by its unique hash identifier. This is useful when you have a permission hash from a previous operation and need to retrieve its current details.
10+
</Info>
11+
12+
## Parameters
13+
14+
<ParamField body="permissionHash" type="string" required>
15+
The unique hash identifier of the permission to retrieve.
16+
</ParamField>
17+
18+
<ParamField body="provider" type="EIP1193Provider">
19+
Optional. EIP-1193 compliant Ethereum provider instance. Get this from `sdk.getProvider()`. If not provided, uses the default SDK provider.
20+
</ParamField>
21+
22+
## Returns
23+
24+
<ResponseField name="permission" type="SpendPermission | null">
25+
The spend permission matching the hash, or null if not found.
26+
27+
<Expandable title="SpendPermission properties">
28+
<ResponseField name="permissionHash" type="string">
29+
Deterministic EIP-712 hash of the permission.
30+
</ResponseField>
31+
32+
<ResponseField name="signature" type="string">
33+
Signature for the EIP-712 payload.
34+
</ResponseField>
35+
36+
<ResponseField name="chainId" type="number">
37+
Target chain ID.
38+
</ResponseField>
39+
40+
<ResponseField name="permission" type="object">
41+
Underlying permission fields.
42+
43+
<Expandable title="permission fields">
44+
<ResponseField name="account" type="address" />
45+
<ResponseField name="spender" type="address" />
46+
<ResponseField name="token" type="address" />
47+
<ResponseField name="allowance" type="bigint" />
48+
<ResponseField name="period" type="number">Duration in seconds.</ResponseField>
49+
<ResponseField name="start" type="number">Unix timestamp (seconds).</ResponseField>
50+
<ResponseField name="end" type="number">Unix timestamp (seconds).</ResponseField>
51+
<ResponseField name="salt" type="string" />
52+
<ResponseField name="extraData" type="string" />
53+
</Expandable>
54+
</ResponseField>
55+
</Expandable>
56+
</ResponseField>
57+
58+
<RequestExample>
59+
```typescript Fetch single permission
60+
import { fetchPermission } from "@base-org/account/spend-permission";
61+
import { createBaseAccountSDK } from "@base-org/account";
62+
63+
const sdk = createBaseAccountSDK({
64+
appName: 'My App',
65+
appLogoUrl: 'https://example.com/logo.png',
66+
appChainIds: [84532],
67+
});
68+
69+
// Fetch a specific permission by its hash
70+
const permission = await fetchPermission({
71+
permissionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
72+
provider: sdk.getProvider(),
73+
});
74+
75+
if (permission) {
76+
console.log('Permission found:', permission);
77+
} else {
78+
console.log('Permission not found');
79+
}
80+
81+
// Using without explicit provider (uses default SDK provider)
82+
const permission2 = await fetchPermission({
83+
permissionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
84+
});
85+
```
86+
</RequestExample>
87+
88+
## Error Handling
89+
90+
The function returns `null` if the permission is not found rather than throwing an error. Always check for null values:
91+
92+
```typescript
93+
const permission = await fetchPermission({
94+
permissionHash: hash,
95+
});
96+
97+
if (!permission) {
98+
// Handle permission not found
99+
console.error('Permission not found');
100+
return;
101+
}
102+
103+
// Safe to use permission here
104+
console.log('Permission details:', permission);
105+
```
106+
107+
## Usage Notes
108+
109+
<Note>
110+
This function is particularly useful when:
111+
- You have a permission hash from a previous operation (e.g., from `requestSpendPermission`)
112+
- You want to verify the current state of a specific permission
113+
- You need to look up permission details without knowing the account or spender information
114+
- You're tracking specific permissions across sessions
115+
</Note>
116+
117+
Unlike `fetchPermissions`, this function:
118+
- Returns a single permission instead of an array
119+
- Does not require account, chain, or spender parameters
120+
- Provides direct access via the permission's unique identifier
121+
- Returns `null` instead of an empty array when no permission is found
122+
123+
import PolicyBanner from "/snippets/PolicyBanner.mdx";
124+
125+
<PolicyBanner />

‎docs/base-account/reference/spend-permission-utilities/fetchPermissions.mdx‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
---
22
title: "fetchPermissions"
3-
description: "Retrieve available Spend Permissions for an account, chain, and spender"
3+
description: "Retrieve available Spend Permissions for an account and chain, optionally filtered by spender"
44
---
55

66
Defined in the [Base Account SDK](https://github.com/base/account-sdk)
77

88
<Info>
9-
Returns all permissions available to a given `spender` for a user's Base
10-
Account on a specific chain.
9+
Returns permissions for a user's Base Account on a specific chain. If a `spender` is provided, returns only permissions for that spender. Otherwise, returns all permissions for the account.
1110
</Info>
1211

1312
## Parameters
@@ -20,12 +19,12 @@ Defined in the [Base Account SDK](https://github.com/base/account-sdk)
2019
Target chain ID.
2120
</ParamField>
2221

23-
<ParamField body="spender" type="address" required>
24-
Spender address you intend to use for spending.
22+
<ParamField body="spender" type="address">
23+
Optional. Spender address you intend to use for spending. If not provided, returns all permissions for the account.
2524
</ParamField>
2625

27-
<ParamField body="provider" type="EIP1193Provider" required>
28-
EIP-1193 compliant Ethereum provider instance. Get this from `sdk.getProvider()`.
26+
<ParamField body="provider" type="EIP1193Provider">
27+
Optional. EIP-1193 compliant Ethereum provider instance. Get this from `sdk.getProvider()`. If not provided, uses the default SDK provider.
2928
</ParamField>
3029

3130
## Returns
@@ -65,7 +64,7 @@ Underlying permission fields.
6564
</ResponseField>
6665

6766
<RequestExample>
68-
```typescript Fetch permissions
67+
```typescript Fetch permissions for specific spender
6968
import { fetchPermissions } from "@base-org/account/spend-permission";
7069
import { createBaseAccountSDK } from "@base-org/account";
7170

@@ -75,12 +74,19 @@ const sdk = createBaseAccountSDK({
7574
appChainIds: [84532],
7675
});
7776

77+
// Fetch permissions for a specific spender
7878
const permissions = await fetchPermissions({
7979
account: "0xUserBaseAccountAddress",
8080
chainId: 84532,
8181
spender: "0xAppSpenderAddress",
8282
provider: sdk.getProvider(),
8383
});
84+
85+
// Fetch all permissions for the account (omitting spender)
86+
const allPermissions = await fetchPermissions({
87+
account: "0xUserBaseAccountAddress",
88+
chainId: 84532,
89+
});
8490
```
8591
</RequestExample>
8692

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,7 @@
252252
"base-account/reference/spend-permission-utilities/requestSpendPermission",
253253
"base-account/reference/spend-permission-utilities/prepareSpendCallData",
254254
"base-account/reference/spend-permission-utilities/fetchPermissions",
255+
"base-account/reference/spend-permission-utilities/fetchPermission",
255256
"base-account/reference/spend-permission-utilities/getPermissionStatus",
256257
"base-account/reference/spend-permission-utilities/requestRevoke",
257258
"base-account/reference/spend-permission-utilities/prepareRevokeCallData",

0 commit comments

Comments
 (0)