Abi*

Contract ABIs define the interface by which clients typically interact with Ethereum smart contracts. They are defined as JSON artifacts. Here’s an ABI for a very simple contract:

[{"constant":true,"inputs":[],"name":"whoAmI","outputs":[{"name":"me","type":"address"}],"payable":false,"stateMutability":"view","type":"function"}]

In order to work with a smart contract in sbt-ethereum, you need to associate it’s address with an ABI.

When a smart contract is compiled, an ABI is often generated as a compilation artifact. However, there is not necessarily a one-to-one mapping between contracts and ABIs. For example, one mode of deploying Ethereum smart contracts is as a “storage proxy”, whose user-facing interface is determined by the contract it delegates to rather than anything the compiler might know about the contract. Even if you do not have “the ABI” for a contract, you may know that it implements some standard interface (like the ERC20 token standard, for example), in which case you can interact with the contract through an ABI that describes that interface.

Default Contract ABIs

When you compile and deploy a smart contract with sbt-ethereum, the deployment address automatically becomes the default contract ABI for the contract. When you wish to interact with a smart contract you have not yourself deployed (or if the compilation ABI is not the appropriate interface), you can set associate a default ABI with an address via ethContractAbiDefaultImport or ethContractAbiDefaultSet.

Default ABI associations are store in the sbt-ethereum “shoebox” and are persistent. Once set, they will remain unless they are overwritten or explicitly dropped.

Override Contract ABIs

Sometimes you may temporarily wish to use an ABI that should not be the default ABI for a contract. ABI overrides define temporary associations of ABIs with contract addresses that only endure within a single sbt-ethereum session.

Aliases

When sbt-ethereum commands expect an ABI, you can refer to it via the address of a contract for which that ABI is already the default. (You can also refer to ABIs by their hashes, which sbt-ethereum computes after normalizing the JSON ABIs by removing unnecessary spaces, and sometimes exposes, see e.g. ethContractAbiAliasList.)

However, it may be convenient to name ABIs you interact with frequently and may wish to reuse. So sbt-ethereum permits you to define ABI aliases. To refer to ABI aliases where sbt-ethereum expects an ABI, prefix the alias name with abi:.

sbt-ethereum also defines aliases for some standard ABIs. These are prefixed with abi:standard:. For the moment, the only supported standard ABI alias is abi:standard:erc20.

Function Call Encoding and Decoding

A contracts functions and the form its calls will take (arguments, return values) are specified by contract ABIs. ethContractAbiCallEncode and ethContractAbiCallDecode permit you to generate the hex bytes that a function call translates to, or to decode those bytes back into a function name and arguments.

ethContractAbiAliasDrop

Usage:

> ethContractAbiAliasDrop <abi-alias>

Removes an alias for a contract abi from the sbt-ethereum shoebox database.

Example:

> ethContractAbiAliasDrop abi:whoami
[info] Abi alias 'abi:whoami' successfully dropped.
[info] Refreshing caches.
[success] Total time: 0 s, completed Jan 27, 2019 11:16:29 PM

ethContractAbiAliasList

Usage:

> ethContractAbiAliasList

Lists all ABI aliases that have been defined in the sbt-ethereum shoebox database.

Example:

> ethContractAbiAliasList
+--------------------+--------------------------------------------------------------------+
| ABI Alias          | ABI Hash                                                           |
+--------------------+--------------------------------------------------------------------+
| abi:fortune        | 0x1c40488a3a264071e539f1a36abe69e4ade3751b15d839af83e015fc2dc6be12 |
| abi:standard:erc20 | 0xa405c7571bcf24cac5ee2f1280f3dee84133398287f650235c093a1384c9a2dd |
| abi:whoami         | 0x093def1bd67f0c4c3f6d578cd27f5135d1fa62e2f652fab0ee79933b23a37c27 |
+--------------------+--------------------------------------------------------------------+
[success] Total time: 0 s, completed Jan 27, 2019 11:20:33 PM

