There are three types of activities you can perform with the the family of projects powered by
eth-command-lineto interact with the ethereum blockchain, and to create and manage ethereum wallets and keys.
eth-command-lineis just a basic
sbt-ethereumproject, predefined for your convenience.
- Define custom
sbt-ethereumprojects to develop and deploy smart contracts in solidity, using sbt as a build tool. Within these projects, you will continue to have access to all of the functionality of
- Define custom
sbt-ethereumprojects to build and run Scala applications that interact with ethereum smart contracts, which may be preexisting and already deployed on the blockchain, or which you may develop yourself in solidty within the same project. This is particularly useful when integrating ethereum applications into existing infrastructure.
All projects based on
eth-command-line, share a common database on the local machine,
so they all have equal access to the Ethereum wallets you create and the contract ABIs you define or import.
When you deploy your smart contracts using
sbt-ethereum, their ABIs and other meta-information will be added to the local machine's database,
and a permanent local record will exist of all the contracts you work.
- A Java 8 runtime environment (we have not tested Java 9 yet). If your machine does not already have one installed, you can download a Java Runtime Environment or a full Java Development Kit.
- Optional: git client.
This documentation assumes the standard
gitcommand-line client, but you can use a gui-based
gitclient if you prefer.
You can use
gitor download a zip file to obtain
a. To use the
gitcommand line, type:
$ git clone [email protected]:swaldman/eth-command-line.git
b. If you download the zip file containing the
eth-command-lineproject, extract it and rename it to
$ wget -O eth-command-line.zip https://github.com/swaldman/eth-command-line/archive/master.zip $ unzip eth-command-line $ mv eth-command-line-master eth-command-line
Move to the
eth-command-linedirectory that was just created.
$ cd eth-command-line
./eth-command-line. The first time you do this, many dependencies be downloaded. At a minimum you will see something like the following output. Don't be concerned if you see lots of other warnings.
sbt-ethereumis based on sbt, which complains a lot. Maybe it should to go to digital boot camp in order to improve its attitude.
If you already have sbt installed in your machine, you can run SBT. For most users, simply type
$ ./eth-command-line [info] Loading global plugins from /home/smiley/.sbt/0.13/plugins [info] Loading project definition from /home/smiley/eth-command-line/project 23:28:14.283 [MLog-Init-Reporter] INFO com.mchange.v2.log.MLog - MLog clients using slf4j logging. [info] Set current project to eth-command-line (in build file:/home/smiley/eth-command-line/) 23:28:16.775 [pool-8-thread-1] INFO org.eclipse.jetty.util.log - Logging initialized @6904ms to org.eclipse.jetty.util.log.Slf4jLog [info] Updating available solidity compiler set. eth-command-line ~>
sbt. from within the
eth-command-linedirectory instead of
eth-command-linescript is just an
- When you see the
eth-command-line ~>) you can begin typing
sbt-ethereumcommands. (These are actually as sbt tasks.) To see a list of all
eth-command-line's tasks and settings, type
Before you can run tasks that require the payment of Ether, such as sending Ether (ethTransactionSend) or invoking state-changing smart-contract functions (ethTransactionInvoke), you will need to first define the ethereum address from which the operation will originate. You can create a new address using the ethKeystoreWalletV3Create task.
eth on master in eth-command-line> ethKeystoreWalletV3Create [info] Generated keypair for address '0xc33071ead8753b04e0ee108cc168f2b22f93525d' [info] Generating V3 wallet, alogorithm=scrypt, n=262144, r=8, p=1, dklen=32 Enter passphrase for new wallet: ******************* Please retype to confirm: ******************* [success] Total time: 31 s, completed Dec 30, 2016 7:53:11 AM
ethKeystoreWalletV3Createis an annoyingly long command to type. Don't type it. Type
ethK<tab>, which will expand to
C<tab>, which will expans to
You can also import any existing
gethwallets into the
sbt-ethereumrepository directory. Just copy the wallet files for the accounts you wish to import from the
gethkeystore into the sbt-ethereum keystore directory. The
gethkeystore directory is
$APPDATA\ethereumon Windows. The
sbt-ethereumkeystore directory is
Be sure to back up your
sbt-ethereumkeystore directory to avoid losing your wallets and accounts!
- Once you have a generated or imported a wallet and transferred some Ether to it,
you can make it the default sender for your interactions with the blockchain by setting a special alias,
Remember to replace the hex string above with your own Ethereum address!
eth-command-line ~> ethAddressAliasSet defaultSender 0xe92db74ce7c392634a1d9af344aeeb4a5f1e0a78 [info] Alias 'defaultSender' now points to address 'e92db74ce7c392634a1d9af344aeeb4a5f1e0a78' (for blockchain 'mainnet'). [info] Refreshing alias cache. [success] Total time: 0 s, completed Oct 25, 2017 11:41:40 PM
Choosing an Ethereum Node
sbt-ethereum is preconfigured to check to see if two environment variables are defined.
If they have values, those values are used to specify the Ethereum node that
sbt-ethereum connects to.
Otherwise, our public Ethereum node is used as a default.
Using One of Infuria's Ethereum Nodes
sbt-ethereum to work with Infura's Ethereum nodes,
obtain a token from infura.io and store it in an environment variable called
You might want to set the environment variable in
The next time you start
eth-command-line, or any program that shares a similar SBT build configuration,
they will notice the token and automatically use it to connect with an Infura Ethereum node.
Using Any Arbitrary Ethereum Node
sbt-ethereum can work with any Ethereum node.
If no environment variable called
ETH_INFURA_TOKEN is defined, the
eth-command-line build configuration checks for an environment variable called
If it is defined, its value is used verbatim to define the Ethereum node to connect to.
When you are ready to run your own node and sync it to the blockchain,
you should store your node's URL in
ETH_DEFAULT_NODE, like this:
If you have defined your own custom sbt-ethereum project, you can also define the setting
ethcfgJsonRpcUrl in your
ethcfgJsonRpcUrl := "http://mynode.domain.com:8545/"
Using the Default Ethereum Node
If neither the environment variable called
ETH_INFURA_TOKEN nor the environment variable called
ETH_DEFAULT_NODE are defined,
the default Ethereum node is used,
Before you begin a custom project, you will need to define a project directory with a
and a special directory structure. If you already have
sbt downloaded and installed, you can type
$ sbt new swaldman/solidity-seed.g8
and then follow the prompts. Just hit return to use the default value.
A minimal solidity project for sbt-ethereum name [my-solidity-project]: hyperdemocracy version [0.0.1-SNAPSHOT]: sbt_ethereum_version [0.0.2-SNAPSHOT]: sbt_version [0.13.16]: Template applied in ./hyperdemocracy
Inside the newly created
hyperdemocracy directory you will find a
build.sbt file, and a directory
src/maim/solidity. The smart contracts you will wish to compile and deploy should be saved in
If you wish to integrate new or already-deployed smart contracts with Scala applications, use
$ sbt new swaldman/solidity-scala-seed.g8 [info] Loading global plugins from /home/smiley/.sbt/0.13/plugins [info] Loading project definition from /home/smiley/tmp/project [info] Set current project to tmp (in build file:/home/smiley/tmp/) A mixed solidity / scala project for sbt-ethereum name [my-scala-solidity-project]: hyperdemocracy organization [eth.anyone]: org.hyperdemocracy package [org.hyperdemocracy]: org.hyperdemocracy.voting scala_stubs_package [org.hyperdemocracy.voting.contract]: scala_version [2.11.11]: version [0.0.1-SNAPSHOT]: sbt_ethereum_version [0.0.2-SNAPSHOT]: consuela_version [0.0.3-SNAPSHOT]: sbt_version [0.13.15]: Template applied in ./hyperdemocracy
You'll find a
src/main/scala directory defined, containing an
for your scala application, in addition to
You will also find a
src/test/scala directory defined with a parallel package directory hierarchy.
Finally, you will find a
src/ethabi directory, where you can put files conatining Ethereum JSON ABI of
smart contracts for which you would like Scala stubs to be generated. Your Scala application can use these
stubs to interact with existing smart contracts.
Introduction to Tasks and Settings
From the top-level directory of any SBT project based on
sbt-ethereum, start SBT:
$ sbt [info] Loading global plugins from /home/mslinn/.sbt/0.13/plugins [info] Loading project definition from /mnt/_/work/eth-command-line/project 12:10:24.290 [MLog-Init-Reporter] INFO com.mchange.v2.log.MLog - MLog clients using slf4j logging. [info] Set current project to sbt-ethereum-template (in build file:/mnt/_/work/eth-command-line/) 2017-10-24 12:10:25.833:INFO::pool-8-thread-1: Logging initialized @5415ms to org.eclipse.jetty.util.log.StdErrLog [info] Updating available solidity compiler set. >
All of the
sbt-ethereum SBT tasks and settings are prefaced with
Tab completion is supported.
eth<tab>, and you will see all the SBT tasks and settings that
sbt-ethereum defines with that prefix:
> eth ethContractAbiForget ethContractAbiList ethContractAbiMemorize ethAddressAliasDrop ethAddressAliasList ethAddressAliasSet ethAddressBalance ethAddressBalanceInWei ethcfgBlockchainId ethContractCompilationsCull ethContractCompilationsInspect ethContractCompilationsList ethContractSpawnAuto ethcfgAutoSpawnContracts ethContractSpawnOnly ethcfgEntropySource ethcfgGasLimitMarkup ethGasPriceMarkup ethcfgIncludeLocations ethInvokeConstant ethTransactionInvoke ethcfgJsonRpcUrl ethcfgKeystoreAutoRelockSeconds ethKeystoreWalletV3Create ethKeystoreWalletV3Inspect ethKeystoreList etcfghKeystoreLocatiosV3 ethKeystoreWalletV3Memorize ethKeystorePrivateKeyReveal ethKeystoreWalletV3Validate ethcfgNetcompileUrl ethcfgScalaStubsPackage ethAddressPing ethTransactionSend ethcfgSender ethcfgSenderOverrideDrop ethcfgSenderOverrideSet ethcfgSenderOverrideShow ethSolidityCompilerSelect ethSolidityCompile ethSolidityDestination ethSolidityCompilerInstall ethSolidityCompilerPrint ethSoliditySource ethTargetDir ethDebugTestrpcLocalRestart ethDebugTestrpcLocalStart ethDebugTestrpcLocalStop > eth
xeth<tab> shows all the SBT tasks and settings that
sbt-ethereum defines with that prefix:
> xeth xethDefaultGasPrice xethcfgEphemeralBlockchains xethFindCacheAliasesIfAvailable xethFindCacheOmitDupsCurrentCompilations xethFindCacheSessionSolidityCompilerKeys xethFindCurrentSender xethFindCurrentSolidityCompiler xethGasOverrideDrop xethGasOverrideSet xethGasOverrideShow xethGasPrice xethGasPriceOverrideDrop xethGasPriceOverrideSet xethGasPriceOverrideShow xethGenKeyPair xethGenScalaStubsAndTestingResources xethInvokeData xethKeystoreWalletV3CreatePbkdf2 xethKeystoreWalletV3CreateScrypt xethLoadAbiFor xethLoadCompilationsKeepDups xethLoadCompilationsOmitDups xethLoadWalletV3 xethLoadWalletV3For xethcfgNamedAbiSource xethNamedAbis xethNextNonce xethQueryRepositoryDatabase xethcfgTestingResourcesObjectName xethTriggerDirtyAliasCache xethTriggerDirtySolidityCompilerList xethUpdateContractDatabase xethUpdateRepositoryDatabase xethUpdateSessionSolidityCompilers xethcfgWalletV3Pbkdf2C xethcfgWalletV3Pbkdf2DkLen xethcfgWalletV3ScryptDkLen xethcfgWalletV3ScryptN xethcfgWalletV3ScryptP xethcfgWalletV3ScryptR > xeth
All of the SBT tasks are described individually.