Each sbt-ethereum session must be associated with an EIP-155 Chain ID, which specifies which Ethereum compatible chain the session should interact with.
Nearly everything sbt-ethereum does is contingent upon this Chain ID. Node URLs are assigned and modified on a per-Chain-ID basis (and indeed, users should define default URLs for every chain they typically interact with via ethNodeUrlDefaultSet).
Users may define a default Chain ID (via ethNodeChainIdDefaultSet, which will be the chain new sbt-ethereum session interact with, unless a repository hardcodes an alternative via the setting ethcfgNodeChainId. If no default is defined (and no hardcoded value or session override occludes it), sbt-ethereum will default to interacting with Chain ID 1, Ethereum mainnet.
However, at any time, users can switch Chain IDs via ethNodeChainIdOverrideSet. The Node URL and the set of available address aliases will automatically update with the Chain ID. sbt-ethereum distinguishes deployments by Chain ID, so deployments on different chains can have different ABIs, and sbt-ethereum will automatically make available (in, for example, ethTransactionInvoke) the methods associated with the currently defined Chain ID.
For a list of common Ethereum-like network Chain IDs, see https://chainid.network.
Chain IDs and Testing
In sbt-ethereum’s Test configuration, the Chain ID defaults to the value -1, signalling an ephemeral chain, for which no Chain ID should be embedded in signatures.
Although it is possible to change this behavior for the Test configuration (using Test / ethNodeChainIdDefaultSet or Test / ethNodeChainIdOverrideSet), it is rare that you would want to.
Running tests on an ephemeral chain (like Ganache) is quite different from deploying to a “test chain” (like ropsten or rinkleby).
Test chains have unique positive Chain IDs and their deployments are permanent. sbt-ethereum maintains permanent records of test-chain deployments as it would for any other permanet deployment.
Usage:
> ethNodeChainIdDefaultDrop
Removes any default EIP-155 Chain ID that may have been set.
Example:
> ethNodeChainIdDefaultDrop
[info] Default chain ID, previously set to 1, has now been dropped. No default node chain ID is set.
[info] The node chain ID will be determined by hardcoded defaults, unless overridden by an on override.
[info] The session is now active on chain with ID 1.
[info] Refreshing caches.
[success] Total time: 0 s, completed Mar 21, 2019 5:04:53 PM
Usage:
> ethNodeChainIdDefaultSet <chain-id>
Sets a default EIP-155 Chain ID.
Example:
> ethNodeChainIdDefaultSet 1
[info] The default chain ID has been set to 1.
[info] The session is now active on chain with ID 1.
[info] Refreshing caches.
[success] Total time: 1 s, completed Mar 21, 2019 5:04:35 PM
Usage:
> ethNodeChainIdDefaultPrint
Displays any default EIP-155 Chain ID that may have been set.
Example:
> ethNodeChainIdDefaultPrint
[info] No default chain ID has been explicitly set. A hardcoded default will be used.
[success] Total time: 0 s, completed Mar 21, 2019 5:09:16 PM
Usage:
> ethNodeChainIdOverrideDrop
Removes any this-session-only override EIP-155 Chain ID that may have been set.
Example:
> ethNodeChainIdOverrideDrop
[info] A chain ID override had been set to 2, but has now been dropped.
[info] The effective chain ID will be determined either by a default set with 'ethNodeChainIdDefaultSet', by an 'ethcfgNodeChainId' set in the build or '.sbt. folder, or an sbt-ethereum hardcoded default.
[info] The session is now active on chain with ID 1.
[info] Refreshing caches.
[success] Total time: 0 s, completed Mar 21, 2019 5:13:39 PM
Usage:
> ethNodeChainIdOverrideSet <chain-id>
Sets a this-session-only override EIP-155 Chain ID.
Example:
> ethNodeChainIdOverrideSet 2
[info] The chain ID has been overridden to 2.
[info] The session is now active on chain with ID 2.
[info] Refreshing caches.
[success] Total time: 0 s, completed Mar 21, 2019 5:13:34 PM
Usage:
> ethNodeChainIdOverridePrint
Displays any this-session-only EIP-155 Chain ID that may have been set.
Example:
> ethNodeChainIdOverridePrint
[info] The chain ID is overridden to 2.
[success] Total time: 0 s, completed Mar 21, 2019 5:17:18 PM
Usage:
> ethNodeChainIdOverride <chain-id>
This is a shorthand for ethNodeChainIdOverrideSet. Please see that command for more information.
Usage:
> ethNodeChainIdPrint
Displays the currently effective EIP-155 Chain ID, and explains how it has been set.
Example:
> ethNodeChainIdPrint
[info] The current effective node chain ID is '2'.
[info] + This value has been explicitly set as a session override via 'ethNodeChainIdOverrideSet'.
[success] Total time: 0 s, completed Mar 21, 2019 5:20:42 PM
This task is not indended for direct use on the console
Yields the currently effective EIP-155 Chain ID, for use by build tasks and plugins.
Example:
> ethNodeChainId
[success] Total time: 0 s, completed Mar 21, 2019 5:24:46 PM
> show ethNodeChainId
[info] 2
[success] Total time: 0 s, completed Mar 21, 2019 5:24:55 PM