Package Exports

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 Elephant Network oracles to manage their data on the Polygon blockchain. This tool helps you validate and submit data to the decentralized Elephant Network.

Quick Start

Installation

# Install globally (recommended)
npm install -g @elephant-xyz/cli

# Or use without installation
npx @elephant-xyz/cli --help

Requirements

To use this tool, the oracle needs to have:

Node.js 20.0 or higher.
A custom JSON RPC URL for Polygon (e.g., from Alchemy or Infura).
An exported Polygon private key (e.g., from MetaMask). For institutional oracles, an API key, domain, and oracle key ID are required.
A Pinata JWT for IPFS uploads.
Stable internet access.

What You Can Do

The Elephant Network CLI provides three main workflows:

🔍 Validate Only - Check your data files for errors without uploading
✅ Validate & Upload - Process and upload your data files
🔗 Submit to Blockchain - Register your submissions on-chain

Plus utility commands:

🔄 CID-Hex Conversion - Convert between IPFS CIDs and Ethereum hex hashes
🔀 Transform - Run generated scripts to produce Lexicon outputs + fact sheets, or use legacy AI mode with --legacy-mode
🧪 Generate-Transform - Generate county extraction scripts from minimal inputs (LLM-assisted)

Workflow 1: Preparing and Uploading Data

Step 1: Organize Your Data

You can provide your data in two ways:

Option 1: Directory Structure (for validate-and-upload)

Structure your data directory like this:

your-data/
├── root_cid1/
│   └── data_group_schema_cid.json     # Your data file
├── root_cid2/
│   └── data_group_schema_cid.json     # Your data file
└── ...

Option 2: ZIP File

You can provide a ZIP file containing the directory structure.

For multiple properties (validate-and-upload):

# Structure: ZIP containing multiple property directories
zip -r multi-property.zip your-data/
# your-data/
#   ├── property1/
#   │   └── schema_cid.json
#   └── property2/
#       └── schema_cid.json

elephant-cli validate-and-upload ./multi-property.zip

For single property (validate and hash commands):

# Structure: ZIP containing single property data directly
zip -r single-property.zip 074527L1060260060/
# 074527L1060260060/
#   ├── bafkreif7ywbjxu3s6jfi6ginvmsufeux3cd5eujuivg2y7tmqt2qk4rsoe.json
#   ├── property_seed.json
#   └── other_schema_cid.json

# For validation only:
elephant-cli validate ./single-property.zip

# For hash calculation:
elephant-cli hash ./single-property.zip

Note: The validate and hash commands expect the property directory contents directly in the ZIP (no wrapper directory).

Important:

Directory names must be root CIDs (a.k.a. seed CIDs) OR contain a seed datagroup file
Files are recognized as datagroup root files if they contain exactly two keys: label and relationships
The datagroup CID is determined by matching the label value with the schema manifest from Elephant Network
Files must contain valid JSON data
Schema CIDs must point to valid data group schemas (see Data Group Schema Requirements)

Flexible File Naming:

Files can have any name. The system automatically recognizes datagroup root files by their structure:

Must have exactly two properties: label and relationships
The label value is matched against the Elephant Network schema manifest to determine the datagroup CID

your-data/
├── property_data_set_1/          # Any name (not a CID)
│   ├── property_seed.json        # Seed file (recognized by label matching seed schema)
│   └── photo_metadata.json       # Other data files (recognized by label)
├── bafybe.../                    # Traditional CID directory
│   └── any_name.json             # Data file (recognized by structure)
└── ...

When using seed datagroup directories:

Files are recognized as datagroups if they have label and relationships properties
The system fetches the schema manifest from Elephant Network to map labels to CIDs
Seed files (with label matching the seed datagroup) are processed first
The CID of the uploaded seed file becomes the propertyCid for ALL files in that directory
This allows flexible file and directory naming while maintaining traceability

Data Group Schema Requirements

All schema CIDs used as file names must point to valid data group schemas. A data group schema is a JSON schema that describes an object with exactly two properties:

label - Can be any valid JSON schema definition
relationships - Can be any valid JSON schema definition

Valid Data Group Schema Example:

