Merkle Oracle CLI

Command-line interface for deploying and managing merkle oracle contract, multisig contract, and the oracle consumer contract.

Merkle Oracle Contracts: https://github.com/zenGate-Global/merkle-oracle-contracts
MultiSig Contract: https://github.com/zenGate-Global/palm-multisig-aiken
Oracle Consumer Contract: https://github.com/zenGate-Global/oracle-consumer

Overview

This CLI tool provides commands for:

Oracle Management: Deploy and manage merkle oracle contracts
Multisig Operations: Deploy and configure multisig contracts
Consumer Contracts: Deploy consumer contracts and spend from them

Every time a transaction is successfully submitted on-chain (using the --submit flag), a deployment artifact is automatically saved to the deployments/ directory in the root of the project. This allows for easy tracking of contract addresses, token units, and transaction history.

Deployment Artifacts

Artifacts are organized into subfolders based on the contract category:

deployments/oracle/: Oracle genesis and management transactions
deployments/multisig/: Multisig deployment and configuration transactions
deployments/consumer/: Consumer deployment and spending transactions

Each artifact is a JSON file named by its transaction hash (e.g., <tx_hash>.json) and contains:

Metadata: Timestamp, network, and connected wallet address
Transaction: The submitted transaction hash and its full CBOR hex
Inputs: The parameters and options used for the command
Outputs: Key blockchain data generated (e.g., singleton token units, contract UTXOs)

Installation

# Install dependencies
pnpm install

# Build the project
pnpm build

# set up cli
pnpm link --global
# alternatively you can run pnpm exec merkle-oracle-cli <command> [options]
# if you dont want to make the command global

# Run CLI commands
merkle-oracle-cli <command> [options]

Command Reference

Make sure you have a config.json file in the root of the project.

{
  "blockfrostApiKey": "your_blockfrost_api_key",
  "walletMnemonic": "your_wallet_mnemonic"
}

This must be filled out!

Oracle Management

`genesis`

Deploys a new merkle oracle contract.

merkle-oracle-cli genesis [options]

Options:

--singleton-name <name> - Name of the singleton token (default: "merkle_oracle_singleton")
--admin-policy-id <id> - Policy ID of the admin token
--admin-asset-name <name> - Asset name of the admin token
--ipfs-cid <cid> - IPFS CID for the oracle data (default: NULL_TRIE_HASH)
--tree-root <root> - Merkle tree root hash (default: NULL_TRIE_HASH)
--submit - Submit the transaction on-chain (default: false)

Note: currently the contract forces ipfs and tree root to be set to the null trie hash for genesis.

Example:

merkle-oracle-cli genesis \
  --admin-policy-id "abc123..." \
  --admin-asset-name "admin_token" \
  --ipfs-cid "QmHash..." \
  --tree-root "0x123abc..." \
  --submit

`recreate`

Recreates an existing merkle oracle contract with new data.

merkle-oracle-cli recreate [options]

Options:

--required-signers <signers...> - Array of required signer addresses for partial signing
--new-merkle-root-hash <hash> - New merkle root hash
--new-ipfs-cid <cid> - New IPFS CID
--genesis-tx-hash <hash> - Genesis transaction hash
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli recreate \
  --genesis-tx-hash "abc123..." \
  --new-merkle-root-hash "0x456def..." \
  --new-ipfs-cid "QmNewHash..." \
  --required-signers "addr1..." "addr2..." \
  --submit

`change-admin`

Changes the admin for a merkle oracle contract.

merkle-oracle-cli change-admin [options]

Options:

--genesis-tx-hash <hash> - Genesis transaction hash
--new-admin-policy-id <id> - New admin policy ID
--new-admin-asset-name <name> - New admin asset name
--required-signers <signers...> - Array of required signer vfks for partial signing
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli change-admin \
  --genesis-tx-hash "abc123..." \
  --new-admin-policy-id "def456..." \
  --new-admin-asset-name "new_admin_token" \
  --required-signers "vfk1..." \
  --submit

`singleton-withdraw`

Withdraws a singleton token to a specified address.

merkle-oracle-cli singleton-withdraw [options]

Options:

--genesis-tx-hash <hash> - Genesis transaction hash
--withdraw-address <address> - Address to withdraw the singleton to
--required-signers <signers...> - Array of required signer vfks for partial signing
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli singleton-withdraw \
  --genesis-tx-hash "abc123..." \
  --withdraw-address "addr_withdraw..." \
  --required-signers "vfk1..." "vfk2..." \
  --submit

Multisig Operations

`deploy`

Deploys a new multisig contract.

merkle-oracle-cli deploy [options]

Options:

--singleton-name <name> - Name of the singleton token (default: "multisig_singleton")
--threshold <number> - Threshold number of signatures required
--signatures <signatures...> - Array of signature addresses
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli deploy \
  --threshold 2 \
  --signatures "vfk1..." "vfk2..." "vfk3..." \
  --submit

`change-signatures`

Changes the signatures for a multisig contract.

merkle-oracle-cli change-signatures [options]

Options:

--genesis-tx-hash <hash> - Genesis transaction hash
--required-signers <signers...> - Array of required signer vfks for partial signing
--signatures <signatures...> - Array of new signature addresses
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli change-signatures \
  --genesis-tx-hash "abc123..." \
  --signatures "vfk1..." "vfk2..." "vfk3..." \
  --required-signers "vfk1..." "vfk2..." \
  --submit

`change-threshold`

Changes the threshold for a multisig contract.

merkle-oracle-cli change-threshold [options]

Options:

--genesis-tx-hash <hash> - Genesis transaction hash
--required-signers <signers...> - Array of required signer vfks for partial signing
--threshold <number> - New threshold number of signatures required
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli change-threshold \
  --genesis-tx-hash "abc123..." \
  --threshold 3 \
  --required-signers "vfk1..." "vfk2..." \
  --submit

