GraphQL APIbeta
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
undo
field in forward searches, which signal that the matching element
(a block) was in fact REMOVED from the chain because of blocks reorganization.cursor
field in the responses of this call.searchTransactions
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.
cursor
field in the responses of this call. It is safe to use the same cursor in BOTH directions (forward and backward).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
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.transactionLifecycle
unknown
or pending
state at the time of the request
See https://docs.dfuse.io/guides/ethereum/concepts/trx_lifecycle/Subscription
_alphaPendingTransactions
Query
block
blockByNumber
execute
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
searchTransactions
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.
PageInfo
startCursor
endCursor
TransactionConnection
edges
pageInfo
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
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
block
block
is the block in which this transaction was minednode
Method
hexSignature
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
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
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
is an ever incrementing counter of transactions issued by the from
account.gasPrice
gasPrice
is the price offered to miners for gas, in wei per unit.gasLimit
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/#aliasesvalue
value
is the Ether value (in wei) sent along with this transaction.inputData
inputData
is the data supplied to the target contract of the transaction. It is sometimes named input
elsewhere.input
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
hash
hash
is the hash of this transaction. It is also a universally unique pointer to this transaction.from
from
is the account that sent this transaction - this will always be an externally owned account in the context of this object.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 derivedraw
TransactionTraceConnection
edges
pageInfo
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
cursor
block
node
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
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
is an ever incrementing counter of transactions issued by the from
account.gasPrice
gasPrice
is the price offered to miners for gas, in wei per unit. You can encode it differently with the encoding
parameter.gasLimit
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/#aliasesvalue
value
is the Ether value (in wei) sent along with this transaction.inputData
inputData
is the data supplied to the target contract of the transaction. It is sometimes named input
elsewhere.input
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
hash
hash
is the hash of this transaction. It is also a universally unique pointer to this transaction.from
from
is the account that sent this transaction - this will always be an externally owned account in the context of this object.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 derivedraw
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
is the quantity of gas units that was consumed processing this transaction.cumulativeGasUsed
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
index
index
is the 0-based index of this transaction’s execution within the block. TODO: REVIEWcreate
create
is true when the transaction represents a contract deploymentoutcome
block
block
is the block in which this transaction was mined.allLogs
allLogs
is a list of all log events within the transaction, flattened and ordered by execution time.flatCalls
matchingCalls
matchingLogs
Signature
v
r
s
TransactionReceipt
stateRoot
cumulativeGasUsed
logsBloom
logs
Call
index
index
is the unique sequential number of the call within the teansaction. Used to make some relationship with other calls in the tree, like the parent’s index.parentIndex
parentIndex
is the index
of the call that directly generated this one. Can be used to build back the full call hierarchy.depth
depth
is the nesting value of this call in regards to the top-level transaction. Can be used in layout to place the call at the correct level of indentation.callType
from
from
is the address of the caller that is performing the actual call.to
to
is the address of the contract being executed or the recipient of the fund in the case of pure transfer that does not involve smart contract execution.value
value
is the amount of Ether transferred to the from
counterpart of this call.gasConsumed
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
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
represents the outcome of the execution of this Call.
Important: Relying solely on status of the call to determine if the state changes performed by the call were committed is wrong. The way Ethereum internal calls work is that if the callee (i.e. the parent) fails, all it’s child calls are reverted even if they succeed. Refer to the stateReverted
flag to determine if the call’s changes were committed to the chain.
stateReverted
stateReverted
determines if the following, regardless of its status
, was committed to the chain completely.
The way Ethereum internal calls work is that if the callee (i.e. the parent) fails, all it’s child calls are reverted even if they succeed. For example, assume a big transactions that performs internal calls and themselves perform other deep calls.
Transaction 0xe604e8...
Call #2
Call #3
Call #4
Call #5
Call #6
Call #7
Call #8
Call #9
Call #10
Call #11
In this hierarchy, if Call #3 fails, the Call #4, #5 and #6 are reverted automatically by the Ethereum blockchain and the state changes performed by those calls are reverted. This means you cannot rely solely on the call’s status
to take a decision.
The stateReverted
field on the opposite is aware of the call hierarchy and will correctly flag Call #3, #4, #5 and #6 has being stateReverted: true
because we correctly inferred that since Call #3 failed, all its children (and children of children recursively) have been reverted by the chain. You would end up with the following fields:
Transaction 0xe604e8... (status: success)
Call #2 (status: success, stateReverted: false)
Call #3 (status: failed, stateReverted: true)
Call #4 (status: success, stateReverted: true)
Call #5 (status: success, stateReverted: true)
Call #6 (status: success, stateReverted: true)
Call #7 (status: success, stateReverted: false)
Call #8 (status: failed, stateReverted: true)
Call #9 (status: success, stateReverted: true)
Call #10 (status: success, stateReverted: true)
Call #11 (status: failed, stateReverted: true)
failureCause
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
is the data supplied to the target contract of the transaction. It is sometimes named input
elsewhere.input
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
returnData
storageChanges
storageChanges
is the list of all storage changes that happen as part of this call. A storage change is any Smart Contract variables that changed throughout the execution of the Smart Contract.
By default, if the call was reverted (as defined by the stateReverted
flag), the storage changes will be empty. Use the includeReverted: true
argument to get the populated list even on reverted calls.
balanceChanges
balanceChanges
is the list of all balance changes that happen as part of this call. A balance change is a transfer of Ether from one entity to the other.
By default, if the call was reverted (as defined by the stateReverted
flag), the balance changes will be empty. Use the includeReverted: true
argument to get the populated list even on reverted calls.
logs
logs
is the list of all logs that were emitted as part of this call.
By default, if the call was reverted (as defined by the stateReverted
flag), the logs will be empty. Use the includeReverted: true
argument to get the populated list even on reverted calls.
analyze
ERC20Transfer
address
from
to
amount
name
symbol
decimals
reverted
Inputs
data
json
InputParameter
type
name
value
BalanceChange
address
oldValue
newValue
reason
StorageChange
key
address
oldValue
newValue
EventLog
address
topics
data
blockIndex
transactionIndex
BlockRefWithHeader
BlockRefWithHeader
is an object that refers to a block and contains its header. Think of it as an incomplete Block
object.hash
number
header
Block
hash
number
size
header
uncles
transactions
BlockHeader
parentHash
unclesHash
coinbase
stateRoot
transactionsRoot
receiptRoot
logsBloom
difficulty
number
gasLimit
gasUsed
timestamp
extraData
mixHash
nonce
hash
BlockEdge
undo
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
node
MinedBlock
hash
number
size
header
uncles
transactionTraces
TransactionState
hash
hash
is the hash of this transaction. It is also a universally unique pointer to this transaction.