horizon

package
v0.0.0-...-3131eb7 Latest Latest
Warning

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

Go to latest
Published: Feb 13, 2019 License: Apache-2.0 Imports: 8 Imported by: 0

README

Horizon Protocol Changelog

Any changes to the Horizon Public API should be included in this doc.

SDK support

We started tracking SDK support at version 0.12.3. Support for 0.12.3 means that SDK can correctly:

  • Send requests using all available query params / POST params / headers,
  • Parse all fields in responses structs and headers.

For each new version we will only track changes from the previous version.

Changes

0.15.0
SDKs with full support
Changes
  • Assets stats are disabled by default. This can be changed using an environment variable (ENABLE_ASSET_STATS=true) or CLI parameter (--enable-asset-stats=true). Please note that it has a negative impact on a DB and ingestion time.
  • In "Offers for Account", last_modified_time field endpoint can be null when ledger data is not available (has not been ingested yet).
  • "Trades for Offer" endpoint will query for trades that match the given offer on either side of trades, rather than just the "sell" offer. Offer IDs are now synthetic.
  • New /operation_fee_stats endpoint includes fee stats for the last 5 ledgers.
  • "Trades" endpoint can now be streamed.
  • In "Trade Aggregations" endpoint, offset parameter has been added.
  • Account flags now display auth_immutable value.
  • Rate limiting in streams has been changed to be more fair. Now 1 credit has to be paid every time there's a new ledger instead of per request.
Resource Changes Go SDK 1 JS SDK Java SDK
GET /assets Disabled by default. + 0.10.2 0.4.0
GET /accounts/{account_id}/offers last_modified_time field can be null - 0.10.2 0.4.0
GET /offers/{offer_id}/trades Query fields and syntetic IDs - 0.10.2 0.4.0
GET /trades SSE Can be streamed - - 0.4.0
GET /operation_fee_stats New endpoint - - 0.4.0
GET /trade_aggregations New offset parameter - - 0.4.0
GET /accounts/{account_id} Displaying auth_immutable flag - 0.10.2 0.4.0
0.14.0
SDKs with full support
Changes
  • New bump_sequence operation.
  • New sequence_bumped effect.
  • New fields in Account > Balances collection: buying_liabilities and selling_liabilities.
  • Offer resource last_modified field removed, replaced by last_modified_ledger and last_modified_time.
  • Trade aggregations endpoint accepts only specific time ranges now (1/5/15 minutes, 1 hour, 1 day, 1 week).
  • Horizon now sends Cache-Control: no-cache, no-store, max-age=0 HTTP header for all responses.
Resource Changes Go SDK 1 JS SDK Java SDK
GET /accounts/{account_id} Liabilities fields in Balances collection. + 0.10.2 0.3.1
GET /accounts/{account_id}/effects sequence_bumped effect - 0.10.2 0.3.1
GET /accounts/{account_id}/effects SSE sequence_bumped effect - 0.10.2 0.3.1
GET /accounts/{account_id}/offers last_modified field removed - 0.10.2 0.3.1
GET /accounts/{account_id}/operations bump_sequence operation - 0.10.2 0.3.1
GET /accounts/{account_id}/operations SSE bump_sequence operation - 0.10.2 0.3.1
GET /effects sequence_bumped effect - 0.10.2 0.3.1
GET /effects SSE sequence_bumped effect - 0.10.2 0.3.1
GET /ledgers/{ledger_id}/operations bump_sequence operation - 0.10.2 0.3.1
GET /ledgers/{ledger_id}/operations SSE bump_sequence operation - 0.10.2 0.3.1
GET /ledgers/{ledger_id}/effects sequence_bumped effect - 0.10.2 0.3.1
GET /ledgers/{ledger_id}/effects SSE sequence_bumped effect - 0.10.2 0.3.1
GET /operations bump_sequence operation - 0.10.2 0.3.1
GET /operations SSE bump_sequence operation - 0.10.2 0.3.1
GET /operations/{op_id} bump_sequence operation + 0.10.2 0.3.1
GET /trades_aggregations Only specific time ranges allowed + 0.10.2 0.3.1
GET /transactions/{tx_id}/operations bump_sequence operation - 0.10.2 0.3.1
GET /transactions/{tx_id}/operations SSE bump_sequence operation - 0.10.2 0.3.1
GET /transactions/{tx_id}/effects sequence_bumped effect - 0.10.2 0.3.1
GET /transactions/{tx_id}/effects SSE sequence_bumped effect - 0.10.2 0.3.1
0.13.0
SDKs with full support
Changes
  • amount field in /assets is now a String (to support Stellar amounts larger than int64).
  • Effect resource contains a new created_at field.