{
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Human-readable label for the data group"
    },
    "relationships": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": { "type": "string" },
          "target": { "type": "string" }
        }
      }
    }
  },
  "required": ["label", "relationships"]
}

Invalid Examples:

// ❌ Wrong: Missing relationships property
{
  "type": "object",
  "properties": {
    "label": { "type": "string" }
  }
}

// ❌ Wrong: Has extra properties
{
  "type": "object",
  "properties": {
    "label": { "type": "string" },
    "relationships": { "type": "array" },
    "extra": { "type": "string" }
  }
}

// ❌ Wrong: Not describing an object
{
  "type": "string"
}

Where to Find Valid Schemas:

Visit https://lexicon.elephant.xyz to find valid data group schemas for your use case.

Step 2: Validate Your Data (Optional but Recommended)

Before uploading, you can validate your single property data files without any credentials:

# Validate single property data from a ZIP file (REQUIRED)
elephant-cli validate ./single-property.zip

Note: The validate command only accepts ZIP files containing data for a single property.

This command:

Extracts and validates single property data
Checks directory structure
Validates JSON syntax
Verifies data against schemas
Reports all errors to submit_errors.csv
Shows validation summary

No Pinata JWT or private key needed for validation!

Step 3: Get Your Credentials

You'll need:

Private Key: Your oracle wallet private key
Pinata JWT: Token for IPFS uploads (get from Pinata)

Set up environment variables (recommended):

# Create a .env file in your project directory
echo "ELEPHANT_PRIVATE_KEY=your_private_key_here" >> .env
echo "PINATA_JWT=your_pinata_jwt_here" >> .env

Step 4: Validate and Upload (Dry Run First)

Always test first with --dry-run:

# Test without uploading (from directory)
elephant-cli validate-and-upload ./your-data --dry-run --output-csv test-results.csv

What this does:

Validates your JSON files against the required schemas
Converts file path references to IPFS CIDs
Shows what would be uploaded (without actually uploading)
Creates a CSV report

IPLD Links Support: Your JSON data can reference other files using IPLD links:

Before upload

{
  "from": { "/": "./property.json" },
  "to": { "/": "./address.json" }
}

After upload

{
  "from": { "/": "bafybeifxyz123propertydata456..." },
  "to": { "/": "bafybeiabc789addressdata012..." }
}

You can also build arrays of links. After transformation, the array will be sorted alphabetically by CID:

Before upload:

[
  {
    "/": "./property.json"
  },
  {
    "/": "./address.json"
  }
]

After upload:

[
  {
    "/": "bafybeifxyz123propertydata456..."
  },
  {
    "/": "bafybeiabc789addressdata012..."
  }
]

The CLI automatically:

Uploads referenced files to IPFS
Converts file paths to IPFS CIDs (CIDv1 format)
Creates proper IPLD-linked data structures
Canonicalize the JSON files

Learn more: IPLD Course | IPFS Course

Step 5: Upload for Real

If dry run succeeds, upload your data:

# Upload from directory
elephant-cli validate-and-upload ./your-data --output-csv upload-results.csv

What this does:

Validates all your data files
Uploads valid files to IPFS via Pinata
NEW: Automatically generates HTML fact sheets for each property
Uploads HTML files to IPFS for easy web viewing
Creates a CSV file with upload results and HTML links (needed for next step)

HTML Fact Sheet Generation:

The CLI now automatically generates beautiful HTML fact sheets for your properties:

Installs/updates the fact-sheet tool automatically
Generates self-contained HTML files with inline CSS and JavaScript
Uploads HTML files to IPFS in parallel for faster processing
Provides web-accessible links in the format: http://dweb.link/ipfs/<cid>
Shows the first 5 property links in the console output
All HTML links are saved in the CSV file for reference

Example output:

🌐 Property Fact Sheet Links:
  (Note: It may take a few minutes for pages to propagate through IPFS gateways)

  1. Property: bafkreitest1
     http://dweb.link/ipfs/bafkreihtmlcid1

  2. Property: bafkreitest2
     http://dweb.link/ipfs/bafkreihtmlcid2

  3. Property: bafkreitest3
     http://dweb.link/ipfs/bafkreihtmlcid3

  4. Property: bafkreitest4
     http://dweb.link/ipfs/bafkreihtmlcid4

  5. Property: bafkreitest5
     http://dweb.link/ipfs/bafkreihtmlcid5

  ... and 15 more properties.

