From 5d91cb9b644ef76f7c31e3df6d0cf083adf342ee Mon Sep 17 00:00:00 2001 From: AyushBherwani1998 Date: Tue, 10 Mar 2026 10:32:54 +0530 Subject: [PATCH] update gator-cli SKILL --- metamask/gator-cli/SKILL.md | 118 ++++++++++++------- metamask/gator-cli/references/allow-types.md | 50 ++++++++ 2 files changed, 126 insertions(+), 42 deletions(-) create mode 100644 metamask/gator-cli/references/allow-types.md diff --git a/metamask/gator-cli/SKILL.md b/metamask/gator-cli/SKILL.md index 20ca868..e00c1e8 100644 --- a/metamask/gator-cli/SKILL.md +++ b/metamask/gator-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: gator-cli -description: Use when you need to operate the @metamask/gator-cli to initialize profiles, upgrade EOA to EIP-7702, grant, redeem, and revoke ERC-7710 delegations, or inspect balances and delegations. Covers commands, required flags, grant scopes, redeem action types, configuration locations, and common usage flows. +description: Use when you need to operate the @metamask/gator-cli to initialize profiles, upgrade EOA to EIP-7702, grant, redeem, and revoke ERC-7710 delegations, or inspect balances and delegations. Covers commands, required flags, allow types, redeem action types, configuration locations, and common usage flows. metadata: openclaw: emoji: "🐊" @@ -19,6 +19,30 @@ metadata: Use this skill to run the gator CLI from the repo and to choose the correct command/flags for delegation workflows. +## Grant Decision Flow + +Follow these steps when building a `gator grant` command: + +1. Identify what the user wants to delegate. + +2. Check if the intent matches a **primary allow type**: + - Token transfer with max amount → `erc20TransferAmount` or `nativeTokenTransferAmount` + - Periodic token transfer → `erc20PeriodTransfer` or `nativeTokenPeriodTransfer` + - Token streaming → `erc20Streaming` or `nativeTokenStreaming` + - NFT transfer → `erc721Transfer` + - Ownership transfer → `ownershipTransfer` + - Function call restriction → `functionCall` + +3. If a primary allow type matches: + a. Start with `--allow ` and its required flags (see Primary Allow Types table). + b. Does the user need extra constraints (time limits, call limits, redeemer restrictions, etc.)? + c. If yes → append `--allow ` for each constraint (see Additional Allow Types table). + d. If no → the command is complete. + +4. If NO primary allow type matches the intent: + - Compose the grant using only additional allow types. + - Use one `--allow ` per constraint, each with its own flags. + ## Installation ```sh @@ -90,46 +114,14 @@ Show native balance and optional ERC-20 balance. ### grant -Create, sign, and store a delegation with a predefined scope. - -- `gator grant --to --scope [scope flags] [--profile ]` - -Scope flags: +Create, sign, and store a delegation with one or more allow types. Multiple `--allow` flags can be combined in a single grant to compose constraints. -- Token scopes: `--tokenAddress `, `--maxAmount `, `--tokenId ` -- Periodic scopes: `--periodAmount `, `--periodDuration `, `--startDate ` -- Streaming scopes: `--amountPerSecond `, `--initialAmount `, `--startTime ` -- Function call scope: `--targets `, `--selectors `, `--valueLte ` -- Ownership transfer: `--contractAddress ` +- `gator grant --to --allow [type flags] [--allow [type flags] ...] [--profile ]` -Supported scopes: +Run `gator help grant` for the full list of flags. -- `erc20TransferAmount` -- `erc20PeriodTransfer` -- `erc20Streaming` -- `erc721Transfer` -- `nativeTokenTransferAmount` -- `nativeTokenPeriodTransfer` -- `nativeTokenStreaming` -- `functionCall` -- `ownershipTransfer` +For the full list of allow types with descriptions, required flags, and optional flags, see the [Allow Types Reference](./references/allow-types.md). -Grant flags per scope: - -| Scope | Required Flags | Optional Flags | -| --------------------------- | ----------------------------------------------------------------------- | ---------------- | -| `erc20TransferAmount` | `--tokenAddress`, `--maxAmount` | | -| `erc20PeriodTransfer` | `--tokenAddress`, `--periodAmount`, `--periodDuration` | `--startDate` | -| `erc20Streaming` | `--tokenAddress`, `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime` | -| `erc721Transfer` | `--tokenAddress`, `--tokenId` | | -| `nativeTokenTransferAmount` | `--maxAmount` | | -| `nativeTokenPeriodTransfer` | `--periodAmount`, `--periodDuration` | `--startDate` | -| `nativeTokenStreaming` | `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime` | -| `functionCall` | `--targets`, `--selectors` | `--valueLte` | -| `ownershipTransfer` | `--contractAddress` | | - -- `--startDate` and `--startTime` default to the current time (unix seconds) when omitted. -- `--valueLte` sets the max native token value per call for `functionCall` scopes. ### redeem @@ -182,11 +174,51 @@ gator init --profile gator create --profile ``` -Grant an ERC-20 transfer delegation: +Grant an ERC-20 transfer delegation (primary allow type only): + +```bash +gator grant --profile --to \ + --allow erc20TransferAmount --tokenAddress --maxAmount 50 +``` + +Grant with additional constraints (primary + additional allow types): + +```bash +gator grant --profile --to \ + --allow erc20TransferAmount --tokenAddress --maxAmount 50 \ + --allow limitedCalls --limit 5 +``` + +Time-bounded native transfer delegation: + +```bash +gator grant --profile --to \ + --allow nativeTokenTransferAmount --maxAmount 0.5 \ + --allow timestamp --afterTimestamp 1700000000 --beforeTimestamp 1800000000 +``` + +Redeemer-restricted delegation: + +```bash +gator grant --profile --to \ + --allow nativeTokenTransferAmount --maxAmount 1 \ + --allow redeemer --redeemers 0xADDR1,0xADDR2 +``` + +Restrict targets and methods (additional allow types only, no primary): + +```bash +gator grant --profile --to \ + --allow allowedTargets --allowedTargets 0xContract \ + --allow allowedMethods --allowedMethods "transfer(address,uint256)" +``` + +Custom caveat enforcer: ```bash -gator grant --profile --to --scope erc20TransferAmount \ - --tokenAddress --maxAmount 50 +gator grant --profile --to \ + --allow nativeTokenTransferAmount --maxAmount 1 \ + --allow custom --enforcerAddress 0xDeployed --enforcerTerms 0xEncoded ``` Redeem an ERC-20 transfer: @@ -227,9 +259,11 @@ gator revoke --profile --to ## Operational Notes - **Private key security**: This is alpha version. Private keys are stored in plaintext JSON. Never use accounts with significant funds. +- Run `gator help ` for full flag details on any command. - `--from` refers to the delegator address; `--to` refers to the delegate/recipient. -- `--targets` and `--selectors` are comma-separated lists. -- `--function` accepts a human-readable Solidity function signature like `"approve(address,uint256)"`. Do **not** pass a 4-byte selector (e.g. `0x095ea7b3`) — the CLI derives the selector from the signature automatically. +- `--allowedTargets` and `--redeemers` are comma-separated lists. +- `--allowedMethods` accepts comma-separated human-readable Solidity function signatures like `"approve(address,uint256)"`. Do **not** pass 4-byte selectors. +- `--function` (for `redeem --action functionCall`) accepts a human-readable Solidity function signature like `"approve(address,uint256)"`. The CLI derives the selector automatically. - `--startDate` and `--startTime` accept unix timestamps in seconds. When omitted, they default to the current time. - `--action` is required for `redeem` and must be one of: `erc20Transfer`, `erc721Transfer`, `nativeTransfer`, `functionCall`, `ownershipTransfer`, `raw`. - Supported chains for `--chain` in `gator init`: `base` (default), `baseSepolia`, `sepolia`. diff --git a/metamask/gator-cli/references/allow-types.md b/metamask/gator-cli/references/allow-types.md new file mode 100644 index 0000000..1e20ee8 --- /dev/null +++ b/metamask/gator-cli/references/allow-types.md @@ -0,0 +1,50 @@ +# Allow Types Reference + +This reference lists all allow types available for the `gator grant --allow` flag. See the [Caveats reference](https://docs.metamask.io/smart-accounts-kit/reference/delegation/caveats/) for the full Smart Accounts Kit documentation. + +## Primary Allow Types + +High-level types for common delegation patterns. Use these when the user's intent directly maps to one. + +| Allow Type | Description | Required Flags | Optional Flags | +|---|---|---|---| +| `erc20TransferAmount` | Limit the total amount of an ERC-20 token the delegate can transfer. | `--tokenAddress`, `--maxAmount` | — | +| `erc20PeriodTransfer` | Allow ERC-20 transfers up to a limit per recurring time period. Unused allowance does not carry over. | `--tokenAddress`, `--periodAmount`, `--periodDuration` | `--startDate` | +| `erc20Streaming` | Linear streaming limit for ERC-20 tokens. Releases an initial amount at start, then accrues linearly up to a max. | `--tokenAddress`, `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime` | +| `erc721Transfer` | Restrict execution to only allow transfer of a specific ERC-721 token ID. | `--tokenAddress`, `--tokenId` | — | +| `nativeTokenTransferAmount` | Enforce a maximum allowance of native currency (e.g. ETH) the delegate can transfer. | `--maxAmount` | — | +| `nativeTokenPeriodTransfer` | Allow native token transfers up to a limit per recurring time period. Unused allowance does not carry over. | `--periodAmount`, `--periodDuration` | `--startDate` | +| `nativeTokenStreaming` | Linear streaming limit for native tokens. Releases an initial amount at start, then accrues linearly up to a max. | `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime` | +| `functionCall` | Restrict which contract addresses and methods the delegate can call. | `--allowedTargets`, `--allowedMethods` | `--maxValue` (adds a `valueLte` constraint) | +| `ownershipTransfer` | Restrict execution to only allow `transferOwnership` on a specific contract. | `--contractAddress` | — | + +Notes: +- `--startDate` and `--startTime` default to the current timestamp (unix seconds) when omitted. +- `--maxValue` on `functionCall` adds a `valueLte` constraint to the delegation. + +## Additional Allow Types + +Granular constraint types that can be layered on top of a primary allow type or composed standalone. + +| Allow Type | Description | Required Flags | Optional Flags | +|---|---|---|---| +| `limitedCalls` | Limit the number of times the delegate can redeem the delegation. | `--limit` | — | +| `timestamp` | Restrict the delegation to a time window. Set either threshold to `0` to leave that side unbounded. | — | `--afterTimestamp`, `--beforeTimestamp` (both default to `0`) | +| `blockNumber` | Restrict the delegation to a block number range. Set either threshold to `0` to leave that side unbounded. | — | `--afterBlock`, `--beforeBlock` (both default to `0`) | +| `redeemer` | Limit which addresses can redeem the delegation. Delegator accounts with delegation support can bypass this by re-delegating. | `--redeemers` (comma-separated) | — | +| `nonce` | Attach a nonce to enable bulk revocation by incrementing the nonce on-chain. | `--nonce` (hex) | — | +| `id` | Assign a shared ID across multiple delegations. Once one is redeemed, the others with the same ID are revoked. | `--caveatId` | — | +| `valueLte` | Limit the native token value that can be sent per execution. | `--maxValue` | — | +| `allowedTargets` | Restrict which contract addresses the delegate can call. | `--allowedTargets` (comma-separated) | — | +| `allowedMethods` | Restrict which methods the delegate can call. Accepts function signatures or 4-byte selectors. | `--allowedMethods` (comma-separated) | — | +| `allowedCalldata` | Enforce that calldata at a specific byte index matches an expected value. Useful for validating static function parameters. | `--calldataStartIndex`, `--calldataValue` | — | +| `argsEqualityCheck` | Ensure the args provided when redeeming match the specified terms exactly. | `--argsCheck` (hex) | — | +| `exactCalldata` | Verify that the entire transaction calldata matches the expected value exactly. | `--exactCalldata` (hex) | — | +| `exactExecution` | Verify that the execution matches an exact target, value, and calldata. | `--execTarget` | `--execValue` (default `0`), `--execCalldata` (default `0x`) | +| `nativeTokenPayment` | Require payment in native token (e.g. ETH) to use the delegation. | `--paymentRecipient`, `--paymentAmount` | — | +| `nativeBalanceChange` | Ensure the recipient's native token balance changes by at least (increase) or at most (decrease) a specified amount. | `--nativeBalanceRecipient`, `--nativeBalanceAmount`, `--nativeBalanceChangeType` | — | +| `erc20BalanceChange` | Ensure the recipient's ERC-20 balance changes within allowed bounds. | `--erc20BalanceToken`, `--erc20BalanceRecipient`, `--erc20BalanceAmount`, `--erc20BalanceChangeType` | — | +| `erc721BalanceChange` | Ensure the recipient's ERC-721 balance changes within allowed bounds. | `--erc721BalanceToken`, `--erc721BalanceRecipient`, `--erc721BalanceAmount`, `--erc721BalanceChangeType` | — | +| `erc1155BalanceChange` | Ensure the recipient's ERC-1155 token balance changes within allowed bounds. | `--erc1155BalanceToken`, `--erc1155BalanceRecipient`, `--erc1155BalanceTokenId`, `--erc1155BalanceAmount`, `--erc1155BalanceChangeType` | — | +| `deployed` | Ensure a contract is deployed at the specified address; deploys it if not. | `--deployAddress`, `--deploySalt`, `--deployBytecode` | — | +| `custom` | Use an arbitrary caveat enforcer contract with custom encoded terms. | `--enforcerAddress`, `--enforcerTerms` | — |