### Quick Start: Run Clear Signing Tests

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/tester/README.md

Execute the setup script, set the gating token, and run tests on a specified descriptor and test file pair. The 'flex' argument indicates the testing mode.

```bash
# 1. Run setup (only needed once)
./setup.sh

# 2. Set your gating token
export GATING_TOKEN='your-token-here'

# 3. Run tests on a descriptor
./run-test.sh \
    ../../registry/circle/eip712-TransferWithAuthorization.json \
    ../../registry/circle/tests/eip712-TransferWithAuthorization.tests.json \
    flex
```

--------------------------------

### Install Prerequisites on Ubuntu/Debian

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/tester/README.md

Installs necessary tools like jq and Docker, and configures user permissions for Docker. Also installs the pnpm package manager globally.

```bash
# Ubuntu/Debian
sudo apt update && sudo apt install -y jq docker.io
sudo usermod -aG docker $USER  # Log out and back in after this

# Install pnpm
npm install -g pnpm
```

--------------------------------

### Install clearsig CLI Tool

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/auditors/README.md

Installs the clearsig command-line interface. Use uv, pipx, or pip for installation.

```bash
uv tool install clearsig    # or: pipx install clearsig / pip install clearsig
```

--------------------------------

### Install Dependencies

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Installs necessary Node.js packages for the project. Run this from the repository root.

```bash
npm install
```

--------------------------------

### Setup ERC7730 from Local Clone

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Clone the repository and run the setup script for local development or to use unreleased changes.

```bash
cd tools/linter
./setup.sh
```

--------------------------------

### Install ERC7730 using uv

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Install the ERC7730 linter using the uv tool for faster dependency management.

```bash
uv tool install erc7730
```

--------------------------------

### Set up Environment Variables from Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Copy the example environment file and edit it with your API keys and other necessary variables. Then, source the file to load them into your current shell session.

```bash
# Option 1: Source from the env template
cp tools/scripts/env.example .env
# Edit .env with your keys
source .env
```

--------------------------------

### Install erc7730 CLI (Optional)

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Install the erc7730 CLI using pip. This is an optional but recommended step for enhanced functionality.

```bash
# Install erc7730 CLI (optional but recommended)
pip install erc7730
```

--------------------------------

### EIP-712 Deployment Configuration Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/prompts/system-eip712.md

Example JSON snippet for configuring EIP-712 deployments, including a placeholder for the contract address when it's unknown.

```json
{
  "$comment": "TODO: Fill in actual deployment addresses",
  "deployments": [
    { "chainId": 1, "address": "0x0000000000000000000000000000000000000000" }
  ]
}
```

--------------------------------

### Install js-sha3 for Keccak-256

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Install the js-sha3 package to ensure accurate Keccak-256 computation, which is necessary for resolving function selector mismatches.

```bash
npm install js-sha3
```

--------------------------------

### Install and Build Libraries in dmk Directory

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/tester/README.md

Install dependencies with force and build libraries within the 'dmk' directory to resolve build errors. Some warnings can be safely ignored.

```bash
cd dmk
pnpm install --force
pnpm build:libs
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Install the necessary Node.js dependencies for the batch processor script using npm.

```bash
# Install Node.js dependencies
npm install
```

--------------------------------

### Install GitHub CLI (gh)

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Install the GitHub CLI, required for PR creation and authentication. Use Homebrew on macOS or apt on Linux.

```bash
# macOS
brew install gh
```

```bash
# Linux
sudo apt install gh
```

```bash
# Then authenticate
gh auth login
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Install the GitHub CLI using package managers for macOS or Linux. Authentication is required for PR creation.

```bash
# macOS
brew install gh

# Linux
sudo apt install gh

# Authenticate
gh auth login
```

--------------------------------

### Copy and Source Environment File

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Copy the example environment file and source it to load your API keys and tokens. Edit the .env file with your specific keys.

```bash
cp tools/scripts/env.example .env
# Edit .env with your keys
source .env
```

--------------------------------

### Install js-sha3 Dependency

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Install the js-sha3 dependency using npm or yarn for proper function selector computation. This is an optional dependency.

```bash
npm install js-sha3
```

```bash
yarn add js-sha3
```

--------------------------------

### Install erc7730 as a uv-managed Tool

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/README.md

Installs the `erc7730` package as a persistent tool managed by `uv`. This allows direct execution of `erc7730` commands.

```bash
uv tool install erc7730
```

```bash
erc7730 lint registry/
```

