Braiins pool API responses in Typescript

braiinsApi.ts

// https://help.braiins.com/en/support/solutions/articles/77000433512-api-configuration-guide

type HashRateUnit = "Gh/s" | "Th/s" | "Ph/s";

const _sampleStatsResponse: GeneralPoolStatsResponse = {
  btc: {
    luck_b10: "0.77",
    luck_b50: "0.85",
    luck_b250: "0.93",
    hash_rate_unit: "Gh/s",
    pool_scoring_hash_rate: 5820970883.3011,
    pool_active_workers: 219210,
    round_probability: "0.67",
    round_started: 1542096907,
    round_duration: 5913,
    blocks: {
      549753: {
        date_found: 1542002919,
        mining_duration: 3423,
        total_shares: 4640771710739,
        state: "confirmed",
        confirmations_left: 0,
        value: "12.92594863",
        user_reward: "0.00006194",
        pool_scoring_hash_rate: 5878745444.967269,
      },
    }
  }
}


/**
 * General Pool Stats
 * https://pool.braiins.com/stats/json/[coin]/ 
 */
export interface GeneralPoolStatsResponse {
  btc: {
    /** pool luck for the last ten blocks */
    luck_b10: string;
    /** pool luck for the last 50 blocks */
    luck_b50: string;
    /** pool luck for the last 250 blocks */
    luck_b250: string;
    /** unit used for the hash rate values, e.g. "Gh/s" */
    hash_rate_unit: HashRateUnit;
    /** pool scoring hash rate */
    pool_scoring_hash_rate: number;
    /** number of pool active workers */
    pool_active_workers: number;
    /** current CDF for the current round */
    round_probability: string;
    /** Unix time when the current round was started */
    round_started: number;
    /** duration of the current round (seconds) */
    round_duration: number;
    /** information for the last 15 blocks (breakdown below) */
    blocks: { [key: string]: BlockInfo };
  }
};

export interface BlockInfo {
  /** Unix time when given block was found */
  date_found: number;
  /** duration of the round leading to given block */
  mining_duration: number;
  /** number of shares collected during the round */
  total_shares: number;
  /** state of given block */
  state: "confirmed" | "unconfirmed"; // TODO are there more states?
  /** number of confirmations left */
  confirmations_left: number;
  /** block value */
  value: string;
  /** user reward for the given block */
  user_reward: string;
  /** pool scoring hash rate at the time when block was found */
  pool_scoring_hash_rate: number;
}


const _sampleUserProfileResponse: UserProfileResponse = {
  username: "username",
  btc: {
    confirmed_reward: "0.00765122",
    unconfirmed_reward: "0.00062272",
    estimated_reward: "0.00006014",
    send_threshold: "0.01000000",
    hash_rate_unit: "Gh/s",
    hash_rate_5m: 27978,
    hash_rate_60m: 28191,
    hash_rate_24h: 28357,
    hash_rate_scoring: 28294,
    hash_rate_yesterday: 28197,
    low_workers: 0,
    off_workers: 0,
    ok_workers: 2,
    dis_workers: 2,

    /** Undocumented - missing from the sample response */
    all_time_reward: "0.00765122",
  }
}

/**
 * User Profile API
 * Provides information about users performance and rewards.
 * https://pool.braiins.com/accounts/profile/json/[coin]/
 */
export interface UserProfileResponse {
  username: string;
  btc: {
    /** confirmed reward */
    confirmed_reward: string;
    /** unconfirmed reward */
    unconfirmed_reward: string;
    /** estimated reward for the current block */
    estimated_reward: string;
    /** cumulative all-time reward */
    all_time_reward: string;
    /** unit used for the hash rate values, e.g. "Gh/s" */
    hash_rate_unit: HashRateUnit;
    /** average hash rate for the last 5 minutes */
    hash_rate_5m: number;
    /** average hash rate for the last 60 minutes */
    hash_rate_60m: number;
    /** average hash rate for the last 24 hours */
    hash_rate_24h: number;
    /** user current scoring hash rate */
    hash_rate_scoring: number;
    /** average hash rate for the previous UTC day */
    hash_rate_yesterday: number;
    /** number of workers with 'low' state */
    low_workers: number;
    /** number of workers with 'off' state */
    off_workers: number;
    /** number of workers with 'ok' state */
    ok_workers: number;
    /** number of workers with disabled monitoring */
    dis_workers: number;

    /** Undocumented - missing from the API docs  */
    send_threshold: string;
  }
}


const _sampleDailyRewardResponse: DailyRewardResponse = {
  "btc": {
    "daily_rewards": [
      {
        "date": 1627862400,
        "total_reward": "0.36361081",
        "mining_reward": "0.35648119",
        "bos_plus_reward": "0.00712962",
        "referral_bonus": "0.00000000",
        "referral_reward": "0.00000000"
      },
    ]
  }
}


/**
 * Daily Reward API
 * Provides information about rewards for the last 90 days.
 * https://pool.braiins.com/accounts/rewards/json/<coin>/
 */
export interface DailyRewardResponse {
  btc: {
    daily_rewards: DailyReward[];
  }
}

interface DailyReward {
  /** Unix time (the first second of the date) */
  date: number;
  /** the sum of all reward types for the day */
  total_reward: string;
  /** the standard mining reward */
  mining_reward: string;
  /** the amount refunded (pool fee refund) for mining with Braiins OS+ */
  bos_plus_reward: string;
  /** bonus received by being referred to Braiins OS+ */
  referral_bonus: string;
  /** reward earned for HR referred to Braiins OS+ */
  referral_reward: string;
}


