shadow-cli

17

0

GitHub

test-rs GitHub release (with filter)

An open-souce CLI which can be used to clone, compile and upload shadow contracts to the decentralized Shadow Contract Registry.

Installation

Ensure that Rust & Cargo are installed:

Note: Rust >= 1.79.0 is required!

snippet.sh
1curl https://sh.rustup.rs -sSf | sh

The CLI's update and installation manager, shadowup, can be installed using the following command:

snippet.sh
1curl -L https://raw.githubusercontent.com/shadow-hq/shadow-cli/main/shadowup/install | bash

If you want to manually install shadowup, you can download the latest release from here.

Once you have installed shadowup, you can use it to install the Shadow CLI using the following command from a new terminal:

snippet.sh
1shadowup

After compilation, the shadow command will be available to use from a new terminal. For advanced options, see the shadowup docs

Expected Usage

The expected workflow for creating and pushing a new shadow contract group is as follows:

From Scratch

  1. Initialize a new contract group with shadow init.
  2. Add shadow contracts to the contract group with shadow fetch.
  3. Modify the shadow contracts as needed.
    1. Optionally, compile the shadow contracts with shadow compile.
    2. Optionally, test the shadow contracts with shadow sim.
  4. Push the contract group to the Shadow Contract Registry with shadow push.

From an Existing Contract Group

  1. Clone an existing contract group with shadow clone.
  2. Modify the shadow contracts as needed.
    1. Optionally, compile the shadow contracts with shadow compile.
    2. Optionally, test the shadow contracts with shadow sim.
  3. Push the contract group to the Shadow Contract Registry with shadow push.

Commands

Create a Contract Group

```bash shadow init ```

This command initializes a new contract group in the current directory. The contract group will have the following structure:

snippet.txt
1ContractGroup_01_01_2000_01_01 2├── info.json # Contains metadata about the contract group 3└── README.md # Contains a README you can fill out with information about the contract group

Optional Flags

  • --root <path>: The path to the directory in which to initialize the shadow contract group [default: .]

Create a Shadow Contract

snippet.sh
1shadow fetch <contract_address> --etherscan-api-key <etherscan_api_key> --rpc-url <rpc_url>

This command fetches a shadow contract and its original compiler settings from Etherscan or Blockscout, and saves it to the current directory.

Required Flags

  • <contract_address>: The address of the shadow contract you wish to fetch
  • --etherscan-api-key <etherscan_api_key>: Your Etherscan API key. Fetching may not work without this.
  • --rpc-url <rpc_url>: Your RPC URL. Fetching may not work without this.

Optional Flags

  • --root <path>: The path to the directory in which to save the shadow contract [default: .]
    • If you wish to save the contract to a contract group, you must either be in the contract group's directory or specify the contract group's directory with the --root flag.
  • --force: Overwrite the shadow contract if it already exists
  • --blockscout-url: If your chain uses Blockscout, you can specify the URL here. You do not need an Etherscan API key if you use this flag. For example, --blockscout-url https://explorer.lyra.finance
  • --reth: Whether to save the compiled contract bytecode to 'https://raw.githubusercontent.com/shadow-hq/shadow-cli/main/shadow.json' for use with shadow-reth. See shadow-reth for more information.

Clone an Existing Contract Group

snippet.sh
1shadow clone <ipfs_cid> --etherscan-api-key <etherscan_api_key> --rpc-url <rpc_url>

This command clones an existing contract group from the Shadow Contract Registry and saves it to the current directory.

Required Flags

  • <ipfs_cid>: The IPFS CID of the contract group you wish to clone
  • --etherscan-api-key <etherscan_api_key>: Your Etherscan API key. Cloning may not work without this.
  • --rpc-url <rpc_url>: Your RPC URL. Fetching may not work without this.

Optional Flags

  • --root <path>: The path to the directory in which to save the shadow contract [default: .]
    • If you wish to save the contract to a contract group, you must either be in the contract group's directory or specify the contract group's directory with the --root flag.
  • --force: Overwrite the shadow contract if it already exists
  • --blockscout-url: If your chain uses Blockscout, you can specify the URL here. You do not need an Etherscan API key if you use this flag. For example, --blockscout-url https://explorer.lyra.finance
  • --reth: Whether to save the compiled contract bytecode to 'https://raw.githubusercontent.com/shadow-hq/shadow-cli/main/shadow.json' for use with shadow-reth. See shadow-reth for more information.

Compiling Your Shadow Contract

snippet.sh
1shadow compile --rpc-url <rpc_url>

This command compiles the shadow contract in the current directory. The compiled contract will be saved in the /out directory, next to the foundry artifact.

Note: The current working directory MUST contain the shadow contract you wish to compile. This is different from the other commands, which require the --root flag to specify the contract group directory.

Required Flags

  • --rpc-url <rpc_url>: Your RPC URL. Compiling may not work without this.

Optional Flags

Testing Your Shadow Contract

snippet.sh
1shadow sim <transaction_hash> --rpc-url <rpc_url>

This command takes in a transaction hash and simulates the transaction using the contracts in your contract group. The simulation will output logs after the transaction has been executed.

Required Flags

  • <transaction_hash>: The transaction hash of the transaction you wish to simulate
  • --rpc-url <rpc_url>: Your RPC URL. Simulating may not work without this.

Optional Flags

  • --root <path>: The path to the directory containing the shadow contract group [default: .]

Uploading Your Contract Group

snippet.sh
1shadow push --rpc-url <rpc_url> --pinata-api-key <pinata_api_key> --pinata-secret-api-key <pinata_secret_api_key>

This command uploads the contract group in the current directory to the Shadow Contract Registry. The contract group will be pinned to IPFS using Pinata. You will also be prompted to broadcast an EAS attestation on Base in order to have your group appear on https://logs.xyz.

Required Flags

  • --rpc-url <rpc_url>: Your RPC URL. Pushing may not work without this.
  • --pinata-api-key <pinata_api_key>: Your Pinata API key. Pushing may not work without this.
  • --pinata-secret-api-key <pinata_secret_api_key>: Your Pinata secret API key. Pushing may not work without this.

Optional Flags

  • --root <path>: The path to the directory containing the shadow contract group [default: .]

Getting Help

  • Join the Telegram to get help, or
  • Open an issue with the bug

Contributing

See our contributing guidelines.

Security

This code has not been audited, and should not be used in any production systems.