--------------------------------

### Install pnpm Globally

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/tester/README.md

Install the pnpm package manager globally using npm. This is necessary if 'pnpm not found' errors occur.

```bash
npm install -g pnpm
```

--------------------------------

### Run with dotenv Package

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Install the dotenv package and use it to preload environment variables from a .env file when running the script.

```bash
# Install dotenv
npm install dotenv

# Create .env file from template
cp tools/scripts/env.example .env
# Edit .env with your keys...

# Run with dotenv preloading
node -r dotenv/config tools/scripts/generate-tests.js registry/file.json
```

--------------------------------

### Display Format Using Metadata Enums

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

This example shows how a field can be formatted using a predefined enumeration from the metadata section.

```json
{
  "display": {
    "formats": {
      "repay(address asset, uint256 amount, uint256 interestRateMode)": {
        "$id": "repay",
        "intent": "Repay loan",
        "fields": [
          {
            "path": "amount",
            "format": "tokenAmount",
            "label": "Amount to repay",
            "params": { "tokenPath": "asset" }
          },
          {
            "path": "interestRateMode",
            "format": "enum",
            "label": "Interest rate mode",
            "params": { "$ref": "$.metadata.enums.interestRateMode" }
          }
        ],
        "required": ["amount", "interestRateMode"]
      }
    }
  }
}
```

--------------------------------

### Generated Registry Files Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

The script outputs JSON files for calldata and EIP-712 descriptors into a specified directory, following a defined naming convention.

```text
registry/myprotocol/
├── calldata-MyContract.json          # Calldata descriptor
├── eip712-Permit.json                # EIP-712 descriptor (if applicable)
└── eip712-TransferWithAuth.json      # Additional EIP-712 descriptors
```

--------------------------------

### EIP-712 Format Key Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/prompts/system-eip712.md

Illustrates the EIP-712 encodeType format, including how to represent nested structs alphabetically.

```text
PrimaryType(type1 field1,type2 field2,...)
```

```text
PrimaryType(SubType sub,uint256 value) SubType(address addr,uint256 amount)
```

--------------------------------

### Adding a New Block Explorer Provider

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Example of how to extend the PROVIDERS object to support a new block explorer API.

```javascript
const PROVIDERS = {
  // ... existing providers
  12345: {  // Chain ID
    name: "NewExplorer",
    baseUrl: "api.newexplorer.io",
    apiKeyEnv: "NEWEXPLORER_API_KEY",
    explorerUrl: "https://newexplorer.io/tx/",
  },
};
```

--------------------------------

### Calldata Test File Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/README.md

Example of a JSON test file for a calldata-based ERC-7730 descriptor. Includes mock data provider for tokens and addresses, and a sample test case.

```json
{
  "$schema": "../../../specs/erc7730-tests-v2.schema.json",
  "descriptor": "../calldata-MyContract.json",
  "dataProvider": {
    "tokens": {
      "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": { "symbol": "USDC", "decimals": 6, "name": "USD Coin" }
    },
    "addressNames": {
      "0x1234567890123456789012345678901234567890": "Treasury"
    },
    "ensNames": {
      "0xabcdef0123456789abcdef0123456789abcdef01": "alice.eth"
    }
  },
  "tests": [
    {
      "description": "Approve 100 USDC for Treasury",
      "rawTx": "0x02f8b0...",
      "txHash": "0x1234...abcd",
      "expected": {
        "intent": "Approve",
        "owner": "MyProtocol",
        "fields": [
          { "label": "Spender", "value": "Treasury" },
          { "label": "Amount", "value": "100 USDC" }
        ]
      }
    }
  ]
}
```

--------------------------------

### Install ERC7730 from PyPI using pip

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Use this command to install the ERC7730 linter package directly from the Python Package Index.

```bash
pip install erc7730
```

--------------------------------

### EIP-712 Test File Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/README.md

Example of a JSON test file for an EIP-712 based ERC-7730 descriptor. It specifies the descriptor and includes a test case with EIP-712 typed data.

```json
{
  "$schema": "../../../specs/erc7730-tests-v2.schema.json",
  "descriptor": "../eip712-MyMessage.json",
  "tests": [
    {
      "description": "Permit 100 USDC",
      "data": {
        "types": { ... },
        "primaryType": "Permit",
        "domain": { ... },
        "message": { ... }
      },
      "expected": {
        "intent": "Permit",
        "owner": "MyProtocol",
        "fields": [
          { "label": "Spender", "value": "0x1234..." },
          { "label": "Amount", "value": "100 USDC" }
        ]
      }
    }
  ]
}
```

