api

package
v0.10.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 26, 2024 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// StatusModuleNotLoaded is a custom http code to indicate that a module
	// wasn't yet loaded by the Daemon and can therefore not be reached.
	StatusModuleNotLoaded = 490
)

Variables

View Source
var ErrAPICallNotRecognized = errors.New("API call not recognized")

ErrAPICallNotRecognized is returned by API client calls made to modules that are not yet loaded.

Functions

func HttpGET

func HttpGET(url string) (resp *http.Response, err error)

HttpGET is a utility function for making http get requests with a whitelisted user-agent. A non-2xx response does not return an error.

func HttpGETAuthenticated

func HttpGETAuthenticated(url string, password string) (resp *http.Response, err error)

HttpGETAuthenticated is a utility function for making authenticated http get requests with a whitelisted user-agent and the supplied password. A non-2xx response does not return an error.

func HttpPOST

func HttpPOST(url string, data string) (resp *http.Response, err error)

HttpPOST is a utility function for making post requests with a whitelisted user-agent. A non-2xx response does not return an error.

func HttpPOSTAuthenticated

func HttpPOSTAuthenticated(url string, data string, password string) (resp *http.Response, err error)

HttpPOSTAuthenticated is a utility function for making authenticated http post requests with a whitelisted user-agent and the supplied password. A non-2xx response does not return an error.

func RegisterRoutesConsensus

func RegisterRoutesConsensus(router *httprouter.Router, cs modules.ConsensusSet)

RegisterRoutesConsensus is a helper function to register all consensus routes.

func RegisterRoutesGateway

func RegisterRoutesGateway(router *httprouter.Router, g modules.Gateway, requiredPassword string)

RegisterRoutesGateway is a helper function to register all gateway routes.

func RegisterRoutesTransactionPool

func RegisterRoutesTransactionPool(router *httprouter.Router, tpool modules.TransactionPool)

RegisterRoutesTransactionPool is a helper function to register all transaction pool routes.

func RegisterRoutesWallet

func RegisterRoutesWallet(router *httprouter.Router, wallet modules.Wallet, requiredPassword string)

RegisterRoutesWallet is a helper function to register all wallet routes.

func RequirePassword

func RequirePassword(h httprouter.Handle, password string) httprouter.Handle

RequirePassword is middleware that requires a request to authenticate with a password using HTTP basic auth. Usernames are ignored. Empty passwords indicate no authentication is required.

func RequireUserAgent

func RequireUserAgent(h http.Handler, ua string) http.Handler

RequireUserAgent is middleware that requires all requests to set a UserAgent that contains the specified string.

func WriteError

func WriteError(w http.ResponseWriter, err Error, code int)

WriteError writes an error to the API caller.

func WriteJSON

func WriteJSON(w http.ResponseWriter, obj interface{})

WriteJSON writes the object to the ResponseWriter. If the encoding fails, an error is written instead. The Content-Type of the response header is set accordingly.

func WriteSuccess

func WriteSuccess(w http.ResponseWriter)

WriteSuccess writes the HTTP header with status 204 No Content to the ResponseWriter. WriteSuccess should only be used to indicate that the requested action succeeded AND there is no data to return.

Types

type API

type API struct {
	Shutdown func() error
	// contains filtered or unexported fields
}

API encapsulates a collection of modules and implements a http.Handler to access their methods.

func New

func New(requiredUserAgent string, requiredPassword string, g modules.Gateway, cs modules.ConsensusSet, m modules.Manager, portal modules.Portal, p modules.Provider, tp modules.TransactionPool, w modules.Wallet) *API

New creates a new API. The API will require authentication using HTTP basic auth for certain endpoints if the supplied password is not the empty string. Usernames are ignored for authentication.

func (*API) ServeHTTP

func (api *API) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

func (*API) SetModules

SetModules allows for replacing the modules in the API at runtime.

func (*API) UnrecognizedCallHandler

func (api *API) UnrecognizedCallHandler(w http.ResponseWriter, _ *http.Request)

UnrecognizedCallHandler handles calls to not-loaded modules.

type Announcement added in v0.7.0

type Announcement struct {
	Text    string `json:"text"`
	Expires uint64 `json:"expires"`
}

Announcement contains the information about a portal announcement.

type ConsensusBlocksGet

