GraphQL API
beta

Introduction

All of these can be played with and discovered through the GraphiQL visual editor. For general information about our GraphQL implementation, take a look at the GraphQL Semantics page in the dfuse Platform — Public APIs section.

Subscription

blocks

blocks(lowBlockNum Int64, cursor String, limit Int64 = 0) : BlockEdge!
Listen to a stream of blocks as they come in. WARN: always consider the undo field in forward searches, which signal that the matching element (a block) was in fact REMOVED from the chain because of blocks reorganization.
Parameters
lowBlockNum
Optional
Int64     Lower block num boundary, inclusive. A negative value means a block relative to the head block. Omitting this value means unbounded (since the genesis block).
cursor
Optional
String     Opaque data piece that you can pass back to continue your stream if it ever disconnected. Retrieve it from the cursor field in the responses of this call.
limit
Optional
Int64 = 0     Limit the number of results streamed back. 0 means unlimited

searchTransactions

searchTransactions(indexName TRANSACTIONS_INDEX_NAME, query String, lowBlockNum Int64, highBlockNum Int64, cursor String, limit Int64 = 0, sort SORT = ASC, liveMarkerInterval Uint32 = 0) : TransactionEdge!

Search the blockchain forward for transaction execution traces based on query. See: https://docs.dfuse.io/guides/core-concepts/search-query-language

WARN: always consider the undo field in forward searches, which signal that the matching element was in fact REMOVED from the chain because of blocks reorganization. The undo field is always false in backward searches.

Parameters
indexName
required
TRANSACTIONS_INDEX_NAME!    
query
required
String!     dfuse Search Query Language string
lowBlockNum
Optional
Int64     Lower block num boundary, inclusive. A negative value means a block relative to the head block. Omitting this value means unbounded (since the genesis block).
highBlockNum
Optional
Int64     Higher block num boundary, inclusive. A value of 0 means live-searching on any incoming blocks (the default behavior). A negative value means a block relative to the head block, ex: -1 means the head block, -2 means the second to last block, etc..
cursor
Optional
String     Opaque data piece that you can pass back to continue your search if it ever disconnected. Retrieve it from the cursor field in the responses of this call. It is safe to use the same cursor in BOTH directions (forward and backward).
limit
Optional
Int64 = 0     Limit the number of results streamed back. 0 means unlimited
sort
Optional
SORT = ASC     From which end to start. ASC means from the past, going into the future. DESC means recent to older transactions.
liveMarkerInterval
Optional
Uint32 = 0    

If non-zero, indicates you want to mark the stream when reaching live blocks. A marker is a response with a trace equal to null, which will be sent at each liveMarkerInterval blocks. The first trace to be equal to null in a stream indicates you are now processing live blocks.

The value for liveMarkerInterval is a number of blocks.

transactions

transactions(addresses String, matchAnyOf TRANSACTION_MATCH_FIELD, maxConfirmations Uint32 = 8) : TransactionState!
Subscribe to transactions for which the addresses match one of the match field provided. Assuming a list of addresses and a matchAnyOf value [FROM, TO], you would receive all transaction for which one of the from or to field matches one of the address found in the addresses list.
Parameters
addresses
required
[String!]     list of ETH addresses that you want to subscribe to
matchAnyOf
required
[TRANSACTION_MATCH_FIELD!]     fields to match against the list of addresses
maxConfirmations
Optional
Uint32 = 8     number of ‘Confirmation’ transitions for a matching transaction, once they are in a block (defaults to 8, set to 0 to disable those transitions)

transactionLifecycle

transactionLifecycle(hash String) : TransactionState!
Subscribe to a transaction to follow its lifecycle (inclusion in a block, confirmations, etc.). The transaction can be in an unknown or pending state at the time of the request See https://docs.dfuse.io/guides/ethereum/concepts/trx_lifecycle/
Parameters
hash
required
String!     hash of the transaction you want to track the state

Subscription

_alphaPendingTransactions

_alphaPendingTransactions(filterAddresses String, filterField FILTER_FIELD = FROM_OR_TO) : Transaction!
Parameters
filterAddresses
required
[String!]    
filterField
Optional
FILTER_FIELD = FROM_OR_TO    

Query

block

block(hash String) : Block
Get a single block by its hash
Parameters
hash
required
String!    

blockByNumber

blockByNumber(number Uint64) : Block
Get a single block by its number
Parameters
number
required
Uint64!    

execute