`add-signature`

Adds a signature to a multisig transaction and submits if all signatures are met.

merkle-oracle-cli add-signature [options]

Options:

--multisig-file <path> - Path to the multisig JSON file
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli add-signature \
  --multisig-file "./multisig.sign.json" \
  --submit

Consumer Contract

`deploy-consumer`

Deploys a consumer contract that can interact with the oracle.

merkle-oracle-cli deploy-consumer [options]

Options:

--oracle-policy-id <id> - Policy ID of the oracle token
--oracle-asset-name <name> - Asset name of the oracle token
--lovelace-to-lock <amount> - Amount of lovelace to lock
--threshold <number> - Threshold number required
--should-deploy-script - Deploy the consumer script on-chain (default: false)
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli deploy-consumer \
  --oracle-policy-id "abc123..." \
  --oracle-asset-name "oracle_token" \
  --lovelace-to-lock 2000000 \
  --threshold 1 \
  --should-deploy-script \
  --submit

`spend`

Spends from a consumer contract using merkle proof verification.

merkle-oracle-cli spend [options]

Options:

--genesis-tx-hash <hash> - Genesis transaction hash
--withdraw-address <address> - Address to withdraw funds to
--item-key-hash <hash> - Item key hash
--item-value <value> - Item value in format 'value1,value2'
--membership-proof <proof> - Merkle membership proof hex string
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli spend \
  --genesis-tx-hash "abc123..." \
  --withdraw-address "addr_withdraw..." \
  --item-key-hash "0x789ghi..." \
  --item-value "100,200" \
  --membership-proof "deadbeef" \
  --submit

`spend-auto`

Automatically spends from consumer contract by fetching data from API.

merkle-oracle-cli spend-auto [options]

Options:

--genesis-tx-hash <hash> - Genesis transaction hash
--withdraw-address <address> - Address to withdraw funds to
--item-id <id> - Item ID to fetch from the API
--item-key <key> - Item key to fetch from the API
--api-base-url <url> - Base URL of the API
--submit - Submit the transaction on-chain (default: false)

Example:

merkle-oracle-cli spend-auto \
  --genesis-tx-hash "abc123..." \
  --withdraw-address "addr_withdraw..." \
  --item-id "item_001" \
  --item-key "price" \
  --api-base-url "https://api.example.com" \
  --submit

Configuration

Setup Configuration File

Copy the example configuration file and customize it:

cp config.json.example config.json

Edit config.json with your specific settings:

Network configuration (mainnet/testnet)
Node endpoints
Wallet settings
Contract addresses

Multisig Configuration

For multisig operations, you may need a multisig configuration file:

cp multisig.sign.json.example multisig.sign.json

Workflow Examples

Basic Oracle Deployment Workflow

Deploy Oracle Contract

merkle-oracle-cli genesis \
  --admin-policy-id "your_admin_policy_id" \
  --admin-asset-name "admin_token" \
  --submit

Deploy Consumer Contract

merkle-oracle-cli deploy-consumer \
  --oracle-policy-id "oracle_policy_from_genesis" \
  --oracle-asset-name "merkle_oracle_singleton" \
  --lovelace-to-lock 5000000 \
  --threshold 1 \
  --submit

Update Oracle Data

merkle-oracle-cli recreate \
  --genesis-tx-hash "genesis_tx_hash" \
  --new-merkle-root-hash "new_data_root" \
  --new-ipfs-cid "new_ipfs_hash" \
  --submit

Spend from Consumer

merkle-oracle-cli spend-auto \
  --genesis-tx-hash "genesis_tx_hash" \
  --withdraw-address "your_address" \
  --item-id "data_item_id" \
  --item-key "price" \
  --api-base-url "https://your-api.com" \
  --submit

Multisig Workflow

Deploy Multisig

merkle-oracle-cli deploy \
  --threshold 2 \
  --signatures "vfk1" "vfk2" "vfk3" \
  --submit

Change Threshold (requires signatures)

merkle-oracle-cli change-threshold \
  --genesis-tx-hash "multisig_genesis_hash" \
  --threshold 3 \
  --required-signers "vfk1" "vfk2"

Add Signatures

merkle-oracle-cli add-signature \
  --multisig-file "./multisig.sign.json" \
  --submit

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
config.json.example		config.json.example
eslint.config.js		eslint.config.js
multisig.sign.json.example		multisig.sign.json.example
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Merkle Oracle CLI

Overview

Deployment Artifacts

Installation

Command Reference

Oracle Management

`genesis`

`recreate`

`change-admin`

`singleton-withdraw`

Multisig Operations

`deploy`

`change-signatures`

`change-threshold`

`add-signature`

Consumer Contract

`deploy-consumer`

`spend`

`spend-auto`

Configuration

Setup Configuration File

Multisig Configuration

Workflow Examples

Basic Oracle Deployment Workflow

Multisig Workflow

About

Uh oh!

Releases

Packages

Languages

License

zenGate-Global/merkle-oracle-cli

Folders and files

Latest commit

History

Repository files navigation

Merkle Oracle CLI

Overview

Deployment Artifacts

Installation

Command Reference

Oracle Management

genesis

recreate

change-admin

singleton-withdraw

Multisig Operations

deploy

change-signatures

change-threshold

add-signature

Consumer Contract

deploy-consumer

spend

spend-auto

Configuration

Setup Configuration File

Multisig Configuration

Workflow Examples

Basic Oracle Deployment Workflow

Multisig Workflow

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`genesis`

`recreate`

`change-admin`

`singleton-withdraw`

`deploy`

`change-signatures`

`change-threshold`

`add-signature`

`deploy-consumer`

`spend`

`spend-auto`

Packages