cmditch / elm-ethereum / Eth

Ethereum RPC Methods

See the official docs for reference.

Contracts

Make sure to use the elm-ethereum-generator to auto-generate the necessary Elm <-> Contract interface from a contract's ABI.

If you're making Eth transactions, you'll need to build a Call, convert it to a Send, and use Eth.Sentry.Tx to hand it off to your browser's wallet (e.g., MetaMask, Trust).

( newSentry, sentryCmd ) =
    myCallParams
        |> Eth.toSend
        |> TxSentry.send TxSendResponse model.txSentry

call : Types.HttpProvider -> Types.Call a -> Task Http.Error a

Call a function on an Ethereum contract. Useful for reading data from contracts, or simulating a transaction before doing a real Send.

Use the elm-ethereum-generator code generator to produce an interface for a smart contract from it's ABI.

Note The decoder for a call is baked into the Call record to allow for a smoother developer experience.

getStorageAt : Types.HttpProvider -> Types.Address -> Basics.Int -> Task Http.Error String

Returns the value from a storage position at a given address. See Ethereum JSON-RPC methods for specification on retrieving data from complex data structures like maps.

getCode : Types.HttpProvider -> Types.Address -> Task Http.Error String

Returns the bytecode from a contract at a given contract's address.

callAtBlock : Types.HttpProvider -> Types.Call a -> Types.BlockId -> Task Http.Error a

Call a function on an Ethereum contract from a particular point in history.

getStorageAtBlock : Types.HttpProvider -> Types.Address -> Basics.Int -> Types.BlockId -> Task Http.Error String

Returns the value from a storage position at a given address, at a certain block height.

getCodeAtBlock : Types.HttpProvider -> Types.Address -> Types.BlockId -> Task Http.Error String

Returns the bytecode from a contract at a given address, at a certain block height.

Transactions

getTx : Types.HttpProvider -> Types.TxHash -> Task Http.Error Types.Tx

Get transaction information from it's hash. Includes pre-execution info: value, nonce, data/input, gas, gasPrice, to, and from.

getTxReceipt : Types.HttpProvider -> Types.TxHash -> Task Http.Error Types.TxReceipt

Get the receipt of a transaction from it's hash. Only exists after the transaction has been mined!

Includes post-execution info: gasUsed, cumulativeGasUsed, contractAddress, logs, logsBloom. Also includes the tx execution status (only if block is post-byzantium).

toSend : Types.Call a -> Types.Send

Prepare a Call to be executed on chain. Used in Eth.Sentry.Tx, a means to interact with MetaMask.

encodeSend : Types.Send -> Json.Encode.Value

Useful if your handling txParams in javascript land yourself.

sendTx : Types.HttpProvider -> Types.Send -> Task Http.Error Types.TxHash

Execute a transaction on chain. Only useful if your keys live on the node your talking too, which is generally considered very poor practice.

NOTE: You probably don't need this. If you're writing a proper dApp, look at using the Eth.Sentry.Tx to interface with wallets like MetaMask.

sendRawTx : Types.HttpProvider -> String -> Task Http.Error Types.TxHash

Broadcast a signed and RLP encoded transaction.

getTxByBlockHashAndIndex : Types.HttpProvider -> Types.BlockHash -> Basics.Int -> Task Http.Error Types.Tx

Get a transaction by it's index in a certain block given the block hash.

getTxByBlockNumberAndIndex : Types.HttpProvider -> Basics.Int -> Basics.Int -> Task Http.Error Types.Tx

Get a transaction by it's index in a certain block given the block number.

Address/Accounts

getBalance : Types.HttpProvider -> Types.Address -> Task Http.Error BigInt

Get the balance of a given address/account. Returns Wei amount as BigInt

getTxCount : Types.HttpProvider -> Types.Address -> Task Http.Error Basics.Int

Get the number of transactions sent from a given address/account.

getBalanceAtBlock : Types.HttpProvider -> Types.Address -> Types.BlockId -> Task Http.Error BigInt

Get the balance of a given address/account, at a certain block height

getTxCountAtBlock : Types.HttpProvider -> Types.Address -> Types.BlockId -> Task Http.Error Basics.Int

Get the number of transactions sent from a given address/account at a given block height.

Blocks

getBlockNumber : Types.HttpProvider -> Task Http.Error Basics.Int

Get the block number of the most recently mined block.

getBlock : Types.HttpProvider -> Basics.Int -> Task Http.Error (Types.Block Types.TxHash)

Get information about a block given a valid block number.

The transactions field will be an array of TxHash's mined during this block.

getBlockByHash : Types.HttpProvider -> Types.BlockHash -> Task Http.Error (Types.Block Types.TxHash)

Get information about a block given a valid block hash.

getBlockWithTxObjs : Types.HttpProvider -> Basics.Int -> Task Http.Error (Types.Block Types.Tx)

Get information about a block given a valid block number.

The transactions field will be an array of Tx objects instead of TxHash's.

getBlockByHashWithTxObjs : Types.HttpProvider -> Types.BlockHash -> Task Http.Error (Types.Block Types.Tx)

See getBlockWithTxObjs above.

Uses block hash instead of number for the identifier.

getBlockTxCount : Types.HttpProvider -> Basics.Int -> Task Http.Error Basics.Int