Resource Changes Go SDK 1 JS SDK Java SDK
GET /assets amount can be larger than MAX_INT64/10^7 + 0.8.2 2 0.2.0
GET /ledgers/{ledger_id}/effects created_at field added + 0.8.2 2 0.2.1
GET /ledgers/{ledger_id}/effects SSE created_at field added + 0.8.2 2 0.2.1
GET /accounts/{account_id}/effects created_at field added + 0.8.2 2 0.2.1
GET /accounts/{account_id}/effects SSE created_at field added + 0.8.2 2 0.2.1
GET /transactions/{tx_id}/effects created_at field added + 0.8.2 2 0.2.1
GET /transactions/{tx_id}/effects SSE created_at field added + 0.8.2 2 0.2.1
GET /operations/{op_id}/effects created_at field added + 0.8.2 2 0.2.1
GET /operations/{op_id}/effects SSE created_at field added + 0.8.2 2 0.2.1
GET /effects created_at field added + 0.8.2 2 0.2.1
GET /effects SSE created_at field added + 0.8.2 2 0.2.1
0.12.3
SDKs with full support
Changes
Resource Go SDK 1 JS SDK Java SDK
GET / +
(some _links missing)
- 0.2.1
GET /metrics - - -
GET /ledgers - 0.8.2 0.2.0
GET /ledgers SSE + 0.8.2 0.2.0
GET /ledgers/{ledger_id} - 0.8.2 0.2.0
GET /ledgers/{ledger_id}/transactions - 0.8.2 0.2.0
GET /ledgers/{ledger_id}/transactions SSE - 0.8.2 0.2.0
GET /ledgers/{ledger_id}/operations - 0.8.2 0.2.0
GET /ledgers/{ledger_id}/operations SSE - 0.8.2 0.2.1
GET /ledgers/{ledger_id}/payments - 0.8.2 0.2.0
GET /ledgers/{ledger_id}/payments SSE - 0.8.2 0.2.0
GET /ledgers/{ledger_id}/effects - 0.8.2 0.2.0
(no support for data, inflation types)
GET /ledgers/{ledger_id}/effects SSE - 0.8.2 0.2.0
(no support for data, inflation types)
GET /accounts/{account_id} + 0.8.2 0.2.0
GET /accounts/{account_id}/transactions - 0.8.2 0.2.0
GET /accounts/{account_id}/transactions SSE - 0.8.2 0.2.0
GET /accounts/{account_id}/operations - 0.8.2 0.2.0
GET /accounts/{account_id}/operations SSE - 0.8.2 0.2.1
GET /accounts/{account_id}/payments - 0.8.2 0.2.0
GET /accounts/{account_id}/payments SSE - 0.8.2 0.2.0
GET /accounts/{account_id}/effects - 0.8.2 0.2.0
(no support for data, inflation types)
GET /accounts/{account_id}/effects SSE - 0.8.2 0.2.0
(no support for data, inflation types)
GET /accounts/{account_id}/offers + 0.8.2 0.2.0
GET /accounts/{account_id}/trades - 0.8.2 0.2.1
GET /accounts/{account_id}/data/{key} - - -
POST /transactions - 0.8.2 0.2.0
GET /transactions + 0.8.2 0.2.0
GET /transactions SSE + 0.8.2 0.2.0
GET /transactions/{tx_id} + 0.8.2 0.2.0
GET /transactions/{tx_id}/operations - 0.8.2 0.2.0
GET /transactions/{tx_id}/operations SSE - 0.8.2 0.2.1
GET /transactions/{tx_id}/payments - 0.8.2 0.2.0
GET /transactions/{tx_id}/payments SSE - 0.8.2 0.2.0
GET /transactions/{tx_id}/effects - 0.8.2 0.2.0
(no support for data, inflation types)
GET /transactions/{tx_id}/effects SSE - 0.8.2 0.2.0
(no support for data, inflation types)
GET /operations - 0.8.2 0.2.0
GET /operations SSE - 0.8.2 0.2.1
GET /operations/{op_id} - 0.8.2 0.2.0
GET /operations/{op_id}/effects - 0.8.2 0.2.0
(no support for data, inflation types)
GET /operations/{op_id}/effects SSE - 0.8.2 0.2.0
(no support for data, inflation types)
GET /payments - 0.8.2 0.2.0
GET /payments SSE + 0.8.2 0.2.0
GET /effects - 0.8.2 0.2.0
(no support for data, inflation types)
GET /effects SSE - 0.8.2 0.2.0
(no support for data, inflation types)
GET /trades + 0.8.2 0.2.0
(no price field)
GET /trades_aggregations + 0.8.2 0.2.0
GET /offers/{offer_id}/trades - 0.8.2 0.2.1
GET /order_book + 0.8.2 0.2.0
GET /order_book SSE - 0.8.2 0.2.1
GET /paths - 0.8.2 0.2.0
GET /assets - 0.8.2 0.2.0

