walrus

README

walrus

walrus is a Sia wallet server. It presents a low-level, performant API that is suitable for private, professional, and commercial use. The server itself does not store seeds or private keys, and therefore cannot sign transactions; these responsibilities are handled by the client. Accordingly, walrus works well with Sia-compatible hardware wallets such as the Ledger Nano S.

API docs for the server are available here.

A client for walrus is available here. The client facilitates constructing, signing, and broadcasting transactions, and supports both hot wallets and hardware wallets.

Running a walrus server

If you plan to expose your walrus API to the public internet, it is highly recommended that you add HTTPS and HTTP Basic Authentication via a reverse proxy. Without these security measures, an attacker would still be unable to access your private keys, but they could potentially trick you into losing funds. Better safe than sorry.

In addition, if you want to access your wallet via a browser (such as Sia Central's Lite Wallet), you will need to enable CORS. Refer to the following documentation based on your reverse proxy:

• Nginx:
  • HTTPS
  • Basic Auth
  • CORS
• Apache:
  • HTTPS
  • Basic Auth
  • CORS
• Caddy:
  • HTTPS
  • Basic Auth
  • CORS

Documentation

Overview

Package walrus defines a walrus server and client.

Index

• func NewServer(w *wallet.SeedWallet, tp TransactionPool) http.Handler
• type Client
  • func NewClient(addr string) *Client
  • func (c *Client) AddAddress(info wallet.SeedAddressInfo) error
  • func (c *Client) AddToLimbo(txn types.Transaction) (err error)
  • func (c *Client) AddressInfo(addr types.UnlockHash) (info wallet.SeedAddressInfo, err error)
  • func (c *Client) Addresses() (addrs []types.UnlockHash, err error)
  • func (c *Client) Balance(limbo bool) (bal types.Currency, err error)
  • func (c *Client) BatchAddresses(addrs []types.UnlockHash) (infos map[types.UnlockHash]wallet.SeedAddressInfo, err error)
  • func (c *Client) BatchTransactions(ids []types.TransactionID) (txns map[types.TransactionID]ResponseTransactionsID, err error)
  • func (c *Client) BlockRewards(max int) (rewards []wallet.BlockReward, err error)
  • func (c *Client) Broadcast(txnSet []types.Transaction) error
  • func (c *Client) ConsensusInfo() (info ResponseConsensus, err error)
  • func (c *Client) FileContractHistory(id types.FileContractID) (history []wallet.FileContract, err error)
  • func (c *Client) FileContracts(max int) (contracts []wallet.FileContract, err error)
  • func (c *Client) LimboTransactions() (txns []wallet.LimboTransaction, err error)
  • func (c *Client) Memo(txid types.TransactionID) (memo []byte, err error)
  • func (c *Client) ProtoTransactionPool() proto.TransactionPool
  • func (c *Client) ProtoWallet(seed wallet.Seed) proto.Wallet
  • func (c *Client) RecommendedFee() (fee types.Currency, err error)
  • func (c *Client) RemoveAddress(addr types.UnlockHash) error
  • func (c *Client) RemoveFromLimbo(txid types.TransactionID) (err error)
  • func (c *Client) SeedIndex() (index uint64, err error)
  • func (c *Client) SetMemo(txid types.TransactionID, memo []byte) (err error)
  • func (c *Client) Transaction(txid types.TransactionID) (txn ResponseTransactionsID, err error)
  • func (c *Client) Transactions(max int) (txids []types.TransactionID, err error)
  • func (c *Client) TransactionsByAddress(addr types.UnlockHash, max int) (txids []types.TransactionID, err error)
  • func (c *Client) UnconfirmedParents(txn types.Transaction) (parents []wallet.LimboTransaction, err error)
  • func (c *Client) UnspentOutputs(limbo bool) (utxos []wallet.UnspentOutput, err error)
• type JSONTransaction
  • func (txn JSONTransaction) MarshalJSON() ([]byte, error)
• type ResponseConsensus
• type ResponseTransactionsID
  • func (r ResponseTransactionsID) MarshalJSON() ([]byte, error)
• type TransactionPool

Functions

func NewServer

func NewServer(w *wallet.SeedWallet, tp TransactionPool) http.Handler

NewServer returns an HTTP handler that serves the walrus API.

Types

type Client

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

A Client communicates with a walrus server.

func NewClient

func NewClient(addr string) *Client

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

func (*Client) AddAddress

func (c *Client) AddAddress(info wallet.SeedAddressInfo) error

AddAddress adds a set of address metadata to the wallet. Future transactions and outputs relevant to this address will be considered relevant to the wallet.

Importing an address does NOT import transactions and outputs relevant to that address that are already in the blockchain.

func (*Client) AddToLimbo

func (c *Client) AddToLimbo(txn types.Transaction) (err error)

AddToLimbo places a transaction in Limbo. The output will no longer be returned by Outputs or contribute to the wallet's balance.

Manually adding transactions to Limbo is typically unnecessary. Calling Broadcast will move all transactions in the set to Limbo automatically.

func (*Client) AddressInfo

func (c *Client) AddressInfo(addr types.UnlockHash) (info wallet.SeedAddressInfo, err error)

AddressInfo returns information about a specific address, including its unlock conditions and the index it was derived from.

func (*Client) Addresses

func (c *Client) Addresses() (addrs []types.UnlockHash, err error)

Addresses returns all addresses known to the wallet.

func (*Client) Balance

func (c *Client) Balance(limbo bool) (bal types.Currency, err error)

Balance returns the current wallet balance. If the limbo flag is true, the balance will reflect any transactions currently in Limbo.

func (*Client) BatchAddresses

func (c *Client) BatchAddresses(addrs []types.UnlockHash) (infos map[types.UnlockHash]wallet.SeedAddressInfo, err error)

BatchAddresses returns information about a set of addresses, including their unlock conditions and the index they were derived from. If an address is not found, no error is returned; the address is simply omitted from the response.

func (*Client) BatchTransactions

func (c *Client) BatchTransactions(ids []types.TransactionID) (txns map[types.TransactionID]ResponseTransactionsID, err error)

BatchTransactions returns information about a set of transactions. If a transaction is not found, no error is returned; the transaction is simply omitted from the response.

func (*Client) BlockRewards

func (c *Client) BlockRewards(max int) (rewards []wallet.BlockReward, err error)

BlockRewards returns the block rewards tracked by the wallet. If max < 0, all rewards are returned; otherwise, at most max rewards are returned. The rewards are ordered newest-to-oldest.

func (*Client) Broadcast

func (c *Client) Broadcast(txnSet []types.Transaction) error

Broadcast broadcasts the supplied transaction set to all connected peers.

func (*Client) ConsensusInfo

func (c *Client) ConsensusInfo() (info ResponseConsensus, err error)

ConsensusInfo returns the current blockchain height and consensus change ID. The latter is a unique ID that changes whenever blocks are added to the blockchain.

func (*Client) FileContractHistory

func (c *Client) FileContractHistory(id types.FileContractID) (history []wallet.FileContract, err error)

FileContractHistory returns the revision history of the specified file contract, which must be a contract tracked by the wallet.

func (*Client) FileContracts

func (c *Client) FileContracts(max int) (contracts []wallet.FileContract, err error)

FileContracts returns the file contracts tracked by the wallet. If max < 0, all contracts are returned; otherwise, at most max contracts are returned. The contracts are ordered newest-to-oldest.

func (*Client) LimboTransactions

func (c *Client) LimboTransactions() (txns []wallet.LimboTransaction, err error)

LimboTransactions returns transactions that are in Limbo.

func (*Client) Memo

func (c *Client) Memo(txid types.TransactionID) (memo []byte, err error)

Memo retrieves the memo for a transaction.

func (*Client) ProtoTransactionPool

func (c *Client) ProtoTransactionPool() proto.TransactionPool

ProtoTransactionPool returns a wrapped Client that implements the proto.TransactionPool interface.

func (*Client) ProtoWallet

func (c *Client) ProtoWallet(seed wallet.Seed) proto.Wallet

ProtoWallet returns a wrapped Client that implements the proto.Wallet interface using an in-memory seed.

func (*Client) RecommendedFee

func (c *Client) RecommendedFee() (fee types.Currency, err error)

RecommendedFee returns the current recommended transaction fee in hastings per byte of the Sia-encoded transaction.

func (*Client) RemoveAddress

func (c *Client) RemoveAddress(addr types.UnlockHash) error

RemoveAddress removes an address from the wallet. Future transactions and outputs relevant to this address will not be considered relevant to the wallet.

Removing an address does NOT remove transactions and outputs relevant to that address that are already recorded in the wallet.

func (*Client) RemoveFromLimbo

func (c *Client) RemoveFromLimbo(txid types.TransactionID) (err error)

RemoveFromLimbo removes a transaction from Limbo.

Manually removing transactions from Limbo is typically unnecessary. When a transaction appears in a valid block, it will be removed from Limbo automatically.

func (*Client) SeedIndex

func (c *Client) SeedIndex() (index uint64, err error)

SeedIndex returns the index that should be used to derive the next address.

func (*Client) SetMemo

func (c *Client) SetMemo(txid types.TransactionID, memo []byte) (err error)

SetMemo adds a memo for a transaction, overwriting the previous memo if it exists.

Memos are not stored on the blockchain. They exist only in the local wallet.

func (*Client) Transaction

func (c *Client) Transaction(txid types.TransactionID) (txn ResponseTransactionsID, err error)

Transaction returns the transaction with the specified ID, as well as credit, debit, and fee information. The transaction must be relevant to the wallet.

func (*Client) Transactions

func (c *Client) Transactions(max int) (txids []types.TransactionID, err error)

Transactions lists the IDs of transactions relevant to the wallet. If max < 0, all such IDs are returned; otherwise, at most max IDs are returned. The IDs are ordered newest-to-oldest.

func (*Client) TransactionsByAddress

func (c *Client) TransactionsByAddress(addr types.UnlockHash, max int) (txids []types.TransactionID, err error)

TransactionsByAddress lists the IDs of transactions relevant to the specified address, which must be owned by the wallet. If max < 0, all such IDs are returned; otherwise, at most max IDs are returned. The IDs are ordered newest-to-oldest.

func (*Client) UnconfirmedParents

func (c *Client) UnconfirmedParents(txn types.Transaction) (parents []wallet.LimboTransaction, err error)

UnconfirmedParents returns any parents of txn that are in Limbo. These transactions will need to be included in the transaction set passed to Broadcast.

func (*Client) UnspentOutputs

func (c *Client) UnspentOutputs(limbo bool) (utxos []wallet.UnspentOutput, err error)

UnspentOutputs returns the outputs that the wallet can spend. If the limbo flag is true, the outputs will reflect any transactions currently in Limbo.

type JSONTransaction

type JSONTransaction types.Transaction

JSONTransaction overrides the default JSON encoding of types.Transaction to use camelCase and stringified pubkeys and omit empty fields.

func (JSONTransaction) MarshalJSON

func (txn JSONTransaction) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type ResponseConsensus

type ResponseConsensus struct {
	Height types.BlockHeight `json:"height"`
	CCID   crypto.Hash       `json:"ccid"`
}

ResponseConsensus is the response type for the /consensus endpoint.

type ResponseTransactionsID

type ResponseTransactionsID struct {
	Transaction types.Transaction `json:"transaction"`
	BlockID     types.BlockID     `json:"blockID"`
	BlockHeight types.BlockHeight `json:"blockHeight"`
	Timestamp   time.Time         `json:"timestamp"`
	FeePerByte  types.Currency    `json:"feePerByte"`
	Credit      types.Currency    `json:"credit"`
	Debit       types.Currency    `json:"debit"`
}

ResponseTransactionsID is the response type for the /transactions/:id endpoint.

func (ResponseTransactionsID) MarshalJSON

func (r ResponseTransactionsID) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

type TransactionPool

type TransactionPool interface {
	AcceptTransactionSet([]types.Transaction) error
	FeeEstimation() (min types.Currency, max types.Currency)
}

A TransactionPool can broadcast transactions and estimate transaction fees.