type ConsensusBlocksGet struct {
	ID           types.BlockID           `json:"id"`
	Height       uint64                  `json:"height"`
	ParentID     types.BlockID           `json:"parentid"`
	Nonce        uint64                  `json:"nonce"`
	Difficulty   types.Currency          `json:"difficulty"`
	Timestamp    time.Time               `json:"timestamp"`
	MinerPayouts []types.SiacoinOutput   `json:"minerpayouts"`
	Transactions []ConsensusBlocksGetTxn `json:"transactions"`
}

ConsensusBlocksGet contains all fields of a types.Block and additional fields for ID and Height.

type ConsensusBlocksGetFileContract

type ConsensusBlocksGetFileContract struct {
	ID                 types.FileContractID              `json:"id"`
	Filesize           uint64                            `json:"filesize"`
	FileMerkleRoot     types.Hash256                     `json:"filemerkleroot"`
	WindowStart        uint64                            `json:"windowstart"`
	WindowEnd          uint64                            `json:"windowend"`
	Payout             types.Currency                    `json:"payout"`
	ValidProofOutputs  []ConsensusBlocksGetSiacoinOutput `json:"validproofoutputs"`
	MissedProofOutputs []ConsensusBlocksGetSiacoinOutput `json:"missedproofoutputs"`
	UnlockHash         types.Hash256                     `json:"unlockhash"`
	RevisionNumber     uint64                            `json:"revisionnumber"`
}

ConsensusBlocksGetFileContract contains all fields of a types.FileContract and an additional ID field.

type ConsensusBlocksGetSiacoinOutput

type ConsensusBlocksGetSiacoinOutput struct {
	ID      types.SiacoinOutputID `json:"id"`
	Value   types.Currency        `json:"value"`
	Address types.Address         `json:"unlockhash"`
}

ConsensusBlocksGetSiacoinOutput contains all fields of a types.SiacoinOutput and an additional ID field.

type ConsensusBlocksGetSiafundOutput

type ConsensusBlocksGetSiafundOutput struct {
	ID      types.SiafundOutputID `json:"id"`
	Value   uint64                `json:"value"`
	Address types.Address         `json:"unlockhash"`
}

ConsensusBlocksGetSiafundOutput contains all fields of a types.SiafundOutput and an additional ID field.

type ConsensusBlocksGetTxn

type ConsensusBlocksGetTxn struct {
	ID                    types.TransactionID               `json:"id"`
	SiacoinInputs         []types.SiacoinInput              `json:"siacoininputs"`
	SiacoinOutputs        []ConsensusBlocksGetSiacoinOutput `json:"siacoinoutputs"`
	FileContracts         []ConsensusBlocksGetFileContract  `json:"filecontracts"`
	FileContractRevisions []types.FileContractRevision      `json:"filecontractrevisions"`
	StorageProofs         []types.StorageProof              `json:"storageproofs"`
	SiafundInputs         []types.SiafundInput              `json:"siafundinputs"`
	SiafundOutputs        []ConsensusBlocksGetSiafundOutput `json:"siafundoutputs"`
	MinerFees             []types.Currency                  `json:"minerfees"`
	ArbitraryData         [][]byte                          `json:"arbitrarydata"`
	TransactionSignatures []types.TransactionSignature      `json:"transactionsignatures"`
}

ConsensusBlocksGetTxn contains all fields of a types.Transaction and an additional ID field.

type ConsensusGET

type ConsensusGET struct {
	Synced       bool           `json:"synced"`
	Height       uint64         `json:"height"`
	CurrentBlock types.BlockID  `json:"currentblock"`
	Target       modules.Target `json:"target"`
	Difficulty   types.Currency `json:"difficulty"`
}

ConsensusGET contains general information about the consensus set, with tags to support idiomatic json encodings.

type ConsensusHeadersGET

type ConsensusHeadersGET struct {
	BlockID types.BlockID `json:"blockid"`
}

ConsensusHeadersGET contains information from a blocks header.

type DaemonAlertsGet

type DaemonAlertsGet struct {
	Alerts         []modules.Alert `json:"alerts"`
	CriticalAlerts []modules.Alert `json:"criticalalerts"`
	ErrorAlerts    []modules.Alert `json:"erroralerts"`
	WarningAlerts  []modules.Alert `json:"warningalerts"`
	InfoAlerts     []modules.Alert `json:"infoalerts"`
}

DaemonAlertsGet contains information about currently registered alerts across all loaded modules.

type DaemonVersion