--------------------------------

### Example Metadata Constants

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

This snippet introduces a constant `nativeAssetAddress` which can be referenced using its path.

```json
{
    "metadata": {
        "constants": {
            "nativeAssetAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
        }
    }
}
```

--------------------------------

### Example Metadata Enums

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

This snippet introduces an enumeration for `interestRateMode` and a dynamic enumeration for `vaultIDs` retrievable via a URL.

```json
{
    "metadata": {
        "enums": {
            "interestRateMode": {
                "1": "stable",
                "2": "variable"
            },
            "vaultIDs": "https://example.com/vaultIDs"
        }
    }
}
```

--------------------------------

### Example Script Execution

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Execute the ERC-7730 test generator script with Etherscan API key, input JSON file, and dry-run/verbose flags. This command demonstrates how to initiate the test generation process without writing any files.

```bash
$ ETHERSCAN_API_KEY="your-api-key" \
  node tools/scripts/generate-tests.js registry/ethena/calldata-ethena.json --dry-run --verbose
```

--------------------------------

### Example Solidity Contract

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

A sample Solidity contract with a struct and a function, used to illustrate ERC-7730 structured data formatting.

```solidity
pragma solidity ^0.8.0;

contract MyContract {

    struct MyParamType {
        string name;
        uint256 value;
    }

    // Function declaration
    function myFunction(address _address, uint256 _amount, MyParamType memory _param) public {
        // Function logic here
    }
}
```

--------------------------------

### ERC7730 Registry v1 Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/migrate-v1-to-v2.README.md

This is an example of an ERC7730 registry configuration in version 1. It includes schema definition, contract context with ABI, metadata, and display formats.

```json
{
  "$schema": "../../specs/erc7730-v1.schema.json",
  "context": {
    "$id": "Staked USDe",
    "contract": {
      "deployments": [{ "chainId": 1, "address": "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497" }],
      "abi": [
        {
          "type": "function",
          "name": "cooldownShares",
          "inputs": [{ "name": "shares", "type": "uint256" }],
          "outputs": [{ "name": "assets", "type": "uint256" }],
          "stateMutability": "nonpayable"
        }
      ],
      "addressMatcher": null
    }
  },
  "metadata": {
    "owner": "Ethena",
    "info": { "legalName": "Ethena", "url": "https://ethena.fi/" }
  },
  "display": {
    "formats": {
      "cooldownShares(uint256)": {
        "$id": null,
        "intent": "Cooldown Shares",
        "screens": null,
        "fields": [
          {
            "$id": null,
            "label": "Amount",
            "format": "tokenAmount",
            "params": { "token": "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497" },
            "path": "#.shares",
            "value": null
          }
        ],
        "required": ["#.shares"],
        "excluded": null
      }
    }
  }
}
```

--------------------------------

### Run erc7730 Commands with uvx

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/README.md

Executes `erc7730` commands without prior installation using `uvx`. This is useful for ad-hoc command execution.

```bash
uvx erc7730 lint registry/**/eip712-*.json registry/**/calldata-*.json
```

```bash
uvx erc7730 format
```

--------------------------------

### ERC-7730 Calldata Descriptor v2 Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/prompts/system-calldata.md

A complete example of an ERC-7730 v2 calldata descriptor, demonstrating field visibility, intent formatting, and metadata for a WrappedTokenGatewayV3 contract.

```json
{
  "$schema": "../../specs/erc7730-v2.schema.json",
  "context": {
    "$id": "WrappedTokenGatewayV3",
    "contract": {
      "deployments": [
        { "chainId": 1, "address": "0xd01607c3C5eCABa394D8be377a08590149325722" }
      ]
    }
  },
  "metadata": {
    "owner": "Aave",
    "contractName": "WrappedTokenGatewayV3",
    "info": { "url": "https://aave.com" }
  },
  "display": {
    "formats": {
      "depositETH(address pool, address onBehalfOf, uint16 referralCode)": {
        "intent": "Supply",
        "interpolatedIntent": "Supply ETH on behalf of {onBehalfOf}",
        "fields": [
          { "path": "@.value", "format": "amount", "label": "Amount to supply" },
          {
            "path": "onBehalfOf",
            "format": "addressName",
            "label": "Recipient",
            "params": { "types": ["eoa"], "sources": ["local", "ens"] }
          },
          { "path": "referralCode", "label": "Referral code", "format": "raw", "visible": "never" },
          { "path": "pool", "label": "Pool", "format": "addressName", "visible": "never" }
        ]
      },
      "withdrawETH(address pool, uint256 amount, address to)": {
        "intent": "Withdraw",
        "interpolatedIntent": "Withdraw {amount} to {to}",
        "fields": [
          { "path": "amount", "format": "amount", "label": "Amount to withdraw" },
          {
            "path": "to",
            "format": "addressName",
            "label": "Recipient",
            "params": { "types": ["eoa"], "sources": ["local", "ens"] }
          },
          { "path": "pool", "label": "Pool", "format": "addressName", "visible": "never" }
        ]
      }
    }
  }
}
```