1 We don't do proper versioning for GO SDK yet. + means implemented in master branch.

2 Native JSON support in JS, no changes needed.

Documentation

Overview

Package resource contains the type definitions for all of horizons response resources.

Index

Constants

This section is empty.

Variables

View Source
var KeyTypeNames = map[strkey.VersionByte]string{
	strkey.VersionByteAccountID: "ed25519_public_key",
	strkey.VersionByteSeed:      "ed25519_secret_seed",
	strkey.VersionByteHashX:     "sha256_hash",
	strkey.VersionByteHashTx:    "preauth_tx",
}

KeyTypeNames maps from strkey version bytes into json string values to use in horizon responses.

Functions

func KeyTypeFromAddress

func KeyTypeFromAddress(address string) (string, error)

KeyTypeFromAddress converts the version byte of the provided strkey encoded value (for example an account id or a signer key) and returns the appropriate horizon-specific type name.

func MustKeyTypeFromAddress

func MustKeyTypeFromAddress(address string) string

MustKeyTypeFromAddress is the panicking variant of KeyTypeFromAddress.

Types

type Account

type Account struct {
	Links struct {
		Self         hal.Link `json:"self"`
		Transactions hal.Link `json:"transactions"`
		Operations   hal.Link `json:"operations"`
		Payments     hal.Link `json:"payments"`
		Effects      hal.Link `json:"effects"`
		Offers       hal.Link `json:"offers"`
		Trades       hal.Link `json:"trades"`
		Data         hal.Link `json:"data"`
	} `json:"_links"`

	HistoryAccount
	Sequence             string            `json:"sequence"`
	SubentryCount        int32             `json:"subentry_count"`
	InflationDestination string            `json:"inflation_destination,omitempty"`
	HomeDomain           string            `json:"home_domain,omitempty"`
	Thresholds           AccountThresholds `json:"thresholds"`
	Flags                AccountFlags      `json:"flags"`
	Balances             []Balance         `json:"balances"`
	Signers              []Signer          `json:"signers"`
	Data                 map[string]string `json:"data"`
}

Account is the summary of an account

func (Account) GetCreditBalance

func (a Account) GetCreditBalance(code string, issuer string) string

GetCreditBalance returns the balance for given code and issuer

func (*Account) GetData

func (this *Account) GetData(key string) ([]byte, error)

GetData returns decoded value for a given key. If the key does not exist, empty slice will be returned.

func (Account) GetNativeBalance

func (a Account) GetNativeBalance() (string, error)

GetNativeBalance returns the native balance of the account

func (*Account) MustGetData

func (this *Account) MustGetData(key string) []byte

MustGetData returns decoded value for a given key. If the key does not exist, empty slice will be returned. If there is an error decoding a value, it will panic.

type AccountFlags

type AccountFlags struct {
	AuthRequired  bool `json:"auth_required"`
	AuthRevocable bool `json:"auth_revocable"`
	AuthImmutable bool `json:"auth_immutable"`
}

AccountFlags represents the state of an account's flags

type AccountThresholds

type AccountThresholds struct {
	LowThreshold  byte `json:"low_threshold"`
	MedThreshold  byte `json:"med_threshold"`
	HighThreshold byte `json:"high_threshold"`
}