type DaemonVersion struct {
	Version     string `json:"version"`
	GitRevision string `json:"gitrevision"`
	BuildTime   string `json:"buildtime"`
}

DaemonVersion holds the version information for satd.

type DaemonVersionGet

type DaemonVersionGet struct {
	Version     string
	GitRevision string
	BuildTime   string
}

DaemonVersionGet contains information about the running daemon's version.

type EmailPreferences

type EmailPreferences struct {
	Email         string         `json:"email"`
	WarnThreshold types.Currency `json:"threshold"`
}

EmailPreferences contains the email preferences.

type Error

type Error struct {
	// Message describes the error in English. Typically it is set to
	// `err.Error()`. This field is required.
	Message string `json:"message"`
}

Error is a type that is encoded as JSON and returned in an API response in the event of an error. Only the Message field is required. More fields may be added to this struct in the future for better error reporting.

func (Error) Error

func (err Error) Error() string

Error implements the error interface for the Error type. It returns only the Message field.

type ExchangeRate

type ExchangeRate struct {
	Currency string  `json:"currency"`
	Rate     float64 `json:"rate"`
}

ExchangeRate contains the exchange rate of a given currency.

type ExtendedHostDBEntry

type ExtendedHostDBEntry struct {
	modules.HostDBEntry
	PublicKeyString string `json:"publickeystring"`
}

ExtendedHostDBEntry is an extension to modules.HostDBEntry that includes the string representation of the public key.

type GatewayBlocklistGET

type GatewayBlocklistGET struct {
	Blocklist []string `json:"blocklist"`
}

GatewayBlocklistGET contains the Blocklist of the gateway.

type GatewayBlocklistPOST

type GatewayBlocklistPOST struct {
	Action    string   `json:"action"`
	Addresses []string `json:"addresses"`
}

GatewayBlocklistPOST contains the information needed to set the Blocklist. of the gateway

type GatewayGET

type GatewayGET struct {
	NetAddress modules.NetAddress `json:"netaddress"`
	Peers      []modules.Peer     `json:"peers"`
	Online     bool               `json:"online"`
}

GatewayGET contains the fields returned by a GET call to "/gateway".

type HostAverages

type HostAverages struct {
	modules.HostAverages
	Rate float64
}

HostAverages contains the host network averages.

type HostdbActiveGET

type HostdbActiveGET struct {
	Hosts []ExtendedHostDBEntry `json:"hosts"`
}

HostdbActiveGET lists active hosts on the network.

type HostdbAllGET

type HostdbAllGET struct {
	Hosts []ExtendedHostDBEntry `json:"hosts"`
}

HostdbAllGET lists all hosts that the manager is aware of.

type HostdbFilterModeGET

type HostdbFilterModeGET struct {
	FilterMode   string   `json:"filtermode"`
	Hosts        []string `json:"hosts"`
	NetAddresses []string `json:"netaddresses"`
}

HostdbFilterModeGET contains the information about the HostDB's filtermode.

type HostdbFilterModePOST

type HostdbFilterModePOST struct {
	FilterMode   string            `json:"filtermode"`
	Hosts        []types.PublicKey `json:"hosts"`
	NetAddresses []string          `json:"netaddresses"`
}

HostdbFilterModePOST contains the information needed to set the the FilterMode of the hostDB.

type HostdbGet

type HostdbGet struct {
	BlockHeight         uint64 `json:"blockheight"`
	InitialScanComplete bool   `json:"initialscancomplete"`
}

HostdbGet holds information about the hostdb.

type HostdbHostsGET

type HostdbHostsGET struct {
	Entry          ExtendedHostDBEntry        `json:"entry"`
	ScoreBreakdown modules.HostScoreBreakdown `json:"scorebreakdown"`
}

HostdbHostsGET lists detailed statistics for a particular host, selected by pubkey.

type Renter

type Renter struct {
	Email     string          `json:"email"`
	PublicKey types.PublicKey `json:"publickey"`
}

Renter contains information about the renter.

type RenterContract