--------------------------------

### ERC7730 Registry v2 Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/migrate-v1-to-v2.README.md

This is an example of an ERC7730 registry configuration after migrating to version 2. It reflects updated schema, contract context, metadata, and display format definitions.

```json
{
  "$schema": "../../specs/erc7730-v2.schema.json",
  "context": {
    "$id": "Staked USDe",
    "contract": {
      "deployments": [
        { "chainId": 1, "address": "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497" }
      ]
    }
  },
  "metadata": {
    "owner": "Ethena",
    "info": { "url": "https://ethena.fi/" },
    "contractName": "Staked USDe"
  },
  "display": {
    "formats": {
      "cooldownShares(uint256 shares)": {
        "intent": "Cooldown Shares",
        "fields": [
          {
            "label": "Amount",
            "format": "tokenAmount",
            "params": { "token": "0x9D39A5DE30e57443BfF2A8307A4256c8797A3497" },
            "path": "#.shares",
            "visible": "always"
          }
        ]
      }
    }
  }
}
```

--------------------------------

### Generate Descriptors from Address (Mainnet)

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Generates descriptors using only the contract address. The script automatically fetches ABI and source code from Sourcify or Etherscan. This example targets the Tether contract on Ethereum mainnet.

```bash
# Minimal: address + output directory (tries Sourcify, then Etherscan)
node tools/scripts/generate-7730.js \
  --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --output registry/tether \
  --name "Tether"
```

--------------------------------

### Generate Tests and Use Local API Server

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Generates tests and directs the tester to use a local API server that is started by the script itself. This is useful for isolated testing. Ensure .env is sourced and Docker is running.

```bash
source .env && node tools/scripts/generate-tests.js registry/ethena/calldata-ethena.json --local-api
```

--------------------------------

### Generate Descriptors from Address (Polygon)

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Generates descriptors using the contract address and specifies a chain ID. This example targets a contract on Polygon (chain ID 137).

```bash
# With chain ID (default is 1 / Ethereum mainnet)
node tools/scripts/generate-7730.js \
  --address 0x794a61358D6845594F94dc1DB02A252b5b4814aD \
  --chain 137 \
  --output registry/aave \
  --name "Aave"
```

--------------------------------

### EIP-712 TransferWithAuthorization Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/prompts/system-eip712.md

This JSON defines the structure for a TransferWithAuthorization message according to EIP-712, including domain separation, deployment information, and display formats for user-friendly intent presentation.

```json
[
  {
    "filename": "eip712-TransferWithAuthorization.json",
    "descriptor": {
      "$schema": "../../specs/erc7730-v2.schema.json",
      "context": {
        "$id": "TransferWithAuthorization",
        "eip712": {
          "domain": { "name": "USD Coin", "version": "2" },
          "deployments": [
            { "chainId": 1, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }
          ]
        }
      },
      "metadata": {
        "owner": "Circle",
        "contractName": "FiatTokenV2",
        "info": { "url": "https://www.circle.com/" }
      },
      "display": {
        "formats": {
          "TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)": {
            "intent": "Authorize transfer",
            "interpolatedIntent": "Authorize transfer of {value} from {from} to {to}",
            "fields": [
              {
                "path": "from",
                "label": "From",
                "format": "addressName",
                "params": { "types": ["wallet"], "sources": ["local", "ens"] }
              },
              {
                "path": "to",
                "label": "To",
                "format": "addressName",
                "params": { "types": ["eoa", "contract"], "sources": ["local", "ens"] }
              },
              {
                "path": "value",
                "label": "Amount",
                "format": "tokenAmount",
                "params": { "tokenPath": "@.to" }
              },
              {
                "path": "validAfter",
                "label": "Valid after",
                "format": "date",
                "params": { "encoding": "timestamp" }
              },
              {
                "path": "validBefore",
                "label": "Valid before",
                "format": "date",
                "params": { "encoding": "timestamp" }
              },
              {
                "path": "nonce",
                "label": "Nonce",
                "format": "raw",
                "visible": "never" 
              }
            ]
          }
        }
      }
    }
  }
]
```

