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.