Get the number of transactions in a block from a given block number.

getBlockTxCountByHash : Types.HttpProvider -> Types.BlockHash -> Task Http.Error Basics.Int

Get the number of transactions in a block from a given block hash.

getUncleCount : Types.HttpProvider -> Basics.Int -> Task Http.Error Basics.Int

Get the number of uncles in a given block given a block number.

getUncleCountByHash : Types.HttpProvider -> Types.BlockHash -> Task Http.Error Basics.Int

Get the number of uncles in a given block given a block hash.

getUncleAtIndex : Types.HttpProvider -> Basics.Int -> Basics.Int -> Task Http.Error Types.Uncle

Get information about an uncle given it's index in a block by block number

getUncleByBlockHashAtIndex : Types.HttpProvider -> Types.BlockHash -> Basics.Int -> Task Http.Error Types.Uncle

Get information about an uncle given it's index in a block by block hash

Filter/Logs/Events

If you have access to a websocket RPC endpoint, it's much easier to just use Eth.Sentry.Event. Geth, Parity, and Infura support websockets.

getLogs : Types.HttpProvider -> Types.LogFilter -> Task Http.Error (List Types.Log)

Get an array of all logs matching a given filter object. Most likely you won't need this, as they are generated for you in elm-ethereum-generator

newFilter : Types.HttpProvider -> Types.LogFilter -> Task Http.Error Types.FilterId

Establishes a filter object on a given node. Useful for contract events.

To check if the state has changed, call getFilterChanges.

newBlockFilter : Types.HttpProvider -> Task Http.Error Types.FilterId

Creates a filter in the node to notify when a new block arrives. To check if the state has changed, call getFilterChanges.

newPendingTxFilter : Types.HttpProvider -> Task Http.Error Types.FilterId

Creates a filter in the node to notify when new pending transactions arrive. To check if the state has changed, call getFilterChanges.

getFilterChanges : Types.HttpProvider -> Json.Decode.Decoder a -> Types.FilterId -> Task Http.Error (List a)

Polling method for a filter, which returns an array of logs which occurred since last poll.

Use the correct decoder for the given filter type:

For a newFilter:

import Eth.Abi.Decode as Abi
import Eth.Decode as Decode
import Json.Decode exposing (Decoder)
import Json.Decode.Pipeline exposing (custom)

transferEventDecoder : Decoder (Event Erc20Transfer)
transferEventDecoder =
    Decode.event erc20TransferDecoder

type alias Erc20Transfer =
    { from : Address
    , to : Address
    , value : BigInt
    }

erc20TransferDecoder : Decoder Erc20Transfer
erc20TransferDecoder =
    decode Transfer
        |> custom (Evm.topic 1 Abi.address)
        |> custom (Evm.topic 2 Abi.address)
        |> custom (Evm.data 0 Abi.uint)

For a newBlockFilter:

newBlockDecoder : Decoder BlockHead
newBlockDecoder =
    Eth.Decode.blockHead

For a newPendingTxFilter:

newPendingTxDecoder : Decoder TxHash
newPendingTxDecoder =
    Eth.Decode.tx

getFilterLogs : Types.HttpProvider -> Json.Decode.Decoder a -> Types.FilterId -> Task Http.Error (List a)

Returns an array of all logs matching filter with given id. See above note on decoders.

uninstallFilter : Types.HttpProvider -> Types.FilterId -> Task Http.Error Types.FilterId

Uninstalls a filter with given id. Should always be called when watch is no longer needed. Additonally Filters timeout when they aren't requested with eth_getFilterChanges for a period of time.

Misc

sign : Types.HttpProvider -> Types.Address -> String -> Task Http.Error String

Sign an arbitrary chunk of N bytes.

The sign method calculates an Ethereum specific signature with: sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))).

By adding a prefix to the message makes the calculated signature recognisable as an Ethereum specific signature. This prevents misuse where a malicious DApp can sign arbitrary data (e.g. transaction) and use the signature to impersonate the victim.

Note the address to sign with must be unlocked.

protocolVersion : Types.HttpProvider -> Task Http.Error Basics.Int

Get the current ethereum protocol version.

syncing : Types.HttpProvider -> Task Http.Error (Maybe Types.SyncStatus)

Get the sync status of a particular node.

Nothing == Not Syncing
Just SyncStatus == starting, current, and highestBlock

coinbase : Types.HttpProvider -> Task Http.Error Types.Address

Get the client's coinbase address.

mining : Types.HttpProvider -> Task Http.Error Basics.Bool

See whether or not a given node is mining.

hashrate : Types.HttpProvider -> Task Http.Error Basics.Int

Returns the number of hashes per second that the node is mining with.

gasPrice : Types.HttpProvider -> Task Http.Error BigInt

Get the current price per gas in wei

Note: not always accurate. See EthGasStation website

accounts : Types.HttpProvider -> Task Http.Error (List Types.Address)

Returns a list of addresses owned by client.

estimateGas : Types.HttpProvider -> Types.Call a -> Task Http.Error Basics.Int

Generates and returns an estimate of how much gas is necessary to allow the transaction to complete. Note that the estimate may be significantly more than the amount of gas actually used by the transaction, for a variety of reasons including EVM mechanics and node performance.