AccountThresholds represents an accounts "thresholds", the numerical values needed to satisfy the authorization of a given operation.

type Asset

type Asset base.Asset

Asset represents a single asset

type AssetStat

type AssetStat struct {
	Links struct {
		Toml hal.Link `json:"toml"`
	} `json:"_links"`

	base.Asset
	PT          string       `json:"paging_token"`
	Amount      string       `json:"amount"`
	NumAccounts int32        `json:"num_accounts"`
	Flags       AccountFlags `json:"flags"`
}

AssetStat represents the statistics for a single Asset

func (AssetStat) PagingToken

func (res AssetStat) PagingToken() string

PagingToken implementation for hal.Pageable

type Balance

type Balance struct {
	Balance            string `json:"balance"`
	Limit              string `json:"limit,omitempty"`
	BuyingLiabilities  string `json:"buying_liabilities"`
	SellingLiabilities string `json:"selling_liabilities"`
	base.Asset
}

Balance represents an account's holdings for a single currency type

type HistoryAccount

type HistoryAccount struct {
	ID        string `json:"id"`
	PT        string `json:"paging_token"`
	AccountID string `json:"account_id"`
}

HistoryAccount is a simple resource, used for the account collection actions. It provides only the "TotalOrderID" of the account and its account id.

type Ledger

type Ledger struct {
	Links struct {
		Self         hal.Link `json:"self"`
		Transactions hal.Link `json:"transactions"`
		Operations   hal.Link `json:"operations"`
		Payments     hal.Link `json:"payments"`
		Effects      hal.Link `json:"effects"`
	} `json:"_links"`
	ID       string `json:"id"`
	PT       string `json:"paging_token"`
	Hash     string `json:"hash"`
	PrevHash string `json:"prev_hash,omitempty"`
	Sequence int32  `json:"sequence"`
	// Deprecated - remove in: horizon-v0.17.0
	TransactionCount           int32     `json:"transaction_count"`
	SuccessfulTransactionCount int32     `json:"successful_transaction_count"`
	FailedTransactionCount     *int32    `json:"failed_transaction_count"`
	OperationCount             int32     `json:"operation_count"`
	ClosedAt                   time.Time `json:"closed_at"`
	TotalCoins                 string    `json:"total_coins"`
	FeePool                    string    `json:"fee_pool"`
	BaseFee                    int32     `json:"base_fee_in_stroops"`
	BaseReserve                int32     `json:"base_reserve_in_stroops"`
	MaxTxSetSize               int32     `json:"max_tx_set_size"`
	ProtocolVersion            int32     `json:"protocol_version"`
	HeaderXDR                  string    `json:"header_xdr"`
}

Ledger represents a single closed ledger

func (Ledger) PagingToken

func (this Ledger) PagingToken() string

type Offer

type Offer struct {
	Links struct {
		Self       hal.Link `json:"self"`
		OfferMaker hal.Link `json:"offer_maker"`
	} `json:"_links"`

	ID                 int64      `json:"id"`
	PT                 string     `json:"paging_token"`
	Seller             string     `json:"seller"`
	Selling            Asset      `json:"selling"`
	Buying             Asset      `json:"buying"`
	Amount             string     `json:"amount"`
	PriceR             Price      `json:"price_r"`
	Price              string     `json:"price"`
	LastModifiedLedger int32      `json:"last_modified_ledger"`
	LastModifiedTime   *time.Time `json:"last_modified_time"`
}

Offer is the display form of an offer to trade currency.

func (Offer) PagingToken

func (this Offer) PagingToken() string

type OrderBookSummary

type OrderBookSummary struct {
	Bids    []PriceLevel `json:"bids"`
	Asks    []PriceLevel `json:"asks"`
	Selling Asset        `json:"base"`
	Buying  Asset        `json:"counter"`
}

OrderBookSummary represents a snapshot summary of a given order book

type Path

