types

package
v1.1.1 Latest Latest
Warning

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

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

README

Types

GoDoc

Types contains a collection of auto-generated Rosetta types. Using this package ensures that you don't need to automatically generate code on your own.

Installation

go get github.com/almightyhelp/rosetta-sdk-go/types

Documentation

Index

Constants

View Source
const (
	// RosettaAPIVersion is the version of the Rosetta API
	// specification used to generate code for this release
	// of the SDK.
	RosettaAPIVersion = "1.4.8"
)

Variables

This section is empty.

Functions

func AccountString

func AccountString(account *AccountIdentifier) string

AccountString returns a human-readable representation of a *AccountIdentifier.

func AddValues

func AddValues(
	a string,
	b string,
) (string, error)

AddValues adds string amounts using big.Int.

func AmountValue

func AmountValue(amount *Amount) (*big.Int, error)

AmountValue returns a *big.Int representation of an Amount.Value or an error.

func BigInt

func BigInt(value string) (*big.Int, error)

BigInt returns a *big.Int representation of a value.

func Bool

func Bool(b bool) *bool

Bool returns a pointer to the bool passed as an argument.

func CurrencyString

func CurrencyString(currency *Currency) string

CurrencyString returns a human-readable representation of a *Currency.

func Hash

func Hash(i interface{}) string

Hash returns a deterministic hash for any interface. This works because Golang's JSON marshaler sorts all map keys, recursively. Source: https://golang.org/pkg/encoding/json/#Marshal Inspiration: https://github.com/onsi/gomega/blob/c0be49994280db30b6b68390f67126d773bc5558/matchers/match_json_matcher.go#L16

It is important to note that any interface that is a slice or contains slices will not be equal if the slice ordering is different.

func Int64

func Int64(i int64) *int64

Int64 returns a pointer to the int64 passed as an argument.

func MarshalMap

func MarshalMap(input interface{}) (map[string]interface{}, error)

MarshalMap attempts to marshal an interface into a map[string]interface{}. This function is used similarly to json.Marshal.

func NegateValue

func NegateValue(
	val string,
) (string, error)

NegateValue flips the sign of a value.

func PrettyPrintStruct

func PrettyPrintStruct(val interface{}) string

PrettyPrintStruct marshals a struct to JSON and returns it as a string.

func PrintStruct

func PrintStruct(val interface{}) string

PrintStruct marshals a struct to JSON and returns it as a string without newlines.

func String

func String(s string) *string

String returns a pointer to the string passed as an argument.

func SubtractValues

func SubtractValues(
	a string,
	b string,
) (string, error)

SubtractValues subtracts a-b using big.Int.

func UnmarshalMap

func UnmarshalMap(metadata map[string]interface{}, output interface{}) error

UnmarshalMap attempts to unmarshal a map[string]interface{} into an interface. This function is used similarly to json.Unmarshal.

Types

type AccountBalanceRequest

type AccountBalanceRequest struct {
	NetworkIdentifier *NetworkIdentifier      `json:"network_identifier"`
	AccountIdentifier *AccountIdentifier      `json:"account_identifier"`
	BlockIdentifier   *PartialBlockIdentifier `json:"block_identifier,omitempty"`
	// In some cases, the caller may not want to retrieve all available balances for an
	// AccountIdentifier. If the currencies field is populated, only balances for the specified
	// currencies will be returned. If not populated, all available balances will be returned.
	Currencies []*Currency `json:"currencies,omitempty"`
}

AccountBalanceRequest An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint. If the block_identifier is populated, a historical balance query should be performed.

type AccountBalanceResponse

type AccountBalanceResponse struct {
	BlockIdentifier *BlockIdentifier `json:"block_identifier"`
	// A single account may have a balance in multiple currencies.
	Balances []*Amount `json:"balances"`
	// Account-based blockchains that utilize a nonce or sequence number should include that number
	// in the metadata. This number could be unique to the identifier or global across the account
	// address.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

AccountBalanceResponse An AccountBalanceResponse is returned on the /account/balance endpoint. If an account has a balance for each AccountIdentifier describing it (ex: an ERC-20 token balance on a few smart contracts), an account balance request must be made with each AccountIdentifier. The `coins` field was removed and replaced by by `/account/coins` in `v1.4.7`.

type AccountCoin

type AccountCoin struct {
	Account *AccountIdentifier `json:"account,omitempty"`
	Coin    *Coin              `json:"coin,omitempty"`
}

AccountCoin contains an *AccountIdentifier and a Coin that it owns.

type AccountCoinsRequest

type AccountCoinsRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	AccountIdentifier *AccountIdentifier `json:"account_identifier"`
	// Include state from the mempool when looking up an account's unspent coins. Note, using this
	// functionality breaks any guarantee of idempotency.
	IncludeMempool bool `json:"include_mempool"`
	// In some cases, the caller may not want to retrieve coins for all currencies for an
	// AccountIdentifier. If the currencies field is populated, only coins for the specified
	// currencies will be returned. If not populated, all unspent coins will be returned.
	Currencies []*Currency `json:"currencies,omitempty"`
}

AccountCoinsRequest AccountCoinsRequest is utilized to make a request on the /account/coins endpoint.

type AccountCoinsResponse