ethContractAbiAliasSet

Usage:

> ethContractAbiAliasSet <new-abi-alias> <abi-as-hex-address-or-address-alias-or-ens-address-or-abi-hash-or-abi-alias>

Defines a new ABI alias, based on the address of a contract associated with the ABI, an ABI hash, or an existing ABI alias.

Examples:

> ethContractAbiAliasSet whoami 0xe599f637dfb705e56589951a5d777afdaf618b5b
> ethContractAbiAliasSet whoami who-am-i
> ethContractAbiAliasSet whoami who-am-i.eth
> ethContractAbiAliasSet whoami 0x093def1bd67f0c4c3f6d578cd27f5135d1fa62e2f652fab0ee79933b23a37c27
> ethContractAbiAliasSet whoami abi:some-other-alias

Example response:

[info] Abi alias 'abi:whoami' successfully bound to ABI found via ABI associated with contract address '0xe599f637dfb705e56589951a5d777afdaf618b5b' on chain with ID 1.
[info] Refreshing caches.
[success] Total time: 0 s, completed Jan 27, 2019 11:34:46 PM

ethContractAbiCallDecode

Usage:

> ethContractAbiCallDecode <abi-as-hex-address-or-address-alias-or-ens-address-or-abi-hash-or-abi-alias> <hex-encoded-function-call>

Decodes a hex-encoded function call (second argument) back into the function name and arguments, based on a specified ABI (first argument).

Example:

> ethContractAbiCallDecode abi:fortune 0x4cf373e6000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000135468697320697320616e206578616d706c652e00000000000000000000000000
Function called: addFortune(string)
   Arg 1 [name=fortune, type=string]: "This is an example."
[success] Total time: 0 s, completed Jan 27, 2019 11:50:18 PM

ethContractAbiCallEncode

Usage:

> ethContractAbiCallEncode <abi-as-hex-address-or-address-alias-or-ens-address-or-abi-hash-or-abi-alias> <function-name> [<function-args-if-any>*]

Encodes a function call with its arguments (if any) into a hex message, based on a specified ABI (first argument).

Example:

> ethContractAbiCallEncode abi:fortune addFortune "This is an example."
Encoded data:
0x4cf373e6000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000135468697320697320616e206578616d706c652e00000000000000000000000000
[success] Total time: 0 s, completed Jan 27, 2019 11:49:50 PM

ethContractAbiDefaultDrop

Usage:

> ethContractAbiDefaultDrop <address-as-hex-or-ens-or-alias>

Removes any default contract ABI that may have been associated with an address for the current EIP-155 Chain ID.

Examples:

> ethContractAbiDefaultDrop 0x82ea8ab1e836272322f376a5f71d5a34a71688f1
> ethContractAbiDefaultDrop fortune
> ethContractAbiDefaultDrop some-address.eth

Example response:

[info] Previously imported or set ABI for contract with address '0x82ea8ab1e836272322f376a5f71d5a34a71688f1' (on chain with ID 1) has been dropped.
[success] Total time: 0 s, completed Feb 15, 2019 4:28:47 PM

ethContractAbiDefaultList

Usage:

> ethContractAbiDefaultList [optional-regex-to-filter-rows]

Lists all addresses and contract ABIs for which a default association has been defined, either explicitly or automatically upon deployment, for the current EIP-155 Chain ID.

Example:

> ethContractAbiDefaultList
+--------------------------------------------+--------------------------------------------------------------------+----------+
| Address                                    | ABI Hash                                                           | Source   |
+--------------------------------------------+--------------------------------------------------------------------+----------+
| 0x82ea8ab1e836272322f376a5f71d5a34a71688f1 | 0x1c40488a3a264071e539f1a36abe69e4ade3751b15d839af83e015fc2dc6be12 | Imported | <-- address aliases: ['fortune','fortune3']
+--------------------------------------------+--------------------------------------------------------------------+----------+
[success] Total time: 0 s, completed Feb 15, 2019 4:36:10 PM