type RenterContract struct {
	// Amount of contract funds that have been spent on downloads.
	DownloadSpending types.Currency `json:"downloadspending"`
	// Block height that the file contract ends on.
	EndHeight uint64 `json:"endheight"`
	// Fees paid in order to form the file contract.
	Fees types.Currency `json:"fees"`
	// Amount of contract funds that have been spent on funding an ephemeral
	// account on the host.
	FundAccountSpending types.Currency `json:"fundaccountspending"`
	// Public key of the renter that formed the contract.
	RenterPublicKey types.PublicKey `json:"renterpublickey"`
	// Public key of the host the contract was formed with.
	HostPublicKey types.PublicKey `json:"hostpublickey"`
	// HostVersion is the version of Sia that the host is running.
	HostVersion string `json:"hostversion"`
	// ID of the file contract.
	ID types.FileContractID `json:"id"`
	// A signed transaction containing the most recent contract revision.
	LastTransaction types.Transaction `json:"lasttransaction"`
	// Amount of contract funds that have been spent on maintenance tasks
	// such as updating the price table or syncing the ephemeral account
	// balance.
	MaintenanceSpending modules.MaintenanceSpending `json:"maintenancespending"`
	// Address of the host the file contract was formed with.
	NetAddress string `json:"netaddress"`
	// Remaining funds left to spend on uploads & downloads.
	RenterFunds types.Currency `json:"renterfunds"`
	// Size of the file contract, which is typically equal to the number of
	// bytes that have been uploaded to the host.
	Size uint64 `json:"size"`
	// Block height that the file contract began on.
	StartHeight uint64 `json:"startheight"`
	// Amount of contract funds that have been spent on storage.
	StorageSpending types.Currency `json:"storagespending"`
	// Total cost to the wallet of forming the file contract.
	TotalCost types.Currency `json:"totalcost"`
	// Amount of contract funds that have been spent on uploads.
	UploadSpending types.Currency `json:"uploadspending"`
	// Signals if contract is good for uploading data.
	GoodForUpload bool `json:"goodforupload"`
	// Signals if contract is good for a renewal.
	GoodForRenew bool `json:"goodforrenew"`
	// Signals if a contract has been marked as bad.
	BadContract bool `json:"badcontract"`
}

RenterContract represents a contract formed by the renter.

type RenterContracts

type RenterContracts struct {
	ActiveContracts           []RenterContract `json:"activecontracts"`
	PassiveContracts          []RenterContract `json:"passivecontracts"`
	RefreshedContracts        []RenterContract `json:"refreshedcontracts"`
	DisabledContracts         []RenterContract `json:"disabledcontracts"`
	ExpiredContracts          []RenterContract `json:"expiredcontracts"`
	ExpiredRefreshedContracts []RenterContract `json:"expiredrefreshedcontracts"`
}

RenterContracts contains the renter's contracts.

type RentersGET

type RentersGET struct {
	Renters []Renter `json:"renters"`
}

RentersGET contains the list of the renters.

type TpoolConfirmedGET

type TpoolConfirmedGET struct {
	Confirmed bool `json:"confirmed"`
}

TpoolConfirmedGET contains information about whether or not the transaction has been seen on the blockhain.

type TpoolFeeGET

type TpoolFeeGET struct {
	Minimum types.Currency `json:"minimum"`
	Maximum types.Currency `json:"maximum"`
}

TpoolFeeGET contains the current estimated fee.

type TpoolRawGET

type TpoolRawGET struct {
	ID          types.TransactionID `json:"id"`
	Parents     []byte              `json:"parents"`
	Transaction []byte              `json:"transaction"`
}

TpoolRawGET contains the requested transaction encoded to the raw format, along with the id of that transaction.

type TpoolTxnsGET

type TpoolTxnsGET struct {
	Transactions []types.Transaction `json:"transactions"`
}

TpoolTxnsGET contains the information about the tpool's transactions.

type WalletAddressGET

type WalletAddressGET struct {
	Address types.Address `json:"address"`
}

WalletAddressGET contains an address returned by a GET call to /wallet/address.

type WalletAddressesGET

type WalletAddressesGET struct {
	Addresses []types.Address `json:"addresses"`
}

WalletAddressesGET contains the list of wallet addresses returned by a GET call to /wallet/addresses.

type WalletGET

type WalletGET struct {
	Encrypted  bool   `json:"encrypted"`
	Height     uint64 `json:"height"`
	Rescanning bool   `json:"rescanning"`
	Unlocked   bool   `json:"unlocked"`

	ConfirmedSiacoinBalance     types.Currency `json:"confirmedsiacoinbalance"`
	UnconfirmedOutgoingSiacoins types.Currency `json:"unconfirmedoutgoingsiacoins"`
	UnconfirmedIncomingSiacoins types.Currency `json:"unconfirmedincomingsiacoins"`

	DustThreshold types.Currency `json:"dustthreshold"`
}

