Polymer CLI

Command-line interface for interacting with Polymer's proof API and blockchain verification. Request proofs of blockchain events, query proof status, verify cryptographic proofs, and manage cross-chain execution requests.

🚀 Installation

# Install globally
npm install -g @polymerdao/polymer-cli

# Or use without installing
npx @polymerdao/polymer-cli

🎯 Quick Start

# Set your API key
export POLYMER_API_KEY=your_api_key_here

# Request a proof for a blockchain event
polymer proof request --chain ethereum --global-log-index 12345 --block-number 19000000

# Check the status of a proof request
polymer proof query --job-id 123

# Verify a proof locally (no API key needed)
polymer proof verify --proof <base64_proof_data> --parse

# List connected blockchain chains
polymer info chains

# Get help
polymer --help

📋 Commands

Proof Operations

Request a proof:

polymer proof request --chain <chain_name> --global-log-index <index> --block-number <number> [options]

# Examples
polymer proof request -c ethereum -i 12345 -n 19000000 -k API_KEY
polymer proof request --chain polygon --global-log-index 54321 --block-number 20000000

Query proof status:

polymer proof query --job-id <job_id> [options]

# Examples  
polymer proof query --job-id 123 --api-key API_KEY
polymer proof query -j 456 -k API_KEY

Verify proof locally:

polymer proof verify --proof <proof_data> [options]

# Examples
polymer proof verify --proof base64_proof_data --parse
polymer proof verify -p proof_data --from-file proof.json

Cross-Chain Execution

Submit execution request:

polymer execute request --execute-envelope <envelope> [options]

# Examples
polymer execute request --execute-envelope envelope.json --from-file
polymer execute request -e envelope_data -k API_KEY

Query execution status:

polymer execute query --job-id <job_id> [options]

Chain Information

List connected chains:

polymer info chains [options]

# Examples
polymer info chains --api-key API_KEY --output json
polymer info chains -k API_KEY -o table

Get chain status:

polymer info status [options]

Backward Compatibility

Legacy commands are still supported:

# These map to the new command structure
polymer chains     # → polymer info chains
polymer verify     # → polymer proof verify  
polymer status     # → polymer proof query

⚙️ Configuration

API Key

Set your Polymer API key in one of these ways:

1. Environment variable (recommended):

   export POLYMER_API_KEY=your_api_key_here

2. Command line flag:

   polymer proof request --api-key your_api_key_here [other_options]

Global Options

polymer [command] [options]

Global Options:
  -k, --api-key <key>          Polymer API key
  -b, --api-base <url>         Polymer API base URL (default: https://api.polymer.zone/v1)
  -v, --verbose                Log API requests and responses
      --skip-payment-confirmation  Skip x402 payment confirmation prompts
  -s, --signer-pubkey <key>    Public signing key for proof verification (default: 0x4632e987c6f31d6351e39324dec6f1404af56209)
  --polymer-chain-id <id>      Polymer chain ID for verification (default: 444)
  -o, --output <format>        Output format: json|table|raw (default: table)
  --help                       Show help
  --version                    Show version

📤 Output Formats

The CLI supports multiple output formats:

Table (default):

polymer info chains --output table

JSON:

polymer info chains --output json

Raw:

polymer info chains --output raw

🛠️ Development

Building from Source

# Clone the monorepo
git clone https://github.com/polymerdao/mcp-polymer.git
cd mcp-polymer/packages/cli

# Install dependencies  
npm install

# Build
npm run build

# Run locally
node dist/cli.js --help

Running Tests

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Project Structure

src/
├── cli.ts                    # Main CLI entry point
├── commands/                 # Command implementations
│   ├── proof/               # Proof-related commands
│   │   ├── request.ts       # proof request
│   │   ├── query.ts         # proof query  
│   │   └── verify.ts        # proof verify
│   ├── execute/             # Cross-chain execution commands
│   ├── info/                # Information commands
│   └── [legacy commands]    # Backward compatibility
├── utils/                   # Utility functions
│   ├── config.ts           # Configuration management
│   └── version.ts          # Dynamic version resolution
└── __tests__/              # Test suites

🔧 API Integration

The CLI uses the @polymerdao/polymer-api-client package for API interactions:

import { PolymerOpenRpcClient } from '@polymerdao/polymer-api-client';

const client = new PolymerOpenRpcClient(apiKey, apiBase);

📚 Examples

Complete Proof Workflow

# 1. Request a proof
PROOF_JOB=$(polymer proof request -c ethereum -i 12345 -n 19000000 -k $API_KEY --output json | jq -r '.jobId')

# 2. Check status (repeat until completed)
polymer proof query --job-id $PROOF_JOB -k $API_KEY

# 3. Get completed proof and verify
polymer proof query --job-id $PROOF_JOB -k $API_KEY --output json | jq -r '.proof' | \
polymer proof verify --from-file --parse

Cross-Chain Execution

# 1. Prepare execution envelope (JSON file)
cat > execute.json << 'EOF'
{
  "proof": "base64_proof_data",
  "executeRequest": { 
    "chainId": 1,
    "payload": "0x..."
  }
}
EOF

# 2. Submit execution request
polymer execute request --execute-envelope execute.json --from-file -k $API_KEY

🐛 Troubleshooting

API Key Issues:

# Verify API key is set
echo $POLYMER_API_KEY

# Test API connectivity
polymer info chains -k $POLYMER_API_KEY

Command Not Found:

# Check installation
which polymer

# Reinstall if needed
npm install -g @polymerdao/polymer-cli

Permission Issues:

# Use npx instead of global install
npx @polymerdao/polymer-cli --help

🤝 Contributing

See the main repository README for contribution guidelines.

Adding New Commands

1. Create command file in src/commands/
2. Implement using the yargs command structure
3. Add tests in src/__tests__/
4. Update this README

📄 License

Apache 2.0 License - see LICENSE for details.