type AccountCoinsResponse struct {
	BlockIdentifier *BlockIdentifier `json:"block_identifier"`
	// If a blockchain is UTXO-based, all unspent Coins owned by an account_identifier should be
	// returned alongside the balance. It is highly recommended to populate this field so that users
	// of the Rosetta API implementation don't need to maintain their own indexer to track their
	// UTXOs.
	Coins []*Coin `json:"coins"`
	// Account-based blockchains that utilize a nonce or sequence number should include that number
	// in the metadata. This number could be unique to the identifier or global across the account
	// address.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

AccountCoinsResponse AccountCoinsResponse is returned on the /account/coins endpoint and includes all unspent Coins owned by an AccountIdentifier.

type AccountCurrency

type AccountCurrency struct {
	Account  *AccountIdentifier `json:"account_identifier,omitempty"`
	Currency *Currency          `json:"currency,omitempty"`
}

AccountCurrency is a simple struct combining a *types.Account and *types.Currency. This can be useful for looking up balances.

type AccountIdentifier

type AccountIdentifier struct {
	// The address may be a cryptographic public key (or some encoding of it) or a provided
	// username.
	Address    string                `json:"address"`
	SubAccount *SubAccountIdentifier `json:"sub_account,omitempty"`
	// Blockchains that utilize a username model (where the address is not a derivative of a
	// cryptographic public key) should specify the public key(s) owned by the address in metadata.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

AccountIdentifier The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).

type Allow

type Allow struct {
	// All Operation.Status this implementation supports. Any status that is returned during parsing
	// that is not listed here will cause client validation to error.
	OperationStatuses []*OperationStatus `json:"operation_statuses"`
	// All Operation.Type this implementation supports. Any type that is returned during parsing
	// that is not listed here will cause client validation to error.
	OperationTypes []string `json:"operation_types"`
	// All Errors that this implementation could return. Any error that is returned during parsing
	// that is not listed here will cause client validation to error.
	Errors []*Error `json:"errors"`
	// Any Rosetta implementation that supports querying the balance of an account at any height in
	// the past should set this to true.
	HistoricalBalanceLookup bool `json:"historical_balance_lookup"`
	// If populated, `timestamp_start_index` indicates the first block index where block timestamps
	// are considered valid (i.e. all blocks less than `timestamp_start_index` could have invalid
	// timestamps). This is useful when the genesis block (or blocks) of a network have timestamp 0.
	// If not populated, block timestamps are assumed to be valid for all available blocks.
	TimestampStartIndex *int64 `json:"timestamp_start_index,omitempty"`
	// All methods that are supported by the /call endpoint. Communicating which parameters should
	// be provided to /call is the responsibility of the implementer (this is en lieu of defining an
	// entire type system and requiring the implementer to define that in Allow).
	CallMethods []string `json:"call_methods"`
	// BalanceExemptions is an array of BalanceExemption indicating which account balances could
	// change without a corresponding Operation. BalanceExemptions should be used sparingly as they
	// may introduce significant complexity for integrators that attempt to reconcile all account
	// balance changes. If your implementation relies on any BalanceExemptions, you MUST implement
	// historical balance lookup (the ability to query an account balance at any BlockIdentifier).
	BalanceExemptions []*BalanceExemption `json:"balance_exemptions"`
	// Any Rosetta implementation that can update an AccountIdentifier's unspent coins based on the
	// contents of the mempool should populate this field as true. If false, requests to
	// `/account/coins` that set `include_mempool` as true will be automatically rejected.
	MempoolCoins bool `json:"mempool_coins"`
}

Allow Allow specifies supported Operation status, Operation types, and all possible error statuses. This Allow object is used by clients to validate the correctness of a Rosetta Server implementation. It is expected that these clients will error if they receive some response that contains any of the above information that is not specified here.

type Amount

type Amount struct {
	// Value of the transaction in atomic units represented as an arbitrary-sized signed integer.
	// For example, 1 BTC would be represented by a value of 100000000.
	Value    string                 `json:"value"`
	Currency *Currency              `json:"currency"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Amount Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.

func ExtractAmount

func ExtractAmount(
	balances []*Amount,
	currency *Currency,
) (*Amount, error)

ExtractAmount returns the Amount from a slice of Balance pertaining to an AccountAndCurrency.

type BalanceExemption

type BalanceExemption struct {
	// SubAccountAddress is the SubAccountIdentifier.Address that the BalanceExemption applies to
	// (regardless of the value of SubAccountIdentifier.Metadata).
	SubAccountAddress *string       `json:"sub_account_address,omitempty"`
	Currency          *Currency     `json:"currency,omitempty"`
	ExemptionType     ExemptionType `json:"exemption_type,omitempty"`
}

BalanceExemption BalanceExemption indicates that the balance for an exempt account could change without a corresponding Operation. This typically occurs with staking rewards, vesting balances, and Currencies with a dynamic supply. Currently, it is possible to exempt an account from strict reconciliation by SubAccountIdentifier.Address or by Currency. This means that any account with SubAccountIdentifier.Address would be exempt or any balance of a particular Currency would be exempt, respectively. BalanceExemptions should be used sparingly as they may introduce significant complexity for integrators that attempt to reconcile all account balance changes. If your implementation relies on any BalanceExemptions, you MUST implement historical balance lookup (the ability to query an account balance at any BlockIdentifier).

type Block

type Block struct {
	BlockIdentifier       *BlockIdentifier `json:"block_identifier"`
	ParentBlockIdentifier *BlockIdentifier `json:"parent_block_identifier"`
	// The timestamp of the block in milliseconds since the Unix Epoch. The timestamp is stored in
	// milliseconds because some blockchains produce blocks more often than once a second.
	Timestamp    int64                  `json:"timestamp"`
	Transactions []*Transaction         `json:"transactions"`
	Metadata     map[string]interface{} `json:"metadata,omitempty"`
}

Block Blocks contain an array of Transactions that occurred at a particular BlockIdentifier. A hard requirement for blocks returned by Rosetta implementations is that they MUST be _inalterable_: once a client has requested and received a block identified by a specific BlockIndentifier, all future calls for that same BlockIdentifier must return the same block contents.

type BlockEvent

type BlockEvent struct {
	// sequence is the unique identifier of a BlockEvent within the context of a NetworkIdentifier.
	Sequence        int64            `json:"sequence"`
	BlockIdentifier *BlockIdentifier `json:"block_identifier"`
	Type            BlockEventType   `json:"type"`
}

BlockEvent BlockEvent represents the addition or removal of a BlockIdentifier from storage. Streaming BlockEvents allows lightweight clients to update their own state without needing to implement their own syncing logic.

type BlockEventType

type BlockEventType string

BlockEventType BlockEventType determines if a BlockEvent represents the addition or removal of a block.

const (
	ADDED   BlockEventType = "block_added"
	REMOVED BlockEventType = "block_removed"
)

List of BlockEventType

type BlockIdentifier

type BlockIdentifier struct {
	// This is also known as the block height.
	Index int64  `json:"index"`
	Hash  string `json:"hash"`
}

BlockIdentifier The block_identifier uniquely identifies a block in a particular network.

type BlockRequest

type BlockRequest struct {
	NetworkIdentifier *NetworkIdentifier      `json:"network_identifier"`
	BlockIdentifier   *PartialBlockIdentifier `json:"block_identifier"`
}

BlockRequest A BlockRequest is utilized to make a block request on the /block endpoint.

type BlockResponse

type BlockResponse struct {
	Block *Block `json:"block,omitempty"`
	// Some blockchains may require additional transactions to be fetched that weren't returned in
	// the block response (ex: block only returns transaction hashes). For blockchains with a lot of
	// transactions in each block, this can be very useful as consumers can concurrently fetch all
	// transactions returned.
	OtherTransactions []*TransactionIdentifier `json:"other_transactions,omitempty"`
}

BlockResponse A BlockResponse includes a fully-populated block or a partially-populated block with a list of other transactions to fetch (other_transactions). As a result of the consensus algorithm of some blockchains, blocks can be omitted (i.e. certain block indexes can be skipped). If a query for one of these omitted indexes is made, the response should not include a `Block` object. It is VERY important to note that blocks MUST still form a canonical, connected chain of blocks where each block has a unique index. In other words, the `PartialBlockIdentifier` of a block after an omitted block should reference the last non-omitted block.

type BlockTransaction

type BlockTransaction struct {
	BlockIdentifier *BlockIdentifier `json:"block_identifier"`
	Transaction     *Transaction     `json:"transaction"`
}

BlockTransaction BlockTransaction contains a populated Transaction and the BlockIdentifier that contains it.

type BlockTransactionRequest

type BlockTransactionRequest struct {
	NetworkIdentifier     *NetworkIdentifier     `json:"network_identifier"`
	BlockIdentifier       *BlockIdentifier       `json:"block_identifier"`
	TransactionIdentifier *TransactionIdentifier `json:"transaction_identifier"`
}

BlockTransactionRequest A BlockTransactionRequest is used to fetch a Transaction included in a block that is not returned in a BlockResponse.

type BlockTransactionResponse

type BlockTransactionResponse struct {
	Transaction *Transaction `json:"transaction"`
}

BlockTransactionResponse A BlockTransactionResponse contains information about a block transaction.

type CallRequest

type CallRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	// Method is some network-specific procedure call. This method could map to a network-specific
	// RPC endpoint, a method in an SDK generated from a smart contract, or some hybrid of the two.
	// The implementation must define all available methods in the Allow object. However, it is up
	// to the caller to determine which parameters to provide when invoking `/call`.
	Method string `json:"method"`
	// Parameters is some network-specific argument for a method. It is up to the caller to
	// determine which parameters to provide when invoking `/call`.
	Parameters map[string]interface{} `json:"parameters"`
}

CallRequest CallRequest is the input to the `/call` endpoint.

type CallResponse

type CallResponse struct {
	// Result contains the result of the `/call` invocation. This result will not be inspected or
	// interpreted by Rosetta tooling and is left to the caller to decode.
	Result map[string]interface{} `json:"result"`
	// Idempotent indicates that if `/call` is invoked with the same CallRequest again, at any point
	// in time, it will return the same CallResponse. Integrators may cache the CallResponse if this
	// is set to true to avoid making unnecessary calls to the Rosetta implementation. For this
	// reason, implementers should be very conservative about returning true here or they could
	// cause issues for the caller.
	Idempotent bool `json:"idempotent"`
}

CallResponse CallResponse contains the result of a `/call` invocation.

type Coin

type Coin struct {
	CoinIdentifier *CoinIdentifier `json:"coin_identifier"`
	Amount         *Amount         `json:"amount"`
}

Coin Coin contains its unique identifier and the amount it represents.

type CoinAction

type CoinAction string

CoinAction CoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once.

const (
	CoinCreated CoinAction = "coin_created"
	CoinSpent   CoinAction = "coin_spent"
)

List of CoinAction

type CoinChange

type CoinChange struct {
	CoinIdentifier *CoinIdentifier `json:"coin_identifier"`
	CoinAction     CoinAction      `json:"coin_action"`
}

CoinChange CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. This object is part of the Operation model and must be populated for UTXO-based blockchains. Coincidentally, this abstraction of UTXOs allows for supporting both account-based transfers and UTXO-based transfers on the same blockchain (when a transfer is account-based, don't populate this model).

type CoinIdentifier

type CoinIdentifier struct {
	// Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this
	// identifier would be transaction_hash:index.
	Identifier string `json:"identifier"`
}

CoinIdentifier CoinIdentifier uniquely identifies a Coin.

type ConstructionCombineRequest

type ConstructionCombineRequest struct {
	NetworkIdentifier   *NetworkIdentifier `json:"network_identifier"`
	UnsignedTransaction string             `json:"unsigned_transaction"`
	Signatures          []*Signature       `json:"signatures"`
}

ConstructionCombineRequest ConstructionCombineRequest is the input to the `/construction/combine` endpoint. It contains the unsigned transaction blob returned by `/construction/payloads` and all required signatures to create a network transaction.

type ConstructionCombineResponse

type ConstructionCombineResponse struct {
	SignedTransaction string `json:"signed_transaction"`
}

ConstructionCombineResponse ConstructionCombineResponse is returned by `/construction/combine`. The network payload will be sent directly to the `construction/submit` endpoint.

type ConstructionDeriveRequest

type ConstructionDeriveRequest struct {
	NetworkIdentifier *NetworkIdentifier     `json:"network_identifier"`
	PublicKey         *PublicKey             `json:"public_key"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
}

ConstructionDeriveRequest ConstructionDeriveRequest is passed to the `/construction/derive` endpoint. Network is provided in the request because some blockchains have different address formats for different networks. Metadata is provided in the request because some blockchains allow for multiple address types (i.e. different address for validators vs normal accounts).

type ConstructionDeriveResponse

type ConstructionDeriveResponse struct {
	AccountIdentifier *AccountIdentifier     `json:"account_identifier,omitempty"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
}

ConstructionDeriveResponse ConstructionDeriveResponse is returned by the `/construction/derive` endpoint.

func (*ConstructionDeriveResponse) MarshalJSON

func (c *ConstructionDeriveResponse) MarshalJSON() ([]byte, error)

MarshalJSON overrides the default JSON marshaler and adds the deprecated "address" field to the response.

func (*ConstructionDeriveResponse) UnmarshalJSON

func (c *ConstructionDeriveResponse) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides the default JSON unmarshaler and reads the deprecated "address" field from the response.

type ConstructionHashRequest

type ConstructionHashRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	SignedTransaction string             `json:"signed_transaction"`
}

ConstructionHashRequest ConstructionHashRequest is the input to the `/construction/hash` endpoint.

type ConstructionMetadataRequest

type ConstructionMetadataRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	// Some blockchains require different metadata for different types of transaction construction
	// (ex: delegation versus a transfer). Instead of requiring a blockchain node to return all
	// possible types of metadata for construction (which may require multiple node fetches), the
	// client can populate an options object to limit the metadata returned to only the subset
	// required.
	Options    map[string]interface{} `json:"options,omitempty"`
	PublicKeys []*PublicKey           `json:"public_keys,omitempty"`
}

ConstructionMetadataRequest A ConstructionMetadataRequest is utilized to get information required to construct a transaction. The Options object used to specify which metadata to return is left purposely unstructured to allow flexibility for implementers. Options is not required in the case that there is network-wide metadata of interest. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.

type ConstructionMetadataResponse

type ConstructionMetadataResponse struct {
	Metadata     map[string]interface{} `json:"metadata"`
	SuggestedFee []*Amount              `json:"suggested_fee,omitempty"`
}

ConstructionMetadataResponse The ConstructionMetadataResponse returns network-specific metadata used for transaction construction. Optionally, the implementer can return the suggested fee associated with the transaction being constructed. The caller may use this info to adjust the intent of the transaction or to create a transaction with a different account that can pay the suggested fee. Suggested fee is an array in case fee payment must occur in multiple currencies.

type ConstructionParseRequest

type ConstructionParseRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	// Signed is a boolean indicating whether the transaction is signed.
	Signed bool `json:"signed"`
	// This must be either the unsigned transaction blob returned by `/construction/payloads` or the
	// signed transaction blob returned by `/construction/combine`.
	Transaction string `json:"transaction"`
}

ConstructionParseRequest ConstructionParseRequest is the input to the `/construction/parse` endpoint. It allows the caller to parse either an unsigned or signed transaction.

type ConstructionParseResponse

type ConstructionParseResponse struct {
	Operations               []*Operation           `json:"operations"`
	AccountIdentifierSigners []*AccountIdentifier   `json:"account_identifier_signers,omitempty"`
	Metadata                 map[string]interface{} `json:"metadata,omitempty"`
}

ConstructionParseResponse ConstructionParseResponse contains an array of operations that occur in a transaction blob. This should match the array of operations provided to `/construction/preprocess` and `/construction/payloads`.

func (*ConstructionParseResponse) MarshalJSON

func (c *ConstructionParseResponse) MarshalJSON() ([]byte, error)

MarshalJSON overrides the default JSON marshaler and adds the deprecated "signers" field to the response.

func (*ConstructionParseResponse) UnmarshalJSON

func (c *ConstructionParseResponse) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides the default JSON unmarshaler and reads the deprecated "signers" field from the response.

type ConstructionPayloadsRequest

type ConstructionPayloadsRequest struct {
	NetworkIdentifier *NetworkIdentifier     `json:"network_identifier"`
	Operations        []*Operation           `json:"operations"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
	PublicKeys        []*PublicKey           `json:"public_keys,omitempty"`
}

ConstructionPayloadsRequest ConstructionPayloadsRequest is the request to `/construction/payloads`. It contains the network, a slice of operations, and arbitrary metadata that was returned by the call to `/construction/metadata`. Optionally, the request can also include an array of PublicKeys associated with the AccountIdentifiers returned in ConstructionPreprocessResponse.

type ConstructionPayloadsResponse

type ConstructionPayloadsResponse struct {
	UnsignedTransaction string            `json:"unsigned_transaction"`
	Payloads            []*SigningPayload `json:"payloads"`
}

ConstructionPayloadsResponse ConstructionTransactionResponse is returned by `/construction/payloads`. It contains an unsigned transaction blob (that is usually needed to construct the a network transaction from a collection of signatures) and an array of payloads that must be signed by the caller.

type ConstructionPreprocessRequest

type ConstructionPreprocessRequest struct {
	NetworkIdentifier      *NetworkIdentifier     `json:"network_identifier"`
	Operations             []*Operation           `json:"operations"`
	Metadata               map[string]interface{} `json:"metadata,omitempty"`
	MaxFee                 []*Amount              `json:"max_fee,omitempty"`
	SuggestedFeeMultiplier *float64               `json:"suggested_fee_multiplier,omitempty"`
}

ConstructionPreprocessRequest ConstructionPreprocessRequest is passed to the `/construction/preprocess` endpoint so that a Rosetta implementation can determine which metadata it needs to request for construction. Metadata provided in this object should NEVER be a product of live data (i.e. the caller must follow some network-specific data fetching strategy outside of the Construction API to populate required Metadata). If live data is required for construction, it MUST be fetched in the call to `/construction/metadata`. The caller can provide a max fee they are willing to pay for a transaction. This is an array in the case fees must be paid in multiple currencies. The caller can also provide a suggested fee multiplier to indicate that the suggested fee should be scaled. This may be used to set higher fees for urgent transactions or to pay lower fees when there is less urgency. It is assumed that providing a very low multiplier (like 0.0001) will never lead to a transaction being created with a fee less than the minimum network fee (if applicable). In the case that the caller provides both a max fee and a suggested fee multiplier, the max fee will set an upper bound on the suggested fee (regardless of the multiplier provided).

type ConstructionPreprocessResponse

type ConstructionPreprocessResponse struct {
	// The options that will be sent directly to `/construction/metadata` by the caller.
	Options            map[string]interface{} `json:"options,omitempty"`
	RequiredPublicKeys []*AccountIdentifier   `json:"required_public_keys,omitempty"`
}

ConstructionPreprocessResponse ConstructionPreprocessResponse contains `options` that will be sent unmodified to `/construction/metadata`. If it is not necessary to make a request to `/construction/metadata`, `options` should be omitted. Some blockchains require the PublicKey of particular AccountIdentifiers to construct a valid transaction. To fetch these PublicKeys, populate `required_public_keys` with the AccountIdentifiers associated with the desired PublicKeys. If it is not necessary to retrieve any PublicKeys for construction, `required_public_keys` should be omitted.

type ConstructionSubmitRequest

type ConstructionSubmitRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	SignedTransaction string             `json:"signed_transaction"`
}

