JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 861
  • Score
    100M100P100Q104009F
  • License MIT

CLI tool for Elephant Network

Package Exports

  • @elephant-xyz/cli
  • @elephant-xyz/cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@elephant-xyz/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Elephant Network CLI

A command-line tool for interacting with the Elephant Network on Polygon blockchain. This tool allows elephant operators to list and download their assignments from IPFS based on blockchain events, and also to submit new data to the network.

Useful links

Elephant Lexicon

Installation

Global Installation

npm install -g @elephant-xyz/cli

Using NPX (No Installation Required)

npx @elephant-xyz/cli list-assignments --oracle 0xYourElephantAddress

Features

  • 📊 List and download elephant assignments from the blockchain
  • 📥 Download assigned files from IPFS with automatic retry
  • ✅ Validate JSON files against schemas before submission
  • 📤 Upload validated data to IPFS via Pinata
  • 🔗 Support for IPLD links - automatically convert file paths to IPFS CIDs
  • 📝 Submit data hashes to smart contracts in batches
  • 🔄 Two-step submission process for reliability
  • 📊 CSV output for tracking submissions

Usage

Basic Usage - List Assignments

List all assignments for an elephant address:

# If installed globally
elephant-cli list-assignments --oracle 0xYourElephantAddress

# Using npx (recommended)
npx @elephant-xyz/cli list-assignments --oracle 0xYourElephantAddress