type Path struct {
	SourceAssetType        string  `json:"source_asset_type"`
	SourceAssetCode        string  `json:"source_asset_code,omitempty"`
	SourceAssetIssuer      string  `json:"source_asset_issuer,omitempty"`
	SourceAmount           string  `json:"source_amount"`
	DestinationAssetType   string  `json:"destination_asset_type"`
	DestinationAssetCode   string  `json:"destination_asset_code,omitempty"`
	DestinationAssetIssuer string  `json:"destination_asset_issuer,omitempty"`
	DestinationAmount      string  `json:"destination_amount"`
	Path                   []Asset `json:"path"`
}

Path represents a single payment path.

func (Path) PagingToken

func (this Path) PagingToken() string

stub implementation to satisfy pageable interface

type Price

type Price base.Price

Price represents a price

type PriceLevel

type PriceLevel struct {
	PriceR Price  `json:"price_r"`
	Price  string `json:"price"`
	Amount string `json:"amount"`
}

PriceLevel represents an aggregation of offers that share a given price

type Root

type Root struct {
	Links struct {
		Account             hal.Link  `json:"account"`
		AccountTransactions hal.Link  `json:"account_transactions"`
		Assets              hal.Link  `json:"assets"`
		Friendbot           *hal.Link `json:"friendbot,omitempty"`
		Metrics             hal.Link  `json:"metrics"`
		OrderBook           hal.Link  `json:"order_book"`
		Self                hal.Link  `json:"self"`
		Transaction         hal.Link  `json:"transaction"`
		Transactions        hal.Link  `json:"transactions"`
	} `json:"_links"`

	HorizonVersion       string `json:"horizon_version"`
	StellarCoreVersion   string `json:"core_version"`
	HorizonSequence      int32  `json:"history_latest_ledger"`
	HistoryElderSequence int32  `json:"history_elder_ledger"`
	CoreSequence         int32  `json:"core_latest_ledger"`
	NetworkPassphrase    string `json:"network_passphrase"`
	// Deprecated - remove in: horizon-v0.17.0
	ProtocolVersion              int32 `json:"protocol_version"`
	CurrentProtocolVersion       int32 `json:"current_protocol_version"`
	CoreSupportedProtocolVersion int32 `json:"core_supported_protocol_version"`
}

Root is the initial map of links into the api.

type Signer

type Signer struct {
	// Deprecated - remove in: horizon-v0.17.0
	PublicKey string `json:"public_key"`
	Weight    int32  `json:"weight"`
	Key       string `json:"key"`
	Type      string `json:"type"`
}

Signer represents one of an account's signers.

type Trade

type Trade struct {
	Links struct {
		Self      hal.Link `json:"self"`
		Base      hal.Link `json:"base"`
		Counter   hal.Link `json:"counter"`
		Operation hal.Link `json:"operation"`
	} `json:"_links"`

	ID                 string    `json:"id"`
	PT                 string    `json:"paging_token"`
	LedgerCloseTime    time.Time `json:"ledger_close_time"`
	OfferID            string    `json:"offer_id"`
	BaseOfferID        string    `json:"base_offer_id"`
	BaseAccount        string    `json:"base_account"`
	BaseAmount         string    `json:"base_amount"`
	BaseAssetType      string    `json:"base_asset_type"`
	BaseAssetCode      string    `json:"base_asset_code,omitempty"`
	BaseAssetIssuer    string    `json:"base_asset_issuer,omitempty"`
	CounterOfferID     string    `json:"counter_offer_id"`
	CounterAccount     string    `json:"counter_account"`
	CounterAmount      string    `json:"counter_amount"`
	CounterAssetType   string    `json:"counter_asset_type"`
	CounterAssetCode   string    `json:"counter_asset_code,omitempty"`
	CounterAssetIssuer string    `json:"counter_asset_issuer,omitempty"`
	BaseIsSeller       bool      `json:"base_is_seller"`
	Price              *Price    `json:"price"`
}

Trade represents a horizon digested trade

func (Trade) PagingToken

func (res Trade) PagingToken() string

PagingToken implementation for hal.Pageable

type TradeAggregation

type TradeAggregation struct {
	Timestamp     int64     `json:"timestamp"`
	TradeCount    int64     `json:"trade_count"`
	BaseVolume    string    `json:"base_volume"`
	CounterVolume string    `json:"counter_volume"`
	Average       string    `json:"avg"`
	High          string    `json:"high"`
	HighR         xdr.Price `json:"high_r"`
	Low           string    `json:"low"`
	LowR          xdr.Price `json:"low_r"`
	Open          string    `json:"open"`
	OpenR         xdr.Price `json:"open_r"`
	Close         string    `json:"close"`
	CloseR        xdr.Price `json:"close_r"`
}