ethContractAbiDefaultImport

Usage:

> ethContractAbiDefaultImport <address-as-hex-or-ens-or-alias>

Imports an ABI into the sbt-ethereum shoebox database, and associates it as the default ABI for the given address for the current EIP-155 Chain ID.

ABIs can be imported manually by cut-and-paste. They can also be imported automatically from Etherscan, if an Etherscan API key has been set.

For examples, please see the tutorial section “Acquiring an ABI for a smart contract”.

ethContractAbiDefaultSet

Usage:

> ethContractAbiDefaultSet <address-as-hex-or-ens-or-alias> <abi-as-hex-address-or-address-alias-or-ens-address-or-abi-hash-or-abi-alias>

Creates a default association between an address and an ABI for the current EIP-155 Chain ID.

Addresses may be specified as sbt-ethereum aliases, ENS addresses, or raw hex. ABIs may be specified by explicit ABI aliases, hex ABI hashes, via any address currently associated with the same ABI.

Example:

> ethContractAbiDefaultSet 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 abi:standard:erc20
[info] The ABI previously associated with ABI alias 'abi:standard:erc20' (on chain with ID 1) ABI has been associated with address 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.
Enter an optional alias for the address '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', now associated with the newly matched ABI (or [return] for none): WETH
[info] Alias 'WETH' now points to address '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2' (for chain with ID 1).
[info] Refreshing caches.
[success] Total time: 8 s, completed Feb 15, 2019 5:14:34 PM

ethContractAbiImport

Usage:

> ethContractAbiImport <address-as-hex-or-ens-or-alias>

For now, this is a shorthand for ethContractAbiDefaultImport. Please see that command for more information.

It imports (either via Etherscan or by copy-and-paste) an ABI as the default ABI associated with the given address.

Note: In the future, this command may also support imports with no address supplied, simply to bring in an ABI and define an alias for it

ethContractAbiOverride

Usage:

> ethContractAbiOverride <address-as-hex-or-ens-or-alias> <abi-as-hex-address-or-address-alias-or-ens-address-or-abi-hash-or-abi-alias>

This is a shorthand for ethContractAbiOverrideSet. Please see that command for more information.

ethContractAbiOverrideDrop

Usage:

> ethContractAbiOverrideDrop <address-as-hex-or-ens-or-alias>

Drops any session override of the association between an address and a contract ABI that may have been set (for the current EIP-155 Chain ID).

Example:

> ethContractAbiOverrideDrop fortune
[info] ABI override successfully dropped.
[info] Refreshing caches.
[success] Total time: 0 s, completed Feb 16, 2019 12:31:00 PM

ethContractAbiOverrideDropAll

Usage:

> ethContractAbiOverrideDropAll

Drops all session overrides of associations between an address and a contract ABI that may have been set (for the current EIP-155 Chain ID).

Example:

> ethContractAbiOverrideDropAll
[info] ABI overrides on chain with ID 1 successfully dropped.
[info] Refreshing caches.
[success] Total time: 0 s, completed Feb 16, 2019 12:35:46 PM

ethContractAbiOverrideList

Usage:

> ethContractAbiOverrideDropList

Lists any session overrides of associations between an address and a contract ABI that may have been set (for the current EIP-155 Chain ID).

Example:

> ethContractAbiOverrideList
+--------------------------------------------+--------------------------------------------------------------------+
| ABI Override Addresses                     | ABI Hash                                                           |
+--------------------------------------------+--------------------------------------------------------------------+
| 0x82ea8ab1e836272322f376a5f71d5a34a71688f1 | 0x1c40488a3a264071e539f1a36abe69e4ade3751b15d839af83e015fc2dc6be12 | <-- address aliases: ['fortune','fortune3'], abi alias: 'abi:oracle'
+--------------------------------------------+--------------------------------------------------------------------+
[success] Total time: 0 s, completed Feb 16, 2019 12:36:27 PM

