README
¶
shard
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. |
Documentation
¶
Index ¶
- func NewServer(r *Relay) http.Handler
- type Client
- type ConsensusSet
- type JSONPersist
- type PersistData
- type Persister
- type Relay
- func (r *Relay) Height() types.BlockHeight
- func (r *Relay) Host(prefix hostdb.HostPublicKey) (pk hostdb.HostPublicKey, unique bool)
- func (r *Relay) HostAnnouncement(pubkey hostdb.HostPublicKey) ([]byte, bool)
- func (r *Relay) ProcessConsensusChange(cc modules.ConsensusChange)
- func (r *Relay) Synced() bool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶ added in v0.3.0
type Client struct {
// contains filtered or unexported fields
}
A Client communicates with a SHARD server.
func NewClient ¶ added in v0.3.0
NewClient returns a Client that communicates with the SHARD server at the specified address.
func (*Client) ChainHeight ¶ added in v0.3.0
func (c *Client) ChainHeight() (types.BlockHeight, error)
ChainHeight returns the current block height.
func (*Client) LookupHost ¶ added in v0.3.0
func (c *Client) LookupHost(prefix string) (hostdb.HostPublicKey, error)
LookupHost returns the host public key matching the specified prefix.
func (*Client) ResolveHostKey ¶ added in v0.3.0
func (c *Client) ResolveHostKey(pubkey hostdb.HostPublicKey) (modules.NetAddress, error)
ResolveHostKey resolves a host public key to that host's most recently announced network address.
type ConsensusSet ¶
type ConsensusSet interface {
ConsensusSetSubscribe(modules.ConsensusSetSubscriber, modules.ConsensusChangeID, <-chan struct{}) error
Synced() bool
}
A ConsensusSet provides updates to the Sia blockchain.
type JSONPersist ¶
type JSONPersist struct {
// contains filtered or unexported fields
}
JSONPersist implements Persister using a JSON file stored on disk.
func NewJSONPersist ¶
func NewJSONPersist(dir string) JSONPersist
NewJSONPersist returns a new JSONPersist that writes to the specified directory.
func (JSONPersist) Load ¶
func (p JSONPersist) Load(data *PersistData) error
Load implements Persister.
func (JSONPersist) Save ¶
func (p JSONPersist) Save(data PersistData) error
Save implements Persister.
type PersistData ¶
type PersistData struct {
Height types.BlockHeight
Hosts map[hostdb.HostPublicKey][]byte
LastChange modules.ConsensusChangeID
}
PersistData contains the data that a Relay loads on startup.
type Persister ¶
type Persister interface {
Save(PersistData) error
Load(*PersistData) error
}
A Persister can save and load PersistData.
type Relay ¶ added in v0.3.0
type Relay struct {
// contains filtered or unexported fields
}
A Relay watches the Sia blockchain for new host announcements and makes them available for queries.
func NewRelay ¶ added in v0.3.0
func NewRelay(cs ConsensusSet, p Persister) (*Relay, error)
NewRelay initializes a Relay using the provided ConsensusSet and Persister.
func (*Relay) Height ¶ added in v0.3.0
func (r *Relay) Height() types.BlockHeight
Height returns the current blockchain height.
func (*Relay) Host ¶ added in v0.3.0
func (r *Relay) Host(prefix hostdb.HostPublicKey) (pk hostdb.HostPublicKey, unique bool)
Host looks up a host using the given prefix of the host's public key. If more than one host shares the prefix, it returns false. If no host is found, it returns an empty string.
func (*Relay) HostAnnouncement ¶ added in v0.3.0
func (r *Relay) HostAnnouncement(pubkey hostdb.HostPublicKey) ([]byte, bool)
HostAnnouncement returns the raw bytes of the announcement recorded in the Sia blockchain for the given host public key, or false if the host is not found.
func (*Relay) ProcessConsensusChange ¶ added in v0.3.0
func (r *Relay) ProcessConsensusChange(cc modules.ConsensusChange)
ProcessConsensusChange implements modules.ConsensusSetSubscriber.
Source Files
Directories