--------------------------------

### Run Migration Script: Dry Run with Verbose Output

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/migrate-v1-to-v2.README.md

Perform a dry run of the migration script with verbose output enabled to get detailed information about the changes being previewed. This helps in understanding the script's process.

```bash
node tools/scripts/migrate-v1-to-v2.js --dry-run --verbose
```

--------------------------------

### Run Analyzer with uv

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Execute the analyzer using uv for dependency management. Navigate to the analyzer directory first.

```bash
cd tools/analyzer/erc7730-analyzer
uv run analyze_7730 --erc7730_file <path-to-descriptor>
```

--------------------------------

### ERC7730 CLI Help

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Display all available commands and options for the erc7730 CLI.

```bash
erc7730 --help
```

--------------------------------

### Activate Virtual Environment and Run Analyzer with pip

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Activate the project's virtual environment and then run the analyzer directly.

```bash
source tools/analyzer/erc7730-analyzer/.venv/bin/activate
analyze_7730 --erc7730_file <path-to-descriptor>
```

--------------------------------

### EIP-712 Schema Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

An example of an EIP-712 schema structure as required for ERC-7730 context. This defines the types and primary type for an EIP-712 message.

```json
{
    "context": {
        "eip712": {
            "schemas": [
                {
                    "types": {
                        "EIP712Domain": [
                            { "name": "name", "type": "string" },
                            { "name": "version", "type": "string" },
                            { "name": "chainId", "type": "uint256" },
                            { "name": "verifyingContract", "type": "address" }
                        ],
                        "Person": [
                            { "name": "name", "type": "string" },
                            { "name": "wallet", "type": "address" }
                        ],
                        "Mail": [
                            { "name": "from", "type": "Person" },
                            { "name": "to", "type": "Person" },
                            { "name": "contents", "type": "string" }
                        ]
                    },
                    "primaryType": "Mail"
                }
            ]
        }
    }
}
```

--------------------------------

### Processing a New Protocol with Batch Script

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Use this command to preview or run the batch processing for a new protocol. Load API keys from a .env file before running the actual processing.

```bash
# 1. Preview what will happen
node tools/scripts/batch-process.js newprotocol --dry-run --verbose

# 2. Run the actual processing
source .env  # Load API keys
node tools/scripts/batch-process.js newprotocol

# 3. Review the PR
# The script outputs the PR URL

```

--------------------------------

### Activate Environment and Source .env

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Source the .env file for API keys and activate the virtual environment before running linter commands.

```bash
source .env && source tools/linter/.venv/bin/activate
```

--------------------------------

### Run Full Migration on All Registry Files

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/migrate-v1-to-v2.README.md

Execute the migration script to process all registry files in the project. This performs a full migration without any specific file targeting or options.

```bash
node tools/scripts/migrate-v1-to-v2.js
```

--------------------------------

### Using Azure OpenAI with CLI Arguments

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Configure Azure OpenAI integration using command-line arguments, specifying the Azure endpoint and API key.

```bash
# Using CLI arguments
node tools/scripts/generate-tests.js registry/uniswap/eip712-uniswap.json \
  --azure \
  --openai-url "https://YOUR-RESOURCE.openai.azure.com/openai/deployments/YOUR-DEPLOYMENT/chat/completions?api-version=2024-02-15-preview" \
  --openai-key "YOUR-AZURE-API-KEY"
```

--------------------------------

### Run Analyzer with OpenAI Backend

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Utilize the OpenAI backend for analysis, specifying the model. Ensure OPENAI_API_KEY is set.

```bash
uv run analyze_7730 --erc7730_file ../../../registry/uniswap/calldata-UniswapV3Router.json \
  --backend openai --model gpt-4o
```

--------------------------------

### Generate Registry with Cursor Backend

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Use this command to generate a registry with the Cursor backend. This backend does not require an API key as it uses your Cursor subscription.

```bash
node tools/scripts/generate-7730.js \
  --address 0x1234... \
  --output registry/myprotocol \
  --backend cursor
```

--------------------------------

### Activate Environment and Lint Registry

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

