feat(explored): add the HostByPubkey API

.changeset/itchy-dingos-act.md

@@ -0,0 +1,7 @@
+---
+'@siafoundation/explored-js': minor
+'@siafoundation/explored-react': minor
+'@siafoundation/explored-types': minor
+---
+
+Added the HostByPubkey API.

libs/explored-js/src/api.ts

@@ -52,6 +52,10 @@ import {
   ContractByPubkeyParams,
   ContractByPubkeyPayload,
   ContractByPubkeyResponse,
+  hostByPubkeyRoute,
+  HostByPubkeyParams,
+  HostByPubkeyPayload,
+  HostByPubkeyResponse,
   metricsRoute,
   MetricsParams,
   MetricsPayload,
@@ -265,5 +269,11 @@ export function Explored({
       SearchResultTypePayload,
       SearchResultTypeResponse
     >(axios, 'get', searchResultTypeRoute),
+    // Host
+    hostByPubkey: buildRequestHandler<
+      HostByPubkeyParams,
+      HostByPubkeyPayload,
+      HostByPubkeyResponse
+    >(axios, 'get', hostByPubkeyRoute),
   }
 }

libs/explored-react/src/hooks.ts

@@ -30,6 +30,9 @@ import {
   ContractsByIDsPayload,
   ContractsByIDsResponse,
   contractsByIDsRoute,
+  HostByPubkeyParams,
+  HostByPubkeyResponse,
+  hostByPubkeyRoute,
   MetricsByIDParams,
   MetricsByIDResponse,
   metricsByIDRoute,
@@ -350,3 +353,13 @@ export function useSearchResultType(
     route: searchResultTypeRoute,
   })
 }
+
+// Host
+export function useHostByPubkey(
+  args: HookArgsSwr<HostByPubkeyParams, HostByPubkeyResponse>
+) {
+  return useGetSwr({
+    ...args,
+    route: hostByPubkeyRoute,
+  })
+}

libs/explored-types/src/api.ts

@@ -9,13 +9,15 @@ import {
   Currency,
   ExplorerBlock,
   ExplorerFileContract,
+  ExplorerHost,
   ExplorerSiacoinOutput,
   ExplorerSiafundOutput,
   ExplorerTransaction,
   FileContractID,
   Hash256,
   Metrics,
   Peer,
+  PublicKey,
   SearchResultType,
   SiacoinOutputID,
   SiafundElement,
@@ -221,3 +223,11 @@ export const searchResultTypeRoute = '/search/:id'
 export type SearchResultTypeParams = { id: Hash256 }
 export type SearchResultTypePayload = void
 export type SearchResultTypeResponse = SearchResultType
+
+// Host
+
+// Returns the host with the specified public key
+export const hostByPubkeyRoute = '/pubkey/:id/host'
+export type HostByPubkeyParams = { id: PublicKey }
+export type HostByPubkeyPayload = void
+export type HostByPubkeyResponse = ExplorerHost

libs/explored-types/src/types.ts

@@ -8,6 +8,8 @@ import type {
   Currency,
   FileContractID,
   Hash256,
+  HostSettings,
+  HostPriceTable,
   PublicKey,
   SiacoinElement,
   SiacoinInput,
@@ -36,6 +38,7 @@ export {
   Currency,
   FileContractID,
   Hash256,
+  PublicKey,
   SiacoinOutput,
   SiacoinOutputID,
   SiafundElement,
@@ -105,13 +108,6 @@ export type TxpoolTransactions = {
 }
 
 // Novel Explored Types - There are three main differences that inform what's below:
-//   1. New keys ExplorerSiacoinInput/Output and ExplorerSiafundInput/Output, which cascades
-//      into Transaction and Block.
-//   2. The Resolved and Valid keys with a FileContract.
-//   3. Payout included with FileContractRevision, where the core type removes payout
-//      because a revision cannot change this field. This is still true here but included
-//      for more independent data types--one would not need the original contract to display
-//      a list of revisions, for example.
 
 /**
  * HostAnnouncement represents a signed announcement of a host's network address.
@@ -227,3 +223,23 @@ export type ExplorerBlock = {
   minerPayouts: ExplorerSiacoinOutput[]
   transactions: ExplorerTransaction[]
 }
+
+/**
+ * An ExplorerHost represents a host and the information gathered from scanning it.
+ */
+export type ExplorerHost = {
+  publicKey: PublicKey
+  netAddress: string
+  countryCode: string
+
+  knownSince: string
+  lastScan: string
+  lastScanSuccessful: boolean
+  lastAnnouncement: string
+  totalScans: number
+  successfulInteractions: number
+  failedInteractions: number
+
+  settings: HostSettings
+  priceTable: HostPriceTable
+}