const _sampleDailyHashrateResponse: DailyHashrateResponse = {
  btc: [
    {
      date: 1662674400,
      hash_rate_unit: "Gh/s",
      hash_rate_24h: 1073.7,
      scoring_hash_rate_24h: 322122.5,
      total_shares: 21600000,
    },
    {
      date: 1662588000,
      hash_rate_unit: "Gh/s",
      hash_rate_24h: 1000.7,
      scoring_hash_rate_24h: 322100.5,
      total_shares: 21200000,
    },
  ]
}

/**
 * Daily Hashrate API
 * Provides information about daily averages of hashrate for user or user group.
 * https://pool.braiins.com/accounts/hash_rate_daily/json/[group]/[coin]
 * 
 * Where group is indicating if average hash rates should be returned for the user group. Variable coin is BTC.
 * Example URL request:
 * https://pool.braiins.com/accounts/hash_rate_daily/json/group/btc
 */
export interface DailyHashrateResponse {
  btc: DailyHashrate[];
}

interface DailyHashrate {
  /** Unix time (the first second of the date) */
  date: number;
  /** unit used for the hash rate values, e.g. "Gh/s" */
  hash_rate_unit: HashRateUnit;
  /** average hash rate for the last 24 hours */
  hash_rate_24h: number;
  /** average scoring hashrate for the last 24 hours */
  scoring_hash_rate_24h: number;
  /** number of shares collected during the day */
  total_shares: number;
}


const _sampleBlockRewardsResponse: BlockRewardsResponse = {
  "btc": {
    "block_rewards": [
      {
        "block_found_at": 1651804117,
        "pool_scoring_hash_rate": 4441768989.204721,
        "user_scoring_hash_rate": 12981.581642348925,
        "block_value": "12.59169582",
        "user_reward": "0.06366676",
        "block_height": 567815,
        "mining_reward": "0.06366676",
        "braiinsos_plus_mining_bonus": "0.00000000",
        "referral_reward": "0.00000000",
        "referral_bonus": "0.00000000",
        "confirmations_left": 0
      },
      {
        "block_found_at": 1651811734,
        "pool_scoring_hash_rate": 4441768989.387698,
        "user_scoring_hash_rate": 13041.508413918604,
        "block_value": "12.66780812",
        "user_reward": "0.07129083",
        "block_height": 567816,
        "mining_reward": "0.07129083",
        "braiinsos_plus_mining_bonus": "0.00000000",
        "referral_reward": "0.00000000",
        "referral_bonus": "0.00000000",
        "confirmations_left": 0
      }
    ],
    "hash_rate_unit": "Gh/s"
  }
}


/**
Block Rewards API
Provides information about block rewards.
https://pool.braiins.com/accounts/block_rewards/json/[coin]?from=[from date]&to=[to date]

Where COIN is BTC, FROM date is string representation of date in ISO format (YYYY-MM-DD), and TO date is string representation of date in ISO format (YYYY-MM-DD).
Example URL request:
https://pool.braiins.com/accounts/block_rewards/json/btc?from=2022-05-01&to=2022-05-07
 */
export interface BlockRewardsResponse {
  btc: {
    block_rewards: BlockReward[];
    /** unit used for the hash rate values, e.g. "Gh/s" */
    hash_rate_unit: HashRateUnit;
  };
}

interface BlockReward {
  /** unix timestamp (UTC), when the block was found */
  block_found_at: number;
  /** total scoring hash rate of the pool at time when the block was found */
  pool_scoring_hash_rate: number;
  /** total scoring hash rate of the user at time when the block was found */
  user_scoring_hash_rate: number;
  /** total value of the block */
  block_value: string;
  /** total reward amount for the user */
  user_reward: string;
  /** number of the block within the coin's blockchain */
  block_height: number;
  /** amount of mining reward for delivered shares on the block */
  mining_reward: string;
  /** pool fee refund for mining with Braiins OS+ device */
  braiinsos_plus_mining_bonus: string;
  /** pool fee refund for mining with Braiins OS+ device and with special referral code */
  referral_reward: string;
  /** pool fee refund for propagation of Braiins OS+ with dedicated referral code */
  referral_bonus: string;
  /** number of confirmations left before the block is considered valid */
  confirmations_left: number;
}


const _sampleWorkerResponse: WorkerResponse = {
  btc: {
    workers: {
      "username.worker1": {
        state: "ok",
        last_share: 1542103204,
        hash_rate_unit: "Gh/s",
        hash_rate_scoring: 15342,
        hash_rate_5m: 14977,
        hash_rate_60m: 15302,
        hash_rate_24h: 15351,
      },
      "username.worker2": {
        state: "ok",
        last_share: 1542103200,
        hash_rate_unit: "Gh/s",
        hash_rate_scoring: 12952,
        hash_rate_5m: 13001,
        hash_rate_60m: 12889,
        hash_rate_24h: 13006,
      },
    }
  }
}

/**
Worker API
Provides performance data for each one of users worker.
https://pool.braiins.com/accounts/workers/json/[coin]/
*/
export interface WorkerResponse {
  btc: {
    workers: {
      [workerName: string]: {
        /** Unix time of the last accepted share */
        last_share: number;
        /** state of the worker (ok/low/off/dis) */
        state: "ok" | "low" | "off" | "dis";
        /** unit used for the hash rate values, e.g. "Gh/s" */
        hash_rate_unit: HashRateUnit;
        /** current scoring hash rate */
        hash_rate_scoring: number;
        /** average hash rate for the last 5 minutes */
        hash_rate_5m: number;
        /** average hash rate for the last 60 minutes */
        hash_rate_60m: number;
        /** average hash rate for the last 24 hours */
        hash_rate_24h: number;
      };
    };
  };
}