execute(hash String, from String, to String, input String, gasLimit Uint64, gasPrice String, value String, atBlock BlockRef) : TransactionTrace
Speculatively execute a transaction and get back the TransactionTrace it produced. If a hash is provided, it is used directly to speculatively execute the transaction. If only call details are provided, they are use to craft a transaction and speculatively execute it. If hash and call details are provided, the transaction is the one identified by hash and provided call details override fields in the transaction.
Parameters
hash
Optional
String     The hash of a transaction to speculatively execute. When provided, retrieve the transaction information from it and speculatively execute it.
from
Optional
String    
to
Optional
String    
input
Optional
String    
gasLimit
Optional
Uint64    
gasPrice
Optional
String    
value
Optional
String    
atBlock
Optional
BlockRef     BlockRef defines against which block height the execution should be performed against, optional, if not present, use HEAD block (as seen by dfuse). For best precision, use the hash. Passing only the num will use the longest block chain for this block number.

transaction

transaction(hash String) : TransactionTrace
Get a single transaction by its hash
Parameters
hash
required
String!    

searchTransactions

searchTransactions(indexName TRANSACTIONS_INDEX_NAME, query String, lowBlockNum Int64, highBlockNum Int64, cursor String, limit Int64 = 100, sort SORT = ASC) : TransactionConnection!

Search the blockchain forward for transaction execution traces based on query. See: https://docs.dfuse.io/guides/core-concepts/search-query-language

WARN: always consider the undo field in forward searches, which signal that the matching element was in fact REMOVED from the chain because of blocks reorganization. The undo field is always false in backward searches.

Parameters
indexName
required
TRANSACTIONS_INDEX_NAME!     The index that will be queried (CALLS or LOGS), see https://docs.dfuse.io/reference/ethereum/search-terms/
query
required
String!     See https://docs.dfuse.io/guides/core-concepts/search-query-language
lowBlockNum
Optional
Int64     Lower boundary for search. Use -1 for HEAD. See https://docs.dfuse.io/guides/ethereum/concepts/search-ranges/
highBlockNum
Optional
Int64     Upper boundary for search. Use -1 for HEAD. See https://docs.dfuse.io/guides/ethereum/concepts/search-ranges/
cursor
Optional
String     See https://docs.dfuse.io/guides/core-concepts/cursors/
limit
Optional
Int64 = 100     Maximum number of results to include in a result
sort
Optional
SORT = ASC     Direction in which to perform the search

PageInfo

Cursors required to continue either forward or backwards from a list of paginated elements

startCursor

startCursor : String!
cursor of the first element of the list, use it to search in the opposite direction

endCursor

endCursor : String!
cursor of the last element of the list, use it to continue

TransactionConnection

The Connection type for a Transaction. See the GraphQL core concepts

edges

edges : [TransactionEdge]!
A list of edges to transactions

pageInfo

pageInfo : PageInfo!
Information to aid pagination

TransactionEdge

A single transaction response.

WARNING: when doing forward streaming searches, do NOT forget to include the undo field to determine if the message is actually a REVERSAL of the transaction.

NOTE: always check the value of node.status to make sure it is successfully executed before assuming it is.

undo

undo : Boolean!

Whether this response is an UNDO operation of a previously sent response.

In a forward search, make sure you catch this and always verify its value.. as to not double/triple count transactions.

In a backward searches, undo will always be false.

cursor

cursor : String!
Query cursor, allowing you to continue fetching results even after interruption of your connection, without missing a beat.

block

block : BlockRefWithHeader!
block is the block in which this transaction was mined

node

node : TransactionTrace
The TransactionTrace object.

Method

Contains raw & decoded (if available) information about the smart contract method invoked by this transaction or EVM call.

hexSignature

hexSignature : String!
hexSignature is the first 4 bytes of the inputData which represents the smart contract method signature. If hexSignature is empty or less than 4 bytes long, it will return as 0x.

textSignature

textSignature : String!
textSignature is the method signature in text form as recognized by a key/value lookup. The key is the first 4 bytes of the input data. If method signature is not found in common signatures table, textSignature will return as empty string.

Transaction

to

to : String!
to is the recipient address of a transfer, or target contract of a call. [VERIFY: will be empty for contract-creating calls / if untrue, resurface the create: true variable like in a TransactioNTrace for consistency.]

nonce

nonce : Uint64!
nonce is an ever incrementing counter of transactions issued by the from account.

gasPrice