WalletGET contains general information about the wallet.

type WalletInitPOST

type WalletInitPOST struct {
	PrimarySeed string `json:"primaryseed"`
}

WalletInitPOST contains the primary seed that gets generated during a POST call to /wallet/init.

type WalletSeedsGET

type WalletSeedsGET struct {
	PrimarySeed        string   `json:"primaryseed"`
	AddressesRemaining int      `json:"addressesremaining"`
	AllSeeds           []string `json:"allseeds"`
}

WalletSeedsGET contains the seeds used by the wallet.

type WalletSiacoinsPOST

type WalletSiacoinsPOST struct {
	Transactions   []types.Transaction   `json:"transactions"`
	TransactionIDs []types.TransactionID `json:"transactionids"`
}

WalletSiacoinsPOST contains the transaction sent in the POST call to /wallet/siacoins.

type WalletSignPOSTParams

type WalletSignPOSTParams struct {
	Transaction types.Transaction `json:"transaction"`
	ToSign      []types.Hash256   `json:"tosign"`
}

WalletSignPOSTParams contains the unsigned transaction and a set of inputs to sign.

type WalletSignPOSTResp

type WalletSignPOSTResp struct {
	Transaction types.Transaction `json:"transaction"`
}

WalletSignPOSTResp contains the signed transaction.

type WalletSweepPOST

type WalletSweepPOST struct {
	Coins types.Currency `json:"coins"`
}

WalletSweepPOST contains the coins returned by a call to /wallet/sweep.

type WalletTransactionGETid

type WalletTransactionGETid struct {
	Transaction modules.ProcessedTransaction `json:"transaction"`
}

WalletTransactionGETid contains the transaction returned by a call to /wallet/transaction/:id

type WalletTransactionsGET

type WalletTransactionsGET struct {
	ConfirmedTransactions   []modules.ProcessedTransaction `json:"confirmedtransactions"`
	UnconfirmedTransactions []modules.ProcessedTransaction `json:"unconfirmedtransactions"`
}

WalletTransactionsGET contains the specified set of confirmed and unconfirmed transactions.

type WalletTransactionsGETaddr

type WalletTransactionsGETaddr struct {
	ConfirmedTransactions   []modules.ProcessedTransaction `json:"confirmedtransactions"`
	UnconfirmedTransactions []modules.ProcessedTransaction `json:"unconfirmedtransactions"`
}

WalletTransactionsGETaddr contains the set of wallet transactions relevant to the input address provided in the call to /wallet/transaction/:addr.

type WalletUnlockConditionsGET

type WalletUnlockConditionsGET struct {
	UnlockConditions types.UnlockConditions `json:"unlockconditions"`
}

WalletUnlockConditionsGET contains a set of unlock conditions.

type WalletUnlockConditionsPOSTParams

type WalletUnlockConditionsPOSTParams struct {
	UnlockConditions types.UnlockConditions `json:"unlockconditions"`
}

WalletUnlockConditionsPOSTParams contains a set of unlock conditions.

type WalletUnspentGET

type WalletUnspentGET struct {
	Outputs []modules.UnspentOutput `json:"outputs"`
}

WalletUnspentGET contains the unspent outputs tracked by the wallet. The MaturityHeight field of each output indicates the height of the block that the output appeared in.

type WalletVerifyAddressGET

type WalletVerifyAddressGET struct {
	Valid bool `json:"valid"`
}

WalletVerifyAddressGET contains a bool indicating if the address passed to /wallet/verify/address/:addr is a valid address.

type WalletVerifyPasswordGET

type WalletVerifyPasswordGET struct {
	Valid bool `json:"valid"`
}

WalletVerifyPasswordGET contains a bool indicating if the password passed to /wallet/verifypassword is the password being used to encrypt the wallet.

type WalletWatchGET

type WalletWatchGET struct {
	Addresses []types.Address `json:"addresses"`
}

WalletWatchGET contains the set of addresses that the wallet is currently watching.

type WalletWatchPOST

type WalletWatchPOST struct {
	Addresses []types.Address `json:"addresses"`
	Remove    bool            `json:"remove"`
	Unused    bool            `json:"unused"`
}

WalletWatchPOST contains the set of addresses to add or remove from the watch set.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL