muse

README

muse

muse is a contract server for Sia. It provides contracts to apps like user so that they can store and retrieve files on Sia hosts. This means that you can administrate your contracts (choose hosts, form contracts with them, and renew those contracts periodically) in a single place and use them on any of your devices. Alternatively, you can offload this responsibility to a third party who runs a muse server on your behalf.

To run a muse server, you will need access to a shard server (to lookup host IP addresses) and a walrus server (to fund contract transactions). For convenience, I run public instances of these services. My shard server address is http://shard.lukechampine.com, and you can get a personal walrus server by visiting https://narwal.lukechampine.com.

To communicate with your muse server, you can use the musec CLI client, or interface with the API directly. API documentation can be found here.

Documentation

Overview

Package muse provides a Sia contract server and client.

Index

• func NewServer(dir string, wallet proto.Wallet, tpool proto.TransactionPool, shardAddr string) (http.Handler, error)
• type Client
  • func NewClient(addr string) *Client
  • func (c *Client) AllContracts() (cs []Contract, err error)
  • func (c *Client) Contracts(set string) (cs []Contract, err error)
  • func (c *Client) Delete(id types.FileContractID) (err error)
  • func (c *Client) Form(host hostdb.HostPublicKey, funds types.Currency, start, end types.BlockHeight, ...) (contract Contract, err error)
  • func (c *Client) HostSet(name string) (hosts []hostdb.HostPublicKey, err error)
  • func (c *Client) HostSets() (hs []string, err error)
  • func (c *Client) Renew(id types.FileContractID, funds types.Currency, start, end types.BlockHeight, ...) (contract Contract, err error)
  • func (c *Client) SHARD() *shard.Client
  • func (c *Client) Scan(host hostdb.HostPublicKey) (settings hostdb.HostSettings, err error)
  • func (c *Client) SetHostSet(name string, hosts []hostdb.HostPublicKey) (err error)
  • func (c *Client) WithContext(ctx context.Context) *Client
• type Contract
• type RequestForm
• type RequestRenew
• type RequestScan

Functions

func NewServer

func NewServer(dir string, wallet proto.Wallet, tpool proto.TransactionPool, shardAddr string) (http.Handler, error)

NewServer returns an HTTP handler that serves the muse API.

Types

type Client

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

A Client communicates with a muse server.

func NewClient

func NewClient(addr string) *Client

NewClient returns a client that communicates with a muse server listening on the specified address.

func (*Client) AllContracts

func (c *Client) AllContracts() (cs []Contract, err error)

AllContracts returns all contracts formed by the server.

func (*Client) Contracts

func (c *Client) Contracts(set string) (cs []Contract, err error)

Contracts returns the contracts in the specified set.

func (*Client) Delete

func (c *Client) Delete(id types.FileContractID) (err error)

Delete removes the record of a contract from the server. The contract itself is not revised or otherwise affected in any way. In general, this method should only be used on contracts that have expired and are no longer needed.

func (*Client) Form

func (c *Client) Form(host hostdb.HostPublicKey, funds types.Currency, start, end types.BlockHeight, settings hostdb.HostSettings) (contract Contract, err error)

Form forms a contract with a host. The settings should be obtained from a recent call to Scan. If the settings have changed in the interim, the host may reject the contract.

func (*Client) HostSet

func (c *Client) HostSet(name string) (hosts []hostdb.HostPublicKey, err error)

HostSet returns the contents of the named host set.

func (*Client) HostSets

func (c *Client) HostSets() (hs []string, err error)

HostSets returns the current list of host sets.

func (*Client) Renew

func (c *Client) Renew(id types.FileContractID, funds types.Currency, start, end types.BlockHeight, settings hostdb.HostSettings) (contract Contract, err error)

Renew renews the contract with the specified ID, which must refer to a contract previously formed by the server. The settings should be obtained from a recent call to Scan. If the settings have changed in the interim, the host may reject the contract.

func (*Client) SHARD

func (c *Client) SHARD() *shard.Client

SHARD returns a client for the muse server's shard endpoints.

func (*Client) Scan

func (c *Client) Scan(host hostdb.HostPublicKey) (settings hostdb.HostSettings, err error)

Scan queries the specified host for its current settings.

Note that the host may also be scanned via the hostdb.Scan function.

func (*Client) SetHostSet

func (c *Client) SetHostSet(name string, hosts []hostdb.HostPublicKey) (err error)

SetHostSet sets the contents of a host set, creating it if it does not exist. If an empty slice is passed, the host set is deleted.

func (*Client) WithContext

func (c *Client) WithContext(ctx context.Context) *Client

WithContext returns a new Client whose requests are subject to the supplied context.

type Contract

type Contract struct {
	renter.Contract
	HostAddress modules.NetAddress
	EndHeight   types.BlockHeight
}

A Contract represents a Sia file contract, along with additional metadata.

type RequestForm

type RequestForm struct {
	HostKey     hostdb.HostPublicKey
	Funds       types.Currency
	StartHeight types.BlockHeight
	EndHeight   types.BlockHeight
	Settings    hostdb.HostSettings
}

RequestForm is the request type for the /form endpoint.

type RequestRenew

type RequestRenew struct {
	ID          types.FileContractID
	Funds       types.Currency
	StartHeight types.BlockHeight
	EndHeight   types.BlockHeight
	Settings    hostdb.HostSettings
}

RequestRenew is the request type for the /renew endpoint.

type RequestScan

type RequestScan struct {
	HostKey hostdb.HostPublicKey
}

RequestScan is the request type for the /scan endpoint.