TradeAggregation represents trade data aggregation over a period of time

func (TradeAggregation) PagingToken

func (res TradeAggregation) PagingToken() string

PagingToken implementation for hal.Pageable. Not actually used

type TradeEffect

type TradeEffect struct {
	Links struct {
		Self      hal.Link `json:"self"`
		Seller    hal.Link `json:"seller"`
		Buyer     hal.Link `json:"buyer"`
		Operation hal.Link `json:"operation"`
	} `json:"_links"`

	ID                string    `json:"id"`
	PT                string    `json:"paging_token"`
	OfferID           string    `json:"offer_id"`
	Seller            string    `json:"seller"`
	SoldAmount        string    `json:"sold_amount"`
	SoldAssetType     string    `json:"sold_asset_type"`
	SoldAssetCode     string    `json:"sold_asset_code,omitempty"`
	SoldAssetIssuer   string    `json:"sold_asset_issuer,omitempty"`
	Buyer             string    `json:"buyer"`
	BoughtAmount      string    `json:"bought_amount"`
	BoughtAssetType   string    `json:"bought_asset_type"`
	BoughtAssetCode   string    `json:"bought_asset_code,omitempty"`
	BoughtAssetIssuer string    `json:"bought_asset_issuer,omitempty"`
	LedgerCloseTime   time.Time `json:"created_at"`
}

TradeEffect represents a trade effect resource. NOTE (scott, 2017-12-08): this resource is being added back in temporarily to deal with a deploy snafu. I didn't properly message the community that we were changing the response format, and so we're adding this back in to allow transition.

type Transaction

type Transaction struct {
	Links struct {
		Self       hal.Link `json:"self"`
		Account    hal.Link `json:"account"`
		Ledger     hal.Link `json:"ledger"`
		Operations hal.Link `json:"operations"`
		Effects    hal.Link `json:"effects"`
		Precedes   hal.Link `json:"precedes"`
		Succeeds   hal.Link `json:"succeeds"`
	} `json:"_links"`
	ID              string    `json:"id"`
	PT              string    `json:"paging_token"`
	Hash            string    `json:"hash"`
	Ledger          int32     `json:"ledger"`
	LedgerCloseTime time.Time `json:"created_at"`
	Account         string    `json:"source_account"`
	AccountSequence string    `json:"source_account_sequence"`
	FeePaid         int32     `json:"fee_paid"`
	OperationCount  int32     `json:"operation_count"`
	EnvelopeXdr     string    `json:"envelope_xdr"`
	ResultXdr       string    `json:"result_xdr"`
	ResultMetaXdr   string    `json:"result_meta_xdr"`
	FeeMetaXdr      string    `json:"fee_meta_xdr"`
	MemoType        string    `json:"memo_type"`
	Memo            string    `json:"memo,omitempty"`
	Signatures      []string  `json:"signatures"`
	ValidAfter      string    `json:"valid_after,omitempty"`
	ValidBefore     string    `json:"valid_before,omitempty"`
}

Transaction represents a single, successful transaction

func (Transaction) MarshalJSON

func (t Transaction) MarshalJSON() ([]byte, error)

MarshalJSON implements a custom marshaler for Transaction. The memo field should be omitted if and only if the memo_type is "none".

func (Transaction) PagingToken

func (res Transaction) PagingToken() string

PagingToken implementation for hal.Pageable

type TransactionResultCodes

type TransactionResultCodes struct {
	TransactionCode string   `json:"transaction"`
	OperationCodes  []string `json:"operations,omitempty"`
}

TransactionResultCodes represent a summary of result codes returned from a single xdr TransactionResult

type TransactionSuccess

type TransactionSuccess struct {
	Links struct {
		Transaction hal.Link `json:"transaction"`
	} `json:"_links"`
	Hash   string `json:"hash"`
	Ledger int32  `json:"ledger"`
	Env    string `json:"envelope_xdr"`
	Result string `json:"result_xdr"`
	Meta   string `json:"result_meta_xdr"`
}

TransactionSuccess represents the result of a successful transaction submission.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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