📄 All HTML links have been saved to: upload-results.csv
  Please check this file for the complete list of property fact sheet URLs.

Workflow 2: Submitting to Blockchain

Step 1: Review Upload Results

Check the CSV file from the previous step (upload-results.csv). It contains:

Root CIDs (a.k.a. seed CIDs)
Data group CIDs
Your uploaded data CIDs
File paths and timestamps
HTML fact sheet links for web viewing

Step 2: Submit to Contract (Dry Run First)

Test the blockchain submission:

elephant-cli submit-to-contract upload-results.csv --dry-run

What this does:

Verifies your data differs from existing consensus
Checks you haven't already submitted the same data
Shows what transactions would be sent (without sending them)

Step 3: Submit for Real

If dry run succeeds, submit to the blockchain:

elephant-cli submit-to-contract upload-results.csv --gas-price 30

What this does:

Submits your data hashes to the Elephant Network smart contract
Groups submissions into batches for efficiency
NEW: Returns immediately after submission (no waiting for confirmations)
NEW: Saves transaction IDs to a CSV file for tracking
NEW: Displays transaction IDs in console when less than 5 transactions

Transaction Tracking:

The CLI now automatically tracks all submitted transactions:

Generates a CSV file with transaction details (hash, batch index, item count, timestamp, status)
Default filename: transaction-ids-{timestamp}.csv in the reports directory
Use --transaction-ids-csv to specify a custom output path
When submitting less than 5 transactions, IDs are displayed directly in the console
All transactions are marked as "pending" - use check-transaction-status to check their status

Example output for small submissions:

📝 Transaction IDs:
  0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
  0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
  0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321

Step 4: Check Transaction Status

Check the status of your submitted transactions:

elephant-cli check-transaction-status transaction-ids.csv

What this does:

Reads transaction IDs from the CSV file
Checks current status on the blockchain (success/failed/pending)
Updates the CSV with current status, block numbers, and gas used
Shows a summary of transaction statuses

Options:

# Specify output file
elephant-cli check-transaction-status transaction-ids.csv --output-csv status-update.csv

# Control concurrent checks
elephant-cli check-transaction-status transaction-ids.csv --max-concurrent 20

# Use custom RPC
elephant-cli check-transaction-status transaction-ids.csv --rpc-url https://polygon-rpc.com

Utility Commands

Hash Command

The hash command calculates CIDs for all files in your data, replaces file path links with their corresponding CIDs, calculates a directory CID for HTML and image files if present, and outputs the transformed data as a ZIP archive with CID-based filenames. This is useful for:

Pre-calculating CIDs without uploading to IPFS
Verifying what CIDs your data will have after upload
Creating a portable archive of your data with all links resolved
Testing data transformations before actual submission

# Basic usage (outputs to hashed-data.zip by default)
elephant-cli hash ./single-property.zip

# With custom output ZIP file
elephant-cli hash ./single-property.zip --output-zip ./transformed-data.zip

# With custom concurrency limit
elephant-cli hash ./single-property.zip --max-concurrent-tasks 5

# With explicit property CID (overrides automatic detection)
elephant-cli hash ./single-property.zip --property-cid bafkreiexample123

Property CID Determination:

The hash command determines the property CID using the following priority:

User-provided CID via --property-cid option (highest priority)
Calculated Seed datagroup CID if a Seed file exists in the data
Error if neither is available

This ensures that all files in a single property have a consistent property CID in the output.

Features:

Calculates CIDs for all files using the same algorithm as validate-and-upload --dry-run
Replaces file path references (e.g., {"/": "./file.json"}) with calculated CIDs
Handles IPLD links and ipfs_url fields
Processes seed datagroup files correctly
Outputs a ZIP archive with transformed data, using CIDs as filenames
Calculates directory CID for HTML and image files (included as htmlLink in CSV)
Validates data against schemas before processing

Output Structure:

hashed-data.zip
└── property-cid-1/
    ├── bafybeiabc123...json  # File named with its calculated CID
    │── bafybeixyz789...json
    ...