gasPrice(encoding VALUE_ENCODING = HEX) : String!
gasPrice is the price offered to miners for gas, in wei per unit.
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

gasLimit

gasLimit : Uint64!
gasLimit is the maximum amount of gas this transaction can consume. Other Ethereum nodes often name this field simply gas. Alias the field name if you prefer. See: https://graphql.org/learn/queries/#aliases

value

value(encoding VALUE_ENCODING = HEX) : String!
value is the Ether value (in wei) sent along with this transaction.
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

inputData

inputData : String!
inputData is the data supplied to the target contract of the transaction. It is sometimes named input elsewhere.

input

input : Inputs!
input is the data supplied to the target contract of the transaction. It contains the raw data and the decoded data (will be null if it wasn’t possible to decode it)

method

method : Method!
The Method object with method signature in hex and text.

hash

hash : String!
hash is the hash of this transaction. It is also a universally unique pointer to this transaction.

from

from : String!
from is the account that sent this transaction - this will always be an externally owned account in the context of this object.

signature

signature : Signature!
signature holds the V, R and S values representing the cryptographic signature for this transaction. It is based on these values that the from address is derived

TransactionTraceConnection

The Connection type for a TransactionTrace

edges

edges : [TransactionTraceEdge]!
A list of edges to transaction traces

pageInfo

pageInfo : PageInfo!
Information to aid pagination

TransactionTraceEdge

A single transaction trace response.

WARNING: when doing forward streaming searches, do NOT forget to include the undo field to determine if the message is actually a REVERSAL of the transaction.

NOTE: always check the value of node.status to make sure it is successfully executed before assuming it is.

undo

undo : Boolean!

cursor

cursor : String!
Query cursor, allowing you to continue fetching results even after interruption of your connection, without missing a beat.

block

block : BlockRefWithHeader!

node

node : TransactionTrace
The transaction trace object.

TransactionTrace

Traces of the execution of a given transaction. This means the transaction was executed on the chain. You also get context about the block in which it was executed, and the status of the execution.

WARN: Make sure to always check the status to make sure you’re not considering a failed transaction as if it was successful.

to

to : String!

to is the recipient address of a transfer, or target contract of a call.

NOTE: this field will always be set, even when the transaction creates a contract. To distinguish contract creations, use the create field.

nonce

nonce : Uint64!
nonce is an ever incrementing counter of transactions issued by the from account.

gasPrice

gasPrice(encoding VALUE_ENCODING = HEX) : String!
gasPrice is the price offered to miners for gas, in wei per unit. You can encode it differently with the encoding parameter.
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

gasLimit

gasLimit : Uint64!
gasLimit is the maximum amount of gas this transaction can consume. Other Ethereum nodes often name this field simply gas. Alias the field name if you prefer. See: https://graphql.org/learn/queries/#aliases

value

value(encoding VALUE_ENCODING = HEX) : String!
value is the Ether value (in wei) sent along with this transaction.
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

inputData

inputData : String!
inputData is the data supplied to the target contract of the transaction. It is sometimes named input elsewhere.

input

input : Inputs!
input is the data supplied to the target contract of the transaction. It contains the raw data and the decoded data (will be null if it wasn’t possible to decode it)

method

method : Method!
The Method object with method signature in hex and text.

hash

hash : String!
hash is the hash of this transaction. It is also a universally unique pointer to this transaction.

from

from : String!
from is the account that sent this transaction - this will always be an externally owned account in the context of this object.

signature

signature : Signature!
signature holds the V, R and S values representing the cryptographic signature for this transaction. It is based on these values that the from address is derived

status

status : TRANSACTION_STATUS!
status shows if the transaction was successful, failed or was reverted. You have the details on the Calls as to which execution is responsible for the failure, and traces up to that point.

gasUsed

gasUsed : Uint64!
gasUsed is the quantity of gas units that was consumed processing this transaction.

cumulativeGasUsed

cumulativeGasUsed : Uint64!
cumulativeGasUsed is the quantity of gas units that was consumed processing this transaction plus all the gas units user by all the transaction before this one in the block.

publicKey

publicKey : String!
TODO: detail, which type of encoding.. and is it even present?

index

index : Int!
index is the 0-based index of this transaction’s execution within the block. TODO: REVIEW

create

create : Boolean!
create is true when the transaction represents a contract deployment

outcome

outcome : String!

block

block : BlockRefWithHeader
block is the block in which this transaction was mined.

