shard is a stripped-down Sia node that records host announcements and
basically nothing else. When run as a public service, it provides these
announcements to clients, sparing them the trouble of running a node themselves.
Host announcements are the mechanism by which Sia hosts associate their public
key with their current IP address or domain name. Subsequent announcements for
the same public key replace earlier ones. A shard server is thus analogous to
a DNS resolver: it resolves public keys to network addresses.
While this is convenient, it also introduces a degree of trust. The amount of
trust is (nearly) minimized, but still present. The host announcements reported
by shard are signed by their public key, so shard cannot forge the
announcements themselves. However, it can report outdated information. For
example, a host might switch from address A to B, and make a new announcement
declaring so; but a malicious shard server can continue providing the old
announcement. shard also provides the current blockheight, and it can lie
about that too. Fortunately, the consequences of these lies are minor, and the
lies can be easily detected by comparing the responses of two or more servers.
The API for a shard server is as follows:
| Endpoint | Type | Description |
|---|---|---|
/synced |
JSON bool | If false, the server's responses may be outdated. |
/height |
JSON number | The current height of the Sia blockchain. |
/host/:pubkey |
Binary | The most recent announcement of the host with the request public key. |
Announcements are encoded in binary using the Sia encoding format. An informal description of the announcement structure is as follows:
| Field | Size (bytes) | Description |
|---|---|---|
| Magic | 16 | The string "HostAnnouncement". |
| Address Len | 8 | The length of the subsequent address. |
| Address | (variable) | The host's network address, as a string. |
| Pubkey Type | 16 | The string "ed25519\0\0\0\0\0\0\0\0\0". |
| Pubkey Len | 8 | The length of the subsequent key; always 32. |
| Pubkey | 32 | The raw bytes of the ed25519 public key. |
| Signature | 64 | The ed25519 signature of the BLAKE-2B hash of the preceding bytes. |