Documentation ¶
Index ¶
- type AuroraDBLedgerHashStore
- type Base64Ledger
- type CaptiveCoreConfig
- type CaptiveCoreToml
- type CaptiveCoreTomlParams
- type CaptiveDiamcircleCore
- func (c *CaptiveDiamcircleCore) Close() error
- func (c *CaptiveDiamcircleCore) GetLatestLedgerSequence(ctx context.Context) (uint32, error)
- func (c *CaptiveDiamcircleCore) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
- func (c *CaptiveDiamcircleCore) IsPrepared(ctx context.Context, ledgerRange Range) (bool, error)
- func (c *CaptiveDiamcircleCore) PrepareRange(ctx context.Context, ledgerRange Range) error
- type DatabaseBackend
- func (dbb *DatabaseBackend) Close() error
- func (dbb *DatabaseBackend) GetLatestLedgerSequence(ctx context.Context) (uint32, error)
- func (dbb *DatabaseBackend) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
- func (*DatabaseBackend) IsPrepared(ctx context.Context, ledgerRange Range) (bool, error)
- func (dbb *DatabaseBackend) PrepareRange(ctx context.Context, ledgerRange Range) error
- type History
- type HomeDomain
- type LatestLedgerSequenceResponse
- type LedgerBackend
- type LedgerResponse
- type MockDatabaseBackend
- func (m *MockDatabaseBackend) Close() error
- func (m *MockDatabaseBackend) GetLatestLedgerSequence(ctx context.Context) (uint32, error)
- func (m *MockDatabaseBackend) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
- func (m *MockDatabaseBackend) IsPrepared(ctx context.Context, ledgerRange Range) (bool, error)
- func (m *MockDatabaseBackend) PrepareRange(ctx context.Context, ledgerRange Range) error
- type MockLedgerHashStore
- type PrepareRangeResponse
- type QuorumSet
- type Range
- type RemoteCaptiveDiamcircleCore
- func (c RemoteCaptiveDiamcircleCore) Close() error
- func (c RemoteCaptiveDiamcircleCore) GetLatestLedgerSequence(ctx context.Context) (sequence uint32, err error)
- func (c RemoteCaptiveDiamcircleCore) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
- func (c RemoteCaptiveDiamcircleCore) IsPrepared(ctx context.Context, ledgerRange Range) (bool, error)
- func (c RemoteCaptiveDiamcircleCore) PrepareRange(ctx context.Context, ledgerRange Range) error
- type RemoteCaptiveOption
- type TrustedLedgerHashStore
- type Validator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuroraDBLedgerHashStore ¶
type AuroraDBLedgerHashStore struct {
// contains filtered or unexported fields
}
AuroraDBLedgerHashStore is a TrustedLedgerHashStore which uses aurora's db to look up ledger hashes
func (AuroraDBLedgerHashStore) Close ¶
func (h AuroraDBLedgerHashStore) Close() error
func (AuroraDBLedgerHashStore) GetLedgerHash ¶
func (h AuroraDBLedgerHashStore) GetLedgerHash(ctx context.Context, seq uint32) (string, bool, error)
GetLedgerHash returns the ledger hash for the given sequence number
type Base64Ledger ¶
type Base64Ledger xdr.LedgerCloseMeta
Base64Ledger extends xdr.LedgerCloseMeta with JSON encoding and decoding
func (Base64Ledger) MarshalJSON ¶
func (r Base64Ledger) MarshalJSON() ([]byte, error)
func (*Base64Ledger) UnmarshalJSON ¶
func (r *Base64Ledger) UnmarshalJSON(b []byte) error
type CaptiveCoreConfig ¶
type CaptiveCoreConfig struct { // BinaryPath is the file path to the Diamcircle Core binary BinaryPath string // NetworkPassphrase is the Diamcircle network passphrase used by captive core when connecting to the Diamcircle network NetworkPassphrase string // HistoryArchiveURLs are a list of history archive urls HistoryArchiveURLs []string Toml *CaptiveCoreToml // CheckpointFrequency is the number of ledgers between checkpoints // if unset, DefaultCheckpointFrequency will be used CheckpointFrequency uint32 // LedgerHashStore is an optional store used to obtain hashes for ledger sequences from a trusted source LedgerHashStore TrustedLedgerHashStore // Log is an (optional) custom logger which will capture any output from the Diamcircle Core process. // If Log is omitted then all output will be printed to stdout. Log *log.Entry // Context is the (optional) context which controls the lifetime of a CaptiveDiamcircleCore instance. Once the context is done // the CaptiveDiamcircleCore instance will not be able to stream ledgers from Diamcircle Core or spawn new // instances of Diamcircle Core. If Context is omitted CaptiveDiamcircleCore will default to using context.Background. Context context.Context // StoragePath is the (optional) base path passed along to Core's // BUCKET_DIR_PATH which specifies where various bucket data should be // stored. We always append /captive-core to this directory, since we clean // it up entirely on shutdown. StoragePath string }
CaptiveCoreConfig contains all the parameters required to create a CaptiveDiamcircleCore instance
type CaptiveCoreToml ¶
type CaptiveCoreToml struct {
// contains filtered or unexported fields
}
CaptiveCoreToml represents a parsed captive core configuration.
func NewCaptiveCoreToml ¶
func NewCaptiveCoreToml(params CaptiveCoreTomlParams) (*CaptiveCoreToml, error)
NewCaptiveCoreToml constructs a new CaptiveCoreToml instance based off the configuration in `params`.
func NewCaptiveCoreTomlFromFile ¶
func NewCaptiveCoreTomlFromFile(configPath string, params CaptiveCoreTomlParams) (*CaptiveCoreToml, error)
NewCaptiveCoreTomlFromFile constructs a new CaptiveCoreToml instance by merging configuration from the toml file located at `configPath` and the configuration provided by `params`.
func (*CaptiveCoreToml) AddExamplePubnetValidators ¶
func (c *CaptiveCoreToml) AddExamplePubnetValidators()
AddExamplePubnetQuorum adds example pubnet validators to toml file
func (*CaptiveCoreToml) CatchupToml ¶
func (c *CaptiveCoreToml) CatchupToml() (*CaptiveCoreToml, error)
CatchupToml returns a new CaptiveCoreToml instance based off the existing instance with some modifications which are suitable for running the catchup command on captive core.
func (*CaptiveCoreToml) HistoryIsConfigured ¶
func (c *CaptiveCoreToml) HistoryIsConfigured() bool
HistoryIsConfigured returns true if the history archive locations are configured.
func (*CaptiveCoreToml) Marshal ¶
func (c *CaptiveCoreToml) Marshal() ([]byte, error)
Marshal serializes the CaptiveCoreToml into a toml document.
func (*CaptiveCoreToml) QuorumSetIsConfigured ¶
func (c *CaptiveCoreToml) QuorumSetIsConfigured() bool
QuorumSetIsConfigured returns true if there is a quorum set defined in the configuration.
type CaptiveCoreTomlParams ¶
type CaptiveCoreTomlParams struct { // NetworkPassphrase is the Diamcircle network passphrase used by captive core when connecting to the Diamcircle network. NetworkPassphrase string // HistoryArchiveURLs are a list of history archive urls. HistoryArchiveURLs []string // HTTPPort is the TCP port to listen for requests (defaults to 0, which disables the HTTP server). HTTPPort *uint // PeerPort is the TCP port to bind to for connecting to the Diamcircle network // (defaults to 11625). It may be useful for example when there's >1 Diamcircle-Core // instance running on a machine. PeerPort *uint // LogPath is the (optional) path in which to store Core logs, passed along // to Diamcircle Core's LOG_FILE_PATH. LogPath *string // Strict is a flag which, if enabled, rejects Diamcircle Core toml fields which are not supported by captive core. Strict bool }
CaptiveCoreTomlParams defines captive core configuration provided by Aurora flags.
type CaptiveDiamcircleCore ¶
type CaptiveDiamcircleCore struct {
// contains filtered or unexported fields
}
CaptiveDiamcircleCore is a ledger backend that starts internal Diamcircle-Core subprocess responsible for streaming ledger data. It provides better decoupling than DatabaseBackend but requires some extra init time.
It operates in two modes:
- When a BoundedRange is prepared it starts Diamcircle-Core in catchup mode that replays ledgers in memory. This is very fast but requires Diamcircle-Core to keep ledger state in RAM. It requires around 3GB of RAM as of August 2020.
- When a UnboundedRange is prepared it runs Diamcircle-Core catchup mode to sync with the first ledger and then runs it in a normal mode. This requires the configAppendPath to be provided because a quorum set needs to be selected.
When running CaptiveDiamcircleCore will create a temporary folder to store bucket files and other temporary files. The folder is removed when Close is called.
The communication is performed via filesystem pipe which is created in a temporary folder.
Currently BoundedRange requires a full-trust on history archive. This issue is being fixed in Diamcircle-Core.
While using BoundedRanges is straightforward there are a few gotchas connected to UnboundedRanges:
- PrepareRange takes more time because all ledger entries must be stored on disk instead of RAM.
- If GetLedger is not called frequently (every 5 sec. on average) the Diamcircle-Core process can go out of sync with the network. This happens because there is no buffering of communication pipe and CaptiveDiamcircleCore has a very small internal buffer and Diamcircle-Core will not close the new ledger if it's not read.
Except for the Close function, CaptiveDiamcircleCore is not thread-safe and should not be accessed by multiple go routines. Close is thread-safe and can be called from another go routine. Once Close is called it will interrupt and cancel any pending operations.
Requires Diamcircle-Core v13.2.0+.
func NewCaptive ¶
func NewCaptive(config CaptiveCoreConfig) (*CaptiveDiamcircleCore, error)
NewCaptive returns a new CaptiveDiamcircleCore instance.
func (*CaptiveDiamcircleCore) Close ¶
func (c *CaptiveDiamcircleCore) Close() error
Close closes existing Diamcircle-Core process, streaming sessions and removes all temporary files. Note, once a CaptiveDiamcircleCore instance is closed it can no longer be used and all subsequent calls to PrepareRange(), GetLedger(), etc will fail. Close is thread-safe and can be called from another go routine.
func (*CaptiveDiamcircleCore) GetLatestLedgerSequence ¶
func (c *CaptiveDiamcircleCore) GetLatestLedgerSequence(ctx context.Context) (uint32, error)
GetLatestLedgerSequence returns the sequence of the latest ledger available in the backend. This method returns an error if not in a session (start with PrepareRange).
Note that for UnboundedRange the returned sequence number is not necessarily the latest sequence closed by the network. It's always the last value available in the backend.
func (*CaptiveDiamcircleCore) GetLedger ¶
func (c *CaptiveDiamcircleCore) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
GetLedger will block until the ledger is available in the backend (even for UnboundedRange), then return it's LedgerCloseMeta.
Call PrepareRange first to instruct the backend which ledgers to fetch. CaptiveDiamcircleCore requires PrepareRange call first to initialize Diamcircle-Core. Requesting a ledger on non-prepared backend will return an error.
Please note that requesting a ledger sequence far after current ledger will block the execution for a long time.
Because ledger data is streamed from Diamcircle-Core sequentially, users should request sequences in a non-decreasing order. If the requested sequence number is less than the last requested sequence number, an error will be returned.
This function behaves differently for bounded and unbounded ranges:
- BoundedRange: After getting the last ledger in a range this method will also Close() the backend.
func (*CaptiveDiamcircleCore) IsPrepared ¶
IsPrepared returns true if a given ledgerRange is prepared.
func (*CaptiveDiamcircleCore) PrepareRange ¶
func (c *CaptiveDiamcircleCore) PrepareRange(ctx context.Context, ledgerRange Range) error
PrepareRange prepares the given range (including from and to) to be loaded. Captive diamcircle-core backend needs to initialize Diamcircle-Core state to be able to stream ledgers. Diamcircle-Core mode depends on the provided ledgerRange:
- For BoundedRange it will start Diamcircle-Core in catchup mode.
- For UnboundedRange it will first catchup to starting ledger and then run it normally (including connecting to the Diamcircle network).
Please note that using a BoundedRange, currently, requires a full-trust on history archive. This issue is being fixed in Diamcircle-Core.
type DatabaseBackend ¶
type DatabaseBackend struct {
// contains filtered or unexported fields
}
DatabaseBackend implements a database data store.
func NewDatabaseBackend ¶
func NewDatabaseBackend(dataSourceName, networkPassphrase string) (*DatabaseBackend, error)
func NewDatabaseBackendFromSession ¶
func NewDatabaseBackendFromSession(session db.SessionInterface, networkPassphrase string) (*DatabaseBackend, error)
func (*DatabaseBackend) Close ¶
func (dbb *DatabaseBackend) Close() error
Close disconnects an active database session.
func (*DatabaseBackend) GetLatestLedgerSequence ¶
func (dbb *DatabaseBackend) GetLatestLedgerSequence(ctx context.Context) (uint32, error)
GetLatestLedgerSequence returns the most recent ledger sequence number present in the database.
func (*DatabaseBackend) GetLedger ¶
func (dbb *DatabaseBackend) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
GetLedger will block until the ledger is available in the backend (even for UnaboundedRange). Please note that requesting a ledger sequence far after current ledger will block the execution for a long time.
func (*DatabaseBackend) IsPrepared ¶
IsPrepared returns true if a given ledgerRange is prepared.
func (*DatabaseBackend) PrepareRange ¶
func (dbb *DatabaseBackend) PrepareRange(ctx context.Context, ledgerRange Range) error
type History ¶
type History struct { Get string `toml:"get"` // should we allow put and mkdir for captive core? Put string `toml:"put,omitempty"` Mkdir string `toml:"mkdir,omitempty"` }
History represents a [HISTORY] table in the captive core toml file.
type HomeDomain ¶
HomeDomain represents a [[HOME_DOMAINS]] entry in the captive core toml file.
type LatestLedgerSequenceResponse ¶
type LatestLedgerSequenceResponse struct {
Sequence uint32 `json:"sequence"`
}
LatestLedgerSequenceResponse is the response for the GetLatestLedgerSequence command.
type LedgerBackend ¶
type LedgerBackend interface { // GetLatestLedgerSequence returns the sequence of the latest ledger available // in the backend. GetLatestLedgerSequence(ctx context.Context) (sequence uint32, err error) // GetLedger will block until the ledger is available. GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error) // PrepareRange prepares the given range (including from and to) to be loaded. // Some backends (like captive diamcircle-core) need to initalize data to be // able to stream ledgers. Blocks until the first ledger is available. PrepareRange(ctx context.Context, ledgerRange Range) error // IsPrepared returns true if a given ledgerRange is prepared. IsPrepared(ctx context.Context, ledgerRange Range) (bool, error) Close() error }
LedgerBackend represents the interface to a ledger data store.
type LedgerResponse ¶
type LedgerResponse struct {
Ledger Base64Ledger `json:"ledger"`
}
LedgerResponse is the response for the GetLedger command.
type MockDatabaseBackend ¶
func (*MockDatabaseBackend) Close ¶
func (m *MockDatabaseBackend) Close() error
func (*MockDatabaseBackend) GetLatestLedgerSequence ¶
func (m *MockDatabaseBackend) GetLatestLedgerSequence(ctx context.Context) (uint32, error)
func (*MockDatabaseBackend) GetLedger ¶
func (m *MockDatabaseBackend) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
func (*MockDatabaseBackend) IsPrepared ¶
func (*MockDatabaseBackend) PrepareRange ¶
func (m *MockDatabaseBackend) PrepareRange(ctx context.Context, ledgerRange Range) error
type MockLedgerHashStore ¶
MockLedgerHashStore is a mock implementation of TrustedLedgerHashStore
func (*MockLedgerHashStore) Close ¶
func (m *MockLedgerHashStore) Close() error
func (*MockLedgerHashStore) GetLedgerHash ¶
GetLedgerHash returns the ledger hash for the given sequence number
type PrepareRangeResponse ¶
type PrepareRangeResponse struct { LedgerRange Range `json:"ledgerRange"` StartTime time.Time `json:"startTime"` Ready bool `json:"ready"` ReadyDuration int `json:"readyDuration"` }
PrepareRangeResponse describes the status of the pending PrepareRange operation.
type QuorumSet ¶
type QuorumSet struct { ThresholdPercent int `toml:"THRESHOLD_PERCENT"` Validators []string `toml:"VALIDATORS"` }
QuorumSet represents a [QUORUM_SET] table in the captive core toml file.
type Range ¶
type Range struct {
// contains filtered or unexported fields
}
Range represents a range of ledger sequence numbers.
func BoundedRange ¶
BoundedRange constructs a bounded range of ledgers with a fixed starting ledger and ending ledger.
func SingleLedgerRange ¶
SingleLedgerRange constructs a bounded range containing a single ledger.
func UnboundedRange ¶
BoundedRange constructs a unbounded range of ledgers with a fixed starting ledger.
func (Range) MarshalJSON ¶
func (*Range) UnmarshalJSON ¶
type RemoteCaptiveDiamcircleCore ¶
type RemoteCaptiveDiamcircleCore struct {
// contains filtered or unexported fields
}
RemoteCaptiveDiamcircleCore is an http client for interacting with a remote captive core server.
func NewRemoteCaptive ¶
func NewRemoteCaptive(captiveCoreURL string, options ...RemoteCaptiveOption) (RemoteCaptiveDiamcircleCore, error)
NewRemoteCaptive returns a new RemoteCaptiveDiamcircleCore instance.
Only the captiveCoreURL parameter is required.
func (RemoteCaptiveDiamcircleCore) Close ¶
func (c RemoteCaptiveDiamcircleCore) Close() error
Close cancels any pending PrepareRange requests.
func (RemoteCaptiveDiamcircleCore) GetLatestLedgerSequence ¶
func (c RemoteCaptiveDiamcircleCore) GetLatestLedgerSequence(ctx context.Context) (sequence uint32, err error)
GetLatestLedgerSequence returns the sequence of the latest ledger available in the backend. This method returns an error if not in a session (start with PrepareRange).
Note that for UnboundedRange the returned sequence number is not necessarily the latest sequence closed by the network. It's always the last value available in the backend.
func (RemoteCaptiveDiamcircleCore) GetLedger ¶
func (c RemoteCaptiveDiamcircleCore) GetLedger(ctx context.Context, sequence uint32) (xdr.LedgerCloseMeta, error)
Call PrepareRange first to instruct the backend which ledgers to fetch.
Requesting a ledger on non-prepared backend will return an error.
Because data is streamed from Diamcircle-Core ledger after ledger user should request sequences in a non-decreasing order. If the requested sequence number is less than the last requested sequence number, an error will be returned.
func (RemoteCaptiveDiamcircleCore) IsPrepared ¶
func (c RemoteCaptiveDiamcircleCore) IsPrepared(ctx context.Context, ledgerRange Range) (bool, error)
IsPrepared returns true if a given ledgerRange is prepared.
func (RemoteCaptiveDiamcircleCore) PrepareRange ¶
func (c RemoteCaptiveDiamcircleCore) PrepareRange(ctx context.Context, ledgerRange Range) error
PrepareRange prepares the given range (including from and to) to be loaded. Captive diamcircle-core backend needs to initalize Diamcircle-Core state to be able to stream ledgers. Diamcircle-Core mode depends on the provided ledgerRange:
- For BoundedRange it will start Diamcircle-Core in catchup mode.
- For UnboundedRange it will first catchup to starting ledger and then run it normally (including connecting to the Diamcircle network).
Please note that using a BoundedRange, currently, requires a full-trust on history archive. This issue is being fixed in Diamcircle-Core.
type RemoteCaptiveOption ¶
type RemoteCaptiveOption func(c *RemoteCaptiveDiamcircleCore)
RemoteCaptiveOption values can be passed into NewRemoteCaptive to customize a RemoteCaptiveDiamcircleCore instance.
func PrepareRangePollInterval ¶
func PrepareRangePollInterval(d time.Duration) RemoteCaptiveOption
PrepareRangePollInterval configures how often the captive core server will be polled when blocking on the PrepareRange operation.
type TrustedLedgerHashStore ¶
type TrustedLedgerHashStore interface { // GetLedgerHash returns the ledger hash for the given sequence number GetLedgerHash(ctx context.Context, seq uint32) (string, bool, error) Close() error }
TrustedLedgerHashStore is used to query ledger data from a trusted source. The store should contain ledgers verified by Diamcircle-Core, do not use untrusted source like history archives.
func NewAuroraDBLedgerHashStore ¶
func NewAuroraDBLedgerHashStore(session db.SessionInterface) TrustedLedgerHashStore
NewAuroraDBLedgerHashStore constructs a new TrustedLedgerHashStore backed by the aurora db
type Validator ¶
type Validator struct { Name string `toml:"NAME"` Quality string `toml:"QUALITY,omitempty"` HomeDomain string `toml:"HOME_DOMAIN"` PublicKey string `toml:"PUBLIC_KEY"` Address string `toml:"ADDRESS,omitempty"` History string `toml:"HISTORY,omitempty"` }
Validator represents a [[VALIDATORS]] entry in the captive core toml file.