shard

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 host 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

• type ConsensusSet
• type JSONPersist
  • func NewJSONPersist(dir string) JSONPersist
  • func (p JSONPersist) Load(data *PersistData) error
  • func (p JSONPersist) Save(data PersistData) error
• type PersistData
• type Persister
• type SHARD
  • func New(cs ConsensusSet, p Persister) (*SHARD, error)
  • func (s *SHARD) Height() types.BlockHeight
  • func (s *SHARD) Host(prefix string) (pk string, unique bool)
  • func (s *SHARD) HostAnnouncement(pubkey string) ([]byte, bool)
  • func (s *SHARD) ProcessConsensusChange(cc modules.ConsensusChange)
  • func (s *SHARD) Synced() bool

Types

type ConsensusSet

type ConsensusSet interface {
	ConsensusSetSubscribe(modules.ConsensusSetSubscriber, modules.ConsensusChangeID, <-chan struct{}) error
	Synced() bool
}

type JSONPersist

type JSONPersist struct {
	// contains filtered or unexported fields
}

func NewJSONPersist

func NewJSONPersist(dir string) JSONPersist

func (JSONPersist) Load

func (p JSONPersist) Load(data *PersistData) error

func (JSONPersist) Save

func (p JSONPersist) Save(data PersistData) error

type PersistData

type PersistData struct {
	Height     types.BlockHeight
	Hosts      map[string][]byte
	LastChange modules.ConsensusChangeID
}

type Persister

type Persister interface {
	Save(PersistData) error
	Load(*PersistData) error
}

type SHARD

type SHARD struct {
	// contains filtered or unexported fields
}

func New

func New(cs ConsensusSet, p Persister) (*SHARD, error)

func (*SHARD) Height

func (s *SHARD) Height() types.BlockHeight

func (*SHARD) Host

func (s *SHARD) Host(prefix string) (pk string, unique bool)

func (*SHARD) HostAnnouncement

func (s *SHARD) HostAnnouncement(pubkey string) ([]byte, bool)

func (*SHARD) ProcessConsensusChange

func (s *SHARD) ProcessConsensusChange(cc modules.ConsensusChange)

func (*SHARD) Synced

func (s *SHARD) Synced() bool