allLogs

allLogs : [EventLog!]!
allLogs is a list of all log events within the transaction, flattened and ordered by execution time.

flatCalls

flatCalls : [Call!]!
Lists all calls, flattened and ordered by execution time.

matchingCalls

matchingCalls : [Call!]!
Returns a flattened list of calls, in execution order, of only the matching elements (from a search, or other filtering).

matchingLogs

matchingLogs : [EventLog!]!
Returns a flattened list of logs, in execution order, of only the matching elements (from a search, or other filtering).

Signature

v

v : String!

r

r : String!

s

s : String!

TransactionReceipt

stateRoot

stateRoot : String!

cumulativeGasUsed

cumulativeGasUsed : Uint64!

logsBloom

logsBloom : String!

logs

logs : [EventLog!]!

Call

index

index : Uint32!

parentIndex

parentIndex : Uint32!

depth

depth : Uint32!

callType

callType : CALL_TYPE!

from

from : String!
from is the address of the caller that will

to

to : String!
to is the address of the contract being executed

value

value(encoding VALUE_ENCODING = HEX) : String!
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

gasConsumed

gasConsumed : Uint64!
gasConsumed is the amount of gas specifically consumed by this call. We use the term specifically since for transaction call (i.e. the first call), it does not include implicit transaction gas cost.

gasLimit

gasLimit : Uint64!
gasLimit is the maximum gas value specifically set by this call. We use the term specifically since for transaction call (i.e. the first call), this limit here will be reduced by the implicit transaction gas cost.

status

status : TRANSACTION_STATUS!
status represents the outcome of the execution of this Call

failureCause

failureCause : String

Defines the cause of the failure. Will be set only when status is either REVERTED or FAILED. The reason is a free form string extracted from the Ethereum node that executed the call.

IMPORTANT: This field has no backward policy and the value could change at any moment. Use it for logging purposes, direct user display, debugging help etc. Use it for logic decisions at your own risk.

inputData

inputData : String!
inputData is the data supplied to the target contract of the transaction. It is sometimes named input elsewhere.

input

input : Inputs!
input is the data supplied to the target contract of the transaction. It contains the raw data and the decoded data (will be null if it wasn’t possible to decode it)

method

method : Method!
The Method object with method signature in hex and text.

returnData

returnData : String!

storageChanges

storageChanges(includeReverted Boolean) : [StorageChange!]!
Parameters
includeReverted
Optional
Boolean    

balanceChanges

balanceChanges(includeReverted Boolean) : [BalanceChange!]!
Parameters
includeReverted
Optional
Boolean    

logs

logs(includeReverted Boolean) : [EventLog!]!
Parameters
includeReverted
Optional
Boolean    

analyze

analyze : Analyzed
Provide a higher-level view of the call based on an analysis (ex. ERC20 Transfers) of its decoded data (input, output & logs).

ERC20Transfer

address

address : String!

from

from : String!

to

to : String!

amount

amount(encoding AMOUNT_ENCODING = HEX) : String!
Parameters
encoding
Optional
AMOUNT_ENCODING = HEX    

name

name : String

symbol

symbol : String

decimals

decimals : Uint64

reverted

reverted : Boolean!

Inputs

data

data : String!

json

json : [InputParameter!]!

InputParameter

type

type : String!

name

name : String

value

value : JSON!

BalanceChange

address

address : String!

oldValue

oldValue(encoding VALUE_ENCODING = HEX) : String!
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

newValue

newValue(encoding VALUE_ENCODING = HEX) : String!
Parameters
encoding
Optional
VALUE_ENCODING = HEX    

reason

reason : BALANCE_CHANGE_REASON!

StorageChange

key

key : String!

address

address : String!

oldValue

oldValue : String!

newValue

newValue : String!

EventLog

address

address : String!

topics

topics : [String!]!

data

data : String!

blockIndex

blockIndex : Uint32!

transactionIndex

transactionIndex : Uint32!

BlockRefWithHeader

BlockRefWithHeader is an object that refers to a block and contains its header. Think of it as an incomplete Block object.

hash

hash : String!
Hash (or ID) of this block. It is a unique pointer to this block.

number

number : Uint64!
Sequential number of this block on the chain. Unlike the hash, it is not unique because of forked blocks.

header

header : BlockHeader!

Block

hash

hash : String!
Hash (or ID) of this block. It is a unique pointer to this block.

number

