"""
Account information
The Account type contains identity information for HOPR nodes including keys,
addresses, and network announcements. To query balances and allowances, use the
dedicated balance and allowance queries (hoprBalance, nativeBalance, safeHoprAllowance).
"""
type Account {
"""
Unique identifier for the account
"""
keyid: Int!
"""
Unique account on-chain address in hexadecimal format
"""
chainKey: String!
"""
Unique account packet key in peer id format
"""
packetKey: String!
"""
HOPR Safe contract address to which the account is linked
"""
safeAddress: String
"""
Latest announced multiaddress for the packet key, returned as an empty or single-element list
"""
multiAddresses: [String!]!
}
"""
Success response for accounts list query
"""
type AccountsList {
"""
List of accounts
"""
accounts: [Account!]!
}
"""
Result type for accounts list query
"""
union AccountsResult = AccountsList | MissingFilterError | QueryFailedError
"""
Result type for module address calculation
"""
union CalculateModuleAddressResult = ModuleAddress | InvalidAddressError | QueryFailedError
"""
Blockchain and HOPR network information
"""
type ChainInfo {
"""
Current block number of the blockchain
"""
blockNumber: Int!
"""
Chain ID of the connected blockchain network
"""
chainId: Int!
"""
Network name (e.g., 'rotsee', 'jura')
"""
network: String!
"""
Current HOPR token price
"""
ticketPrice: TokenValueString!
"""
Current key binding fee
"""
keyBindingFee: TokenValueString!
"""
Estimated legacy gas price in wei from RPC
"""
gasPrice: String
"""
Estimated EIP-1559 max fee per gas in wei from RPC, scaled by api.gas_multiplier
"""
maxFeePerGas: String
"""
Estimated EIP-1559 max priority fee per gas in wei from RPC, scaled by api.gas_multiplier
"""
maxPriorityFeePerGas: String
"""
Current minimum ticket winning probability (decimal value between 0.0 and 1.0)
"""
minTicketWinningProbability: Float!
"""
Channel smart contract domain separator (hex string)
"""
channelDst: String
"""
Map of contract identifiers to their deployed addresses
"""
contractAddresses: ContractAddressMap!
"""
Ledger smart contract domain separator (hex string)
"""
ledgerDst: String
"""
Safe Registry smart contract domain separator (hex string)
"""
safeRegistryDst: String
"""
Channel closure grace period in seconds
"""
channelClosureGracePeriod: UInt64!
"""
Expected block time in seconds
"""
expectedBlockTime: UInt64!
"""
Number of block confirmations required for finality
"""
finality: UInt64!
}
"""
Result type for chain info queries
"""
union ChainInfoResult = ChainInfo | QueryFailedError
"""
Payment channel between two nodes
"""
type Channel {
"""
Unique identifier for the payment channel in hexadecimal format
"""
concreteChannelId: String!
"""
Account keyid of the source node
"""
source: Int!
"""
Account keyid of the destination node
"""
destination: Int!
"""
Total amount of HOPR tokens allocated to the channel
"""
balance: TokenValueString!
"""
Current state of the channel (OPEN, PENDINGTOCLOSE, or CLOSED)
"""
status: ChannelStatus!
"""
Current epoch of the channel (uint24)
"""
epoch: Int!
"""
Latest ticket index used in the channel (uint48, max: 281474976710655)
"""
ticketIndex: UInt64!
"""
Timestamp when the channel closure was initiated (null if no closure initiated)
"""
closureTime: DateTime
}
"""
Aggregated channel statistics: count and total balance
"""
type ChannelStats {
"""
Number of channels matching the filters
"""
count: Int!
"""
Total wxHOPR balance across all matching channels
"""
balance: TokenValueString!
}
"""
Result type for channel statistics query
"""
union ChannelStatsResult = ChannelStats | InvalidAddressError | QueryFailedError
"""
Status of a payment channel
"""
enum ChannelStatus {
"""
Channel is open and operational
"""
OPEN
"""
Channel is in the process of closing
"""
PENDINGTOCLOSE
"""
Channel has been closed
"""
CLOSED
}
"""
Success response for channels list query
"""
type ChannelsList {
"""
List of channels
"""
channels: [Channel!]!
}
"""
Result type for channels list query
"""
union ChannelsResult = ChannelsList | InvalidAddressError | MissingFilterError | QueryFailedError
"""
Response for the legacy `compatibility` query.
"""
type Compatibility {
"""
Server version (semver).
"""
apiVersion: String!
"""
Semver range of compatible client versions. Always `"*"` — any client is accepted.
"""
supportedClientVersions: String!
"""
Feature flags advertised by this server. Always empty since versioning is now header-based.
"""
features: [String!]!
}
scalar ContractAddressMap
"""
Target contract not in allowlist
"""
type ContractNotAllowedError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
"""
Contract address that was rejected
"""
contractAddress: String!
}
"""
Count value for count queries
"""
type Count {
"""
Count value
"""
count: Int!
}
"""
Result type for count queries
"""
union CountResult = Count | MissingFilterError | QueryFailedError
"""
Address returned by a Curvy portal lookup.
"""
type CurvyAddress {
"""
Curvy portal address in hexadecimal format.
"""
address: String!
}
"""
Curvy Aggregator fee configuration needed to build a valid aggregation proof.
"""
type CurvyAggregatorFees {
"""
Protocol fee charged per thousand units.
"""
protocolFeePerThousand: UInt256!
"""
Root of the commitment gas-fee tree.
"""
commitmentFeeRoot: Hex32!
"""
Baby Jubjub public key that owns protocol fee notes.
"""
feeNotePublicKey: [UInt256!]!
}
"""
Result type for the Curvy Aggregator fee query.
"""
union CurvyAggregatorFeesResult = CurvyAggregatorFees | QueryFailedError
"""
Current Curvy Aggregator indices and notes-tree root.
"""
type CurvyAggregatorState {
"""
Current notes-tree root.
"""
notesTreeRoot: Hex32!
"""
Current committed-notes batch index.
"""
notesBatchIndex: UInt256!
"""
Current committed-nullifiers batch index.
"""
nullifiersBatchIndex: UInt256!
"""
Number of non-padding notes committed to the notes tree.
"""
noteIndex: UInt256!
}
"""
Result type for the Curvy Aggregator state query.
"""
union CurvyAggregatorStateResult = CurvyAggregatorState | QueryFailedError
"""
Boolean value returned by Curvy contract checks.
"""
type CurvyBooleanValue {
"""
Result of the contract check.
"""
value: Boolean!
}
"""
One note emitted by `CommittedNotes`.
"""
type CurvyCommittedNote {
"""
Commitment batch index as a fixed-width 32-byte value.
"""
batchIndex: Hex32!
"""
Committed note identifier.
"""
noteId: Hex32!
"""
Dense zero-based position in the notes tree.
"""
leafIndex: UInt64!
"""
Chain position of the array item that emitted this note.
"""
position: CurvyEventPosition!
}
"""
Collection of indexed Curvy committed notes.
"""
type CurvyCommittedNotes {
"""
Committed notes ordered by chain position.
"""
notes: [CurvyCommittedNote!]!
}
"""
Result type for the indexed Curvy committed-notes query.
"""
union CurvyCommittedNotesResult = CurvyCommittedNotes | QueryFailedError
"""
One nullifier emitted by `CommittedNullifiers`.
"""
type CurvyCommittedNullifier {
"""
Nullifier batch index as a fixed-width 32-byte value.
"""
batchIndex: Hex32!
"""
Committed nullifier value.
"""
nullifier: Hex32!
"""
Dense zero-based position in the nullifier sequence.
"""
nullifierIndex: UInt64!
"""
Chain position of the array item that emitted this nullifier.
"""
position: CurvyEventPosition!
}
"""
Collection of indexed Curvy committed nullifiers.
"""
type CurvyCommittedNullifiers {
"""
Committed nullifiers ordered by chain position.
"""
nullifiers: [CurvyCommittedNullifier!]!
}
"""
Result type for the indexed Curvy committed-nullifiers query.
"""
union CurvyCommittedNullifiersResult = CurvyCommittedNullifiers | QueryFailedError
"""
Result type for a derived Curvy entry portal address.
"""
union CurvyEntryPortalAddressResult = CurvyAddress | InvalidAddressError | QueryFailedError
"""
Exclusive pagination cursor for indexed Curvy events.
"""
input CurvyEventCursor {
"""
Block number containing the event.
"""
block: UInt64!
"""
Zero-based transaction index inside the block.
"""
transactionIndex: UInt64!
"""
Zero-based log index inside the transaction receipt.
"""
logIndex: UInt64!
"""
Zero-based position of the item inside the event array.
"""
eventItemIndex: UInt64!
"""
Hash of the block containing the event, when known.
"""
blockHash: Hex32
}
"""
Position and transaction identity shared by indexed Curvy events.
"""
type CurvyEventPosition {
"""
Hash of the transaction that emitted the event.
"""
transactionHash: Hex32!
"""
Hash of the block containing the event.
"""
blockHash: Hex32!
"""
Block number containing the event.
"""
block: UInt64!
"""
Zero-based transaction index inside the block.
"""
transactionIndex: UInt64!
"""
Zero-based log index inside the transaction receipt.
"""
logIndex: UInt64!
"""
Zero-based position of the item inside the event array.
"""
eventItemIndex: UInt64!
}
"""
Result type for a derived Curvy exit portal address.
"""
union CurvyExitPortalAddressResult = CurvyAddress | InvalidAddressError | QueryFailedError
"""
Current per-token gas fees read from the Curvy Vault.
"""
type CurvyGasFees {
"""
Identifier of the configured vault token.
"""
tokenId: UInt256!
"""
Gas fee charged when deploying a portal.
"""
portalDeployment: UInt256!
"""
Gas fee charged when committing a pending note.
"""
pendingNoteCommitment: UInt256!
"""
Gas fee charged when withdrawing a note.
"""
withdrawal: UInt256!
}
"""
Raw status of a Curvy note.
"""
type CurvyNoteStatus {
"""
Numeric `NoteStatus` value returned by the Aggregator.
"""
status: Int!
}
"""
Result type for the Curvy note-status query.
"""
union CurvyNoteStatusResult = CurvyNoteStatus | QueryFailedError
"""
Result type for the Curvy nullifier-spent check.
"""
union CurvyNullifierSpentResult = CurvyBooleanValue | QueryFailedError
"""
One note emitted by `PendingNotes`.
"""
type CurvyPendingNote {
"""
Pending note identifier.
"""
noteId: Hex32!
"""
Baby Jubjub ephemeral public key coordinates.
"""
ephemeralKey: [UInt256!]!
"""
View tag used for local ownership detection.
"""
viewTag: Int!
"""
Vault token identifier.
"""
tokenId: UInt256!
"""
Raw note amount.
"""
amount: UInt256!
"""
Whether the note payload is plaintext.
"""
isPlaintext: Boolean!
"""
Chain position of the array item that emitted this note.
"""
position: CurvyEventPosition!
}
"""
Collection of indexed Curvy pending notes.
"""
type CurvyPendingNotes {
"""
Pending notes ordered by chain position.
"""
notes: [CurvyPendingNote!]!
}
"""
Result type for the indexed Curvy pending-notes query.
"""
union CurvyPendingNotesResult = CurvyPendingNotes | QueryFailedError
"""
Result type for the Curvy portal-registration check.
"""
union CurvyPortalRegisteredResult = CurvyBooleanValue | InvalidAddressError | QueryFailedError
"""
One completed Curvy notes-tree shard.
"""
type CurvyShardRoot {
"""
Dense zero-based shard index.
"""
shardIndex: UInt64!
"""
Root of the completed shard.
"""
root: Hex32!
"""
Chain position at which the shard became complete.
"""
completionPosition: CurvyEventPosition!
}
"""
Checkpoint-pinned page of completed Curvy shard roots.
"""
type CurvyShardRootPage {
"""
Block hash identifying the synchronization checkpoint.
"""
checkpoint: Hex32!
"""
Completed shard roots in this page.
"""
shardRoots: [CurvyShardRoot!]!
"""
Dense index from which the next page starts.
"""
nextIndex: UInt64!
"""
Total number of completed shards at the checkpoint.
"""
total: UInt64!
}
"""
Result type for the checkpoint-pinned Curvy shard-root query.
"""
union CurvyShardRootsResult = CurvyShardRootPage | QueryFailedError
"""
Finalized, immutable Curvy synchronization checkpoint.
"""
type CurvySyncCheckpoint {
"""
Number of the finalized checkpoint block.
"""
blockNumber: UInt64!
"""
Hash of the finalized checkpoint block.
"""
blockHash: Hex32!
"""
Address of the indexed Curvy Aggregator.
"""
aggregatorAddress: String!
"""
Version of the persisted notes-tree representation.
"""
treeVersion: Int!
"""
Depth of the Curvy notes tree.
"""
treeDepth: Int!
"""
Height of each persisted notes-tree shard.
"""
shardHeight: Int!
"""
Number of leaves in each notes-tree shard.
"""
shardSize: UInt64!
"""
Number of indexed non-padding notes.
"""
noteCount: UInt64!
"""
Number of indexed non-padding nullifiers.
"""
nullifierCount: UInt64!
"""
Number of completed notes-tree shards.
"""
shardCount: UInt64!
"""
Notes-tree root at the checkpoint.
"""
notesRoot: Hex32!
}
"""
Result type for the Curvy synchronization-checkpoint query.
"""
union CurvySyncCheckpointResult = CurvySyncCheckpoint | QueryFailedError
"""
Committed note plus its optional announcement metadata for SDK synchronization.
"""
type CurvySyncNote {
"""
Dense zero-based position in the notes tree.
"""
leafIndex: UInt64!
"""
Committed note identifier.
"""
noteId: Hex32!
"""
Commitment batch index.
"""
batchIndex: Hex32!
"""
Matching pending-note announcement, when indexed.
"""
announcement: CurvyPendingNote
"""
Chain position at which the note was committed.
"""
commitPosition: CurvyEventPosition!
}
"""
Checkpoint-pinned page of dense Curvy committed notes.
"""
type CurvySyncNotePage {
"""
Block hash identifying the synchronization checkpoint.
"""
checkpoint: Hex32!
"""
Committed notes in this page.
"""
notes: [CurvySyncNote!]!
"""
Dense index from which the next page starts.
"""
nextIndex: UInt64!
"""
Total number of notes at the checkpoint.
"""
total: UInt64!
}
"""
Result type for the checkpoint-pinned Curvy notes query.
"""
union CurvySyncNotesResult = CurvySyncNotePage | QueryFailedError
"""
Checkpoint-pinned page of dense Curvy nullifiers.
"""
type CurvySyncNullifierPage {
"""
Block hash identifying the synchronization checkpoint.
"""
checkpoint: Hex32!
"""
Committed nullifiers in this page.
"""
nullifiers: [CurvyCommittedNullifier!]!
"""
Dense index from which the next page starts.
"""
nextIndex: UInt64!
"""
Total number of nullifiers at the checkpoint.
"""
total: UInt64!
}
"""
Result type for the checkpoint-pinned Curvy nullifiers query.
"""
union CurvySyncNullifiersResult = CurvySyncNullifierPage | QueryFailedError
"""
Result type for the Curvy valid-notes-root check.
"""
union CurvyValidNotesRootResult = CurvyBooleanValue | QueryFailedError
"""
Current Curvy Vault protocol-level fees.
"""
type CurvyVaultFees {
"""
Protocol fee charged on deposits.
"""
depositFee: UInt256!
"""
Protocol fee charged on withdrawals.
"""
withdrawalFee: UInt256!
}
"""
Result type for the Curvy Vault fee query.
"""
union CurvyVaultFeesResult = CurvyVaultFees | QueryFailedError
"""
A Curvy Vault token and its configured gas fees.
"""
type CurvyVaultToken {
"""
ERC-20 token contract address.
"""
tokenAddress: String!
"""
Gas fees configured for the token.
"""
gasFees: CurvyGasFees!
}
"""
The number of tokens registered in the Curvy Vault.
"""
type CurvyVaultTokenCount {
"""
Number of registered vault tokens.
"""
count: UInt256!
}
"""
Result type for the Curvy Vault token-count query.
"""
union CurvyVaultTokenCountResult = CurvyVaultTokenCount | QueryFailedError
"""
Result type for a Curvy Vault token query.
"""
union CurvyVaultTokenResult = CurvyVaultToken | QueryFailedError
"""
Implement the DateTime<Utc> scalar
The input/output is a string in RFC3339 format.
"""
scalar DateTime
"""
Function selector not allowed
"""
type FunctionNotAllowedError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
"""
Contract address
"""
contractAddress: String!
"""
Function selector that was rejected
"""
functionSelector: String!
}
scalar Hex32
"""
HOPR token balance information for a specific address
"""
type HoprBalance {
"""
Address holding the HOPR token balance
"""
address: String!
"""
HOPR token balance
"""
balance: TokenValueString!
}
"""
Result type for HOPR balance queries
"""
union HoprBalanceResult = HoprBalance | InvalidAddressError | QueryFailedError
"""
Address format is invalid
"""
type InvalidAddressError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
"""
The invalid address that was provided
"""
address: String!
}
"""
Transaction ID format is invalid
"""
type InvalidTransactionIdError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
"""
The invalid transaction ID that was provided
"""
transactionId: String!
}
"""
Missing required filter parameter error
"""
type MissingFilterError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
}
"""
Calculated module address
"""
type ModuleAddress {
"""
Predicted module address (hexadecimal format)
"""
moduleAddress: String!
}
type MutationRoot {
"""
Submit a transaction with fire-and-forget mode
Validates the pre-signed raw transaction data and submits it to the chain.
Returns the transaction hash immediately after submission.
Does not wait for confirmation and does not track transaction status.
Use this mode for maximum performance when you don't need confirmation tracking.
"""
sendTransaction(input: TransactionInput!): SendTransactionResult!
"""
Submit a transaction asynchronously
Validates the pre-signed raw transaction data and submits it to the chain immediately.
Returns the transaction ID that can be used to query status later.
Does not wait for on-chain confirmation. Background monitor tracks confirmation.
"""
sendTransactionAsync(input: TransactionInput!): SendTransactionAsyncResult!
"""
Submit a transaction synchronously
Validates the pre-signed raw transaction data, submits it to the chain, and waits for
the specified number of confirmations (default: 3 blocks) before returning.
Transaction is persisted to store and can be queried later.
"""
sendTransactionSync(input: TransactionInput!, confirmations: Int): SendTransactionSyncResult!
}
"""
Native token balance information for a specific address
"""
type NativeBalance {
"""
Address holding the native token balance
"""
address: String!
"""
Native token balance
"""
balance: TokenValueString!
}
"""
Result type for native balance queries
"""
union NativeBalanceResult = NativeBalance | InvalidAddressError | QueryFailedError
"""
A single edge in the opened payment channels graph
Represents one channel with its associated source and destination accounts.
This is a directed edge: source → destination. If channels exist in both
directions (A→B and B→A), these are emitted as separate entries.
**Structure:**
- Each entry contains exactly one channel with its source and destination accounts
- If multiple channels exist between the same account pair, each is emitted as a separate entry
- The channel is always open (closed channels are not included)
**Usage in subscriptions:**
The `openedChannelGraphUpdated` subscription streams these entries one at a time.
Clients must accumulate entries to build the complete channel graph.
An entry is emitted whenever that specific channel is updated.
"""
type OpenedChannelsGraphEntry {
"""
The open payment channel from source to destination
"""
channel: Channel!
"""
Source account (sender end of the directed edge)
"""
source: Account!
"""
Destination account (recipient end of the directed edge)
"""
destination: Account!
}
"""
Database or internal query error
"""
type QueryFailedError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
}
type QueryRoot {
"""
Retrieve Curvy notes emitted by `PendingNotes`, ordered by chain position.
"""
curvyPendingNotes(
"""
Earliest block number to include
"""
fromBlock: UInt64,
"""
Exclusive event cursor after which results start
"""
after: CurvyEventCursor,
"""
Maximum number of notes to return
"""
first: Int
): CurvyPendingNotesResult!
"""
Retrieve Curvy notes emitted by `CommittedNotes`, ordered by chain position.
"""
curvyCommittedNotes(
"""
Earliest block number to include
"""
fromBlock: UInt64,
"""
Exclusive event cursor after which results start
"""
after: CurvyEventCursor,
"""
Maximum number of notes to return
"""
first: Int
): CurvyCommittedNotesResult!
"""
Retrieve Curvy nullifiers emitted by `CommittedNullifiers`.
"""
curvyCommittedNullifiers(
"""
Earliest block number to include
"""
fromBlock: UInt64,
"""
Exclusive event cursor after which results start
"""
after: CurvyEventCursor,
"""
Maximum number of nullifiers to return
"""
first: Int
): CurvyCommittedNullifiersResult!
"""
Retrieve the latest Curvy synchronization checkpoint or one pinned by block hash.
"""
curvySyncCheckpoint(
"""
Finalized block hash to pin, or null for the latest checkpoint
"""
blockHash: Hex32
): CurvySyncCheckpointResult!
"""
Retrieve checkpoint-pinned committed notes by dense leaf index.
"""
curvySyncNotes(
"""
Block hash identifying the synchronization checkpoint
"""
checkpoint: Hex32!,
"""
Dense leaf index from which results start
"""
fromIndex: UInt64,
"""
Maximum number of notes to return
"""
first: Int
): CurvySyncNotesResult!
"""
Retrieve checkpoint-pinned nullifiers by dense nullifier index.
"""
curvySyncNullifiers(
"""
Block hash identifying the synchronization checkpoint
"""
checkpoint: Hex32!,
"""
Dense nullifier index from which results start
"""
fromIndex: UInt64,
"""
Maximum number of nullifiers to return
"""
first: Int
): CurvySyncNullifiersResult!
"""
Retrieve checkpoint-pinned completed notes-tree shard roots.
"""
curvyShardRoots(
"""
Block hash identifying the synchronization checkpoint
"""
checkpoint: Hex32!,
"""
Dense shard index from which results start
"""
fromIndex: UInt64,
"""
Maximum number of shard roots to return
"""
first: Int
): CurvyShardRootsResult!
"""
Read the current Curvy Aggregator root and indices directly from chain.
"""
curvyAggregatorState: CurvyAggregatorStateResult!
"""
Read a Curvy note's raw `NoteStatus` value directly from chain.
"""
curvyNoteStatus(
"""
Identifier of the note to inspect
"""
noteId: Hex32!
): CurvyNoteStatusResult!
"""
Check whether a notes root is valid in the Curvy Aggregator.
"""
curvyValidNotesRoot(
"""
Notes-tree root to validate
"""
root: Hex32!
): CurvyValidNotesRootResult!
"""
Check whether a nullifier is already present in the Curvy Aggregator.
"""
curvyNullifierSpent(
"""
Nullifier value to inspect
"""
nullifier: Hex32!
): CurvyNullifierSpentResult!
"""
Read the Curvy Vault deposit and withdrawal fees directly from chain.
"""
curvyVaultFees: CurvyVaultFeesResult!
"""
Read the Curvy Aggregator fee configuration directly from chain.
The protocol fee rate, the commitment gas-fee tree root, and the fee-note
public key are all required to build a valid aggregation proof: the circuit
constrains the fee note's owner to `feeNotePublicKey` and its amount to
`gasFee + protocolFeeQ`.
"""
curvyAggregatorFees: CurvyAggregatorFeesResult!
"""
Read how many tokens are registered in the Curvy Vault, so a client can
enumerate `curvyVaultToken` over the real set instead of probing ids.
"""
curvyVaultTokenCount: CurvyVaultTokenCountResult!
"""
Read a Curvy Vault token address and per-token gas fees directly from chain.
"""
curvyVaultToken(
"""
Identifier of the vault token to read
"""
tokenId: UInt256!
): CurvyVaultTokenResult!
"""
Derive a Curvy entry portal address directly from PortalFactory.
"""
curvyEntryPortalAddress(
"""
Hash of the entry portal owner identity
"""
ownerHash: UInt256!,
"""
Recovery address configured for the portal
"""
recovery: String!
): CurvyEntryPortalAddressResult!
"""
Derive a Curvy exit portal address directly from PortalFactory.
"""
curvyExitPortalAddress(
"""
Exit owner address configured for the portal
"""
exitAddress: String!,
"""
Chain identifier on which the exit operates
"""
exitChainId: UInt256!,
"""
Recovery address configured for the portal
"""
recovery: String!
): CurvyExitPortalAddressResult!
"""
Check whether an address is registered with Curvy PortalFactory.
"""
curvyPortalRegistered(
"""
Portal address to inspect
"""
portalAddress: String!
): CurvyPortalRegisteredResult!
"""
Retrieve accounts from the database with required filtering
At least one filter parameter must be provided (keyid, packet_key, or chain_key).
Returns a union type indicating success or specific error conditions.
Filters can be combined to narrow results.
"""
accounts(
"""
Filter by account keyid
"""
keyid: Int,
"""
Filter by packet key (peer ID format)
"""
packetKey: String,
"""
Filter by chain key (hexadecimal format)
"""
chainKey: String
): AccountsResult!
"""
Count accounts matching optional filters
If no filters are provided, returns total account count.
Filters can be combined to narrow results.
"""
accountCount(
"""
Filter by account keyid
"""
keyid: Int,
"""
Filter by packet key (peer ID format)
"""
packetKey: String,
"""
Filter by chain key (hexadecimal format)
"""
chainKey: String
): CountResult!
"""
Count channels matching optional filters
If no filters are provided, returns total channels count.
Filters can be combined to narrow results.
"""
channelCount(
"""
Filter by source node keyid
"""
sourceKeyId: Int,
"""
Filter by destination node keyid
"""
destinationKeyId: Int,
"""
Filter by concrete channel ID (hexadecimal format)
"""
concreteChannelId: String,
"""
Filter by safe address — restricts to channels where the source belongs to this safe (hexadecimal format)
"""
safeAddress: String,
"""
Filter by channel status (optional, combine with identity filters)
"""
status: ChannelStatus
): CountResult! @deprecated(reason: "Use channelStats instead, which also returns the total wxHOPR balance.")
"""
Retrieve count and total wxHOPR balance for channels matching optional filters
If no filters are provided, returns stats across all channels.
The safe_address filter restricts results to channels where the source account
is associated with the given safe contract.
Filters can be combined to narrow results.
"""
channelStats(
"""
Filter by source node keyid
"""
sourceKeyId: Int,
"""
Filter by destination node keyid
"""
destinationKeyId: Int,
"""
Filter by concrete channel ID (hexadecimal format)
"""
concreteChannelId: String,
"""
Filter by safe address — restricts to channels where the source belongs to this safe (hexadecimal format)
"""
safeAddress: String,
"""
Filter by channel status
"""
status: ChannelStatus
): ChannelStatsResult!
"""
Retrieve channels with required filtering
At least one identity-based filter must be provided (source_key_id, destination_key_id,
concrete_channel_id, or safe_address). The status filter is optional and can be combined
with others. The safe_address filter restricts results to channels where the source account
is associated with the given safe contract.
Returns the list of matching channels.
"""
channels(
"""
Filter by source node keyid
"""
sourceKeyId: Int,
"""
Filter by destination node keyid
"""
destinationKeyId: Int,
"""
Filter by concrete channel ID (hexadecimal format)
"""
concreteChannelId: String,
"""
Filter by channel status (optional, combine with identity filters)
"""
status: ChannelStatus,
"""
Filter by safe address — restricts to channels where the source belongs to this safe (hexadecimal format)
"""
safeAddress: String
): ChannelsResult!
"""
Retrieve HOPR token balance for a specific address
This query makes a direct RPC call to the blockchain to get a current HOPR token balance.
No database storage is used - balance is fetched directly from the chain.
"""
hoprBalance(
"""
On-chain address to query (hexadecimal format)
"""
address: String!,
"""
Token type to query (defaults to wxHOPR)
"""
token: Token
): HoprBalanceResult!
"""
Retrieve native token balance for a specific address
This query makes a direct RPC call to the blockchain to get the current native token (xDAI) balance.
No database storage is used - balance is fetched directly from the chain.
"""
nativeBalance(
"""
On-chain address to query (hexadecimal format)
"""
address: String!
): NativeBalanceResult!
"""
Retrieve Safe HOPR token allowance for a specific Safe address
Returns the wxHOPR token allowance that the specified Safe contract has granted
to the HOPR channels contract.
This query makes a direct RPC call to the blockchain to get the current allowance.
No database storage is used - allowance is fetched directly from the chain.
"""
safeHoprAllowance(
"""
Safe contract address to query (hexadecimal format)
"""
address: String!
): SafeHoprAllowanceResult!
"""
Retrieve aggregated TicketRedeemed statistics filtered by safe, node, or both.
At least one filter field must be provided. If both are provided, both filters are applied.
"""
ticketRedemptionStats(
"""
Filter specifying which safe/node combination to aggregate
"""
filter: RedeemedStatsFilter!
): RedeemedStatsResult!
"""
Fetches the transaction count for any Ethereum address (EOA or contract).
The `address` must be a hexadecimal Ethereum address. The resolver validates the address format,
queries the blockchain RPC for the transaction count with smart detection, and returns a
`TransactionCountResult` that indicates success, an invalid address error, or a query failure.
This method supports multiple address types:
- **EOAs (Externally Owned Accounts)**: Returns the transaction count via `eth_getTransactionCount`
- **Safe contracts**: Returns the Safe's internal nonce via `nonce()` function
- **Other contracts**: Attempts `nonce()` call, falls back to `eth_getTransactionCount`
# Returns
- `TransactionCountResult::TransactionCount` containing the queried `address` and the `count` on success.
- `TransactionCountResult::InvalidAddress` if the provided address is not a valid hexadecimal Ethereum address.
- `TransactionCountResult::QueryFailed` if the RPC call fails.
# Examples
```ignore
# use api::query::TransactionCountResult;
# use api::query::TransactionCount;
# use api::query::UInt64;
// Suppose `res` is the value returned by `transaction_count`.
let res: TransactionCountResult = TransactionCountResult::TransactionCount(TransactionCount {
address: "0x0000000000000000000000000000000000000000".to_string(),
count: UInt64(42),
});
match res {
TransactionCountResult::TransactionCount(tc) => {
assert_eq!(tc.count.0, 42);
assert_eq!(tc.address, "0x0000000000000000000000000000000000000000");
}
TransactionCountResult::InvalidAddress(err) => panic!("invalid address: {}", err.message),
TransactionCountResult::QueryFailed(err) => panic!("query failed: {}", err.message),
}
```
"""
transactionCount(
"""
Address to query (hexadecimal format) - supports EOAs and contracts
"""
address: String!
): TransactionCountResult!
safeBy(
"""
Selector type for safe lookup
"""
selector: SafeSelectorInput!,
"""
Address value for the selector (hexadecimal format)
"""
address: String!
): SafeByResult
"""
Fetches a Safe by its contract address.
Validates the provided hexadecimal address, queries the database for a matching safe contract,
and returns a GraphQL-safe result wrapper indicating success, validation failure, or query failure.
The function returns `None` when no safe with the given address exists.
# Returns
- `Some(SafeResult::Safe)` with the found safe on success.
- `Some(SafeResult::InvalidAddress)` when the address format is invalid.
- `Some(SafeResult::QueryFailed)` when the database query fails.
- `None` when no safe is found for the given address.
# Examples
```
// Example usage (executed in an async context with a prepared `ctx`):
// let res = query_root.safe(&ctx, "0x0123...abcd".to_string()).await?;
// match res {
// Some(SafeResult::Safe(s)) => println!("Found safe: {}", s.address),
// Some(SafeResult::InvalidAddress(err)) => eprintln!("Invalid address: {}", err.message),
// Some(SafeResult::QueryFailed(err)) => eprintln!("Query failed: {}", err.message),
// None => println!("Safe not found"),
// }
```
"""
safe(
"""
Safe contract address to query (hexadecimal format)
"""
address: String!
): SafeResult @deprecated(reason: "Use safeBy(selector: ...)")
"""
Finds a Safe by chain key using the deprecated `safeByChainKey` resolver.
The function validates the provided `chain_key` as an Ethereum-style hex address and returns one of the GraphQL
union variants describing the outcome:
- `Some(SafeResult::Safe(...))` when a matching safe is found,
- `None` when no safe exists for the given chain key,
- `Some(SafeResult::InvalidAddress(...))` when the `chain_key` is not a valid hex address,
- `Some(SafeResult::QueryFailed(...))` when the database query fails.
# Parameters
- `chain_key`: Chain key to query (hexadecimal format).
# Returns
`Some(SafeResult::Safe)` with the found `Safe` if a record exists; `None` if no record exists;
`Some(SafeResult::InvalidAddress)` if the chain key format is invalid; `Some(SafeResult::QueryFailed)` if
the database query fails.
# Examples
```ignore
// Given a prepared `query_root` and GraphQL `ctx`:
let res = futures::executor::block_on(query_root.safe_by_chain_key(&ctx, "0x0123...".to_string())).unwrap();
match res {
Some(SafeResult::Safe(s)) => println!("Found safe: {}", s.address),
Some(SafeResult::InvalidAddress(_)) => println!("Invalid chain key"),
Some(SafeResult::QueryFailed(_)) => println!("Query failed"),
None => println!("No safe for that chain key"),
}
```
"""
safeByChainKey(
"""
Chain key to query (hexadecimal format)
"""
chainKey: String!
): SafeResult @deprecated(reason: "Use safeBy(selector: ...)")
"""
Fetches a Safe contract by registered node address.
Returns the safe that a given node is registered to. If the node is not
registered to any safe, returns `None`. On success, the returned `Safe` includes
all node addresses registered to that safe in the `registered_nodes` field.
# Arguments
* `chain_key` - Hex-encoded Ethereum address of the registered node
# Returns
* `Some(SafeResult::Safe)` - The safe that the node is registered to
* `None` - Node is not registered to any safe
* `Some(SafeResult::InvalidAddress)` - Invalid address format
* `Some(SafeResult::QueryFailed)` - Database error
# Examples
```ignore
# use async_graphql::Context;
# use crate::api::QueryRoot;
# async fn doc_example(ctx: &Context<'_>) {
let query = QueryRoot;
let node_addr = "0x1234567890123456789012345678901234567890";
match query.safe_by_registered_node(ctx, node_addr.to_string()).await.unwrap() {
Some(crate::api::SafeResult::Safe(safe)) => {
println!("Node registered to safe: {}", safe.address);
}
None => {
println!("Node not registered to any safe");
}
_ => {}
}
# }
```
"""
safeByRegisteredNode(chainKey: String!): SafeResult @deprecated(reason: "Use safeBy(selector: ...)")
"""
Fetches all indexed Safe contracts.
On success returns `SafesResult::Safes` containing a `SafesList` with each safe's
`address`, `module_address`, and `chain_key` encoded as hex strings. If the database
query fails, returns `SafesResult::QueryFailed` with code `"QUERY_FAILED"` and a message.
# Examples
```ignore
# use async_graphql::Context;
# use crate::api::QueryRoot;
# async fn doc_example(ctx: &Context<'_>) {
let query = QueryRoot;
let res = query.safes(ctx).await.unwrap();
match res {
crate::api::SafesResult::Safes(list) => {
for safe in list.safes {
println!("safe: {}", safe.address);
}
}
crate::api::SafesResult::QueryFailed(err) => {
eprintln!("query failed: {}", err.message);
}
}
# }
```
"""
safes: SafesResult!
"""
Returns the current chain configuration and runtime state exposed by the API.
The returned `ChainInfo` contains the last indexed block number, the configured chain ID
and network name, human-readable token values for ticket price and key binding fee,
live gas fee estimates from RPC (`gasPrice`, `maxFeePerGas`, `maxPriorityFeePerGas`) in wei,
where `maxFeePerGas` and `maxPriorityFeePerGas` are scaled by `api.gas_multiplier`,
minimum incoming ticket winning probability, optional 32-byte domain separator hashes
for channels/ledger/safe registry as `Hex32`, a map of contract addresses, and an optional
channel closure grace period in seconds.
# Examples
```
# async fn doc_example() {
// Query the GraphQL API for chain information
let resp = /* execute GraphQL query `{ chainInfo { blockNumber chainId network } }` */ unimplemented!();
// Inspect returned `ChainInfo` in the GraphQL response
# }
```
"""
chainInfo: ChainInfoResult!
"""
Health check endpoint
Returns "ok" to indicate the service is running
"""
health: String!
"""
Client compatibility information
Legacy endpoint retained for backward compatibility with older clients.
Always reports `supported_client_versions = "*"` so any client version
that calls this query is considered compatible.
"""
compatibility: Compatibility!
"""
Calculate the predicted module address for a Safe deployment
Calls the HoprNodeStakeFactory.predictModuleAddress_1 function to compute
the deterministic CREATE2 address for a HOPR node management module.
"""
calculateModuleAddress(
"""
Safe owner address (hexadecimal format)
"""
owner: String!,
"""
Safe deployment nonce
"""
nonce: UInt64!,
"""
Safe contract address (hexadecimal format)
"""
safeAddress: String!
): CalculateModuleAddressResult!
"""
Sum the wxHOPR token balances across indexed safe contracts.
When `owner_address` is provided, restricts to safes whose indexed owner
set currently contains that address.
"""
safesBalance(
"""
Restrict to safes whose current owner set contains this address (hexadecimal format)
"""
ownerAddress: String
): SafesBalanceResult!
"""
Count service registry entries matching optional filters.
"""
serviceCount(
"""Filter by service type - ASCII name such as gvpn:exit, or 0x-prefixed hex"""
serviceType: String,
"""Filter by node chain address (hexadecimal format)"""
node: String
): CountResult!
"""
Retrieve the registry-wide service configuration.
"""
serviceRegistryConfig: ServiceRegistryConfigResult!
"""
Retrieve service type configuration, optionally filtered by service type.
"""
serviceTypes(
"""Filter by service type - ASCII name such as gvpn:exit, or 0x-prefixed hex"""
serviceType: String
): ServiceTypesResult!
"""
Retrieve a stable, paginated view of service registry entries.
"""
services(
"""Filter by service type - ASCII name such as gvpn:exit, or 0x-prefixed hex"""
serviceType: String,
"""Filter by node chain address (hexadecimal format)"""
node: String,
"""Maximum entries in this page (1-1000)"""
first: Int! = 100,
"""Cursor returned by the previous page"""
after: UInt64,
"""Watermark returned by the first page"""
watermark: UInt64,
"""Only entries whose node is bound in the registry's current NodeSafeRegistry"""
liveOnly: Boolean! = false
): ServicesResult!
"""
API version information
Returns the current version of the blokli-api package
"""
version: String!
"""
Retrieve transaction status by ID
Returns the current status of a previously submitted transaction.
Returns Error with code INVALID_TRANSACTION_ID if ID format is invalid.
Returns None if transaction ID is not found.
"""
transaction(id: ID!): TransactionResult
}
"""
Readiness state of the API server
"""
enum ReadinessState {
"""
Server is ready to accept GraphQL requests
"""
READY
"""
Server is not ready (usually during initial indexing)
"""
NOT_READY
}
"""
GraphQL output type for a ticket redemption event.
Uniquely identifies the ticket (`issuerAddress` + `recipientAddress` +
`epoch` + `index`) and reports whether it was accepted or rejected.
Returned by the `ticketRedeemed` subscription.
"""
type RedeemTicketDetails {
"""
Issuer account on-chain address in hexadecimal format
"""
issuerAddress: String!
"""
Recipient account on-chain address in hexadecimal format
"""
recipientAddress: String!
"""
Epoch of the channel where the ticket was redeemed
"""
epoch: UInt64!
"""
Index of the ticket within the channel epoch
"""
index: UInt64!
"""
Outcome of the redemption attempt
"""
result: RedemptionResult!
}
"""
Aggregated ticket redemption attempt statistics
"""
type RedeemedStats {
"""
Total amount redeemed from matching ticket redemption events
"""
redeemedAmount: TokenValueString!
"""
Total number of matching ticket redemption events
"""
redemptionCount: UInt64!
"""
Total amount from matching failed ticket redemption attempts
"""
rejectedAmount: TokenValueString!
"""
Total number of matching failed ticket redemption attempts
"""
rejectionCount: UInt64!
}
"""
Filter for ticket redemption stats queries.
At least one field must be provided. Providing both fields restricts the result
to the single matching safe/node pair; providing only one aggregates all rows
for that address.
"""
input RedeemedStatsFilter {
"""
Safe contract address to filter by (hexadecimal format)
"""
safeAddress: String
"""
Destination node address to filter by (hexadecimal format)
"""
nodeAddress: String
}
"""
Result type for redeemed statistics queries with safe/node filters
"""
union RedeemedStatsResult = RedeemedStats | MissingFilterError | InvalidAddressError | QueryFailedError
"""
Outcome of a ticket redemption attempt.
Carried in [`RedeemTicketDetails`] to allow subscribers to distinguish
successful on-chain redemptions from inner Safe transaction failures
(rejected) without polling the chain.
"""
enum RedemptionResult {
"""
Ticket was successfully redeemed on-chain.
"""
REDEEMED
"""
Ticket redemption was rejected (inner Safe transaction failed).
"""
REJECTED
}
"""
RPC or blockchain error during transaction submission
"""
type RpcError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
}
"""
HOPR Safe contract deployment information
"""
type Safe {
"""
Safe contract address (hexadecimal format)
"""
address: String!
"""
HOPR Node Management Module address (hexadecimal format)
"""
moduleAddress: String!
"""
Legacy chain key field retained for backward compatibility
"""
chainKey: String! @deprecated(reason: "Use owners instead. chainKey is legacy Safe metadata and may not reflect the current owner set.")
"""
Current signer threshold reconstructed from indexed Safe events
"""
threshold: String
"""
Current Safe owner addresses reconstructed from indexed Safe events
"""
owners: [String!]!
"""
List of node addresses (chain keys) registered to this safe via RegisteredNodeSafe events
"""
registeredNodes: [String!]!
}
"""
Result type for safe-by-selector query
"""
union SafeByResult = SafesList | InvalidAddressError | QueryFailedError
"""
Internal Safe contract execution result.
This is supplementary to [`TransactionStatus`]: the `status` field on [`Transaction`] is
the authoritative terminal outcome (e.g. `Confirmed` means the outer on-chain tx succeeded).
When `safe_execution` is present, it describes the *internal* Safe module call outcome,
which can differ from the outer tx status — a `Confirmed` transaction may still have
`safe_execution.success == false` if the internal call reverted.
"""
type SafeExecution {
"""
Whether the internal Safe transaction succeeded
"""
success: Boolean!
"""
Safe internal transaction hash (bytes32 hex).
Null for module-executed transactions (`execTransactionFromModule`) which do not
emit a txHash, or if the event data was malformed and the hash could not be extracted.
"""
safeTxHash: Hex32
"""
Revert reason (if execution failed and reason is decodable)
"""
revertReason: String
}
"""
Safe HOPR token allowance information for a specific Safe address
"""
type SafeHoprAllowance {
"""
Safe contract address
"""
address: String!
"""
wxHOPR token allowance granted by the safe to the channels contract
"""
allowance: TokenValueString!
}
"""
Result type for Safe HOPR allowance queries
"""
union SafeHoprAllowanceResult = SafeHoprAllowance | InvalidAddressError | QueryFailedError
"""
Result type for deprecated single-safe queries (`safe`, `safeByChainKey`, `safeByRegisteredNode`).
"""
union SafeResult = Safe | InvalidAddressError | QueryFailedError
"""
Selector for safe lookup queries.
This enum is used together with a single `address` argument when querying
for a safe. The selected variant determines how that `address` value is
interpreted:
- `Address`: `address` is the safe contract address
- `Owner`: `address` is a current safe owner address
- `ChainKey`: legacy alias for `Owner`
- `RegisteredNode`: `address` is a registered node address
"""
enum SafeSelectorInput {
"""
Safe contract address to filter by (hexadecimal format)
"""
ADDRESS
"""
Current safe owner address to filter by (hexadecimal format)
"""
OWNER
"""
Legacy alias for owner address filtering (hexadecimal format)
"""
CHAIN_KEY @deprecated(reason: "Use OWNER instead. CHAIN_KEY is a legacy alias for Safe owner lookup.")
"""
Registered node address to filter by (hexadecimal format)
"""
REGISTERED_NODE
}
"""
Aggregated wxHOPR holdings across all or a filtered subset of indexed safe contracts
"""
type SafesBalance {
"""
Sum of wxHOPR balances for all safe contract addresses
"""
balance: TokenValueString!
"""
Number of safes included
"""
count: Int!
}
"""
Result type for total safe wxHOPR balance query
"""
union SafesBalanceResult = InvalidAddressError | QueryFailedError | SafesBalance
"""
Success response for safes list query
"""
type SafesList {
"""
List of safes
"""
safes: [Safe!]!
}
"""
Result type for safes list query
"""
union SafesResult = SafesList | QueryFailedError
"""
Result type for asynchronous transaction submission
"""
union SendTransactionAsyncResult = Transaction | ContractNotAllowedError | FunctionNotAllowedError | RpcError
"""
Result type for fire-and-forget transaction submission
"""
union SendTransactionResult = SendTransactionSuccess | ContractNotAllowedError | FunctionNotAllowedError | RpcError
"""
Success response for fire-and-forget transaction submission
"""
type SendTransactionSuccess {
"""
Transaction hash after successful submission
"""
transactionHash: Hex32!
}
"""
Result type for synchronous transaction submission
"""
union SendTransactionSyncResult = Transaction | ContractNotAllowedError | FunctionNotAllowedError | RpcError | TimeoutError
"""
A single entry in the on-chain service registry: one node offering one service type.
"""
type ServiceEntry {
"Service type identifier - ASCII name, or 0x-prefixed hex when the id is not printable ASCII"
serviceType: String!
"Chain address of the node offering the service (hexadecimal format)"
node: String!
"Safe that performed the last write to this entry (hexadecimal format)"
safe: String!
"Opaque metadata as 0x-prefixed hex; the schema belongs to the service type, not the registry"
metadata: String!
"Unix timestamp in seconds at which the entry was registered"
registeredAt: UInt64!
"Unix timestamp in seconds at which the entry was last updated"
updatedAt: UInt64!
}
"""
Registry-wide configuration, shared by every service type.
"""
type ServiceRegistryConfig {
"wxHOPR burned to register a new service type, as a decimal string in wei"
typeRegistrationFee: String!
"Node-safe registry the service registry resolves node bindings against (hexadecimal format)"
nodeSafeRegistry: String!
}
"""
Result type for the registry-wide configuration query.
"""
union ServiceRegistryConfigResult = ServiceRegistryConfig | QueryFailedError
"""
Configuration of a single service type.
"""
type ServiceTypeInfo {
"Service type identifier - ASCII name, or 0x-prefixed hex"
serviceType: String!
"Owner of the type; null once the type has been abandoned, which is one-way"
owner: String
"Requirement contract gating registration; null for an open type"
requirement: String
"wxHOPR burned on self-registration, as a decimal string in wei"
registrationBurn: String!
"wxHOPR burned on self-update, as a decimal string in wei"
updateBurn: String!
}
"""
A change to service-type or registry-wide configuration.
"""
type ServiceTypeUpdate {
"What changed"
kind: ServiceTypeUpdateKind!
"Service type affected; null for REGISTRATION_FEE_CHANGED and REGISTRY_POINTER_CHANGED"
serviceType: String
"Type configuration after the change; null for the two registry-wide kinds"
config: ServiceTypeInfo
"Registry-wide configuration after the change; null for the five per-type kinds"
registryConfig: ServiceRegistryConfig
}
"Kind of change to service-type or registry-wide configuration"
enum ServiceTypeUpdateKind {
REGISTERED
OWNER_CHANGED
REQUIREMENT_CHANGED
REGISTRATION_BURN_CHANGED
UPDATE_BURN_CHANGED
REGISTRATION_FEE_CHANGED
REGISTRY_POINTER_CHANGED
}
"Success response for the serviceTypes query"
type ServiceTypesList {
"Matching service types"
serviceTypes: [ServiceTypeInfo!]!
}
"""
Result type for the serviceTypes query
"""
union ServiceTypesResult = ServiceTypesList | QueryFailedError
"""
A change to one registry entry.
"""
type ServiceUpdate {
"What happened to the entry"
kind: ServiceUpdateKind!
"Service type the entry belongs to"
serviceType: String!
"Node the entry belongs to (hexadecimal format)"
node: String!
"Entry state after the change; null for DEREGISTERED, where the entry no longer exists"
entry: ServiceEntry
}
"Kind of change to a single registry entry"
enum ServiceUpdateKind {
REGISTERED
UPDATED
DEREGISTERED
}
"Success response for the services query"
type ServicesList {
"Matching registry entries"
services: [ServiceEntry!]!
"Fully indexed block at which this page is evaluated"
watermark: UInt64!
"Cursor for the next page, or null at the end"
nextCursor: UInt64
}
"""
Result type for the services query
"""
union ServicesResult = ServicesList | MissingFilterError | QueryFailedError
"""
Root subscription type providing real-time updates via Server-Sent Events (SSE)
"""
type SubscriptionRoot {
"""
Stream indexed Curvy `PendingNotes` entries with an optional historical phase.
"""
curvyPendingNote(
"""
Earliest block number to replay before live streaming starts
"""
fromBlock: UInt64
): CurvyPendingNote!
"""
Stream indexed Curvy `CommittedNotes` entries with an optional historical phase.
"""
curvyCommittedNote(
"""
Earliest block number to replay before live streaming starts
"""
fromBlock: UInt64
): CurvyCommittedNote!
"""
Stream indexed Curvy `CommittedNullifiers` entries with an optional historical phase.
"""
curvyCommittedNullifier(
"""
Earliest block number to replay before live streaming starts
"""
fromBlock: UInt64
): CurvyCommittedNullifier!
"""
Subscribe to health status updates of the API
Provides updates whenever the server state changes.
"""
health: ReadinessState!
"""
Subscribe to real-time updates of payment channels
**Streaming Behavior:**
- Emits all matching channels once on subscription start (Phase 1)
- Subsequently emits updates only when channels actually change (Phase 2)
- Uses IndexerState event bus for real-time notifications
**Phase 1 Ordering:**
The initial snapshot (Phase 1) emits channels in randomized order to prevent
clients from relying on a specific ordering. Clients that reconnect will
receive entries in a different order each time.
**Update Triggers:**
A channel is re-emitted when:
- The channel's status changes (e.g., OPEN -> PENDINGTOCLOSE -> CLOSED)
- The channel's balance changes
- The channel's epoch or ticket_index changes
- A new channel opens that matches the filters
**Filters:**
All filters are optional and can be combined:
- `source_key_id`: Only channels from this source account
- `destination_key_id`: Only channels to this destination account
- `concrete_channel_id`: Only this specific channel (with or without 0x prefix)
- `status`: Only channels with this status (OPEN, CLOSED, PENDINGTOCLOSE)
**Automatic Shutdown:**
The subscription automatically terminates on blockchain reorganization,
requiring clients to reconnect to re-establish consistent state.
"""
channelUpdated(
"""
Filter by source node keyid
"""
sourceKeyId: Int,
"""
Filter by destination node keyid
"""
destinationKeyId: Int,
"""
Filter by concrete channel ID (hexadecimal format)
"""
concreteChannelId: String,
"""
Filter by channel status
"""
status: ChannelStatus
): Channel!
"""
Subscribe to the opened payment channels graph with real-time updates
**Streaming Behavior:**
- Emits one OpenedChannelsGraphEntry per open channel
- Each entry contains a single channel with its source and destination accounts
- On subscription start, emits all existing open channels as separate entries
- Subsequently, emits updates when any channel changes, including non-open states
**Phase 1 Ordering:**
The initial snapshot (Phase 1) emits channels in randomized order to prevent
clients from relying on a specific ordering. Clients that reconnect will
receive entries in a different order each time.
**Building the Graph:**
Clients receive entries incrementally (one per channel) and should accumulate
them to build the complete network topology. Entries should be merged by
concrete channel ID. Closed-channel entries are intentional removal signals
for consumers that maintain an open-channel graph.
**Update Triggers:**
An entry is re-emitted for a channel when:
- The channel's status changes (e.g., OPEN -> PENDINGTOCLOSE)
- The channel's balance changes
- The channel closes (emitted with CLOSED status so consumers can remove it)
- A new channel opens (new entry emitted)
**Example:**
If the network has three open channels: channelA (A->B), channelB (B->A), channelC (A->C),
the subscription emits three separate OpenedChannelsGraphEntry objects, each containing
one channel with its source and destination accounts.
**Note:** This is a directed graph. Bidirectional communication requires
channels in both directions, each emitted as a separate entry.
"""
openedChannelGraphUpdated: OpenedChannelsGraphEntry!
"""
Subscribe to real-time updates of account information
Provides updates whenever there is a change in account information, including
balance changes, Safe address linking, and multiaddress announcements.
Optional filters can be applied to only receive updates for specific accounts.
Uses the IndexerState event bus for real-time notifications:
- Emits matching accounts on subscription start (Phase 1)
- Streams updates when `IndexerEvent::AccountUpdated` events are received (Phase 2)
- Automatically shuts down on blockchain reorganization
**Phase 1 Ordering:**
The initial snapshot (Phase 1) emits accounts in randomized order to prevent
clients from relying on a specific ordering. Clients that reconnect will
receive entries in a different order each time.
"""
accountUpdated(
"""
Filter by account keyid
"""
keyid: Int,
"""
Filter by packet key (peer ID format)
"""
packetKey: String,
"""
Filter by chain key (hexadecimal format)
"""
chainKey: String
): Account!
"""
Subscribe to real-time updates of ticket price and winning probability
Provides updates whenever there is a change in the ticket price or minimum
winning probability on-chain. These values are essential for ticket validation
and payment channel operation.
Uses the IndexerState event bus for real-time notifications:
- Emits current value on subscription start
- Streams updates when TicketParametersUpdated events are received
- Automatically shuts down on blockchain reorganization
"""
ticketParametersUpdated: TicketParameters!
"""
Streams updates to the key binding fee.
Emits the current fee once when the subscription starts, then emits new fee
values whenever a `KeyBindingFeeUpdated` event is processed while the indexer
is synced. Consecutive duplicate fee values are suppressed.
# Examples
```no_run
use futures::StreamExt;
// In an async context with a GraphQL `Context` available:
// let stream = root.key_binding_fee_updated(&ctx).await.unwrap();
// let mut stream = Box::pin(stream);
// if let Some(fee) = stream.next().await {
// println!("current fee: {}", fee.0);
// }
```
"""
keyBindingFeeUpdated: TokenValueString!
"""
Streams newly deployed safes as `Safe` objects.
The stream yields a `Safe` for each `SafeDeployed` event observed by the indexer.
# Examples
```ignore
# use futures::StreamExt;
// `root` is a `SubscriptionRoot` and `ctx` is an `async_graphql::Context<'_>`
let mut stream = root.safe_deployed(&ctx).await.unwrap();
while let Some(safe) = stream.next().await {
println!("{}", safe.address);
}
```
"""
safeDeployed: Safe!
"""
Subscribe to the complete registry-wide configuration.
"""
serviceRegistryConfigUpdated: ServiceRegistryConfig!
"""
Subscribe to real-time changes of service type and registry-wide configuration.
"""
serviceTypeUpdated(
"""Filter by service type - ASCII name such as gvpn:exit, or 0x-prefixed hex"""
serviceType: String
): ServiceTypeUpdate!
"""
Subscribe to real-time changes of service registry entries.
"""
serviceUpdated(
"""Filter by service type - ASCII name such as gvpn:exit, or 0x-prefixed hex"""
serviceType: String,
"""Filter by node chain address (hexadecimal format)"""
node: String
): ServiceUpdate!
"""
Subscribe to real-time updates of a specific transaction
Provides updates whenever the status of the specified transaction changes,
including validation, submission, confirmation, revert, and failure events.
Uses event-driven architecture to receive updates immediately when transaction
status changes, with zero polling overhead. Follows a 2-phase approach:
- Phase 1: Emit current transaction state if it exists
- Phase 2: Listen for future status update events
"""
transactionUpdated(
"""
Transaction ID to monitor (UUID)
"""
id: ID!
): Transaction!
"""
Subscribe to real-time updates of ticket redemptions.
Streams a [`RedeemTicketDetails`] item each time a ticket redemption event
is observed on-chain. Covers both successful redemptions and inner Safe
transaction rejections (see [`RedemptionResult`]).
At most one of the three filter arguments is typically supplied. When none
are given, all ticket redemption events are emitted. Input addresses and
channel IDs are validated as hex before the stream is established.
"""
ticketRedeemed(
"""
Filter by channel ID (hexadecimal format)
"""
channelId: ID,
"""
Filter by ticket issuer (hexadecimal format)
"""
issuerAddress: ID,
"""
Filter by ticket recipient (hexadecimal format)
"""
recipientAddress: ID
): RedeemTicketDetails!
}
"""
Ticket price and winning probability parameters
"""
type TicketParameters {
"""
Current minimum ticket winning probability (decimal value between 0.0 and 1.0)
"""
minTicketWinningProbability: Float!
"""
Current HOPR token price
"""
ticketPrice: TokenValueString!
}
"""
Operation timed out
"""
type TimeoutError {
"""
Error code
"""
code: String!
"""
Human-readable error message
"""
message: String!
}
"""
Token type for balance queries
"""
enum Token {
"""
wxHOPR token
"""
HOPR
"""
xHOPR token
"""
XHOPR
"""
Native token
"""
NATIVE
}
scalar TokenValueString
"""
Transaction submission result
"""
type Transaction {
"""
Unique identifier for the transaction (UUID)
"""
id: ID!
"""
Current status of the transaction
"""
status: TransactionStatus!
"""
Timestamp when transaction was submitted
"""
submittedAt: DateTime!
"""
Transaction hash from successful blockchain submission
"""
transactionHash: Hex32!
"""
Internal Safe execution result (null for non-Safe transactions or before confirmation)
"""
safeExecution: SafeExecution
}
"""
Transaction count information for any Ethereum address
For EOAs (Externally Owned Accounts): Returns the transaction count via eth_getTransactionCount
For Safe contracts: Returns the internal nonce via nonce() function
For other contracts: Attempts nonce() call, falls back to eth_getTransactionCount
"""
type TransactionCount {
"""
Address queried (hexadecimal format)
"""
address: String!
"""
Current transaction count or nonce for the address
"""
count: UInt64!
}
"""
Result type for transaction count queries
"""
union TransactionCountResult = TransactionCount | InvalidAddressError | QueryFailedError
"""
Input for transaction submission
"""
input TransactionInput {
"""
Raw signed transaction data in hexadecimal format (with or without 0x prefix)
"""
rawTransaction: String!
}
"""
Result type for transaction query
"""
union TransactionResult = Transaction | InvalidTransactionIdError
"""
Status of a submitted transaction
"""
enum TransactionStatus {
"""
Transactions are never emitted in this state; they go directly to Submitted.
"""
PENDING @deprecated(reason: "Transactions go directly to SUBMITTED. This variant exists only for backwards compatibility and will be removed in a future release.")
"""
Transaction has been submitted and is awaiting confirmation
"""
SUBMITTED
"""
Transaction has been confirmed on-chain with success
"""
CONFIRMED
"""
Transaction was included on-chain but reverted (receipt.status = 0)
"""
REVERTED
"""
Transaction was not mined within timeout window
"""
TIMEOUT
"""
Transaction validation failed
"""
VALIDATION_FAILED
"""
Transaction submission failed
"""
SUBMISSION_FAILED
}
scalar UInt256
scalar UInt64
"""
Marks an element of a GraphQL schema as no longer supported.
"""
directive @deprecated(reason: String = "No longer supported") on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
"""
Directs the executor to include this field or fragment only when the `if` argument is true.
"""
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Directs the executor to skip this field or fragment when the `if` argument is true.
"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Provides a scalar specification URL for specifying the behavior of custom scalar types.
"""
directive @specifiedBy(url: String!) on SCALAR
schema {
query: QueryRoot
mutation: MutationRoot
subscription: SubscriptionRoot
}