Skip to main content
Version: 5.0.0

Node Statistics API

This document outlines the APIs for retrieving node and account statistics within the network.

Overview​

The Node Statistics API allows you to query information about rewards and nodes associated with accounts. It provides various endpoints to retrieve data such as:

  • Rewards earned in the last 24 hours
  • Rewards earned in a custom time range
  • Lifetime rewards for an account
  • Total rewards for a specific node
  • Count of nodes owned by an account
  • Number of rewards in a time range
  • Average reward amount in a time range

API Reference​

important

The SDK can accept base58 encoded account addresses (ex: 5DA4...pgxV) or hex encoded public keys (ex: 0xc1a6...112c). GraphQL only accepts hex encoded public keys

getAccountRewardsLast24Hours​

Retrieves the total rewards earned by an account in the last 24 hours.

SDK endpoint​

await api.query.getAccountRewardsLast24Hours(<gqlEndpoint>, <accountId>);

GraphQL endpoint​

query GetAccountRewardsLast24Hours($accountId: String!) {
  getAccountRewardsLast24Hours(accountId: $accountId)
}

Parameters:

  • accountId (String!): The ID of the account to query

Returns:

  • BigInt: The total amount of rewards earned in the last 24 hours

Example:

await api.query.getAccountRewardsLast24Hours("https://node-manager.dev.truth-network.io/graphql", "5DA...gxV");
query {
  getAccountRewardsLast24Hours(accountId: "0xc1a6...112c")
}

getAccountRewardsInTimeRange​

Retrieves the total rewards earned by an account within a specified time range.

SDK endpoint​

await api.query.getAccountRewardsInTimeRange(<gqlEndpoint>, <accountId>, <startTime>, <endTime>);

GraphQL endpoint​

query GetAccountRewardsInTimeRange($accountId: String!, $startTime: String!, $endTime: String!) {
  getAccountRewardsInTimeRange(accountId: $accountId, startTime: $startTime, endTime: $endTime)
}

Parameters:

  • accountId (String!): The ID of the account to query
  • startTime (String!): The start time of the range (ISO format)
  • endTime (String!): The end time of the range (ISO format)

Returns:

  • BigInt: The total amount of rewards earned within the specified time range

Example:

await api.query.getAccountRewardsInTimeRange("https://node-manager.dev.truth-network.io/graphql", "5DA...gxV", new Date("2025-03-01T00:00"), new Date("2025-03-14T23:00"));
query {
  getAccountRewardsInTimeRange(
    accountId: "0xc1a6...112c",
    startTime: "2025-01-01T00:00:00Z",
    endTime: "2025-01-31T23:59:59Z"
  )
}

getAccountLifetimeRewards​

Retrieves the total lifetime rewards earned by an account.

SDK endpoint​

await api.query.getAccountLifetimeRewards(<gqlEndpoint>, <accountId>);

GraphQL endpoint​

query GetAccountLifetimeRewards($accountId: String!) {
  getAccountLifetimeRewards(accountId: $accountId)
}

Parameters:

  • accountId (String!): The ID of the account to query

Returns:

  • BigInt: The total amount of rewards earned over the account's lifetime

Example:

await api.query.getAccountLifetimeRewards("https://node-manager.dev.truth-network.io/graphql", "5DA...gxV");
query {
  getAccountLifetimeRewards(accountId: "0xc1a6...112c")
}

getNodeTotalRewards​

Retrieves the total rewards earned by a specific node.

SDK endpoint​

await api.query.getNodeTotalRewards(<gqlEndpoint>, <nodeId>);

GraphQL endpoint​

query GetNodeTotalRewards($nodeId: String!) {
  getNodeTotalRewards(nodeId: $nodeId)
}

Parameters:

  • nodeId (String!): The ID of the node to query

Returns:

  • BigInt: The total amount of rewards earned by the specified node

Example:

await api.query.getNodeTotalRewards("https://node-manager.dev.truth-network.io/graphql", "5CF...den");
query {
  getNodeTotalRewards(nodeId: "0xc1a6...112c")
}

getAccountNodesCount​

Retrieves the count of nodes owned by an account.

SDK endpoint​

await api.query.getAccountNodesCount(<gqlEndpoint>, <accountId>);

GraphQL endpoint​

query GetAccountNodesCount($accountId: String!) {
  getAccountNodesCount(accountId: $accountId)
}

Parameters:

  • accountId (String!): The ID of the account to query

Returns:

  • Number: The number of nodes associated with the account

Example:

await api.query.getAccountNodesCount("https://node-manager.dev.truth-network.io/graphql", "5DA...gxV");
query {
  getAccountNodesCount(accountId: "0xc1a6...112c")
}

getRewardCountInTimeRange​

Retrieves the count of rewards earned by an account within a specified time range.

SDK endpoint​

await api.query.getRewardCountInTimeRange(<gqlEndpoint>, <accountId>, <startTime>, <endTime>);

GraphQL endpoint​

query GetRewardCountInTimeRange($accountId: String!, $startTime: String!, $endTime: String!) {
  getRewardCountInTimeRange(accountId: $accountId, startTime: $startTime, endTime: $endTime)
}

Parameters:

  • accountId (String!): The ID of the account to query
  • startTime (String!): The start time of the range (ISO format)
  • endTime (String!): The end time of the range (ISO format)

Returns:

  • Number: The number of rewards earned within the specified time range

Example:

await api.query.getRewardCountInTimeRange("https://node-manager.dev.truth-network.io/graphql", "5DA...gxV", new Date("2025-03-01T00:00"), new Date("2025-03-14T23:00"));
query {
  getRewardCountInTimeRange(
    accountId: "0xc1a6...112c",
    startTime: "2025-01-01T00:00:00Z",
    endTime: "2025-01-31T23:59:59Z"
  )
}

getAverageRewardInTimeRange​

Retrieves the average reward amount earned by an account within a specified time range.

SDK endpoint​

await api.query.getAverageRewardInTimeRange(<gqlEndpoint>, <accountId>, <startTime>, <endTime>);

GraphQL endpoint​

query GetAverageRewardInTimeRange($accountId: String!, $startTime: String!, $endTime: String!) {
  getAverageRewardInTimeRange(accountId: $accountId, startTime: $startTime, endTime: $endTime)
}

Parameters:

  • accountId (String!): The ID of the account to query
  • startTime (String!): The start time of the range (ISO format)
  • endTime (String!): The end time of the range (ISO format)

Returns:

  • BigInt: The average amount of rewards earned within the specified time range

Example:

await api.query.getAverageRewardInTimeRange("https://node-manager.dev.truth-network.io/graphql", "5DA...gxV", new Date("2025-03-01T00:00"), new Date("2025-03-14T23:00"));
query {
  getAverageRewardInTimeRange(
    accountId: "0xc1a6...112c",
    startTime: "2025-01-01T00:00:00Z",
    endTime: "2025-01-31T23:59:59Z"
  )
}

Input Validation​

All time-based queries include validation to ensure:

  1. Valid date formats
  2. Start time is before end time
  3. Account exists in the system

For the SDK, account Ids can be specified as base58 addresses such as 5DA4...FgxV or 32 bytes hex encoded public keys such as 0xc1a6...112c. For GraphQL, account Ids must be specified as 32 bytes hex encoded public keys.

If validation fails, appropriate error messages will be returned.

Error Handling​

The API returns the following error types:

  • NotFoundError: When the requested account or node does not exist
  • DatabaseError: When there's an issue with the database query

Technical Implementation​

The API is implemented using TypeGraphQL and TypeORM. The service follows a layered architecture:

  1. GraphQL Resolver (NodeStatisticsResolver): Handles incoming GraphQL queries and parameter validation
  2. Service Layer (NodeStatisticsService): Contains business logic and database interactions

Data Models​

The API works with the following entity models:

  • Account: Represents user accounts in the system
  • Node (NetworkNode): Represents nodes in the network owned by accounts
  • Reward: Represents rewards earned by nodes and their owners

Examples​

Getting an Account Summary​

You can combine multiple queries to build a comprehensive account summary:

query AccountSummary($accountId: String!) {
  lifetime: getAccountLifetimeRewards(accountId: $accountId)
  last24Hours: getAccountRewardsLast24Hours(accountId: $accountId)
  nodeCount: getAccountNodesCount(accountId: $accountId)
}

Analyzing Monthly Performance​

To analyze monthly performance:

query MonthlyPerformance($accountId: String!, $startMonth: String!, $endMonth: String!) {
  totalRewards: getAccountRewardsInTimeRange(
    accountId: $accountId,
    startTime: $startMonth,
    endTime: $endMonth
  )
  rewardCount: getRewardCountInTimeRange(
    accountId: $accountId,
    startTime: $startMonth,
    endTime: $endMonth
  )
  averageReward: getAverageRewardInTimeRange(
    accountId: $accountId,
    startTime: $startMonth,
    endTime: $endMonth
  )
}
Last updated on by Nahu