ethContractAbiOverridePrint

Usage:

> ethContractAbiOverridePrint fortune

Pretty-prints the JSON of the session override of the contract ABI associated with an ABI (if any).

Example:

> ethContractAbiOverridePrint fortune
Session override of contract ABI for address '0x82ea8ab1e836272322f376a5f71d5a34a71688f1':
[ {
  "name" : "drawFortune",
  "inputs" : [ ],
  "outputs" : [ {
    "name" : "fortune",
    "type" : "string"
  } ],
  "constant" : true,
  "payable" : false,
  "stateMutability" : "view",
  "type" : "function"
} ]
[success] Total time: 0 s, completed Feb 16, 2019 12:44:19 PM

ethContractAbiOverrideSet

Usage:

> ethContractAbiOverrideSet <address-as-hex-or-ens-or-alias> <abi-as-hex-address-or-address-alias-or-ens-address-or-abi-hash-or-abi-alias>

Creates an association between an address and a contract ABI that will override any default association that may have been set, but only for the current session (and EIP-155 Chain ID).

Example:

> ethContractAbiOverrideSet 0x82ea8ab1e836272322f376a5f71d5a34a71688f1 abi:oracle
[info] ABI override successfully set.
[info] Refreshing caches.
[success] Total time: 0 s, completed Feb 16, 2019 12:21:23 PM

ethContractAbiPrint

Usage:

> ethContractAbiPrint <address-as-hex-or-ens-or-alias>

This is a shorthand for ethContractAbiPrintCompact. Please see that command for more information.

ethContractAbiPrintCompact

Usage:

> ethContractAbiPrintCompact <address-as-hex-or-ens-or-alias>

Compactly prints the ABI currently effective and associated with an address (for the current EIP-155 Chain ID).

If there is a session override set (see ethContractAbiOverrideSet), it will be the override ABI.

If there is no session override set, it will be the default contract ABI, either defines at deployment time or explicitly imported.

If neither a session override nor default ABI is defined for the address, it will let you know that.

Example:

> ethContractAbiPrintCompact WETH
Contract ABI for ABI associated with contract address '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2' on chain with ID 1:
[{"name":"allowance","inputs":[{"name":"tokenOwner","type":"address"},{"name":"spender","type":"address"}],"outputs":[{"name":"remaining","type":"uint256"}],"constant":true,"payable":false,"stateMutability":"view","type":"function"},{"name":"approve","inputs":[{"name":"spender","type":"address"},{"name":"tokens","type":"uint256"}],"outputs":[{"name":"success","type":"bool"}],"constant":false,"payable":false,"stateMutability":"nonpayable","type":"function"},{"name":"balanceOf","inputs":[{"name":"tokenOwner","type":"address"}],"outputs":[{"name":"balance","type":"uint256"}],"constant":true,"payable":false,"stateMutability":"view","type":"function"},{"name":"totalSupply","inputs":[],"outputs":[{"name":"","type":"uint256"}],"constant":true,"payable":false,"stateMutability":"view","type":"function"},{"name":"transfer","inputs":[{"name":"to","type":"address"},{"name":"tokens","type":"uint256"}],"outputs":[{"name":"success","type":"bool"}],"constant":false,"payable":false,"stateMutability":"nonpayable","type":"function"},{"name":"transferFrom","inputs":[{"name":"from","type":"address"},{"name":"to","type":"address"},{"name":"tokens","type":"uint256"}],"outputs":[{"name":"success","type":"bool"}],"constant":false,"payable":false,"stateMutability":"nonpayable","type":"function"},{"name":"Approval","inputs":[{"name":"tokenOwner","type":"address","indexed":true},{"name":"spender","type":"address","indexed":true},{"name":"tokens","type":"uint256","indexed":false}],"anonymous":false,"type":"event"},{"name":"Transfer","inputs":[{"name":"from","type":"address","indexed":true},{"name":"to","type":"address","indexed":true},{"name":"tokens","type":"uint256","indexed":false}],"anonymous":false,"type":"event"}]
[success] Total time: 0 s, completed Feb 16, 2019 1:01:05 PM

