Spark script

NAME

spark-script - Run a smart contract as a script, building transactions that can be sent onchain.

SYNOPSIS

spark script [options] path [args...]

DESCRIPTION

Run a smart contract as a script, building transactions that can be sent onchain.

Scripts can be used to apply state transitions on live contracts, or deploy and initialize a complex set of smart contracts using Ylem.

OPTIONS

--broadcast Broadcasts the transactions.

--debug Open the script in the debugger. Takes precedence over broadcast.

-g --gas-estimate-multiplier multiplier Relative percentage by which to multiply all gas estimates. (i.e. set to 200 to double them) Default: 130

--json Output results in JSON format. Note: The output is under development and prone to change.

--legacy Use legacy transactions instead of EIP1559 ones. This is auto-enabled for common networks without EIP1559.

--resume Resumes submitting transactions that failed or timed-out previously.

-s --sig signature The signature of the function you want to call in the contract, or raw calldata. Default: run()

--skip-simulation Skips on-chain simulation.

--skip Skip compilation of non-essential contract directories like test or script (usage --skip test).

--non-interactive Remove interactive prompts which appear if the contract is near the EIP-170 size limit.

--slow Makes sure a transaction is sent, only after its previous one has been confirmed and succeeded.

--target-contract contract_name The name of the contract you want to run.

--priority-gas-price Sets the priority gas price for EIP1559 transactions. Useful for when gas prices are volatile and you want to get your transaction included.

--with-gas-price price Sets the gas price for broadcasted legacy transactions, or the max fee for broadcasted EIP1559 transactions. Note: To set the gas price in the execution environment of the script use --gas-price instead (see below).

Etherscan Options

--chain chain_name The Etherscan chain.

--etherscan-api-key key Etherscan API key, or the key of an Etherscan configuration table. Environment: ETHERSCAN_API_KEY

Verification Options

--verify If it finds a matching broadcast log, it tries to verify every contract found in the receipts.

--verifier name The verification provider. Available options: etherscan, sourcify & blockscout. Default: etherscan. Note: make sure you add "/api?" to the end of the Blockscout homepage explorer URL.

--verifier-url url The optional verifier url for submitting the verification request. Environment: VERIFIER_URL

--delay delay Optional timeout to apply in between attempts in seconds. Defaults to 3.

--retries retries Number of attempts for retrying. Defaults to 15.

Cache Options

--force Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries Set pre-linked libraries.

The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize Activate the Ylem optimizer.

--optimizer-runs runs The number of optimizer runs.

--via-ir Use the Yul intermediate representation compilation pipeline.

--revert-strings How to treat revert and require reason strings.

--use solc_version Specify the solc version, or a path to a local solc, to build with.

Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline Do not access the network. Missing solc versions will not be installed.

--no-auto-detect Do not auto-detect solc.

--ignored-error-codes error_codes Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector Extra output to include in the contract's artifact.

Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

For a full description, see the Ylem docs.

--extra-output-files selector Extra output to write to separate files.

Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

For a full description, see the Ylem docs.

--evm-version version The target EVM version.

Project Options

--build-info Generate build info files.

--build-info-path path Output path to directory that build info files will be written to.

--root path The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-C path --contracts path The contracts source directory. Environment: DAPP_SRC

--lib-paths path The path to the library folder.

-R remappings --remappings remappings The project's remappings.

The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path The path to the compiler cache.

--config-path file Path to the config file.

--hh --hardhat This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path --out path The project's artifacts directory.

--silent Suppress all output.

Build Options

--names Print compiled contract names.

--sizes Print compiled non-test contract sizes, exiting with code 1 if any of them are above the size limit.

Watch Options

-w [path...] --watch [path...] Watch specific file(s) or folder(s).

By default, the project's source directory is watched.

-d delay --delay delay File update debounce delay.

During the delay, incoming change events are accumulated and only once the delay has passed, is an action taken. Note that this does not mean a command will be started: if --no-restart is given and a command is already running, the outcome of the action will be to do nothing.

Defaults to 50ms. Parses as decimal seconds by default, but using an integer with the ms suffix may be more convenient.

When using --poll mode, you'll want a larger duration, or risk overloading disk I/O.

--no-restart Do not restart the command while it's running.

--run-all Explicitly re-run the command on all files when a change is made.

Wallet Options - Raw

-i --interactives num Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter. Default: 0

--mnemonic-indexes indexes Use the private key from the given mnemonic index. Used with --mnemonic-path. Default: 0

--mnemonic-paths paths Use the mnemonic file at the specified path(s).

--private-key raw_private_key Use the provided private key.

--private-keys raw_private_keys Use the provided private keys.

Wallet Options - Keystore

--keystores paths Use the keystores in the given folders or files. Environment: ETH_KEYSTORE

--account account-name Use a keystore from the default keystores folder (~/.foxar/keystores) by its filename. Environment: ETH_KEYSTORE_ACCOUNT

--password passwords The keystore passwords. Used with --keystore.

Wallet Options - Hardware Wallet

-t --trezor Use a Trezor hardware wallet.

-l --ledger Use a Ledger hardware wallet.

--hd-paths paths The derivation paths to use with hardware wallets.

Wallet Options - Remote

-a addresses --froms addresses Sign the transaction with the specified accounts on the RPC. Environment: ETH_FROM

EVM Options

-f url --rpc-url url --fork-url url Fetch state over a remote endpoint instead of starting from an empty state.

If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF> Initial retry backoff on encountering errors.

--no-storage-caching Explicitly disables the use of RPC caching.

All storage slots are read entirely from the endpoint. See --fork-url.

-v --verbosity Verbosity of the EVM.

Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

Verbosity levels:

• 2: Print logs for all tests
• 3: Print execution traces for failing tests
• 4: Print execution traces for all tests, and setup traces for failing tests
• 5: Print execution and setup traces for all tests

--sender address The address which will be executing tests

--initial-balance balance The initial balance of deployed contracts

--ffi Enables the FFI cheatcode

Executor Options

--base-fee <FEE> --block-base-fee-per-gas <FEE> The base fee in a block (in wei).

--block-coinbase address The coinbase of the block.

--block-difficulty difficulty The block difficulty.

--block-gas-limit gas_limit The block gas limit.

--block-number block The block number.

--block-timestamp timestamp The timestamp of the block (in seconds).

--chain-id chain_id The chain ID.

--gas-limit gas_limit The block gas limit.

--gas-price gas_price The gas price (in wei).

--tx-origin address The transaction origin.

Common Options

-h --help Prints help information.

EXAMPLES

1. Run BroadcastTest as a script, broadcasting generated transactions on-chain

   spark script ./test/Broadcast.t.sol --tc BroadcastTest --sig "deploy()" \
       -vvv --fork-url $SEPOLIA_RPC_URL

2. Deploy a contract on Polygon (see scripting tutorial for an example script). The verifier url is different for every network.

   spark script script/NFT.s.sol:MyScript --chain-id 137 --rpc-url $RPC_URL \
       --etherscan-api-key $POLYGONSCAN_API_KEY --verifier-url https://api.polygonscan.com/api \
       --broadcast --verify -vvvv

3. Resume a failed script. Using the above as an example, remove --broadcast add --resume

   spark script script/NFT.s.sol:MyScript --chain-id 137 --rpc-url $RPC_URL \
       --etherscan-api-key $POLYGONSCAN_API_KEY --verifier-url https://api.polygonscan.com/api \
       --verify -vvvv --resume

4. Verify contracts that were just deployed with a script

   spark script script/NFT.s.sol --rpc-url $RPC_URL --verify --resume