ConstructionSubmitRequest The transaction submission request includes a signed transaction.

type Currency

type Currency struct {
	// Canonical symbol associated with a currency.
	Symbol string `json:"symbol"`
	// Number of decimal places in the standard unit representation of the amount. For example, BTC
	// has 8 decimals. Note that it is not possible to represent the value of some currency in
	// atomic units that is not base 10.
	Decimals int32 `json:"decimals"`
	// Any additional information related to the currency itself. For example, it would be useful to
	// populate this object with the contract address of an ERC-20 token.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Currency Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).

type CurveType

type CurveType string

CurveType CurveType is the type of cryptographic curve associated with a PublicKey. * secp256k1: SEC compressed - `33 bytes` (https://secg.org/sec1-v2.pdf#subsubsection.2.3.3) * secp256r1: SEC compressed - `33 bytes` (https://secg.org/sec1-v2.pdf#subsubsection.2.3.3) * edwards25519: `y (255-bits) || x-sign-bit (1-bit)` - `32 bytes` (https://ed25519.cr.yp.to/ed25519-20110926.pdf) * tweedle: 1st pk : Fq.t (32 bytes) || 2nd pk : Fq.t (32 bytes) (https://github.com/CodaProtocol/coda/blob/develop/rfcs/0038-rosetta-construction-api.md#marshal-keys)

const (
	Secp256k1    CurveType = "secp256k1"
	Secp256r1    CurveType = "secp256r1"
	Edwards25519 CurveType = "edwards25519"
	Tweedle      CurveType = "tweedle"
)

List of CurveType

type Error

type Error struct {
	// Code is a network-specific error code. If desired, this code can be equivalent to an HTTP
	// status code.
	Code int32 `json:"code"`
	// Message is a network-specific error message. The message MUST NOT change for a given code. In
	// particular, this means that any contextual information should be included in the details
	// field.
	Message string `json:"message"`
	// Description allows the implementer to optionally provide additional information about an
	// error. In many cases, the content of this field will be a copy-and-paste from existing
	// developer documentation. Description can ONLY be populated with generic information about a
	// particular type of error. It MUST NOT be populated with information about a particular
	// instantiation of an error (use `details` for this). Whereas the content of Error.Message
	// should stay stable across releases, the content of Error.Description will likely change
	// across releases (as implementers improve error documentation). For this reason, the content
	// in this field is not part of any type assertion (unlike Error.Message).
	Description *string `json:"description,omitempty"`
	// An error is retriable if the same request may succeed if submitted again.
	Retriable bool `json:"retriable"`
	// Often times it is useful to return context specific to the request that caused the error
	// (i.e. a sample of the stack trace or impacted account) in addition to the standard error
	// message.
	Details map[string]interface{} `json:"details,omitempty"`
}

Error Instead of utilizing HTTP status codes to describe node errors (which often do not have a good analog), rich errors are returned using this object. Both the code and message fields can be individually used to correctly identify an error. Implementations MUST use unique values for both fields.

type EventsBlocksRequest

type EventsBlocksRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	// offset is the offset into the event stream to sync events from. If this field is not
	// populated, we return the limit events backwards from tip. If this is set to 0, we start from
	// the beginning.
	Offset *int64 `json:"offset,omitempty"`
	// limit is the maximum number of events to fetch in one call. The implementation may return <=
	// limit events.
	Limit *int64 `json:"limit,omitempty"`
}

EventsBlocksRequest EventsBlocksRequest is utilized to fetch a sequence of BlockEvents indicating which blocks were added and removed from storage to reach the current state.

type EventsBlocksResponse

type EventsBlocksResponse struct {
	// max_sequence is the maximum available sequence number to fetch.
	MaxSequence int64 `json:"max_sequence"`
	// events is an array of BlockEvents indicating the order to add and remove blocks to maintain a
	// canonical view of blockchain state. Lightweight clients can use this event stream to update
	// state without implementing their own block syncing logic.
	Events []*BlockEvent `json:"events"`
}

EventsBlocksResponse EventsBlocksResponse contains an ordered collection of BlockEvents and the max retrievable sequence.

type ExemptionType

type ExemptionType string

ExemptionType ExemptionType is used to indicate if the live balance for an account subject to a BalanceExemption could increase above, decrease below, or equal the computed balance. * greater_or_equal: The live balance may increase above or equal the computed balance. This typically occurs with staking rewards that accrue on each block. * less_or_equal: The live balance may decrease below or equal the computed balance. This typically occurs as balance moves from locked to spendable on a vesting account. * dynamic: The live balance may increase above, decrease below, or equal the computed balance. This typically occurs with tokens that have a dynamic supply.

const (
	BalanceGreaterOrEqual ExemptionType = "greater_or_equal"
	BalanceLessOrEqual    ExemptionType = "less_or_equal"
	BalanceDynamic        ExemptionType = "dynamic"
)

List of ExemptionType

type MempoolResponse

type MempoolResponse struct {
	TransactionIdentifiers []*TransactionIdentifier `json:"transaction_identifiers"`
}

MempoolResponse A MempoolResponse contains all transaction identifiers in the mempool for a particular network_identifier.

type MempoolTransactionRequest

type MempoolTransactionRequest struct {
	NetworkIdentifier     *NetworkIdentifier     `json:"network_identifier"`
	TransactionIdentifier *TransactionIdentifier `json:"transaction_identifier"`
}

MempoolTransactionRequest A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool.

type MempoolTransactionResponse

type MempoolTransactionResponse struct {
	Transaction *Transaction           `json:"transaction"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"`
}

MempoolTransactionResponse A MempoolTransactionResponse contains an estimate of a mempool transaction. It may not be possible to know the full impact of a transaction in the mempool (ex: fee paid).

type MetadataRequest

type MetadataRequest struct {
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

MetadataRequest A MetadataRequest is utilized in any request where the only argument is optional metadata.

type NetworkIdentifier

type NetworkIdentifier struct {
	Blockchain string `json:"blockchain"`
	// If a blockchain has a specific chain-id or network identifier, it should go in this field. It
	// is up to the client to determine which network-specific identifier is mainnet or testnet.
	Network              string                `json:"network"`
	SubNetworkIdentifier *SubNetworkIdentifier `json:"sub_network_identifier,omitempty"`
}

NetworkIdentifier The network_identifier specifies which network a particular object is associated with.

type NetworkListResponse

type NetworkListResponse struct {
	NetworkIdentifiers []*NetworkIdentifier `json:"network_identifiers"`
}

NetworkListResponse A NetworkListResponse contains all NetworkIdentifiers that the node can serve information for.

type NetworkOptionsResponse

type NetworkOptionsResponse struct {
	Version *Version `json:"version"`
	Allow   *Allow   `json:"allow"`
}

NetworkOptionsResponse NetworkOptionsResponse contains information about the versioning of the node and the allowed operation statuses, operation types, and errors.

type NetworkRequest

type NetworkRequest struct {
	NetworkIdentifier *NetworkIdentifier     `json:"network_identifier"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
}

NetworkRequest A NetworkRequest is utilized to retrieve some data specific exclusively to a NetworkIdentifier.

type NetworkStatusResponse

type NetworkStatusResponse struct {
	CurrentBlockIdentifier *BlockIdentifier `json:"current_block_identifier"`
	// The timestamp of the block in milliseconds since the Unix Epoch. The timestamp is stored in
	// milliseconds because some blockchains produce blocks more often than once a second.
	CurrentBlockTimestamp  int64            `json:"current_block_timestamp"`
	GenesisBlockIdentifier *BlockIdentifier `json:"genesis_block_identifier"`
	OldestBlockIdentifier  *BlockIdentifier `json:"oldest_block_identifier,omitempty"`
	SyncStatus             *SyncStatus      `json:"sync_status,omitempty"`
	Peers                  []*Peer          `json:"peers"`
}

NetworkStatusResponse NetworkStatusResponse contains basic information about the node's view of a blockchain network. It is assumed that any BlockIdentifier.Index less than or equal to CurrentBlockIdentifier.Index can be queried. If a Rosetta implementation prunes historical state, it should populate the optional `oldest_block_identifier` field with the oldest block available to query. If this is not populated, it is assumed that the `genesis_block_identifier` is the oldest queryable block. If a Rosetta implementation performs some pre-sync before it is possible to query blocks, sync_status should be populated so that clients can still monitor healthiness. Without this field, it may appear that the implementation is stuck syncing and needs to be terminated.

type Operation

type Operation struct {
	OperationIdentifier *OperationIdentifier `json:"operation_identifier"`
	// Restrict referenced related_operations to identifier indexes < the current
	// operation_identifier.index. This ensures there exists a clear DAG-structure of relations.
	// Since operations are one-sided, one could imagine relating operations in a single transfer or
	// linking operations in a call tree.
	RelatedOperations []*OperationIdentifier `json:"related_operations,omitempty"`
	// Type is the network-specific type of the operation. Ensure that any type that can be returned
	// here is also specified in the NetworkOptionsResponse. This can be very useful to downstream
	// consumers that parse all block data.
	Type string `json:"type"`
	// Status is the network-specific status of the operation. Status is not defined on the
	// transaction object because blockchains with smart contracts may have transactions that
	// partially apply (some operations are successful and some are not). Blockchains with atomic
	// transactions (all operations succeed or all operations fail) will have the same status for
	// each operation. On-chain operations (operations retrieved in the `/block` and
	// `/block/transaction` endpoints) MUST have a populated status field (anything on-chain must
	// have succeeded or failed). However, operations provided during transaction construction
	// (often times called \"intent\" in the documentation) MUST NOT have a populated status field
	// (operations yet to be included on-chain have not yet succeeded or failed).
	Status     *string                `json:"status,omitempty"`
	Account    *AccountIdentifier     `json:"account,omitempty"`
	Amount     *Amount                `json:"amount,omitempty"`
	CoinChange *CoinChange            `json:"coin_change,omitempty"`
	Metadata   map[string]interface{} `json:"metadata,omitempty"`
}

Operation Operations contain all balance-changing information within a transaction. They are always one-sided (only affect 1 AccountIdentifier) and can succeed or fail independently from a Transaction. Operations are used both to represent on-chain data (Data API) and to construct new transactions (Construction API), creating a standard interface for reading and writing to blockchains.

type OperationIdentifier

type OperationIdentifier struct {
	// The operation index is used to ensure each operation has a unique identifier within a
	// transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in
	// each transaction should start from index 0. To clarify, there may not be any notion of an
	// operation index in the blockchain being described.
	Index int64 `json:"index"`
	// Some blockchains specify an operation index that is essential for client use. For example,
	// Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index
	// should not be populated if there is no notion of an operation index in a blockchain
	// (typically most account-based blockchains).
	NetworkIndex *int64 `json:"network_index,omitempty"`
}

OperationIdentifier The operation_identifier uniquely identifies an operation within a transaction.

type OperationStatus

type OperationStatus struct {
	// The status is the network-specific status of the operation.
	Status string `json:"status"`
	// An Operation is considered successful if the Operation.Amount should affect the
	// Operation.Account. Some blockchains (like Bitcoin) only include successful operations in
	// blocks but other blockchains (like Ethereum) include unsuccessful operations that incur a
	// fee. To reconcile the computed balance from the stream of Operations, it is critical to
	// understand which Operation.Status indicate an Operation is successful and should affect an
	// Account.
	Successful bool `json:"successful"`
}

OperationStatus OperationStatus is utilized to indicate which Operation status are considered successful.

type Operator

type Operator string

Operator Operator is used by query-related endpoints to determine how to apply conditions. If this field is not populated, the default `and` value will be used.

const (
	OR  Operator = "or"
	AND Operator = "and"
)

List of Operator

func OperatorP

func OperatorP(o Operator) *Operator

OperatorP returns a pointer to the Operator passed as an argument.

We can't just use Operator because the types package already declares the Operator type.

type PartialBlockIdentifier

type PartialBlockIdentifier struct {
	Index *int64  `json:"index,omitempty"`
	Hash  *string `json:"hash,omitempty"`
}

PartialBlockIdentifier When fetching data by BlockIdentifier, it may be possible to only specify the index or hash. If neither property is specified, it is assumed that the client is making a request at the current block.

func ConstructPartialBlockIdentifier

func ConstructPartialBlockIdentifier(
	blockIdentifier *BlockIdentifier,
) *PartialBlockIdentifier

ConstructPartialBlockIdentifier constructs a *PartialBlockIdentifier from a *BlockIdentifier.

It is useful to have this helper when making block requests with the fetcher.

type Peer

type Peer struct {
	PeerID   string                 `json:"peer_id"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Peer A Peer is a representation of a node's peer.

type PublicKey

type PublicKey struct {
	Bytes     []byte    `json:"hex_bytes"`
	CurveType CurveType `json:"curve_type"`
}

PublicKey PublicKey contains a public key byte array for a particular CurveType encoded in hex. Note that there is no PrivateKey struct as this is NEVER the concern of an implementation.

func (*PublicKey) MarshalJSON

func (s *PublicKey) MarshalJSON() ([]byte, error)

MarshalJSON overrides the default JSON marshaler and encodes bytes as hex instead of base64.

func (*PublicKey) UnmarshalJSON

func (s *PublicKey) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides the default JSON unmarshaler and decodes bytes from hex instead of base64.

type SearchTransactionsRequest

type SearchTransactionsRequest struct {
	NetworkIdentifier *NetworkIdentifier `json:"network_identifier"`
	Operator          *Operator          `json:"operator,omitempty"`
	// max_block is the largest block index to consider when searching for transactions. If this
	// field is not populated, the current block is considered the max_block. If you do not specify
	// a max_block, it is possible a newly synced block will interfere with paginated transaction
	// queries (as the offset could become invalid with newly added rows).
	MaxBlock *int64 `json:"max_block,omitempty"`
	// offset is the offset into the query result to start returning transactions. If any search
	// conditions are changed, the query offset will change and you must restart your search
	// iteration.
	Offset *int64 `json:"offset,omitempty"`
	// limit is the maximum number of transactions to return in one call. The implementation may
	// return <= limit transactions.
	Limit                 *int64                 `json:"limit,omitempty"`
	TransactionIdentifier *TransactionIdentifier `json:"transaction_identifier,omitempty"`
	AccountIdentifier     *AccountIdentifier     `json:"account_identifier,omitempty"`
	CoinIdentifier        *CoinIdentifier        `json:"coin_identifier,omitempty"`
	Currency              *Currency              `json:"currency,omitempty"`
	// status is the network-specific operation type.
	Status *string `json:"status,omitempty"`
	// type is the network-specific operation type.
	Type *string `json:"type,omitempty"`
	// address is AccountIdentifier.Address. This is used to get all transactions related to an
	// AccountIdentifier.Address, regardless of SubAccountIdentifier.
	Address *string `json:"address,omitempty"`
	// success is a synthetic condition populated by parsing network-specific operation statuses
	// (using the mapping provided in `/network/options`).
	Success *bool `json:"success,omitempty"`
}

SearchTransactionsRequest SearchTransactionsRequest is used to search for transactions matching a set of provided conditions in canonical blocks.

type SearchTransactionsResponse

type SearchTransactionsResponse struct {
	// next_offset is the next offset to use when paginating through transaction results. If this
	// field is not populated, there are no more transactions to query.
	NextOffset *int64 `json:"next_offset,omitempty"`
	// transactions is an array of BlockTransactions sorted by most recent BlockIdentifier (meaning
	// that transactions in recent blocks appear first). If there are many transactions for a
	// particular search, transactions may not contain all matching transactions. It is up to the
	// caller to paginate these transactions using the max_block field.
	Transactions []*BlockTransaction `json:"transactions"`
}

SearchTransactionsResponse SearchTransactionsResponse contains an ordered collection of BlockTransactions that match the query in SearchTransactionsRequest. These BlockTransactions are sorted from most recent block to oldest block.

type Signature

type Signature struct {
	SigningPayload *SigningPayload `json:"signing_payload"`
	PublicKey      *PublicKey      `json:"public_key"`
	SignatureType  SignatureType   `json:"signature_type"`
	Bytes          []byte          `json:"hex_bytes"`
}

Signature Signature contains the payload that was signed, the public keys of the keypairs used to produce the signature, the signature (encoded in hex), and the SignatureType. PublicKey is often times not known during construction of the signing payloads but may be needed to combine signatures properly.

func (*Signature) MarshalJSON

func (s *Signature) MarshalJSON() ([]byte, error)

MarshalJSON overrides the default JSON marshaler and encodes bytes as hex instead of base64.

func (*Signature) UnmarshalJSON

func (s *Signature) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides the default JSON unmarshaler and decodes bytes from hex instead of base64.

type SignatureType

type SignatureType string

SignatureType SignatureType is the type of a cryptographic signature. * ecdsa: `r (32-bytes) || s (32-bytes)` - `64 bytes` * ecdsa_recovery: `r (32-bytes) || s (32-bytes) || v (1-byte)` - `65 bytes` * ed25519: `R (32-byte) || s (32-bytes)` - `64 bytes` * schnorr_1: `r (32-bytes) || s (32-bytes)` - `64 bytes` (schnorr signature implemented by Zilliqa where both `r` and `s` are scalars encoded as `32-bytes` values, most significant byte first.) * schnorr_poseidon: `r (32-bytes) || s (32-bytes)` where s = Hash(1st pk || 2nd pk || r) - `64 bytes` (schnorr signature w/ Poseidon hash function implemented by O(1) Labs where both `r` and `s` are scalars encoded as `32-bytes` values, least significant byte first. https://github.com/CodaProtocol/signer-reference/blob/master/schnorr.ml )

const (
	Ecdsa           SignatureType = "ecdsa"
	EcdsaRecovery   SignatureType = "ecdsa_recovery"
	Ed25519         SignatureType = "ed25519"
	Schnorr1        SignatureType = "schnorr_1"
	SchnorrPoseidon SignatureType = "schnorr_poseidon"
)

List of SignatureType

type SigningPayload

type SigningPayload struct {
	AccountIdentifier *AccountIdentifier `json:"account_identifier,omitempty"`
	Bytes             []byte             `json:"hex_bytes"`
	SignatureType     SignatureType      `json:"signature_type,omitempty"`
}

SigningPayload SigningPayload is signed by the client with the keypair associated with an AccountIdentifier using the specified SignatureType. SignatureType can be optionally populated if there is a restriction on the signature scheme that can be used to sign the payload.

func (*SigningPayload) MarshalJSON

func (s *SigningPayload) MarshalJSON() ([]byte, error)

MarshalJSON overrides the default JSON marshaler and encodes bytes as hex instead of base64. It also writes the deprecated "address" field to the response.

func (*SigningPayload) UnmarshalJSON

func (s *SigningPayload) UnmarshalJSON(b []byte) error

UnmarshalJSON overrides the default JSON unmarshaler and decodes bytes from hex instead of base64. It also reads the deprecated "address" field from the response.

type SubAccountIdentifier

type SubAccountIdentifier struct {
	// The SubAccount address may be a cryptographic value or some other identifier (ex: bonded)
	// that uniquely specifies a SubAccount.
	Address string `json:"address"`
	// If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other
	// identifying information can be stored here. It is important to note that two SubAccounts with
	// identical addresses but differing metadata will not be considered equal by clients.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

SubAccountIdentifier An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.

type SubNetworkIdentifier

type SubNetworkIdentifier struct {
	Network  string                 `json:"network"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

SubNetworkIdentifier In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains.

type SyncStatus

type SyncStatus struct {
	// CurrentIndex is the index of the last synced block in the current stage.
	CurrentIndex int64 `json:"current_index"`
	// TargetIndex is the index of the block that the implementation is attempting to sync to in the
	// current stage.
	TargetIndex *int64 `json:"target_index,omitempty"`
	// Stage is the phase of the sync process.
	Stage *string `json:"stage,omitempty"`
}

SyncStatus SyncStatus is used to provide additional context about an implementation's sync status. It is often used to indicate that an implementation is healthy when it cannot be queried until some sync phase occurs. If an implementation is immediately queryable, this model is often not populated.

type Transaction

type Transaction struct {
	TransactionIdentifier *TransactionIdentifier `json:"transaction_identifier"`
	Operations            []*Operation           `json:"operations"`
	// Transactions that are related to other transactions (like a cross-shard transaction) should
	// include the tranaction_identifier of these transactions in the metadata.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Transaction Transactions contain an array of Operations that are attributable to the same TransactionIdentifier.

type TransactionIdentifier

type TransactionIdentifier struct {
	// Any transactions that are attributable only to a block (ex: a block event) should use the
	// hash of the block as the identifier.
	Hash string `json:"hash"`
}

TransactionIdentifier The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.

type TransactionIdentifierResponse

type TransactionIdentifierResponse struct {
	TransactionIdentifier *TransactionIdentifier `json:"transaction_identifier"`
	Metadata              map[string]interface{} `json:"metadata,omitempty"`
}

TransactionIdentifierResponse TransactionIdentifierResponse contains the transaction_identifier of a transaction that was submitted to either `/construction/hash` or `/construction/submit`.

type Version

type Version struct {
	// The rosetta_version is the version of the Rosetta interface the implementation adheres to.
	// This can be useful for clients looking to reliably parse responses.
	RosettaVersion string `json:"rosetta_version"`
	// The node_version is the canonical version of the node runtime. This can help clients manage
	// deployments.
	NodeVersion string `json:"node_version"`
	// When a middleware server is used to adhere to the Rosetta interface, it should return its
	// version here. This can help clients manage deployments.
	MiddlewareVersion *string `json:"middleware_version,omitempty"`
	// Any other information that may be useful about versioning of dependent services should be
	// returned here.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Version The Version object is utilized to inform the client of the versions of different components of the Rosetta implementation.

Source Files

Jump to

Keyboard shortcuts

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