ethContractAbiPrintPretty

Usage:

> ethContractAbiPrintPretty <address-as-hex-or-ens-or-alias>

Pretty-prints the ABI currently effective and associated with an address (for the current EIP-155 Chain ID).

If there is a session override set (see ethContractAbiOverrideSet), it will be the override ABI.

If there is no session override set, it will be the default contract ABI, either defines at deployment time or explicitly imported.

If neither a session override nor default ABI is defined for the address, it will let you know that.

Example:

> ethContractAbiPrintPretty WETH
Contract ABI for ABI associated with contract address '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2' on chain with ID 1:
[ {
  "name" : "allowance",
  "inputs" : [ {
    "name" : "tokenOwner",
    "type" : "address"
  }, {
    "name" : "spender",
    "type" : "address"
  } ],
  "outputs" : [ {
    "name" : "remaining",
    "type" : "uint256"
  } ],
  "constant" : true,
  "payable" : false,
  "stateMutability" : "view",
  "type" : "function"
}, {
  "name" : "approve",
  "inputs" : [ {
    "name" : "spender",
    "type" : "address"
  }, {
    "name" : "tokens",
    "type" : "uint256"
  } ],
  "outputs" : [ {
    "name" : "success",
    "type" : "bool"
  } ],
  "constant" : false,
  "payable" : false,
  "stateMutability" : "nonpayable",
  "type" : "function"
}, {
  "name" : "balanceOf",
  "inputs" : [ {
    "name" : "tokenOwner",
    "type" : "address"
  } ],
  "outputs" : [ {
    "name" : "balance",
    "type" : "uint256"
  } ],
  "constant" : true,
  "payable" : false,
  "stateMutability" : "view",
  "type" : "function"
}, {
  "name" : "totalSupply",
  "inputs" : [ ],
  "outputs" : [ {
    "name" : "",
    "type" : "uint256"
  } ],
  "constant" : true,
  "payable" : false,
  "stateMutability" : "view",
  "type" : "function"
}, {
  "name" : "transfer",
  "inputs" : [ {
    "name" : "to",
    "type" : "address"
  }, {
    "name" : "tokens",
    "type" : "uint256"
  } ],
  "outputs" : [ {
    "name" : "success",
    "type" : "bool"
  } ],
  "constant" : false,
  "payable" : false,
  "stateMutability" : "nonpayable",
  "type" : "function"
}, {
  "name" : "transferFrom",
  "inputs" : [ {
    "name" : "from",
    "type" : "address"
  }, {
    "name" : "to",
    "type" : "address"
  }, {
    "name" : "tokens",
    "type" : "uint256"
  } ],
  "outputs" : [ {
    "name" : "success",
    "type" : "bool"
  } ],
  "constant" : false,
  "payable" : false,
  "stateMutability" : "nonpayable",
  "type" : "function"
}, {
  "name" : "Approval",
  "inputs" : [ {
    "name" : "tokenOwner",
    "type" : "address",
    "indexed" : true
  }, {
    "name" : "spender",
    "type" : "address",
    "indexed" : true
  }, {
    "name" : "tokens",
    "type" : "uint256",
    "indexed" : false
  } ],
  "anonymous" : false,
  "type" : "event"
}, {
  "name" : "Transfer",
  "inputs" : [ {
    "name" : "from",
    "type" : "address",
    "indexed" : true
  }, {
    "name" : "to",
    "type" : "address",
    "indexed" : true
  }, {
    "name" : "tokens",
    "type" : "uint256",
    "indexed" : false
  } ],
  "anonymous" : false,
  "type" : "event"
} ]
[success] Total time: 0 s, completed Feb 16, 2019 12:58:44 PM