A one-liner command to activate the environment, source .env, and immediately lint the registry directory.

```bash
source .env && source tools/linter/.venv/bin/activate && erc7730 lint registry/
```

--------------------------------

### Generate Registry with OpenAI Backend

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Use this command to generate a registry using the OpenAI backend. Ensure you have set the OPENAI_API_KEY environment variable.

```bash
node tools/scripts/generate-7730.js \
  --address 0x1234... \
  --output registry/myprotocol \
  --backend openai \
  --model gpt-4o
```

--------------------------------

### Run Analyzer with Cursor Backend

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Execute the analyzer using the Cursor backend. This method does not require an API key as it leverages the Cursor agent CLI.

```bash
uv run analyze_7730 --erc7730_file ../../../registry/uniswap/calldata-UniswapV3Router.json \
  --backend cursor
```

--------------------------------

### ERC-7730 Structured Data with Flattened Fields

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

An equivalent representation of the previous example, but with flattened field definitions for better compatibility with resource-limited wallets.

```json
{
    "display": {
        "formats": {
            "myFunction(address _address,uint256 _amount,MyParamType _param)" : {
                "fields": [
                    { "path":"_param.name", "$ref": "$.display.definitions.itemName" },
                    { "path":"_param.value", "$ref": "$.display.definitions.itemReference" }
                ]
            }
        }
    }
}
```

--------------------------------

### Run ERC7730 Tests

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/tester/README.md

Execute tests using a descriptor file and a test file. Optional arguments include the target device and log level.

```bash
./run-test.sh <descriptor-file> <test-file> [device] [log-level]
```

```bash
# Test Circle EIP-712 descriptor on Flex
./run-test.sh \
    ../../registry/circle/eip712-TransferWithAuthorization.json \
    ../../registry/circle/tests/eip712-TransferWithAuthorization.tests.json \
    flex

```

```bash
# Test 1inch calldata descriptor on Stax with debug logging
./run-test.sh \
    ../../registry/1inch/calldata-AggregationRouterV6.json \
    ../../registry/1inch/tests/calldata-AggregationRouterV6.tests.json \
    stax \
    debug

```

```bash
# Test on Nano S Plus
./run-test.sh \
    ../../registry/uniswap/eip712-permit2.json \
    ../../registry/uniswap/tests/eip712-permit2.tests.json \
    nanosp

```

--------------------------------

### EIP-712 Struct Definition Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/prompts/system-eip712.md

This Solidity struct definition illustrates the structure of an EIP-712 message. The fields and their types must align with the corresponding type hash definition.

```solidity
struct Permit {
    address owner;
    address spender;
    uint256 value;
    uint256 nonce;
    uint256 deadline;
}
```

--------------------------------

### Auditor Profile Configuration

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/auditors/README.md

Create a profile.json file in the auditors directory to get listed in the registry. The folder name serves as your identifier. ENS and organization are optional fields.

```json
{
  "id": "eip155:1:0xYourAddress",
  "name": "Your Name",
  "ens": "yourname.eth",
  "organization": "Your Org"
}
```

--------------------------------

### Set Environment Variables for Analyzer

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Configure necessary API keys and settings by adding them to a .env file. Source this file before running the analyzer.

```bash
ETHERSCAN_API_KEY=your_etherscan_key

# LLM backend keys (only the one matching your --backend choice is needed)
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# Optional
COREDAO_API_KEY=your_coredao_key   # For Core DAO chain (1116)
LOOKBACK_DAYS=20                    # Transaction lookback period (default: 20)
```

--------------------------------

### Using Azure OpenAI with Environment Variables

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Configure Azure OpenAI integration by setting environment variables for the Azure endpoint and API key. Ensure AZURE_OPENAI is set to true.

```bash
# Using environment variables
export AZURE_OPENAI=true
export LLM_BASE_URL="https://YOUR-RESOURCE.openai.azure.com/openai/deployments/YOUR-DEPLOYMENT/chat/completions?api-version=2024-02-15-preview"
export OPENAI_API_KEY="YOUR-AZURE-API-KEY"
node tools/scripts/generate-tests.js registry/uniswap/eip712-uniswap.json
```

--------------------------------

### Displaying the Last Element of an Array

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

This example shows how to display the last element of an array using an array slice. The 'pools.[-1]' path targets the final element, which will be displayed using the 'raw' format.