Upload Command

The upload command takes the output from the hash command and uploads it to IPFS as a directory via Pinata. This command is optimized for simple, efficient uploads without validation or CID calculation overhead.

# Basic usage (uses PINATA_JWT environment variable)
elephant-cli upload hashed-data.zip

# With explicit Pinata JWT
elephant-cli upload hashed-data.zip --pinata-jwt "your-jwt-token"

# With custom output CSV
elephant-cli upload hashed-data.zip --output-csv upload-results.csv

Features:

Uploads single property directory to IPFS in one request
Generates CSV report compatible with submit-to-contract and upload commands
Single property only - matches hash command output structure
No validation or CID calculation - just pure upload

CSV Output Format: The CSV output matches the hash command format but includes actual upload timestamps:

propertyCid,dataGroupCid,dataCid,filePath,uploadedAt,htmlLink
bafkreiproperty...,bafkreidatagroupschema1...,bafkreidatagrouprootfile1...,bafkreidatagroupfile1....json,2024-08-11T20:35:00.687Z,https://ipfs.io/ipfs/bafybeibeeaa5gxifjqaaneyoxjz37tbp3gu7avghwlcepcbtsbmso3mzrq

Workflow Example:

# Step 1: Calculate CIDs offline
elephant-cli hash property-data.zip

# Step 2: Upload to IPFS
elephant-cli upload hashed-data.zip

# Step 3: Submit to blockchain
elephant-cli submit-to-contract upload-results.csv --private-key "your-key"

Data Fetching

The fetch-data command allows you to download and fetch entire data trees from IPFS, following all CID references recursively and packaging them as a ZIP file. It supports two input modes:

Mode 1: Fetch from CID

Download data starting from a root CID:

# Basic usage (outputs to fetched-data.zip by default)
elephant-cli fetch-data bafkreiabc123...

# With custom output ZIP file
elephant-cli fetch-data bafkreiabc123... --output-zip ./my-data.zip

# With custom IPFS gateway
elephant-cli fetch-data bafkreiabc123... --gateway https://ipfs.io/ipfs/

Mode 2: Fetch from Transaction Hash

Extract and download data from a blockchain transaction (must be a submitBatchData transaction):

# Basic usage (requires RPC access)
# Transaction hash must be 32 bytes (64 hex characters)
elephant-cli fetch-data 0x1234567890abcdef...

# With custom RPC URL
elephant-cli fetch-data 0x1234567890abcdef... --rpc-url https://polygon-rpc.com

# With all options
elephant-cli fetch-data 0x1234567890abcdef... \
  --rpc-url https://polygon-rpc.com \
  --gateway https://ipfs.io/ipfs/ \
  --output-zip ./tx-data.zip

Transaction Mode Details:

Fetches transaction data from the blockchain
Decodes submitBatchData calls to extract property, data group, and data hashes
Converts hashes to CIDs using the CidHexConverterService (raw codec, base32 encoding)
Creates folder structure inside ZIP: propertyCID/ with data files directly inside
Downloads all referenced data recursively

Features:

Recursively follows all CID references in JSON data
Replaces CID references with local file paths
Preserves data structure and relationships
Supports rate limiting with automatic retries
Uses schema manifest from Elephant Network for proper file naming
Outputs as ZIP file for easy distribution and archiving

ZIP File Structure:

my-data.zip/
└── data/                        # Top-level data folder
    ├── bafkreiabc123.../       # Property CID (transaction mode)
    │   ├── bafkreidef456.json # Data group file
    │   ├── property_seed.json # Referenced files
    │   ├── property_seed_from.json
    │   └── property_seed_to.json
    ├── bafkreiabc456.../       # Another property
    │   ├── bafkreidef789.json # Data group file
    │   └── other_data.json    # Referenced files
    └── bafkreicid123.../      # CID mode output
        ├── bafkreiroot.json    # Root data file
        └── bafkreiref456.json  # Referenced files

Hash Command (Offline CID Calculation)

The hash command allows you to calculate CIDs for all files in a single property ZIP archive without uploading to IPFS. This is useful for:

Offline CID calculation and verification
Pre-computing CIDs before submission
Testing data transformations locally
Generating submission CSVs without network access