Command Options - List Assignments

  • -o, --oracle <address> - Elephant address (required)
  • -c, --contract <address> - Smart contract address (default: 0x79D5046e34D4A56D357E12636A18da6eaEfe0586)
  • -r, --rpc <url> - RPC URL (default: https://rpc.therpc.io/polygon)
  • -g, --gateway <url> - IPFS gateway URL (default: https://gateway.pinata.cloud/ipfs/)
  • -f, --from-block <number> - Starting block number (default: queries assignments from approximately the last 24 hours if not specified)
  • -d, --download-dir <path> - Download directory (default: ./downloads)

Basic Usage - Submit Files

The file submission process has been split into two separate commands for better control and reliability:

Step 1: Validate and Upload Files

Validate files against schemas and upload to IPFS:

# If installed globally
elephant-cli validate-and-upload ./path/to/data-directory \
  --private-key "0xYourPrivateKey" \
  --pinata-jwt "YourPinataJWT" \
  --output-csv upload-results.csv

# Using npx (recommended)
npx @elephant-xyz/cli validate-and-upload ./path/to/data-directory \
  --private-key "0xYourPrivateKey" \
  --pinata-jwt "YourPinataJWT" \
  --output-csv upload-results.csv

Step 2: Submit to Smart Contract

Submit the uploaded data hashes to the blockchain:

# If installed globally
elephant-cli submit-to-contract upload-results.csv \
  --private-key "0xYourPrivateKey"

# Using npx (recommended)
npx @elephant-xyz/cli submit-to-contract upload-results.csv \
  --private-key "0xYourPrivateKey"

Command Options - Validate and Upload

  • <inputDir>: (Required) Path to the directory containing the data files structured for submission.
  • -k, --private-key <key>: (Required) Private key for checking assignments. Can also be set via ELEPHANT_PRIVATE_KEY environment variable.
  • -j, --pinata-jwt <jwt>: (Required) Pinata JWT for IPFS uploads. Can also be set via PINATA_JWT environment variable.
  • -o, --output-csv <path>: Output CSV file path. (Default: upload-results.csv)
  • --from-block <number>: Starting block number for assignment check. (Default: 72310501)
  • --rpc-url <url>: RPC URL for the blockchain network. (Default: https://rpc.therpc.io/polygon)
  • --contract-address <address>: Address of the submit smart contract. (Default: 0x79D5046e34D4A56D357E12636A18da6eaEfe0586)
  • --max-concurrent-uploads <number>: Target maximum concurrent local file processing tasks. If not specified, defaults to an OS-derived limit (Unix-like systems) or a CPU-based heuristic (Windows), with a fallback of 10. Actual IPFS uploads are managed by Pinata service limits.
  • --dry-run: Perform validation without uploading to IPFS.

Command Options - Submit to Contract

  • <csvFile>: (Required) Path to the CSV file generated by validate-and-upload command.
  • -k, --private-key <key>: (Required) Private key for the submitting wallet. Can also be set via ELEPHANT_PRIVATE_KEY environment variable.
  • --rpc-url <url>: RPC URL for the blockchain network. (Default: https://rpc.therpc.io/polygon)
  • --contract-address <address>: Address of the submit smart contract. (Default: 0x79D5046e34D4A56D357E12636A18da6eaEfe0586)
  • --transaction-batch-size <number>: Number of items per blockchain transaction. (Default: 200)
  • --gas-price <value>: Gas price in Gwei for transactions. Can be a number (e.g., 50) or 'auto' to let the provider determine the price. (Default: 30)
  • --dry-run: Perform all checks without submitting transactions.

Environment Variables

The CLI supports loading environment variables from a .env file in your current working directory. This is useful for storing sensitive information like private keys and API tokens securely.

Create a .env file in your project directory:

ELEPHANT_PRIVATE_KEY=your_private_key_here
PINATA_JWT=your_pinata_jwt_token_here

When using a .env file, you can run commands without passing sensitive values as command-line arguments:

# With .env file, no need to specify private key or JWT
elephant-cli submit-files ./data-directory --dry-run

Features

  • 🔍 Query blockchain for elephant assignments
  • 📥 Automatic IPFS file downloads
  • ⚡ Concurrent downloads and uploads
  • 🎯 Progress indicators and colored output
  • ⏱️ Execution time tracking
  • 📊 Summary statistics
  • ✅ File validation against JSON schemas with advanced CID support
  • 📤 Batch IPFS uploads via Pinata
  • 🔗 Smart contract batch submissions
  • 📝 CSV reporting for upload results
  • 🔍 Automatic CID pointer resolution for IPFS-stored data

Requirements

  • Node.js 18.0 or higher
  • Internet connection for blockchain and IPFS access

Building from Source

If you want to build and run the CLI from source code:

Prerequisites

  • Node.js 18.0 or higher
  • npm (comes with Node.js)
  • Git

Step-by-step Build Instructions

  1. Clone the repository:

    git clone https://github.com/your-org/elephant-cli-v2.git
cd elephant-cli-v2

  2. Install dependencies:

    npm install

  3. Build the project:

    npm run build

  4. Run the CLI locally:

    # Using the built executable
./bin/elephant-cli list-assignments --oracle 0xYourElephantAddress

# Or using npm/node directly
node dist/index.js list-assignments --oracle 0xYourElephantAddress

  5. Link for global usage (optional):

    npm link
# Now you can use 'elephant-cli' globally
elephant-cli list-assignments --oracle 0xYourElephantAddress

Development Commands

  • Build in watch mode: npm run dev - Automatically rebuilds on file changes
  • Run tests: npm test
  • Run tests with coverage: npm run test:coverage
  • Lint code: npm run lint
  • Format code: npm run format
  • Clean build artifacts: npm run clean

Project Structure

elephant-cli/
├── src/
│   ├── commands/          # CLI command implementations
│   ├── services/          # Blockchain and IPFS services
│   ├── utils/             # Utility functions
│   ├── types/             # TypeScript type definitions
│   └── index.ts           # Main CLI entry point
├── tests/                 # Test files
├── bin/                   # Executable scripts
├── dist/                  # Built JavaScript files
└── package.json

Advanced JSON Validation Features

The CLI includes sophisticated JSON validation with IPFS integration:

CID-Referenced Schemas

Schemas can reference other schemas stored in IPFS:

{
  "type": "object",
  "properties": {
    "data": {
      "type": "string",
      "cid": "QmYjtig7VJQ6XsnUjqqJvj7QaMcCAwtrgNdahSiFofrE7o"
    }
  }
}

The validator automatically fetches and applies the referenced schema from IPFS.

CID Pointer Resolution

Data can contain IPFS CID pointers that are automatically resolved during validation:

{
  "metadata": {
    "/": "QmYjtig7VJQ6XsnUjqqJvj7QaMcCAwtrgNdahSiFofrE7o"
  }
}

The CLI now supports IPLD links with automatic file path to CID conversion. During the upload process, file paths in your JSON data are automatically converted to IPFS CIDs:

// Before upload
{
  "title": "Main Document",
  "metadata": {
    "/": "./metadata.json"
  },
  "license": {
    "/": "../shared/license.json"
  }
}

// After upload
{
  "title": "Main Document",
  "metadata": {
    "/": "QmMetadataCID..."
  },
  "license": {
    "/": "QmLicenseCID..."
  }
}

This feature enables:

  • Modular data structures with linked components
  • Automatic upload of referenced files
  • IPLD compliant output with CID v1 format
  • Support for relative and absolute file paths

See docs/IPLD-LINKS.md for detailed documentation.

Full Validation Example

{
  "user": "Alice",
  "profile": {
    "/": "QmWUnTmuodSYEuHVPgxtrARGra2VpzsusAp4FqT9FWobuU"
  }
}

The validator fetches the content at the CID and validates it against the schema.

Features

  • Automatic Resolution: CID pointers ({"/": "<cid>"}) are resolved before validation
  • Schema Caching: Fetched schemas are cached for performance
  • Recursive Support: Works with nested structures and arrays
  • CID Format Validation: Built-in validation for IPFS CID strings
  • Error Handling: Graceful handling of IPFS fetch failures

Examples

Example 1: Query Recent Blocks (List Assignments)

Check for assignments in the last 1000 blocks:

elephant-cli list-assignments \
  --oracle 0x0e44bfab0f7e1943cF47942221929F898E181505 \
  --from-block 71875000

Example 2: Use Custom RPC and Download Directory (List Assignments)

elephant-cli list-assignments \
  --oracle 0x0e44bfab0f7e1943cF47942221929F898E181505 \
  --rpc https://polygon-mainnet.infura.io/v3/YOUR_KEY \
  --download-dir ./my-assignments

Example 3: Use Different IPFS Gateway (List Assignments)

elephant-cli list-assignments \
  --oracle 0x0e44bfab0f7e1943cF47942221929F898E181505 \
  --gateway https://ipfs.io/ipfs/ \
  --from-block 71800000

Example 4: Two-Step File Submission Workflow

Step 1: Validate and Upload Files

# Validate and upload files to IPFS
npx @elephant-xyz/cli validate-and-upload ./my-data-to-submit \
  --private-key "0xabc123..." \
  --pinata-jwt "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --output-csv my-uploads.csv

Step 2: Submit to Blockchain

# Submit the uploaded data to the smart contract
npx @elephant-xyz/cli submit-to-contract my-uploads.csv \
  --private-key "0xabc123..."

Example 5: Submit to Blockchain with Custom Gas Price

To override the default gas price, use the --gas-price option. This is useful during times of high network congestion.

# Submit with a gas price of 50 Gwei
npx @elephant-xyz/cli submit-to-contract my-uploads.csv \
  --private-key "0xabc123..." \
  --gas-price 50

# Let the RPC provider automatically determine the best gas price
npx @elephant-xyz/cli submit-to-contract my-uploads.csv \
  --private-key "0xabc123..." \
  --gas-price auto

Example 6: Using Legacy Combined Command

The original combined command is still available:

npx @elephant-xyz/cli submit-files ./another-data-set \
  --private-key "0xdef456..." \
  --pinata-jwt "YourPinataJWTTokenValue" \
  --rpc-url "https://your-custom-rpc.io/polygon" \
  --contract-address "0x123SubmitContractAddress456" \
  --max-concurrent-uploads 5 \
  --transaction-batch-size 50 \
  --dry-run

Expected Output

✔ Current block: 71876500
✔ Found 1 assignments

Assignment 1:
  CID: QmWUnTmuodSYEuHVPgxtrARGra2VpzsusAp4FqT9FWobuU
  Block: 71875870
  Transaction: 0x8c0baf3fa5675f0c05fad8df28de704813b85d10ec01b00a842bb8ac9ba4365c
ℹ Starting downloads...
Downloaded 1 of 1 files...
✓ Downloaded QmWUnTmuodSYEuHVPgxtrARGra2VpzsusAp4FqT9FWobuU to ./downloads/QmWUnTmuodSYEuHVPgxtrARGra2VpzsusAp4FqT9FWobuU
✓ Downloads complete! 1 succeeded, 0 failed.

==================================================
ℹ Summary:
ℹ   Total assignments found: 1
ℹ   Files downloaded: 1
ℹ   Download failures: 0
ℹ   Blocks scanned: 700
ℹ   Execution time: 3.2 seconds
==================================================

Troubleshooting

Common Issues

"Invalid elephant address"

  • Ensure your elephant address is a valid Ethereum address (starts with 0x and is 42 characters long)
  • Example: 0x0e44bfab0f7e1943cF47942221929F898E181505

"Failed to connect to RPC endpoint"

  • Check your internet connection
  • Verify the RPC URL is correct
  • Try using a different RPC provider

"Invalid CID format"

  • The smart contract may have returned malformed data
  • Try querying a different block range

IPFS Download Failures

  • The IPFS gateway may be temporarily unavailable
  • Try using a different gateway with the --gateway option
  • Common gateways:
    • https://ipfs.io/ipfs/
    • https://gateway.pinata.cloud/ipfs/
    • https://cloudflare-ipfs.com/ipfs/

No Events Found

  • Verify the elephant address has assignments in the specified block range
  • Try using a wider block range or starting from an earlier block
  • Use --from-block 0 to search from the beginning (may take longer)

Debug Tips

  1. Start with a recent block number to reduce query time
  2. Use smaller block ranges when testing
  3. Check the contract address matches your elephant network deployment

License

MIT