```json
{
    "display": {
        "formats": {
              "0xb2f1e6db": {
                "fields": [
                    {
                        "path": "pools.[-1]",
                        "label": "Last pool",
                        "format": "raw"
                    }
                ]
            }
        }
    }
}
```

--------------------------------

### Run Analyzer with Anthropic Backend

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Use the Anthropic backend for analysis, specifying the model. Ensure ANTHROPIC_API_KEY is set.

```bash
uv run analyze_7730 --erc7730_file ../../../registry/uniswap/calldata-UniswapV3Router.json \
  --backend anthropic --model claude-sonnet-4-20250514
```

--------------------------------

### Generate Registry with Anthropic Backend

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-7730.README.md

Use this command to generate a registry with the Anthropic backend. Ensure you have set the ANTHROPIC_API_KEY environment variable.

```bash
node tools/scripts/generate-7730.js \
  --address 0x1234... \
  --output registry/myprotocol \
  --backend anthropic \
  --model claude-sonnet-4-20250514
```

--------------------------------

### ERC-7730 Simple Transfer Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

This JSON defines how to clear sign an ERC-20 transfer function call. It specifies contract context, metadata, and display formats for parameters like recipient address and transfer amount.

```json
{
    "$schema": "https://github.com/LedgerHQ/clear-signing-erc7730-registry/blob/master/specs/erc7730-v1.schema.json",

    "context": {
        "$id": "Tether USD",
        "contract" : {
            "abi": "https://api.etherscan.io/api?module=contract&action=getabi&address=0xdac17f958d2ee523a2206206994597c13d831ec7",
            "deployments": [
                {
                    "chainId": 1,
                    "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
                },
                {
                    "chainId": 137,
                    "address": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F"
                },
                {
                    "chainId": 42161,
                    "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9"
                }
            ]
        }
    },

    "metadata": {
        "owner": "Tether",
        "info": {
            "legalName": "Tether Limited",
            "url": "https://tether.to/",
            "deploymentDate": "2017-11-28T12:41:21Z"
        }
    },

    "display": {
        "formats": {
            "transfer(address _to,uint256 _value)": {
                "intent": "Send",
                "fields": [
                    {
                        "path": "_to",
                        "label": "To",
                        "format": "addressOrName"
                    },
                    {
                        "path": "_value",
                        "label": "Amount",
                        "format": "tokenAmount",
                        "params": {
                            "tokenPath": "@.to"
                        }
                    }
                ],
                "required": ["_to", "_value"],
                "excluded": []
            }
        }
    }
}

```

--------------------------------

### EIP-712 Type Hash Definition Example

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/prompts/system-eip712.md

This snippet shows a common pattern for defining EIP-712 type hashes in Solidity. Ensure the type name and field definitions match the actual EIP-712 message structure.

```solidity
bytes32 constant TYPEHASH = keccak256("TypeName(type1 field1,type2 field2,...)");
```

```solidity
bytes32 constant TYPE_HASH = keccak256("...");
```

```solidity
bytes32 constant _PERMIT_TYPEHASH = keccak256("Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)");
```

--------------------------------

### Analyze Registry Descriptor with uv

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Perform an analysis of a specific ERC-7730 registry descriptor file using uv.

```bash
source .env
cd tools/analyzer/erc7730-analyzer
uv run analyze_7730 --erc7730_file ../../../registry/uniswap/calldata-UniswapV3Router.json
```

--------------------------------

### Batch Process with Full Path

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

Specify the full path to the registry folder when running the batch processor.

```bash
# Full path syntax
node tools/scripts/batch-process.js registry/morpho
```

--------------------------------

### Migrate Single File

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/migrate-v1-to-v2.README.md

Use the script to migrate a specific registry file. Provide the file path using the --file argument.

```bash
node tools/scripts/migrate-v1-to-v2.js --file registry/ethena/calldata-ethena.json
```

--------------------------------

### Generate Descriptor from ABI

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Create a new descriptor file by providing the path to an ABI file.

```bash
erc7730 generate <abi-path>
```

--------------------------------

### Copy and Edit .env Template

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Copy the environment variable template and edit it with your API keys. This is the recommended method for setting up environment variables.

```bash
# Copy the template to .env in the project root
cp tools/scripts/env.example .env

# Edit .env and add your API keys
nano .env  # or use your preferred editor

# Source the file before running
source .env && node tools/scripts/generate-tests.js registry/file.json
```

--------------------------------

### Check All Supported Chains

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/check-contract-functions.README.md