# Basic usage
elephant-cli hash property-data.zip

# With custom output files
elephant-cli hash property-data.zip \
  --output-zip hashed-data.zip \
  --output-csv hash-results.csv

# With concurrency control
elephant-cli hash property-data.zip \
  --max-concurrent-tasks 20

# With explicit property CID
elephant-cli hash property-data.zip \
  --property-cid bafkreiexample123

What this does:

Requires ZIP input containing single property data
Validates all JSON files against their schemas
Calculates CIDs for all files (including linked files)
Calculates directory CID for HTML and image files if present
Replaces file path links with calculated CIDs
Generates CSV with hash results (includes htmlLink column for media directory)
Creates output ZIP with CID-named files

Key Features:

Completely offline - no network requests or IPFS uploads
Single property processing - optimized for processing one property at a time
IPLD link resolution - automatically converts file paths to CIDs
Seed datagroup support - handles seed files correctly
CSV output - generates submission-ready CSV compatible with submit-to-contract

Input Requirements:

Must be a ZIP file (directories not supported)
Should contain data for a single property
Files must follow standard naming convention (schema CID as filename)

Output Structure:

hashed-data.zip/
└── bafkreiproperty.../           # Property CID folder
    ├── bafkreifile1.json         # Files named by their calculated CID
    ├── bafkreifile2.json
    └── bafkreifile3.json

hash-results.csv:
propertyCid,dataGroupCid,dataCid,filePath,uploadedAt
bafkreiproperty...,bafkreischema1...,bafkreifile1...,data.json,
bafkreiproperty...,bafkreischema2...,bafkreifile2...,other.json,

CID-Hex Conversion

The CLI provides utilities to convert between IPFS CIDs and Ethereum hex hashes:

hex-to-cid

Convert an Ethereum hex hash to a CID v1 with raw codec:

# Convert hex to CID
elephant-cli hex-to-cid 0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
# Output: CID: bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e

# Works with or without 0x prefix
elephant-cli hex-to-cid b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

# Validate input format
elephant-cli hex-to-cid 0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 --validate
# Output: ✓ Valid hex format
#         CID: bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e

# Quiet mode for scripting
elephant-cli hex-to-cid 0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9 --quiet
# Output: bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e

cid-to-hex

Convert a CID v1 to an Ethereum hex hash:

# Convert CID to hex
elephant-cli cid-to-hex bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e
# Output: Hex: 0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

# Validate CID format
elephant-cli cid-to-hex bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e --validate
# Output: ✓ Valid CID format
#         Hex: 0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

# Quiet mode for scripting
elephant-cli cid-to-hex bafkreifzjut3te2nhyekklss27nh3k72ysco7y32koao5eei66wof36n5e --quiet
# Output: 0xb94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

Technical Details:

Only supports CID v1 with raw codec (0x55) and SHA-256 hash (0x12)
Hex output always includes the 0x prefix for Ethereum compatibility
Input hex can be provided with or without the 0x prefix
Both commands validate input format and provide clear error messages

Use Cases:

Converting between IPFS CIDs and smart contract hash representations
Debugging blockchain transactions that reference IPFS content
Integrating with systems that use different hash representations
Scripting and automation with the --quiet flag

Generate Transform Scripts

Generate JavaScript extraction scripts from a minimal input bundle (uses an LLM pipeline under the hood):

# Prepare input ZIP with required files at top level:
#   - unnormalized_address.json
#   - property_seed.json
#   - one HTML/JSON page from the county site (e.g., input.html)

export OPENAI_API_KEY=your_key
elephant-cli generate-transform input.zip --output-zip generated-scripts.zip

Duration and cost: about 1 hour, approximately $10 USD.
Optional: include scripts/ and a prior *errors*.csv in your ZIP to guide improvements.
Output: generated-scripts.zip with *.js scripts and a manifest.json.

Deep dive: see docs/GENERATE-TRANSFORM-WORKFLOW.md.

Data Transformation (Scripts and Legacy)

The transform command runs in two modes:

Scripts mode (default): executes generated scripts against your inputs, enriches outputs, generates relationships and HTML fact sheets, and bundles results.
Legacy mode: runs the previous AI-agent flow. Enable with --legacy-mode.

