@rocketh/verifier 0.17.18 → 0.17.20

package/README.md

@@ -1,7 +1,283 @@
 # @rocketh/verifier
 
-Contract verification tool for rocketh, enabling you to submit verification proofs to verifier services like blockchain explorers (Etherscan) and Sourcify.
+Contract verification tool for Rocketh. Submit your deployed contracts for verification on Etherscan, Sourcify, Blockscout, and other verification services.
 
-For full documentation, visit [rocketh.dev](https://rocketh.dev).
+## Features
 
-For hardhat-deploy documentation, see [rocketh.dev/hardhat-deploy/](https://rocketh.dev/hardhat-deploy/).
+- ✅ **Multi-Platform** - Support for Etherscan, Sourcify, and Blockscout
+- 🔧 **CLI Tool** - Easy-to-use command line interface
+- 📦 **Automatic Metadata** - Uses deployment metadata for verification
+- ⚙️ **Configurable** - Custom endpoints, API keys, and options
+
+## Installation
+
+```bash
+# Using pnpm
+pnpm add @rocketh/verifier
+
+# Using npm
+npm install @rocketh/verifier
+
+# Using yarn
+yarn add @rocketh/verifier
+```
+
+## CLI Usage
+
+The package provides a `rocketh-verify` CLI command.
+
+### Verify on Etherscan
+
+```bash
+# Basic usage
+rocketh-verify -e mainnet etherscan
+
+# With custom options
+rocketh-verify -e mainnet etherscan --license MIT --force-license
+
+# With custom endpoint (for Etherscan-compatible explorers)
+rocketh-verify -e polygon etherscan --endpoint https://api.polygonscan.com/api
+```
+
+### Verify on Sourcify
+
+```bash
+# Basic usage
+rocketh-verify -e mainnet sourcify
+
+# With custom endpoint
+rocketh-verify -e mainnet sourcify --endpoint https://sourcify.dev/server
+```
+
+### Verify on Blockscout
+
+```bash
+# Basic usage
+rocketh-verify -e mainnet blockscout
+
+# With custom endpoint
+rocketh-verify -e gnosis blockscout --endpoint https://blockscout.com/xdai/mainnet/api
+```
+
+### Export Metadata
+
+Export contract metadata for manual verification:
+
+```bash
+rocketh-verify -e mainnet metadata --out ./metadata
+```
+
+## CLI Options
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-e, --environment <value>` | **(Required)** Environment/network name |
+| `-d, --deployments <value>` | Deployments folder path |
+
+### Etherscan Options
+
+| Option | Description |
+|--------|-------------|
+| `--endpoint <value>` | Custom API endpoint |
+| `--license <value>` | Source code license (e.g., MIT, GPL-3.0) |
+| `--force-license` | Force the specified license |
+| `--min-interval <value>` | Minimum interval between requests (ms) |
+| `--fix-mispell` | Fix misspelled form fields (some APIs) |
+
+**Environment Variable:** `ETHERSCAN_API_KEY`
+
+### Sourcify Options
+
+| Option | Description |
+|--------|-------------|
+| `--endpoint <value>` | Custom Sourcify endpoint |
+| `--min-interval <value>` | Minimum interval between requests (ms) |
+
+### Blockscout Options
+
+| Option | Description |
+|--------|-------------|
+| `--endpoint <value>` | Custom Blockscout API endpoint |
+| `--min-interval <value>` | Minimum interval between requests (ms) |
+
+## Programmatic Usage
+
+You can also use the verifier programmatically:
+
+```typescript
+import { run } from '@rocketh/verifier';
+
+await run(resolvedConfig, 'mainnet', {
+  verifier: {
+    type: 'etherscan',
+    apiKey: process.env.ETHERSCAN_API_KEY,
+    license: 'MIT',
+  },
+  deploymentNames: ['MyContract', 'MyToken'], // Optional: specific contracts
+  minInterval: 1000, // Optional: rate limiting
+  logErrorOnFailure: true,
+});
+```
+
+## API Reference
+
+### `run(config, environmentName, options)`
+
+Runs the verification process.
+
+**Parameters:**
+
+- `config: ResolvedUserConfig` - Resolved Rocketh configuration
+- `environmentName: string` - Name of the environment (e.g., 'mainnet', 'sepolia')
+- `options: VerificationOptions` - Verification options
+
+### Verification Options
+
+```typescript
+interface VerificationOptions {
+  verifier: EtherscanOptions | SourcifyOptions | BlockscoutOptions;
+  deploymentNames?: string[];   // Specific contracts to verify
+  minInterval?: number;         // Rate limiting (ms between requests)
+  logErrorOnFailure?: boolean;  // Log errors instead of throwing
+}
+```
+
+### Etherscan Options
+
+```typescript
+interface EtherscanOptions {
+  type: 'etherscan';
+  endpoint?: string;      // Custom API endpoint
+  apiKey?: string;        // Etherscan API key
+  license?: string;       // SPDX license identifier
+  forceLicense?: boolean; // Override contract license
+  fixMispell?: boolean;   // Fix API form field spelling
+}
+```
+
+### Sourcify Options
+
+```typescript
+interface SourcifyOptions {
+  type: 'sourcify';
+  endpoint?: string; // Custom Sourcify endpoint
+}
+```
+
+### Blockscout Options
+
+```typescript
+interface BlockscoutOptions {
+  type: 'blockscout';
+  endpoint?: string; // Custom Blockscout API endpoint
+}
+```
+
+## Supported Networks
+
+### Etherscan Networks
+
+The verifier automatically detects the correct Etherscan endpoint for common networks:
+
+| Network | Chain ID | Endpoint |
+|---------|----------|----------|
+| Ethereum Mainnet | 1 | api.etherscan.io |
+| Goerli | 5 | api-goerli.etherscan.io |
+| Sepolia | 11155111 | api-sepolia.etherscan.io |
+| Polygon | 137 | api.polygonscan.com |
+| Arbitrum | 42161 | api.arbiscan.io |
+| Optimism | 10 | api-optimistic.etherscan.io |
+| Base | 8453 | api.basescan.org |
+
+For other networks, use the `--endpoint` option.
+
+### Sourcify
+
+Sourcify supports all EVM chains. The default endpoint is `https://sourcify.dev/server`.
+
+### Blockscout
+
+Blockscout is self-hosted by many chains. Use the `--endpoint` option to specify the correct API URL for your chain.
+
+## Examples
+
+### Verify All Contracts on Mainnet
+
+```bash
+# Set your API key
+export ETHERSCAN_API_KEY=your-api-key
+
+# Verify all deployed contracts
+rocketh-verify -e mainnet etherscan
+```
+
+### Verify Specific Contracts
+
+```typescript
+import { run } from '@rocketh/verifier';
+
+await run(config, 'mainnet', {
+  verifier: {
+    type: 'etherscan',
+    apiKey: process.env.ETHERSCAN_API_KEY,
+  },
+  deploymentNames: ['Token', 'TokenSale'], // Only verify these
+});
+```
+
+### Verify on Multiple Platforms
+
+```bash
+# Verify on Etherscan
+rocketh-verify -e mainnet etherscan
+
+# Also verify on Sourcify for decentralized verification
+rocketh-verify -e mainnet sourcify
+```
+
+### Custom Deployments Folder
+
+```bash
+rocketh-verify -d ./custom-deployments -e mainnet etherscan
+```
+
+## Troubleshooting
+
+### "Already Verified"
+
+This is not an error - it means the contract is already verified on the platform.
+
+### Rate Limiting
+
+Use `--min-interval` to add delays between verification requests:
+
+```bash
+rocketh-verify -e mainnet etherscan --min-interval 5000
+```
+
+### Missing API Key
+
+Etherscan requires an API key. Get one at:
+- [Etherscan](https://etherscan.io/apis)
+- [Polygonscan](https://polygonscan.com/apis)
+- [Arbiscan](https://arbiscan.io/apis)
+
+### Wrong Network Endpoint
+
+For Etherscan-compatible explorers, ensure you're using the correct API endpoint:
+
+```bash
+rocketh-verify -e bsc etherscan --endpoint https://api.bscscan.com/api
+```
+
+## Related Packages
+
+- [`rocketh`](../rocketh) - Core deployment environment
+- [`@rocketh/node`](../rocketh-node) - Node.js deployment executor
+- [`@rocketh/deploy`](../rocketh-deploy) - Standard deployment functions
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@rocketh/verifier",
-  "version": "0.17.18",
+  "version": "0.17.20",
+  "license": "MIT",
   "description": "submit verification proof to verifier services (blockchain explorer, sourcify...",
   "publishConfig": {
     "access": "public"
@@ -32,17 +33,17 @@
     "fs-extra": "^11.3.3",
     "ldenv": "^0.3.16",
     "neoqs": "^6.13.0",
-    "@rocketh/core": "0.17.9"
+    "@rocketh/core": "0.17.11"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
-    "as-soon": "^0.1.4",
+    "as-soon": "^0.1.5",
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3",
-    "@rocketh/node": "0.17.18"
+    "@rocketh/node": "0.17.20"
   },
   "peerDependencies": {
-    "@rocketh/node": "0.17.18"
+    "@rocketh/node": "0.17.20"
   },
   "scripts": {
     "build": "tsc --project tsconfig.json",