GraphQL API
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
searchTransactionsForward
Search the blockchain forward for transaction execution traces based on query
.
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.
irreversibleOnly
).
irreversibleOnly
). A null
value means no higher limits, therefore searching into the future of the chain.
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.
searchTransactionsBackward
Search the blockchain backward for transaction execution traces based on query
.
NOTE: The undo
field is not used in backwards search.
irreversibleOnly
).
irreversibleOnly
), -1 being the head block.
cursor
field in the responses of this call. It is safe to use the same cursor in BOTH directions (forward and backward).
Query
getAccountHistoryActions
Retrieve the last actions, that are irreversible, and that:
- notified an account, or
- was authorized by an account.
Results are actions, returned in reverse order (from recent to older actions).
NOTE: usually, the backing service of this method holds a truncated window of history, per account.
Read the cursor
in the response, and pass it back to cursor
to continue paginating. This is a short-lived cursor, especially as the truncation window goes by.
getActions
query.
searchTransactionsForward
Search the blockchain forward for transaction execution traces based on query
.
When the returned cursor
is empty, it means you have reached the end of the specified block range.
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.
See also the streaming version under Subscription
irreversibleOnly
).
irreversibleOnly
).
cursor
field in the responses of this call. It is safe to use the same cursor in BOTH directions (forward and backward).
searchTransactionsBackward
Search the blockchain backward for transaction execution traces based on query
.
When the returned cursor
is empty, it means you have reached the end of the specified block
range.
See also the streaming version under Subscription
irreversibleOnly
).
irreversibleOnly
).
cursor
field in the responses of this call. It is safe to use the same cursor in BOTH directions (forward and backward).
blockIDByTime
time
, based on the comparator
provided.blockIDAtAccountCreation
account
was created.Query
block
tokens
accountBalances
tokenBalances
Block
id
num
dposLIBNum
irreversible
header
merkleRoot
executedTransactionCount
transactionTraces
BlockHeader
id
num
timestamp
producer
confirmed
previous
transactionMRoot
actionMRoot
scheduleVersion
newProducers
BlockRootMerkle
nodeCount
activeNodes
ProducerSchedule
version
producers
ProducerKey
producerName
blockSigningKey
TransactionTraceConnection
edges
pageInfo
TransactionTraceEdge
cursor
node
PageInfo
startCursor
endCursor
hasNextPage
hasPreviousPage
SearchTransactionsForwardResponse
cursor
null
cursor means the end of range has been reached.results
SearchTransactionsBackwardResponse
cursor
results
SearchTransactionForwardResponse
A single transaction trace response, matching a forward search query.
WARNING: 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 trace.status
to make sure it is executed
if you want to make sure a transaction made it to the chain.
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 or triple count transactions.
cursor
isIrreversible
irreversibleBlockNum
trace.block.num
), in which case, isIrreversible
is true. In the reversible segment of the chain, this number will be drifting away by the number of blocks separating head block and LIB.block
trace
Traces of execution of the transaction containing matching actions.
Check matchingActions
below to limit the response to only actions matching your search query. Although, all actions from the transactions are available (see executedActions
).
SearchTransactionBackwardResponse
A single transaction trace response, matching a backward search query.
NOTE: always check the value of trace.status
to make sure it is executed
if you want to make sure a transaction made it to the chain.
cursor
isIrreversible
irreversibleBlockNum
trace.block.num
), in which case, isIrreversible
is true. In the reversible segment of the chain, this number will be drifting away by the number of blocks separating head block and LIB.block
trace
Traces of execution of the transaction containing matching actions.
Check matchingActions
below to limit the response to only actions matching your search query. Although, all actions from the transactions are available (see executedActions
).
AccountHistoryActionsConnection
edges
pageInfo
SimpleActionTraceEdge
cursor
node
SimpleActionTrace
SimpleActionTrace holds the traces of execution of a single action within a transaction, but contains less contextual information from the transaction than an ActionTrace.
This object is used with the getActions
Query.
blockNum
blockID
blockTime
trxID
seq
executionIndex
receipt
Action receipt (which differs from the Transaction receipt).
The receipt will be null when failures occur. Verify the status
field on the TransactionTrace object.
receiver
Account which code was executed to produce this execution trace.
Shorthand for receipt.receiver
account
Target method’s account name. This does not correspond to the contract code being executed, that is what receiver
means. This value namespaces your actions.
Shorthand for act.account in nodeos
traces
name
Target method’s action name. This value, combined with the account
, determines which code path will be executed in the receiver
contract code.
Shorthand for act.name in nodeos
traces.
authorization
Signatories required to execute this action.
Shorthand for act.authorization
in nodeos
traces.
data
Data payload. Might be a string or a JSON object, depending on whether it was possible to unpack it using an ABI.
Shorthand for act.data
in nodeos
traces.
json
JSON Object representing the action parameters, decoded through the ABI. Will be null
if it wasn’t possible to decode it.
Shorthand for action.json
hexData
Hex-encoded string representing the raw data for the action.
Shorthand for act.hex_data
in nodeos
traces.
console
print()
statements from within the smart contract.contextFree
isNotify
require_notify
method from the EOSIO intrinsics (from within a smart-contract).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
(in the receipt
) to
make sure you’re not considering a failed transaction as if it was
successful.
id
block
status
receipt.status
.receipt
elapsed
Amount of execution time in microseconds (µs) elapsed by this whole transaction. This
corresponds to the transaction_trace.elapsed
field in the EOSIO software.
WARN: This is not the propagated consensus value. This value is from the EOSIO node
that replayed the transaction from the network. Use receipt.cpuUsageMicroSeconds
in your
GraphQL operation instead to retrieve the consensus value.
netUsage
Amount of network bandwidth consumed (for the sake of the rate limiting engine) by this whole transaction, in
bytes. This corresponds to the transaction_trace.net_usage
field in the EOSIO software (which is usually
equivalent to receipt.net_usage_words * 8
).
WARN: This is not the propagated consensus value. This value is from the EOSIO node
that replayed the transaction from the network. While there is no reason to not match the
consensus value, it still could be different. Use receipt.netUsageWords
in your
GraphQL operation instead to retrieve the consensus value (multiple it by 8 to get the amount of
bytes).
scheduled
executedActions
matchingActions
topLevelActions
nodeos
version 1.7.0 and below, this corresponds to the action_traces
field.exceptJSON
TransactionReceiptHeader
status
cpuUsageMicroSeconds
netUsageWords
ActionTrace
seq
executionIndex
receipt
Action receipt (which differs from the Transaction receipt).
The receipt will be null when failures occur. Verify the status
field on the TransactionTrace object.
receiver
Account which code was executed to produce this execution trace.
Shorthand for receipt.receiver
account
Target method’s account name. This does not correspond to the contract code being executed, that is what receiver
means. This value namespaces your actions.
Shorthand for act.account in nodeos
traces
name
Target method’s action name. This value, combined with the account
, determines which code path will be executed in the receiver
contract code.
Shorthand for act.name in nodeos
traces.
authorization
Signatories required to execute this action.
Shorthand for act.authorization
in nodeos
traces.
data
Data payload. Might be a string or a JSON object, depending on whether it was possible to unpack it using an ABI.
Shorthand for act.data
in nodeos
traces.
json
JSON Object representing the action parameters, decoded through the ABI. Will be null
if it wasn’t possible to decode it.
Shorthand for action.json
hexData
Hex-encoded string representing the raw data for the action.
Shorthand for act.hex_data
in nodeos
traces.
ramOps
A list of RAM mutation operations, produced by this transaction.
NOTE: the RAM ops on an action never include operations that are mutations of the transaction itself (like creation of a deferred, or removal of a deferred from RAM). For this, check ramOps
on the TransactionTrace object.
dtrxOps
tableOps
dbOps
receiver
.console
print()
statements from within the smart contract.contextFree
elapsed
exceptJSON
isNotify
require_notify
method from the EOSIO intrinsics (from within a smart-contract).isMatchingQuery
createdActions
executedActions
on the TransactionTrace object.creatorAction
closestUnnotifiedAncestorAction
Use this to rebuild the execution tree, using the nodeos
dispatch algorithm of notifications, actions and context-free actions.
This is similar to what you would have gotten in nodeos
prior to version 1.8.0.
RAMOp
operation
payer
delta
usage
Number of bytes now used by the payer
account, after applying this RAM operation.
To have a precise view of the RAM left on an account after this transaction was applied, go through all actions in execution order (TransactionTrace.executedActions
) and use the last RAMOp for the given account.
DTrxOp
operation
sender
senderID
payer
publishedAt
delayUntil
expirationAt
trxID
transaction
transaction
TableOp
operation
table
DBOp
Represents the change delta of a row, in a contract table.
The operation
field can be used to determine what happened
to the row. Was is just inserted, modified or deleted?
operation
The operation
type should be referred to when inspecting the oldData
, oldJSON
, newData
, newJSON
fields. The operation
’s value will determine what those value will contain.
Assume the following example fields values (for brievity and clarity, we show the oldJSON
and the newJSON
fields, but the concept applies equally to oldData
and newData
which
are the Hexadecimal binary version of the JSON):
{ operation: "INS", newJSON: { "id":1, "name": "john" }, oldJSON: <nil> } }
{ operation: UPD, newJSON: { "id":1, "name": "johnny"}, oldJSON: { "id":1, "name": "john" } }
{ operation: REM, newJSON: <nil>, oldJSON: { "id":1, "name": "johnny" } }
When the operation
type is "INS"
, the oldJSON
will be null
, since it’s a new row,
it cannot have a previous state, the newJSON
will be set with the new value just inserted.
When the operation
type is "UPD"
, the newJSON
will contain the new row’s value after
the update while the oldJSON
will be set with the value the row had before being updated.
When the operation
type is "REM"
, the newJSON
will be null
, since it’s a deleted row,
no new state exists, the oldJSON
will be set with the value the row had before being
deleted.
oldPayer
newPayer
key
oldData
newData
oldJSON
newJSON
DBOpKey
code
table
scope
key
TableOpKey
code
table
scope
ActionReceipt
Execution receipt for a given ActionTrace.
The nodeos
field auth_sequence
is not yet present. Contact us if you need it.
receiver
account
, or the target account of the action, in the case of notifications. See documentation for require_notify
in EOSIO contractsdigest
act_digest
from nodeos
globalSequence
Globally unique sequence number in all actions from the longest chain. This will never be reused, and is guaranteed to monotonically increment with each action.
This property can be relied on to keep track of forks in your database, at the action level.
WARNING: when micro-forks happens, global sequences from the different forks will be reused, but will be associated with other actions. This is why it’s important to navigate forks properly.
codeSequence
abiSequence
Transaction
expiration
refBlockNum
TaPoS reference block num.
This value holds only 16 bits of the blockNum (instead of 32). The other 16 bits are in the current blockNum (unless overflown).
refBlockPrefix
maxNetUsageWords
maxCPUUsageMS
delaySec
contextFreeActions
actions
Action
account
name
authorization
json
data
hexData
PermissionLevel
actor
permission
AuthSequence
account
sequence
DecodedObject
object
error
BlockIDResponse
time
num
id
TokenConnection
blockRef
block
is the block at which the token data is validedges
pageInfo
TokenEdge
cursor
node
BlockRef
number
id
Token
contract
symbol
precision
issuer
holders
maximumSupply
totalSupply
AccountBalanceConnection
blockRef
block
is the block at which the token data is valid