# Scripts mode: run generated scripts
elephant-cli transform \
  --input-zip input.zip \
  --scripts-zip generated-scripts.zip \
  --output-zip transformed-data.zip

# Scripts mode (seed-only helper): build seed datagroup files from CSV
# Put a top-level seed.csv inside input.zip with headers:
# parcel_id,address,method,url,multiValueQueryString,source_identifier,county
elephant-cli transform --input-zip input.zip --output-zip transformed-data.zip

# Legacy mode: use prior AI-agent behavior (additional flags are forwarded)
elephant-cli transform --legacy-mode --output-zip transformed-data.zip [other-flags]

What scripts mode does:

Normalizes inputs to a temp workdir (input.html, unnormalized_address.json, property_seed.json).
Locates and runs required scripts by filename: ownerMapping.js, structureMapping.js, layoutMapping.js, utilityMapping.js (in parallel), then data_extractor.js.
Injects source_http_request and request_identifier from property_seed.json into produced JSON files.
Auto-generates relationship JSONs between property.json and other entities.
Generates HTML fact sheets and merges them into the output.
Packages results as transformed-data.zip with a top-level data/ directory inside.

For the complete workflow, including validation and iterating on scripts, see docs/GENERATE-TRANSFORM-WORKFLOW.md.

--group county with --input-zip for county data transformation
--output-zip to specify the output file (default: transformed-data.zip)
Any additional AI-agent specific options

Use Cases:

Converting raw property data to standardized Lexicon format
Generating web-viewable fact sheets for property information
Preparing data for validation and upload to IPFS
Streamlining the data transformation workflow

Prepare Command

Fetches the original source page or API response referenced in property_seed.json and packages it with the seed files for reproducible processing.

# Input ZIP must contain at top level:
#   - property_seed.json (with source_http_request and request_identifier)
#   - unnormalized_address.json

# Basic usage
elephant-cli prepare input.zip --output-zip prepared-data.zip

# Force direct HTTP fetch (disable headless browser)
elephant-cli prepare input.zip --output-zip prepared-data.zip --no-browser

What it does:

Reads source_http_request and request_identifier from property_seed.json
Verifies unnormalized_address.json exists
Builds the URL from url and multiValueQueryString
Fetches content using either:
- Headless browser (default for GET): renders dynamic pages and handles simple interstitials
- Direct HTTP fetch: used for POST or when --no-browser is set
Writes fetched content to <request_identifier>.html or <request_identifier>.json
Outputs a ZIP including the original files and the new fetched file

Options:

--output-zip <path>: Output ZIP file path (required)
--no-browser: Disable headless browser; use direct HTTP fetch only

Output structure:

prepared-data.zip/
├── property_seed.json
├── unnormalized_address.json
└── <request_identifier>.html | <request_identifier>.json

Platform notes:

Headless browser mode supports Linux and macOS. Use --no-browser for simple API endpoints.

Advanced Features

Custom Configuration

# Control upload concurrency
elephant-cli validate-and-upload ./data --max-concurrent-uploads 5

# Custom gas price for submissions
elephant-cli submit-to-contract results.csv --gas-price 50
# Or let the network decide
elephant-cli submit-to-contract results.csv --gas-price auto

# Save transaction IDs to a specific file
elephant-cli submit-to-contract results.csv --transaction-ids-csv my-transactions.csv

Cold Wallet & External Signing

For enhanced security, you can generate unsigned transactions for signing on an offline device:

# Generate unsigned transactions without exposing your private key
elephant-cli submit-to-contract upload-results.csv \
  --dry-run \
  --unsigned-transactions-json unsigned-txs.json \
  --from-address 0x742d35Cc6634C0532925a3b844Bc9e7595f89ce0

Centralized API Submission

Submit data through a centralized API instead of directly to the blockchain:

# Submit via API (no private key needed)
elephant-cli submit-to-contract upload-results.csv \
  --domain oracles.staircaseapi.com \
  --api-key YOUR_API_KEY \
  --oracle-key-id YOUR_ORACLE_KEY_ID \
  --from-address 0x742d35Cc6634C0532925a3b844Bc9e7595f89ce0

