From d36c279bc26c5e558b2276dbcc310773df0b4f2b Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Thu, 7 Nov 2024 08:28:26 -0800 Subject: [PATCH 01/10] start on more comprehensive api reference --- .../spend-permissions/api-reference.mdx | 275 ++++++++++++++++++ vocs.config.tsx | 8 +- 2 files changed, 281 insertions(+), 2 deletions(-) create mode 100644 docs/pages/guides/spend-permissions/api-reference.mdx diff --git a/docs/pages/guides/spend-permissions/api-reference.mdx b/docs/pages/guides/spend-permissions/api-reference.mdx new file mode 100644 index 0000000..b0cd2c3 --- /dev/null +++ b/docs/pages/guides/spend-permissions/api-reference.mdx @@ -0,0 +1,275 @@ +# Spend Permissions API Reference + +A more detailed reference guide for integrating with Spend Permissions. + +Integrating with Spend Permissions involves interacting with several APIs: +- direct interaction with the `SpendPermissionManager` smart contract +- interaction with the users' connected Coinbase Smart Wallet +- optionally, using the Coinbase Wallet API to fetch information about existing permissions + +## `SpendPermissionManager.sol` smart contract + +### Structs + +#### `SpendPermission` +Defines the complete parameters of a spend permission. + +| Field | Type | Description | +|-------------|----------|-----------------------------------------------------------------------------| +| `account` | `address`| Smart account this spend permission is valid for. | +| `spender` | `address`| Entity that can spend `account`'s tokens. | +| `token` | `address`| Token address (ERC-7528 native token address or ERC-20 contract). | +| `allowance` | `uint160`| Maximum allowed value to spend within each `period`. | +| `period` | `uint48` | Time duration for resetting used `allowance` on a recurring basis (seconds).| +| `start` | `uint48` | Timestamp this spend permission is valid after (unix seconds). | +| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | +| `salt` | `uint256`| An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | +| `extraData` | `bytes` | Arbitrary data to include in the signature. | + +--- + +#### `SpendPermissionBatch` + +| Field | Type | Description | +|---------------|------------------------|-----------------------------------------------------------------------------| +| `account` | `address` | Smart account this spend permission is valid for. | +| `period` | `uint48` | Time duration for resetting used allowance on a recurring basis (seconds). | +| `start` | `uint48` | Timestamp this spend permission is valid after (unix seconds). | +| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | +| `permissions` | `PermissionDetails[]` | Array of PermissionDetails structs defining properties that apply per-permission. | + +--- + +#### `PermissionDetails` + +| Field | Type | Description | +|-------------|----------|-----------------------------------------------------------------------------| +| `spender` | `address`| Entity that can spend user funds. | +| `token` | `address`| Token address (ERC-7528 ether address or ERC-20 contract). | +| `allowance` | `uint160`| Maximum allowed value to spend within a recurring period. | +| `salt` | `uint256`| An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | +| `extraData` | `bytes` | Arbitrary data to include in the signature. | + +--- + +#### `PeriodSpend` + +| Field | Type | Description | +|-------------|----------|-----------------------------------------------------------------------------| +| `start` | `uint48` | Start time of the period (unix seconds). | +| `end` | `uint48` | End time of the period (unix seconds). | +| `spend` | `uint160`| Accumulated spend amount for period. | + +--- + +### Contract functions +#### `approve` + +Approve a spend permission via a direct call from the account. Only callable by the account owner specified in the spend permission. + +```solidity +function approve(SpendPermission calldata spendPermission) external requireSender(spendPermission.account); +``` + +--- + +#### `approveWithSignature` + +Approve a spend permission via a signature from the account owner. Compatible with [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492) signatures. + +```solidity +function approveWithSignature(SpendPermission calldata spendPermission, bytes calldata signature) external; +``` + +--- + +#### `approveBatchWithSignature` + +Approve a batch of spend permissions via one signature from the account owner. Batched permissions share an `account`, `period`, +`start` and `end`. Details unique to each permission in the batch are specified by an array of `PermissionDetails` structs. + +```solidity +function approveBatchWithSignature(SpendPermissionBatch memory spendPermissionBatch, bytes calldata signature) external; +``` + +--- + +#### `spend` + +Spend tokens using a spend permission, transferring them from the account to the spender. Only callable by the spender specified in the permission. + +```solidity +function spend(SpendPermission memory spendPermission, uint160 value) external requireSender(spendPermission.spender); +``` + +--- + +#### `revoke` + +Revoke a spend permission, permanently disabling its use. Only callable by the account owner specified in the spend permission. + +```solidity +function revoke(SpendPermission calldata spendPermission) external requireSender(spendPermission.account); +``` + +--- + +#### `getHash` + +Generate a hash of a `SpendPermission` struct for signing, in accordance with [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md). + +```solidity +function getHash(SpendPermission memory spendPermission) public view returns (bytes32); +``` + +--- + +#### `getBatchHash` + +Generate a hash of a `SpendPermissionBatch` struct for signing, in accordance with [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md). +Reverts if the batch is empty. + +```solidity +function getBatchHash(SpendPermissionBatch memory spendPermissionBatch) public view returns (bytes32); +``` + +--- + +#### `isApproved` + +Check if a spend permission is approved and not revoked. + +```solidity +function isApproved(SpendPermission memory spendPermission) public view returns (bool); +``` + +--- + +#### `getCurrentPeriod` + +Retrieve the start, end, and accumulated spend for the current period of a spend permission. + +```solidity +function getCurrentPeriod(SpendPermission memory spendPermission) public view returns (PeriodSpend memory); +``` +## Coinbase Smart Wallet clients + +### Using Viem +[Viem](https://viem.sh/) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. + +- **[Getting Started with Viem](https://viem.sh/docs/getting-started.html)** + +- **[Getting Started with Account Abstraction](https://viem.sh/account-abstraction#getting-started-with-account-abstraction)** + Viem provides support for account abstraction clients, including specific support for Coinbase Smart Wallet and paymasters. + +### Using OnchainKit +[OnchainKit](https://onchainkit.xyz/) is a collection of React components and TypeScript utilities that help developers quickly build +onchain applications. + +### Using Wagmi +[Wagmi](https://wagmi.sh/) is a collection of React Hooks that facilitate development of blockchain frontends. + +- **[Getting Started with Wagmi](https://wagmi.sh/react/getting-started)** +- **[coinbaseWallet](https://wagmi.sh/react/api/connectors/coinbaseWallet)** + + +## Coinbase Wallet API + +### `wallet_fetchPermissions` + +#### Schema +```typescript +type FetchPermissionsRequest = { + account: Address; + chainId: string; // 0x... + spender: Address; + pageOptions: PageOptions; // optional, defaults to page size 50 and empty cursor +} + +type FetchPermissionsResponse = { + permissions: FetchPermissionsResponseItem[]; + pageDescription: PageDescription; +} + +type PageOptions = { + pageSize number; // number of items requested, defaults to 50 + cursor string; // identifier for where the page should start +} + +type PageDescription = { + pageSize number; // number of items returned + nextCursor string; // identifier for where the next page should start +} + +type FetchPermissionsResponseItem = { + createdAt: number; // UTC timestamp for when the permission was granted + permissionHash: string; + signature: string; + permission: { + account: string; + spender: string; + token: string; + allowance: string; // base 10 numeric string + period: number; + start: number; + end: number; + salt: string; // base 10 numeric string + extraData: string // 0x... + }; +} +``` + +#### Example request + +```bash +curl --location 'https://wallet-chain-proxy-dev.cbhq.net?targetName=base-sepolia' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc":"2.0", + "method":"wallet_fetchPermissions", + "params":["0x764e97e81a0b1138c70525499037e27e442bd3b2","0x14A34","0xd4e17478581878a967aa22d45a5158a9fe96aa08"], + "id":1 +}' +``` + +#### Example response + +```bash +{ + "permissions": [ + { + "createdAt": 1730320800, + "permissionHash": "0xe15ff6f0f1e666a7b55e3886af487b0f86f17dad1c103932aa215adcd9d3420f", + "signature": "0x000000000000000000000000ca11bde05977b3631167028862be2a173976ca110000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000001e482ad56cb0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000ba5ed0c6aa8c49038f819e587e2633c4a9f428a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e43ffba36f00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040c2a3c9b9ac1dbb4c0887d85bb36e1f406f412eb509be7f50bc0dd0f7e10c2ae239c5385467133101accc9789e5df580ae61eb036eb978d2c9b08af7bd50708d2000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002800000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000017000000000000000000000000000000000000000000000000000000000000000152b3bb6203349a2d949b434711fec2dc2210b54f39b330978e7d861594574d370de2f0d78b35d17226185c5a9580215b96f90d874e6e109d2c5c11f55d928d0b000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000867b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a2238425359395564574a685f41383468565a5a674f4b6e42326e3965465471365a5944656846673252556a73222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73657d00000000000000000000000000000000000000000000000000006492649264926492649264926492649264926492649264926492649264926492", + "spendPermission": { + "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", + "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", + "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "allowance": "10000000000", + "period": 86400, + "start": 1724264802, + "end": 17242884802, + "salt": "1", + "extraData": "0x" + } + }, + { + "createdAt": 1730320968, + "permissionHash": "0x4c1f453f72463e7ba809a33fd2139844c0fcc65eb41301147a91aadc4f784468", + "signature": "0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000260000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000000170000000000000000000000000000000000000000000000000000000000000001b5b5e61db096d44311246729f88cf1fe57fe233e5315f94cf541e6fe3086eaef5142efb9267d19cd64b97866a8cfa6c3b872da47264db3c15d36d75e44373f9f000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f37b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a22704746725847794a654c514f427a6e554c3763533937726435654e46634d396a3357647064704f565f474d222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73652c226f746865725f6b6579735f63616e5f62655f61646465645f68657265223a22646f206e6f7420636f6d7061726520636c69656e74446174614a534f4e20616761696e737420612074656d706c6174652e205365652068747470733a2f2f676f6f2e676c2f796162506578227d00000000000000000000000000", + "spendPermission": { + "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", + "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", + "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "allowance": "10000000000", + "period": 86400, + "start": 1724264802, + "end": 17242884802, + "salt": "2", + "extraData": "0x" + } + } + ] +} + +``` \ No newline at end of file diff --git a/vocs.config.tsx b/vocs.config.tsx index f7d676f..31d7ded 100644 --- a/vocs.config.tsx +++ b/vocs.config.tsx @@ -116,6 +116,10 @@ export default defineConfig({ text: "Quick Start", link: "/guides/spend-permissions/quick-start", }, + { + text: "API Reference", + link: "/guides/spend-permissions/api-reference", + }, ], }, { @@ -172,8 +176,8 @@ export default defineConfig({ link: "https://github.com/coinbase/smart-wallet", }, { - text: "Smart Wallet Permissions", - link: "https://github.com/coinbase/smart-wallet-permissions", + text: "Spend Permissions", + link: "https://github.com/coinbase/spend-permissions", }, { text: "MagicSpend", From ab5365c39f9750867b3f0423556a961d7236608e Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Thu, 7 Nov 2024 08:43:46 -0800 Subject: [PATCH 02/10] add link to contracts repository from api reference page --- docs/pages/guides/spend-permissions/api-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/pages/guides/spend-permissions/api-reference.mdx b/docs/pages/guides/spend-permissions/api-reference.mdx index b0cd2c3..9d49716 100644 --- a/docs/pages/guides/spend-permissions/api-reference.mdx +++ b/docs/pages/guides/spend-permissions/api-reference.mdx @@ -9,6 +9,7 @@ Integrating with Spend Permissions involves interacting with several APIs: ## `SpendPermissionManager.sol` smart contract +The open-source contracts repository is [here](https://github.com/coinbase/spend-permissions). ### Structs #### `SpendPermission` From ee70bd036769853d5912b0172995259b4082ed7d Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Thu, 7 Nov 2024 09:35:25 -0800 Subject: [PATCH 03/10] conner review comments --- .../spend-permissions/api-reference.mdx | 276 ------------------ .../api-reference/client-resources.mdx | 19 ++ .../api-reference/spendpermissionmanager.mdx | 99 +++++++ .../api-reference/wallet-fetchpermissions.mdx | 98 +++++++ vocs.config.tsx | 16 +- 5 files changed, 231 insertions(+), 277 deletions(-) delete mode 100644 docs/pages/guides/spend-permissions/api-reference.mdx create mode 100644 docs/pages/guides/spend-permissions/api-reference/client-resources.mdx create mode 100644 docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx create mode 100644 docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx diff --git a/docs/pages/guides/spend-permissions/api-reference.mdx b/docs/pages/guides/spend-permissions/api-reference.mdx deleted file mode 100644 index 9d49716..0000000 --- a/docs/pages/guides/spend-permissions/api-reference.mdx +++ /dev/null @@ -1,276 +0,0 @@ -# Spend Permissions API Reference - -A more detailed reference guide for integrating with Spend Permissions. - -Integrating with Spend Permissions involves interacting with several APIs: -- direct interaction with the `SpendPermissionManager` smart contract -- interaction with the users' connected Coinbase Smart Wallet -- optionally, using the Coinbase Wallet API to fetch information about existing permissions - -## `SpendPermissionManager.sol` smart contract - -The open-source contracts repository is [here](https://github.com/coinbase/spend-permissions). -### Structs - -#### `SpendPermission` -Defines the complete parameters of a spend permission. - -| Field | Type | Description | -|-------------|----------|-----------------------------------------------------------------------------| -| `account` | `address`| Smart account this spend permission is valid for. | -| `spender` | `address`| Entity that can spend `account`'s tokens. | -| `token` | `address`| Token address (ERC-7528 native token address or ERC-20 contract). | -| `allowance` | `uint160`| Maximum allowed value to spend within each `period`. | -| `period` | `uint48` | Time duration for resetting used `allowance` on a recurring basis (seconds).| -| `start` | `uint48` | Timestamp this spend permission is valid after (unix seconds). | -| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | -| `salt` | `uint256`| An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | -| `extraData` | `bytes` | Arbitrary data to include in the signature. | - ---- - -#### `SpendPermissionBatch` - -| Field | Type | Description | -|---------------|------------------------|-----------------------------------------------------------------------------| -| `account` | `address` | Smart account this spend permission is valid for. | -| `period` | `uint48` | Time duration for resetting used allowance on a recurring basis (seconds). | -| `start` | `uint48` | Timestamp this spend permission is valid after (unix seconds). | -| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | -| `permissions` | `PermissionDetails[]` | Array of PermissionDetails structs defining properties that apply per-permission. | - ---- - -#### `PermissionDetails` - -| Field | Type | Description | -|-------------|----------|-----------------------------------------------------------------------------| -| `spender` | `address`| Entity that can spend user funds. | -| `token` | `address`| Token address (ERC-7528 ether address or ERC-20 contract). | -| `allowance` | `uint160`| Maximum allowed value to spend within a recurring period. | -| `salt` | `uint256`| An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | -| `extraData` | `bytes` | Arbitrary data to include in the signature. | - ---- - -#### `PeriodSpend` - -| Field | Type | Description | -|-------------|----------|-----------------------------------------------------------------------------| -| `start` | `uint48` | Start time of the period (unix seconds). | -| `end` | `uint48` | End time of the period (unix seconds). | -| `spend` | `uint160`| Accumulated spend amount for period. | - ---- - -### Contract functions -#### `approve` - -Approve a spend permission via a direct call from the account. Only callable by the account owner specified in the spend permission. - -```solidity -function approve(SpendPermission calldata spendPermission) external requireSender(spendPermission.account); -``` - ---- - -#### `approveWithSignature` - -Approve a spend permission via a signature from the account owner. Compatible with [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492) signatures. - -```solidity -function approveWithSignature(SpendPermission calldata spendPermission, bytes calldata signature) external; -``` - ---- - -#### `approveBatchWithSignature` - -Approve a batch of spend permissions via one signature from the account owner. Batched permissions share an `account`, `period`, -`start` and `end`. Details unique to each permission in the batch are specified by an array of `PermissionDetails` structs. - -```solidity -function approveBatchWithSignature(SpendPermissionBatch memory spendPermissionBatch, bytes calldata signature) external; -``` - ---- - -#### `spend` - -Spend tokens using a spend permission, transferring them from the account to the spender. Only callable by the spender specified in the permission. - -```solidity -function spend(SpendPermission memory spendPermission, uint160 value) external requireSender(spendPermission.spender); -``` - ---- - -#### `revoke` - -Revoke a spend permission, permanently disabling its use. Only callable by the account owner specified in the spend permission. - -```solidity -function revoke(SpendPermission calldata spendPermission) external requireSender(spendPermission.account); -``` - ---- - -#### `getHash` - -Generate a hash of a `SpendPermission` struct for signing, in accordance with [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md). - -```solidity -function getHash(SpendPermission memory spendPermission) public view returns (bytes32); -``` - ---- - -#### `getBatchHash` - -Generate a hash of a `SpendPermissionBatch` struct for signing, in accordance with [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md). -Reverts if the batch is empty. - -```solidity -function getBatchHash(SpendPermissionBatch memory spendPermissionBatch) public view returns (bytes32); -``` - ---- - -#### `isApproved` - -Check if a spend permission is approved and not revoked. - -```solidity -function isApproved(SpendPermission memory spendPermission) public view returns (bool); -``` - ---- - -#### `getCurrentPeriod` - -Retrieve the start, end, and accumulated spend for the current period of a spend permission. - -```solidity -function getCurrentPeriod(SpendPermission memory spendPermission) public view returns (PeriodSpend memory); -``` -## Coinbase Smart Wallet clients - -### Using Viem -[Viem](https://viem.sh/) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. - -- **[Getting Started with Viem](https://viem.sh/docs/getting-started.html)** - -- **[Getting Started with Account Abstraction](https://viem.sh/account-abstraction#getting-started-with-account-abstraction)** - Viem provides support for account abstraction clients, including specific support for Coinbase Smart Wallet and paymasters. - -### Using OnchainKit -[OnchainKit](https://onchainkit.xyz/) is a collection of React components and TypeScript utilities that help developers quickly build -onchain applications. - -### Using Wagmi -[Wagmi](https://wagmi.sh/) is a collection of React Hooks that facilitate development of blockchain frontends. - -- **[Getting Started with Wagmi](https://wagmi.sh/react/getting-started)** -- **[coinbaseWallet](https://wagmi.sh/react/api/connectors/coinbaseWallet)** - - -## Coinbase Wallet API - -### `wallet_fetchPermissions` - -#### Schema -```typescript -type FetchPermissionsRequest = { - account: Address; - chainId: string; // 0x... - spender: Address; - pageOptions: PageOptions; // optional, defaults to page size 50 and empty cursor -} - -type FetchPermissionsResponse = { - permissions: FetchPermissionsResponseItem[]; - pageDescription: PageDescription; -} - -type PageOptions = { - pageSize number; // number of items requested, defaults to 50 - cursor string; // identifier for where the page should start -} - -type PageDescription = { - pageSize number; // number of items returned - nextCursor string; // identifier for where the next page should start -} - -type FetchPermissionsResponseItem = { - createdAt: number; // UTC timestamp for when the permission was granted - permissionHash: string; - signature: string; - permission: { - account: string; - spender: string; - token: string; - allowance: string; // base 10 numeric string - period: number; - start: number; - end: number; - salt: string; // base 10 numeric string - extraData: string // 0x... - }; -} -``` - -#### Example request - -```bash -curl --location 'https://wallet-chain-proxy-dev.cbhq.net?targetName=base-sepolia' \ ---header 'Content-Type: application/json' \ ---data '{ - "jsonrpc":"2.0", - "method":"wallet_fetchPermissions", - "params":["0x764e97e81a0b1138c70525499037e27e442bd3b2","0x14A34","0xd4e17478581878a967aa22d45a5158a9fe96aa08"], - "id":1 -}' -``` - -#### Example response - -```bash -{ - "permissions": [ - { - "createdAt": 1730320800, - "permissionHash": "0xe15ff6f0f1e666a7b55e3886af487b0f86f17dad1c103932aa215adcd9d3420f", - "signature": "0x000000000000000000000000ca11bde05977b3631167028862be2a173976ca110000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000001e482ad56cb0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000ba5ed0c6aa8c49038f819e587e2633c4a9f428a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e43ffba36f00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040c2a3c9b9ac1dbb4c0887d85bb36e1f406f412eb509be7f50bc0dd0f7e10c2ae239c5385467133101accc9789e5df580ae61eb036eb978d2c9b08af7bd50708d2000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002800000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000017000000000000000000000000000000000000000000000000000000000000000152b3bb6203349a2d949b434711fec2dc2210b54f39b330978e7d861594574d370de2f0d78b35d17226185c5a9580215b96f90d874e6e109d2c5c11f55d928d0b000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000867b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a2238425359395564574a685f41383468565a5a674f4b6e42326e3965465471365a5944656846673252556a73222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73657d00000000000000000000000000000000000000000000000000006492649264926492649264926492649264926492649264926492649264926492", - "spendPermission": { - "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", - "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", - "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", - "allowance": "10000000000", - "period": 86400, - "start": 1724264802, - "end": 17242884802, - "salt": "1", - "extraData": "0x" - } - }, - { - "createdAt": 1730320968, - "permissionHash": "0x4c1f453f72463e7ba809a33fd2139844c0fcc65eb41301147a91aadc4f784468", - "signature": "0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000260000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000000170000000000000000000000000000000000000000000000000000000000000001b5b5e61db096d44311246729f88cf1fe57fe233e5315f94cf541e6fe3086eaef5142efb9267d19cd64b97866a8cfa6c3b872da47264db3c15d36d75e44373f9f000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f37b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a22704746725847794a654c514f427a6e554c3763533937726435654e46634d396a3357647064704f565f474d222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73652c226f746865725f6b6579735f63616e5f62655f61646465645f68657265223a22646f206e6f7420636f6d7061726520636c69656e74446174614a534f4e20616761696e737420612074656d706c6174652e205365652068747470733a2f2f676f6f2e676c2f796162506578227d00000000000000000000000000", - "spendPermission": { - "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", - "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", - "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", - "allowance": "10000000000", - "period": 86400, - "start": 1724264802, - "end": 17242884802, - "salt": "2", - "extraData": "0x" - } - } - ] -} - -``` \ No newline at end of file diff --git a/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx b/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx new file mode 100644 index 0000000..3ad3241 --- /dev/null +++ b/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx @@ -0,0 +1,19 @@ +# Client resources + +### Using Viem +[Viem](https://viem.sh/) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. + +- **[Getting Started with Viem](https://viem.sh/docs/getting-started.html)** + +- **[Getting Started with Account Abstraction](https://viem.sh/account-abstraction#getting-started-with-account-abstraction)** + Viem provides support for account abstraction clients, including specific support for Coinbase Smart Wallet and paymasters. + +### Using OnchainKit +[OnchainKit](https://onchainkit.xyz/) is a collection of React components and TypeScript utilities that help developers quickly build +onchain applications. + +### Using Wagmi +[Wagmi](https://wagmi.sh/) is a collection of React Hooks that facilitate development of blockchain frontends. + +- **[Getting Started with Wagmi](https://wagmi.sh/react/getting-started)** +- **[coinbaseWallet](https://wagmi.sh/react/api/connectors/coinbaseWallet)** diff --git a/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx b/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx new file mode 100644 index 0000000..a793e3c --- /dev/null +++ b/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx @@ -0,0 +1,99 @@ +# `SpendPermissionManager.sol` smart contract +The open-source contracts repository is [here](https://github.com/coinbase/spend-permissions). + +### Structs + +#### `SpendPermission` +Defines the complete parameters of a spend permission. + +| Field | Type | Description | +|-------------|----------|-----------------------------------------------------------------------------| +| `account` | `address`| Smart account this spend permission is valid for. | +| `spender` | `address`| Entity that can spend `account`'s tokens. | +| `token` | `address`| Token address (ERC-7528 native token address or ERC-20 contract). | +| `allowance` | `uint160`| Maximum allowed value to spend within each `period`. | +| `period` | `uint48` | Time duration for resetting used `allowance` on a recurring basis (seconds).| +| `start` | `uint48` | Timestamp this spend permission is valid after (unix seconds). | +| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | +| `salt` | `uint256`| An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | +| `extraData` | `bytes` | Arbitrary data to include in the signature. | + +#### `PeriodSpend` +Describes the cumulative spend for the current active period. + +| Field | Type | Description | +|-------------|----------|-----------------------------------------------------------------------------| +| `start` | `uint48` | Start time of the period (unix seconds). | +| `end` | `uint48` | End time of the period (unix seconds). | +| `spend` | `uint160`| Accumulated spend amount for period. | + +--- + +### Contract functions +#### `approve` + +Approve a spend permission via a direct call from the `account`. Only callable by the `account` specified in the spend permission. + +```solidity +function approve(SpendPermission calldata spendPermission) external; +``` + +--- + +#### `approveWithSignature` + +Approve a spend permission via a signature from the `account` owner. Compatible with [ERC-6492](https://eips.ethereum.org/EIPS/eip-6492) signatures for automatic account creation if needed. + +```solidity +function approveWithSignature(SpendPermission calldata spendPermission, bytes calldata signature) external; +``` + +--- + +#### `spend` + +Spend tokens using a spend permission, transferring them from the `account` to the `spender`. Only callable by the `spender` specified in the permission. + +```solidity +function spend(SpendPermission memory spendPermission, uint160 value) external requireSender(spendPermission.spender); +``` + +--- + +#### `revoke` + +Revoke a spend permission, permanently disabling its use. Only callable by the `account` owner specified in the spend permission. + +```solidity +function revoke(SpendPermission calldata spendPermission) external requireSender(spendPermission.account); +``` + +--- + +#### `getHash` + +Generate a hash of a `SpendPermission` struct for signing, in accordance with [EIP-712](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md). + +```solidity +function getHash(SpendPermission memory spendPermission) public view returns (bytes32); +``` + +--- + +#### `isApproved` + +Check if a spend permission is approved and not revoked. + +```solidity +function isApproved(SpendPermission memory spendPermission) public view returns (bool); +``` + +--- + +#### `getCurrentPeriod` + +Retrieve the `start`, `end`, and accumulated `spend` for the current period of a spend permission. + +```solidity +function getCurrentPeriod(SpendPermission memory spendPermission) public view returns (PeriodSpend memory); +``` diff --git a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx new file mode 100644 index 0000000..f76ed7e --- /dev/null +++ b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx @@ -0,0 +1,98 @@ +## Coinbase Wallet API + +### `wallet_fetchPermissions` + +#### Schema +```typescript +type FetchPermissionsRequest = { + chainId: string; // uint256, hex formatted + account: string; // address + spender: string; // address + pageOptions?: { + pageSize number; // number of items requested, defaults to 50 + cursor string; // identifier for where the page should start + } +} + +type FetchPermissionsResult = { + permissions: FetchPermissionsResultItem[]; + pageDescription: { + pageSize number; // number of items returned + nextCursor string; // identifier for where the next page should start + } +} + +type PageDescription = + +type FetchPermissionsResultItem = { + createdAt: number; // UTC timestamp for when the permission was granted + permissionHash: string; + signature: string; + permission: { + account: string; // address + spender: string; // address + token: string; // address + allowance: string; // base 10 numeric string + period: number; + start: number; + end: number; + salt: string; // base 10 numeric string + extraData: string // hex formatted bytes, i.e. "0x" for empty data + }; +} +``` + +#### Example request + +```bash +curl --location 'https://wallet-chain-proxy-dev.cbhq.net?targetName=base-sepolia' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc":"2.0", + "method":"wallet_fetchPermissions", + "params":["0x764e97e81a0b1138c70525499037e27e442bd3b2","0x14A34","0xd4e17478581878a967aa22d45a5158a9fe96aa08"], + "id":1 +}' +``` + +#### Example response + +```bash +{ + "permissions": [ + { + "createdAt": 1730320800, + "permissionHash": "0xe15ff6f0f1e666a7b55e3886af487b0f86f17dad1c103932aa215adcd9d3420f", + "signature": "0x000000000000000000000000ca11bde05977b3631167028862be2a173976ca110000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000001e482ad56cb0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000ba5ed0c6aa8c49038f819e587e2633c4a9f428a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e43ffba36f00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040c2a3c9b9ac1dbb4c0887d85bb36e1f406f412eb509be7f50bc0dd0f7e10c2ae239c5385467133101accc9789e5df580ae61eb036eb978d2c9b08af7bd50708d2000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002800000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000017000000000000000000000000000000000000000000000000000000000000000152b3bb6203349a2d949b434711fec2dc2210b54f39b330978e7d861594574d370de2f0d78b35d17226185c5a9580215b96f90d874e6e109d2c5c11f55d928d0b000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000867b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a2238425359395564574a685f41383468565a5a674f4b6e42326e3965465471365a5944656846673252556a73222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73657d00000000000000000000000000000000000000000000000000006492649264926492649264926492649264926492649264926492649264926492", + "spendPermission": { + "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", + "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", + "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "allowance": "10000000000", + "period": 86400, + "start": 1724264802, + "end": 17242884802, + "salt": "1", + "extraData": "0x" + } + }, + { + "createdAt": 1730320968, + "permissionHash": "0x4c1f453f72463e7ba809a33fd2139844c0fcc65eb41301147a91aadc4f784468", + "signature": "0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000260000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000000170000000000000000000000000000000000000000000000000000000000000001b5b5e61db096d44311246729f88cf1fe57fe233e5315f94cf541e6fe3086eaef5142efb9267d19cd64b97866a8cfa6c3b872da47264db3c15d36d75e44373f9f000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f37b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a22704746725847794a654c514f427a6e554c3763533937726435654e46634d396a3357647064704f565f474d222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73652c226f746865725f6b6579735f63616e5f62655f61646465645f68657265223a22646f206e6f7420636f6d7061726520636c69656e74446174614a534f4e20616761696e737420612074656d706c6174652e205365652068747470733a2f2f676f6f2e676c2f796162506578227d00000000000000000000000000", + "spendPermission": { + "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", + "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", + "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", + "allowance": "10000000000", + "period": 86400, + "start": 1724264802, + "end": 17242884802, + "salt": "2", + "extraData": "0x" + } + } + ] +} + +``` \ No newline at end of file diff --git a/vocs.config.tsx b/vocs.config.tsx index 31d7ded..1811d74 100644 --- a/vocs.config.tsx +++ b/vocs.config.tsx @@ -107,6 +107,7 @@ export default defineConfig({ }, { text: "Spend Permissions", + collapsed: true, items: [ { text: "Overview", @@ -118,7 +119,20 @@ export default defineConfig({ }, { text: "API Reference", - link: "/guides/spend-permissions/api-reference", + items: [ + { + text: "SpendPermissionManager Contract", + link: "/guides/spend-permissions/api-reference/spendpermissionmanager", + }, + { + text: "wallet_fetchPermissions", + link: "/guides/spend-permissions/api-reference/wallet-fetchpermissions", + }, + { + text: "Client Resources", + link: "/guides/spend-permissions/api-reference/client-resources", + }, + ], }, ], }, From 17cd3d89f086a24b7e760a7f7f9c139bff99e1da Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Thu, 7 Nov 2024 09:37:14 -0800 Subject: [PATCH 04/10] few more comments on types --- .../api-reference/wallet-fetchpermissions.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx index f76ed7e..eccef46 100644 --- a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx @@ -33,9 +33,9 @@ type FetchPermissionsResultItem = { spender: string; // address token: string; // address allowance: string; // base 10 numeric string - period: number; - start: number; - end: number; + period: number; // unix time, seconds + start: number; // unix time, seconds + end: number; // unix time, seconds salt: string; // base 10 numeric string extraData: string // hex formatted bytes, i.e. "0x" for empty data }; From 64e3399fb3a5e7deb595dc268de5ae725c520b9d Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Thu, 7 Nov 2024 10:47:55 -0800 Subject: [PATCH 05/10] remove dev endpoint for now --- .../api-reference/wallet-fetchpermissions.mdx | 55 ------------------- 1 file changed, 55 deletions(-) diff --git a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx index eccef46..53cc5af 100644 --- a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx @@ -41,58 +41,3 @@ type FetchPermissionsResultItem = { }; } ``` - -#### Example request - -```bash -curl --location 'https://wallet-chain-proxy-dev.cbhq.net?targetName=base-sepolia' \ ---header 'Content-Type: application/json' \ ---data '{ - "jsonrpc":"2.0", - "method":"wallet_fetchPermissions", - "params":["0x764e97e81a0b1138c70525499037e27e442bd3b2","0x14A34","0xd4e17478581878a967aa22d45a5158a9fe96aa08"], - "id":1 -}' -``` - -#### Example response - -```bash -{ - "permissions": [ - { - "createdAt": 1730320800, - "permissionHash": "0xe15ff6f0f1e666a7b55e3886af487b0f86f17dad1c103932aa215adcd9d3420f", - "signature": "0x000000000000000000000000ca11bde05977b3631167028862be2a173976ca110000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000028000000000000000000000000000000000000000000000000000000000000001e482ad56cb0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000ba5ed0c6aa8c49038f819e587e2633c4a9f428a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e43ffba36f00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040c2a3c9b9ac1dbb4c0887d85bb36e1f406f412eb509be7f50bc0dd0f7e10c2ae239c5385467133101accc9789e5df580ae61eb036eb978d2c9b08af7bd50708d2000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002800000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000017000000000000000000000000000000000000000000000000000000000000000152b3bb6203349a2d949b434711fec2dc2210b54f39b330978e7d861594574d370de2f0d78b35d17226185c5a9580215b96f90d874e6e109d2c5c11f55d928d0b000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000867b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a2238425359395564574a685f41383468565a5a674f4b6e42326e3965465471365a5944656846673252556a73222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73657d00000000000000000000000000000000000000000000000000006492649264926492649264926492649264926492649264926492649264926492", - "spendPermission": { - "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", - "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", - "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", - "allowance": "10000000000", - "period": 86400, - "start": 1724264802, - "end": 17242884802, - "salt": "1", - "extraData": "0x" - } - }, - { - "createdAt": 1730320968, - "permissionHash": "0x4c1f453f72463e7ba809a33fd2139844c0fcc65eb41301147a91aadc4f784468", - "signature": "0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000260000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000000170000000000000000000000000000000000000000000000000000000000000001b5b5e61db096d44311246729f88cf1fe57fe233e5315f94cf541e6fe3086eaef5142efb9267d19cd64b97866a8cfa6c3b872da47264db3c15d36d75e44373f9f000000000000000000000000000000000000000000000000000000000000002549960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d9763050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f37b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a22704746725847794a654c514f427a6e554c3763533937726435654e46634d396a3357647064704f565f474d222c226f726967696e223a22687474703a2f2f6c6f63616c686f73743a33303035222c2263726f73734f726967696e223a66616c73652c226f746865725f6b6579735f63616e5f62655f61646465645f68657265223a22646f206e6f7420636f6d7061726520636c69656e74446174614a534f4e20616761696e737420612074656d706c6174652e205365652068747470733a2f2f676f6f2e676c2f796162506578227d00000000000000000000000000", - "spendPermission": { - "spender": "0xd4e17478581878a967aa22d45a5158a9fe96aa08", - "account": "0x764e97e81a0b1138c70525499037e27e442bd3b2", - "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", - "allowance": "10000000000", - "period": 86400, - "start": 1724264802, - "end": 17242884802, - "salt": "2", - "extraData": "0x" - } - } - ] -} - -``` \ No newline at end of file From 21815b914c4caa8c532e97d279af133c48a72716 Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Thu, 7 Nov 2024 10:49:00 -0800 Subject: [PATCH 06/10] update keysUrl --- docs/pages/guides/spend-permissions/quick-start.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/guides/spend-permissions/quick-start.mdx b/docs/pages/guides/spend-permissions/quick-start.mdx index a9eb563..b9bb625 100644 --- a/docs/pages/guides/spend-permissions/quick-start.mdx +++ b/docs/pages/guides/spend-permissions/quick-start.mdx @@ -170,7 +170,7 @@ export async function getSpenderBundlerClient() { ### Configure the Smart Wallet URL -In `providers.tsx`, update the value of `keysUrl` to be `"https://wallet.chameleon.systems"`. +In `providers.tsx`, update the value of `keysUrl` to be `"https://keys-beta.coinbase.com/connect"`. This will point your app to connect to our public dev environment for smart wallet connections. From b8c81c664ac34d143cb66ed0ec84a8f589a46afc Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Fri, 8 Nov 2024 06:11:54 -0800 Subject: [PATCH 07/10] spencer review comments --- .../spend-permissions/api-reference/client-resources.mdx | 1 + .../api-reference/spendpermissionmanager.mdx | 5 +++-- .../api-reference/wallet-fetchpermissions.mdx | 1 + 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx b/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx index 3ad3241..45413c7 100644 --- a/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx @@ -1,4 +1,5 @@ # Client resources +Recommended libraries for handling blockchain and wallet interactions. The example project in the [Quick Start](/guides/spend-permissions/quick-start.mdx) guide uses all three of these. ### Using Viem [Viem](https://viem.sh/) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. diff --git a/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx b/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx index a793e3c..1c4b5c1 100644 --- a/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx @@ -82,7 +82,7 @@ function getHash(SpendPermission memory spendPermission) public view returns (by #### `isApproved` -Check if a spend permission is approved and not revoked. +Check if a spend permission is approved and not revoked, regardless of whether the current time is within the valid time range of the permission. ```solidity function isApproved(SpendPermission memory spendPermission) public view returns (bool); @@ -93,7 +93,8 @@ function isApproved(SpendPermission memory spendPermission) public view returns #### `getCurrentPeriod` Retrieve the `start`, `end`, and accumulated `spend` for the current period of a spend permission. - +Reverts if the current time is outside the valid time range of the permission, but does not validate whether the +spend permission has been approved or revoked. ```solidity function getCurrentPeriod(SpendPermission memory spendPermission) public view returns (PeriodSpend memory); ``` diff --git a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx index 53cc5af..5648fbc 100644 --- a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx @@ -1,6 +1,7 @@ ## Coinbase Wallet API ### `wallet_fetchPermissions` +A utility API endpoint for recalling permissions previously granted for a specific user. #### Schema ```typescript From 69f46f038aa5d1083a9d7b727b2a7e1427340c1a Mon Sep 17 00:00:00 2001 From: Amie Corso Date: Fri, 8 Nov 2024 09:00:09 -0800 Subject: [PATCH 08/10] add note about expired or revoked permissions --- .../spend-permissions/api-reference/wallet-fetchpermissions.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx index 5648fbc..6ac49d5 100644 --- a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx @@ -2,6 +2,7 @@ ### `wallet_fetchPermissions` A utility API endpoint for recalling permissions previously granted for a specific user. +Excludes any permissions that have been revoked or are expired. #### Schema ```typescript From 33056a7d0ef3d037090a72d82515e0af37d86bba Mon Sep 17 00:00:00 2001 From: Conner Swenberg Date: Sat, 9 Nov 2024 02:11:01 +0700 Subject: [PATCH 09/10] Update keys-beta to keys-dev --- docs/pages/guides/spend-permissions/quick-start.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/guides/spend-permissions/quick-start.mdx b/docs/pages/guides/spend-permissions/quick-start.mdx index b9bb625..0970cbf 100644 --- a/docs/pages/guides/spend-permissions/quick-start.mdx +++ b/docs/pages/guides/spend-permissions/quick-start.mdx @@ -170,7 +170,7 @@ export async function getSpenderBundlerClient() { ### Configure the Smart Wallet URL -In `providers.tsx`, update the value of `keysUrl` to be `"https://keys-beta.coinbase.com/connect"`. +In `providers.tsx`, update the value of `keysUrl` to be `"https://keys-dev.coinbase.com/connect"`. This will point your app to connect to our public dev environment for smart wallet connections. From dadb7ad46093518ee0c3d7fd06fae10bec0fca2a Mon Sep 17 00:00:00 2001 From: Conner Swenberg Date: Sat, 9 Nov 2024 02:47:26 +0700 Subject: [PATCH 10/10] Lint and make nit edits --- .../api-reference/client-resources.mdx | 24 ++++++----- .../api-reference/spendpermissionmanager.mdx | 43 +++++++++++-------- .../api-reference/wallet-fetchpermissions.mdx | 22 +++++----- 3 files changed, 50 insertions(+), 39 deletions(-) diff --git a/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx b/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx index 45413c7..494a46f 100644 --- a/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/client-resources.mdx @@ -1,20 +1,24 @@ -# Client resources +# Client resources + Recommended libraries for handling blockchain and wallet interactions. The example project in the [Quick Start](/guides/spend-permissions/quick-start.mdx) guide uses all three of these. ### Using Viem -[Viem](https://viem.sh/) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. -- **[Getting Started with Viem](https://viem.sh/docs/getting-started.html)** +[Viem](https://viem.sh/) is a TypeScript interface for Ethereum that provides low-level stateless primitives for interacting with Ethereum. -- **[Getting Started with Account Abstraction](https://viem.sh/account-abstraction#getting-started-with-account-abstraction)** - Viem provides support for account abstraction clients, including specific support for Coinbase Smart Wallet and paymasters. +- **[Getting Started with Viem](https://viem.sh/docs/getting-started.html)** -### Using OnchainKit -[OnchainKit](https://onchainkit.xyz/) is a collection of React components and TypeScript utilities that help developers quickly build -onchain applications. +- **[Getting Started with Account Abstraction](https://viem.sh/account-abstraction#getting-started-with-account-abstraction)** + Viem provides support for account abstraction clients, including specific support for Coinbase Smart Wallet and paymasters. ### Using Wagmi + [Wagmi](https://wagmi.sh/) is a collection of React Hooks that facilitate development of blockchain frontends. -- **[Getting Started with Wagmi](https://wagmi.sh/react/getting-started)** -- **[coinbaseWallet](https://wagmi.sh/react/api/connectors/coinbaseWallet)** +- **[Getting Started with Wagmi](https://wagmi.sh/react/getting-started)** +- **[coinbaseWallet](https://wagmi.sh/react/api/connectors/coinbaseWallet)** + +### Using OnchainKit + +[OnchainKit](https://onchainkit.xyz/) is a collection of React components and TypeScript utilities that help developers quickly build +onchain applications. diff --git a/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx b/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx index 1c4b5c1..404518f 100644 --- a/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/spendpermissionmanager.mdx @@ -1,35 +1,39 @@ # `SpendPermissionManager.sol` smart contract + The open-source contracts repository is [here](https://github.com/coinbase/spend-permissions). ### Structs #### `SpendPermission` + Defines the complete parameters of a spend permission. -| Field | Type | Description | -|-------------|----------|-----------------------------------------------------------------------------| -| `account` | `address`| Smart account this spend permission is valid for. | -| `spender` | `address`| Entity that can spend `account`'s tokens. | -| `token` | `address`| Token address (ERC-7528 native token address or ERC-20 contract). | -| `allowance` | `uint160`| Maximum allowed value to spend within each `period`. | -| `period` | `uint48` | Time duration for resetting used `allowance` on a recurring basis (seconds).| -| `start` | `uint48` | Timestamp this spend permission is valid after (unix seconds). | -| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | -| `salt` | `uint256`| An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | -| `extraData` | `bytes` | Arbitrary data to include in the signature. | +| Field | Type | Description | +| ----------- | --------- | ------------------------------------------------------------------------------------------ | +| `account` | `address` | Smart account this spend permission is valid for. | +| `spender` | `address` | Entity that can spend `account`'s tokens. | +| `token` | `address` | Token address (ERC-7528 native token address or ERC-20 contract). | +| `allowance` | `uint160` | Maximum allowed value to spend within each `period`. | +| `period` | `uint48` | Time duration for resetting used `allowance` on a recurring basis (seconds). | +| `start` | `uint48` | Timestamp this spend permission is valid starting at (unix seconds). | +| `end` | `uint48` | Timestamp this spend permission is valid until (unix seconds). | +| `salt` | `uint256` | An arbitrary salt to differentiate unique spend permissions with otherwise identical data. | +| `extraData` | `bytes` | Arbitrary data to include in the permission. | #### `PeriodSpend` + Describes the cumulative spend for the current active period. -| Field | Type | Description | -|-------------|----------|-----------------------------------------------------------------------------| -| `start` | `uint48` | Start time of the period (unix seconds). | -| `end` | `uint48` | End time of the period (unix seconds). | -| `spend` | `uint160`| Accumulated spend amount for period. | +| Field | Type | Description | +| ------- | --------- | ---------------------------------------- | +| `start` | `uint48` | Start time of the period (unix seconds). | +| `end` | `uint48` | End time of the period (unix seconds). | +| `spend` | `uint160` | Accumulated spend amount for period. | --- ### Contract functions + #### `approve` Approve a spend permission via a direct call from the `account`. Only callable by the `account` specified in the spend permission. @@ -55,7 +59,7 @@ function approveWithSignature(SpendPermission calldata spendPermission, bytes ca Spend tokens using a spend permission, transferring them from the `account` to the `spender`. Only callable by the `spender` specified in the permission. ```solidity -function spend(SpendPermission memory spendPermission, uint160 value) external requireSender(spendPermission.spender); +function spend(SpendPermission memory spendPermission, uint160 value) external; ``` --- @@ -65,7 +69,7 @@ function spend(SpendPermission memory spendPermission, uint160 value) external r Revoke a spend permission, permanently disabling its use. Only callable by the `account` owner specified in the spend permission. ```solidity -function revoke(SpendPermission calldata spendPermission) external requireSender(spendPermission.account); +function revoke(SpendPermission calldata spendPermission) external; ``` --- @@ -93,8 +97,9 @@ function isApproved(SpendPermission memory spendPermission) public view returns #### `getCurrentPeriod` Retrieve the `start`, `end`, and accumulated `spend` for the current period of a spend permission. -Reverts if the current time is outside the valid time range of the permission, but does not validate whether the +Reverts if the current time is outside the valid time range of the permission, but does not validate whether the spend permission has been approved or revoked. + ```solidity function getCurrentPeriod(SpendPermission memory spendPermission) public view returns (PeriodSpend memory); ``` diff --git a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx index 6ac49d5..1532a94 100644 --- a/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx +++ b/docs/pages/guides/spend-permissions/api-reference/wallet-fetchpermissions.mdx @@ -1,13 +1,17 @@ ## Coinbase Wallet API ### `wallet_fetchPermissions` + A utility API endpoint for recalling permissions previously granted for a specific user. -Excludes any permissions that have been revoked or are expired. +Excludes permissions that have expired or been revoked. #### Schema + +**Endpoint:** `https://chain-proxy.wallet.coinbase.com?targetName=base-sepolia`. + ```typescript type FetchPermissionsRequest = { - chainId: string; // uint256, hex formatted + chainId: string; // hex, uint256 account: string; // address spender: string; // address pageOptions?: { @@ -24,22 +28,20 @@ type FetchPermissionsResult = { } } -type PageDescription = - type FetchPermissionsResultItem = { createdAt: number; // UTC timestamp for when the permission was granted - permissionHash: string; - signature: string; + permissionHash: string; // hex + signature: string; // hex permission: { account: string; // address spender: string; // address token: string; // address allowance: string; // base 10 numeric string - period: number; // unix time, seconds - start: number; // unix time, seconds - end: number; // unix time, seconds + period: number; // unix seconds + start: number; // unix seconds + end: number; // unix seconds salt: string; // base 10 numeric string - extraData: string // hex formatted bytes, i.e. "0x" for empty data + extraData: string // hex }; } ```