Validate the descriptor file against all chains supported by the configured explorers and API key. Ensure the ETHERSCAN_API_KEY is set in the environment.

```bash
source .env && node tools/scripts/check-contract-functions.js 
  --file registry/midas/calldata-MinterVault.json 
  --all-chains
```

--------------------------------

### Source .env for Etherscan API Key

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Load the ETHERSCAN_API_KEY from the .env file into the current shell session.

```bash
source .env
```

--------------------------------

### Run Script with Descriptor File

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/check-contract-functions.README.md

Execute the script by providing the path to the descriptor JSON file. This is the primary way to initiate the contract function check.

```bash
node tools/scripts/check-contract-functions.js --file <descriptor.json> [options]
```

```bash
node tools/scripts/check-contract-functions.js <descriptor.json> [options]
```

--------------------------------

### Single File Check (Default Chain)

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/check-contract-functions.README.md

Run the script for a specific descriptor file, defaulting to the Ethereum mainnet (chain ID 1) for validation.

```bash
source .env && node tools/scripts/check-contract-functions.js \
  --file registry/midas/calldata-MinterVault.json
```

--------------------------------

### Format Descriptor Files

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Format a descriptor file at the specified path to ensure consistent style.

```bash
erc7730 format <path>
```

--------------------------------

### Analyze with Debug Output and Custom Lookback

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/analyzer/README.md

Run the analyzer with debug logging enabled and specify a custom number of days for transaction lookback.

```bash
uv run analyze_7730 --erc7730_file ../../../registry/uniswap/calldata-UniswapV3Router.json --debug --lookback-days 30
```

--------------------------------

### Submit Attestation PR

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/auditors/README.md

After signing an attestation, save the raw data as a JSON file and submit it via a Pull Request to the registry. Create the 'sigs' folder if it does not exist.

```bash
registry/<project>/sigs/<descriptorname>.eip155-1-0xYourAddress.json
```

--------------------------------

### Generate Tests and Run Tester on Ledger Flex

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Generates tests for a given JSON file and runs the clear signing tester on the default Ledger Flex device. Ensure the .env file is sourced and Docker is running.

```bash
source .env && node tools/scripts/generate-tests.js registry/ethena/calldata-ethena.json
```

--------------------------------

### Migrating v1 Files with Batch Script (Skip Tests)

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/batch-process.README.md

This command migrates all v1 files in a specified folder to v2, skipping the test generation step.

```bash
# Skip test generation, just migrate
node tools/scripts/batch-process.js oldprotocol --skip-tests

```

--------------------------------

### Basic Usage of Test Generator

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Execute the test generator script with the path to the ERC-7730 file as the primary argument.

```bash
node tools/scripts/generate-tests.js <erc7730-file>
```

--------------------------------

### Applying Formats to All Array Elements

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/specs/erc-7730.md

This snippet illustrates applying a list of formats to all elements within an array. The 'details.[]' path selector targets every item in the 'details' array, applying the specified 'tokenAmount' and 'date' formats.

```json
{
    "display": {
        "formats": {
            "PermitBatch": {
                "fields": [
                    {
                        "path": "details.[]",
                        "fields": [
                            {
                                "path": "amount",
                                "label": "Amount allowance",
                                "format": "tokenAmount",
                                "params": {
                                    "tokenPath": "token"
                                }
                            },
                            {
                                "path": "expiration",
                                "label": "Approval expires",
                                "format": "date",
                                "params": {
                                    "encoding": "timestamp"
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}
```

--------------------------------

### Generate Tests and Skip Tester

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Generates tests for a given JSON file but explicitly skips running the clear signing tester. Use this when you only need test file generation. Requires sourcing .env.

```bash
source .env && node tools/scripts/generate-tests.js registry/ethena/calldata-ethena.json --no-test
```

--------------------------------

### Export Etherscan API Key Directly

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/linter/README.md

Set the ETHERSCAN_API_KEY environment variable directly in the shell.

```bash
export ETHERSCAN_API_KEY=your_api_key_here
```

--------------------------------

### Generate Tests and Run Tester with Debug Logging

Source: https://github.com/ethereum/clear-signing-erc7730-registry/blob/master/tools/scripts/generate-tests.README.md

Generates tests and runs the tester with detailed debug logging enabled. This is useful for troubleshooting. Ensure .env is sourced and Docker is running.

```bash
source .env && node tools/scripts/generate-tests.js registry/ethena/calldata-ethena.json --test-log-level debug
```