This mode:

Generates unsigned transactions locally
Submits them to the API for signing
NEW: Returns immediately after submission (no waiting)
Reports status as "pending" in transaction-status.csv
Use check-transaction-status command to check transaction status

See API Submission Documentation for details.

What this does:

Creates a JSON file with EIP-1474 compatible unsigned transactions
No private key required - specify the sender address directly
Perfect for cold wallet workflows and hardware wallet signing
Transactions can be signed offline and submitted later

Output Format:

The generated JSON follows the EIP-1474 standard for eth_sendTransaction:

[
  {
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f89ce0",
    "to": "0x79D5046e34D4A56D357E12636A18da6eaEfe0586",
    "gas": "0x18741",
    "gasPrice": "0x6fc23ac00",
    "value": "0x0",
    "data": "0xb35d6ef2...",
    "nonce": "0x0",
    "type": "0x0"
  }
]

Use Cases:

Cold Storage: Generate transactions on an online machine, sign on offline device
Hardware Wallets: Export transactions for signing with Ledger, Trezor, etc.
Multi-signature: Prepare transactions for multiple signers
Gas Optimization: Generate now, submit when gas prices are lower

Common Command Options

Validate Options

--output-csv <file> - Error report file name (default: submit_errors.csv)
--max-concurrent-tasks <num> - Control validation speed

Validate and Upload Options

--pinata-jwt <token> - Pinata API token (or use PINATA_JWT env var)
--output-csv <file> - Results file name (default: upload-results.csv)
--max-concurrent-uploads <num> - Control upload speed
--dry-run - Test without uploading

Submit to Contract Options

--private-key <key> - Wallet private key (or use ELEPHANT_PRIVATE_KEY env var)
--rpc-url <url> - Custom RPC endpoint
--contract-address <address> - Custom smart contract address
--gas-price <value> - Gas price in Gwei or 'auto' (default: 30)
--transaction-batch-size <num> - Items per transaction (default: 200)
--dry-run - Test without submitting
--unsigned-transactions-json <file> - Generate unsigned transactions for external signing (dry-run only)
--from-address <address> - Specify sender address for unsigned transactions (makes private key optional)
--transaction-ids-csv <file> - Output CSV file for transaction IDs (default: transaction-ids-{timestamp}.csv)

Troubleshooting

Common Issues

"Invalid oracle address"

Use a valid Ethereum address format: 0x1234... (42 characters)

"No data found"

Check your oracle address is correct
Verify you have data in the specified period

"Validation failed"

Check your JSON files match the required schema
Ensure file paths exist for IPLD links
Review error details in the generated error CSV

"Schema CID is not a valid data group schema"

Verify the schema CID points to a valid data group schema
Data group schemas must have exactly two properties: label and relationships
Visit https://lexicon.elephant.xyz to find valid schemas

"Upload failed"

Verify your Pinata JWT token is valid
Check your internet connection
Try reducing --max-concurrent-uploads

"Transaction failed"

Ensure your private key has sufficient MATIC for gas
Try increasing --gas-price
Check you haven't already submitted the same data

Getting Help

# View all commands
elephant-cli --help

# Get help for specific command
elephant-cli validate --help
elephant-cli validate-and-upload --help
elephant-cli submit-to-contract --help
elephant-cli fetch-data --help
elephant-cli transform --help
elephant-cli hash --help
elephant-cli upload --help
elephant-cli hex-to-cid --help
elephant-cli cid-to-hex --help

Debug Mode

Set DEBUG=elephant:* environment variable for detailed logging:

# Debug with directory input
DEBUG=elephant:* elephant-cli validate-and-upload ./your-data

Network Information

Blockchain: Polygon Mainnet
Smart Contract: 0x79D5046e34D4A56D357E12636A18da6eaEfe0586
Default RPC: https://rpc.therpc.io/polygon
Default IPFS Gateway: https://gateway.pinata.cloud/ipfs/

Security Notes

Never share your private keys
Use environment variables for sensitive data
Always test with --dry-run first
Keep your .env file secure and never commit it to version control

Support

Documentation: Elephant Lexicon
Issues: Report problems via GitHub issues
Community: Join the Elephant Network community for support

License

MIT