number : Uint64!
Sequential number of this block on the chain. Unlike the hash, it is not unique because of forked blocks.

size

size : Uint64!

header

header : BlockHeader!

uncles

uncles : [BlockHeader!]!
List of the block header of the uncles (ommers) of this block

transactions

transactions(first Uint32, last Uint32, before String, after String) : TransactionConnection!
List of transactions contained in this block with pagination parameters following the standard GraphQL connection model
Parameters
first
Optional
Uint32    
last
Optional
Uint32    
before
Optional
String    
after
Optional
String    

BlockHeader

Header of an Ethereum block

parentHash

parentHash : String!
Hash of the parent block

unclesHash

unclesHash : String!

coinbase

coinbase : String!
Address of the block miner

stateRoot

stateRoot : String!
Hash of the state trie’s root node

transactionsRoot

transactionsRoot : String!

receiptRoot

receiptRoot : String!

logsBloom

logsBloom : String!
Bloom Filter, used to optimize searching for transactions inside this block

difficulty

difficulty : Uint64!

number

number : Uint64!
Sequential number of this block on the chain. Unlike the hash, it is not unique because of forked blocks.

gasLimit

gasLimit : Uint64!
Maximum amount of gas allowed in a block (determines how many transactions can fit into it)

gasUsed

gasUsed : Uint64!
Total amount of gas used during execution of all transactions

timestamp

timestamp : Uint64!
Timestamp of the mining of that block

extraData

extraData : String!
Arbitrary data injected by the miner of this block

mixHash

mixHash : String!

nonce

nonce : Uint64!
Proof of work nonce - The random value in a block that was used get the proof of work satisfied

hash

hash : String!
Hash (or ID) of this block. It is a unique pointer to this block.

BlockEdge

undo

undo : Boolean!

Whether this response is an UNDO operation of a previously sent response.

Make sure you catch this and always verify its value, as to not double/triple count blocks.

cursor

cursor : String!
Stream cursor, allowing you to continue fetching results even after interruption of your connection, without missing a beat.

node

node : MinedBlock
The block object.

MinedBlock

hash

hash : String!
Hash (or ID) of this block. It is a unique pointer to this block.

number

number : Uint64!
Sequential number of this block on the chain. Unlike the hash, it is not unique because of forked blocks.

size

size : Uint64!

header

header : BlockHeader!

uncles

uncles : [BlockHeader!]!
List of the block header of the uncles (ommers) of this block

uncles

uncles : [BlockHeader!]!

transactionTraces

transactionTraces(first Uint32, last Uint32, before String, after String) : TransactionTraceConnection!
List of transaction traces contained in this block with pagination parameters following the standard GraphQL connection model
Parameters
first
Optional
Uint32    
last
Optional
Uint32    
before
Optional
String    
after
Optional
String    

TransactionState

A single Transaction State response.

hash

hash : String!
hash is the hash of this transaction. It is also a universally unique pointer to this transaction.

previousState

previousState : TRANSACTION_STATE!
previousState is the previous of the transaction. When the stream is initiated this will be UNKNOWN

currentState

currentState : TRANSACTION_STATE!
currentState is the current known state of the transaction.

transitionName

transitionName : TRANSACTION_TRANSITION!
transitionName is the current transition of the transaction.

transition

transition : TrackerTransition
transition holds the details of the specific transition. This can be one of the following types based on the specific transition: - TrxTransitionInit - TrxTransitionPooled - TrxTransitionSpeculativelyExecuted - TrxTransitionMined - TrxTransitionForked - TrxTransitionConfirmed - TrxTransitionReplaced

TrxTransitionInit

transaction

transaction : Transaction

blockHeader

blockHeader : BlockHeader

trace

trace : TransactionTrace

confirmations

confirmations : Uint64!

replacedById

replacedById : String

TrxTransitionPooled

transaction

transaction : Transaction

TrxTransitionSpeculativelyExecuted

blockHeader

blockHeader : BlockHeader
blockHeader is the block on which the transaction was speculatively executed

trace

trace : TransactionTrace

TrxTransitionMined

blockHeader

blockHeader : BlockHeader

trace

trace : TransactionTrace

confirmations

confirmations : Uint64!

TrxTransitionForked

transaction

transaction : Transaction

TrxTransitionConfirmed

confirmations

confirmations : Uint64!

TrxTransitionReplaced

replacedById

replacedById : String
Transaction Lifecycle Billing & Rate Limiting

Last modified July 31, 2020