diff --git a/exp/services/ledgerexporter/README.md b/exp/services/ledgerexporter/README.md index 967bd1dc9e..57757508e1 100644 --- a/exp/services/ledgerexporter/README.md +++ b/exp/services/ledgerexporter/README.md @@ -21,45 +21,56 @@ type LedgerCloseMetaBatch struct { ### Command Line Options -#### Bounded Mode: -Exports a specific range of ledgers, defined by --start and --end. +#### Scan and Fill Mode: +Exports a specific range of ledgers, defined by --start and --end. Will only export to remote datastore if data is absent. ```bash -ledgerexporter --start --end --config-file +ledgerexporter scan-and-fill --start --end --config-file ``` -#### Unbounded Mode: -Exports ledgers continuously starting from --start. In this mode, the end ledger is either not provided or set to 0. +#### Append Mode: +Exports ledgers initially searching from --start, looking for the next absent ledger sequence number proceeding --start on the data store. If abscence is detected, the export range is narrowed to `--start `. +This feature requires ledgers to be present on the remote data store for some (possibly empty) prefix of the requested range and then absent for the (possibly empty) remainder. + +In this mode, the --end ledger can be provided to stop the process once export has reached that ledger, or if absent or 0 it will result in continous exporting of new ledgers emitted from the network. + + It’s guaranteed that ledgers exported during `append` mode from `start` and up to the last logged ledger file `Uploaded {ledger file name}` were contiguous, meaning all ledgers within that range were exported to the data lake with no gaps or missing ledgers in between. ```bash -ledgerexporter --start --config-file +ledgerexporter append --start --config-file ``` -#### Resumability: -Exporting a ledger range can be optimized further by enabling resumability if the remote data store supports it. +### Configuration (toml): +The `stellar_core_config` supports two ways for configuring captive core: + - use prebuilt captive core config toml, archive urls, and passphrase based on `stellar_core_config.network = testnet|pubnet`. + - manually set the the captive core confg by supplying these core parameters which will override any defaults when `stellar_core_config.network` is present also: + `stellar_core_config.captive_core_toml_path` + `stellar_core_config.history_archive_urls` + `stellar_core_config.network_passphrase` -By default, resumability is disabled, `--resume false` +Ensure you have stellar-core installed and set `stellar_core_config.stellar_core_binary_path` to it's path on o/s. -When enabled, `--resume true`, ledgerexporter will search the remote data store within the requested range, looking for the oldest absent ledger sequence number within range. If abscence is detected, the export range is narrowed to `--start `. -This feature requires all ledgers to be present on the remote data store for some (possibly empty) prefix of the requested range and then absent for the (possibly empty) remainder. - -### Configuration (toml): +Enable web service that will be bound to localhost post and publishes metrics by including `admin_port = {port}` +An example config, demonstrating preconfigured captive core settings and gcs data store config. ```toml -network = "testnet" # Options: `testnet` or `pubnet` +admin_port = 6061 [datastore_config] type = "GCS" [datastore_config.params] -destination_bucket_path = "your-bucket-name/" +destination_bucket_path = "your-bucket-name///" -[exporter_config] +[datastore_config.schema] ledgers_per_file = 64 files_per_partition = 10 -``` -#### Stellar-core configuration: -- The exporter automatically configures stellar-core based on the network specified in the config. -- Ensure you have stellar-core installed and accessible in your system's $PATH. +[stellar_core_config] + network = "testnet" + stellar_core_binary_path = "/my/path/to/stellar-core" + captive_core_toml_path = "my-captive-core.cfg" + history_archive_urls = ["http://testarchiveurl1", "http://testarchiveurl2"] + network_passphrase = "test" +``` ### Exported Files diff --git a/exp/services/ledgerexporter/config.toml b/exp/services/ledgerexporter/config.toml index a56087427c..c41d9376ac 100644 --- a/exp/services/ledgerexporter/config.toml +++ b/exp/services/ledgerexporter/config.toml @@ -1,15 +1,14 @@ -network = "testnet" - [datastore_config] type = "GCS" [datastore_config.params] -destination_bucket_path = "exporter-test/ledgers" +destination_bucket_path = "exporter-test/ledgers/testnet" -[exporter_config] - ledgers_per_file = 1 - files_per_partition = 64000 +[datastore_config.schema] +ledgers_per_file = 1 +files_per_partition = 64000 [stellar_core_config] + network = "testnet" stellar_core_binary_path = "/usr/local/bin/stellar-core" diff --git a/exp/services/ledgerexporter/docker/start b/exp/services/ledgerexporter/docker/start index eca213de0c..3b61c74eee 100644 --- a/exp/services/ledgerexporter/docker/start +++ b/exp/services/ledgerexporter/docker/start @@ -17,23 +17,25 @@ files_per_partition="${FILES_PER_PARTITION:-64000}" # Generate TOML configuration cat < config.toml -network = "${NETWORK}" [datastore_config] type = "GCS" [datastore_config.params] -destination_bucket_path = "${ARCHIVE_TARGET}" +destination_bucket_path = "${ARCHIVE_TARGET}/${NETWORK}" -[exporter_config] +[datastore_config.schema] ledgers_per_file = $ledgers_per_file files_per_partition = $files_per_partition + +[stellar_core_config] + network = "${NETWORK}" EOF # Check if START or END variables are set if [[ -n "$START" || -n "$END" ]]; then echo "START: $START END: $END" - /usr/bin/ledgerexporter --config-file config.toml --start $START --end $END + /usr/bin/ledgerexporter scan-and-fill --config-file config.toml --start $START --end $END else echo "Error: No ledger range provided." exit 1 diff --git a/exp/services/ledgerexporter/internal/app.go b/exp/services/ledgerexporter/internal/app.go index c6adcd41a0..eb0f544ec3 100644 --- a/exp/services/ledgerexporter/internal/app.go +++ b/exp/services/ledgerexporter/internal/app.go @@ -5,6 +5,7 @@ import ( "fmt" "net/http" "os" + "os/exec" "os/signal" "sync" "syscall" @@ -72,7 +73,7 @@ type InvalidDataStoreError struct { func (m InvalidDataStoreError) Error() string { return fmt.Sprintf("The remote data store has inconsistent data, "+ "a resumable starting ledger of %v was identified, "+ - "but that is not aligned to expected ledgers-per-file of %v. use '--resume false' to bypass", + "but that is not aligned to expected ledgers-per-file of %v. use 'scan-and-fill' sub-command to bypass", m.LedgerSequence, m.LedgersPerFile) } @@ -82,17 +83,16 @@ type App struct { dataStore datastore.DataStore exportManager *ExportManager uploader Uploader - flags Flags adminServer *http.Server } -func NewApp(flags Flags) *App { +func NewApp() *App { logger.SetLevel(log.DebugLevel) - app := &App{flags: flags} + app := &App{} return app } -func (a *App) init(ctx context.Context) error { +func (a *App) init(ctx context.Context, runtimeSettings RuntimeSettings) error { var err error var archive historyarchive.ArchiveInterface @@ -104,20 +104,22 @@ func (a *App) init(ctx context.Context) error { collectors.NewGoCollector(), ) - if a.config, err = NewConfig(a.flags); err != nil { + if a.config, err = NewConfig(runtimeSettings); err != nil { return errors.Wrap(err, "Could not load configuration") } - if archive, err = datastore.CreateHistoryArchiveFromNetworkName(ctx, a.config.Network); err != nil { + if archive, err = a.config.GenerateHistoryArchive(ctx); err != nil { + return err + } + if err = a.config.ValidateAndSetLedgerRange(ctx, archive); err != nil { return err } - a.config.ValidateAndSetLedgerRange(ctx, archive) - if a.dataStore, err = datastore.NewDataStore(ctx, a.config.DataStoreConfig, a.config.Network); err != nil { + if a.dataStore, err = datastore.NewDataStore(ctx, a.config.DataStoreConfig); err != nil { return errors.Wrap(err, "Could not connect to destination data store") } - if a.config.Resume { + if a.config.Resumable() { if err = a.applyResumability(ctx, - datastore.NewResumableManager(a.dataStore, a.config.Network, a.config.LedgerBatchConfig, archive)); err != nil { + datastore.NewResumableManager(a.dataStore, a.config.DataStoreConfig.Schema, archive)); err != nil { return err } } @@ -129,7 +131,10 @@ func (a *App) init(ctx context.Context) error { } queue := NewUploadQueue(uploadQueueCapacity, registry) - if a.exportManager, err = NewExportManager(a.config, a.ledgerBackend, queue, registry); err != nil { + if a.exportManager, err = NewExportManager(a.config.DataStoreConfig.Schema, + a.ledgerBackend, queue, registry, + a.config.StellarCoreConfig.NetworkPassphrase, + a.config.CoreVersion); err != nil { return err } a.uploader = NewUploader(a.dataStore, queue, registry) @@ -151,8 +156,8 @@ func (a *App) applyResumability(ctx context.Context, resumableManager datastore. // TODO - evaluate a more robust validation of remote data for ledgers-per-file consistency // this assumes ValidateAndSetLedgerRange() has conditioned the a.config.StartLedger to be at least > 1 - if absentLedger > 2 && absentLedger != a.config.LedgerBatchConfig.GetSequenceNumberStartBoundary(absentLedger) { - return NewInvalidDataStoreError(absentLedger, a.config.LedgerBatchConfig.LedgersPerFile) + if absentLedger > 2 && absentLedger != a.config.DataStoreConfig.Schema.GetSequenceNumberStartBoundary(absentLedger) { + return NewInvalidDataStoreError(absentLedger, a.config.DataStoreConfig.Schema.LedgersPerFile) } logger.Infof("For export ledger range start=%d, end=%d, the remote storage has some of this data already, will resume at later start ledger of %d", a.config.StartLedger, a.config.EndLedger, absentLedger) a.config.StartLedger = absentLedger @@ -180,18 +185,19 @@ func newAdminServer(adminPort int, prometheusRegistry *prometheus.Registry) *htt } } -func (a *App) Run() { +func (a *App) Run(runtimeSettings RuntimeSettings) error { ctx, cancel := context.WithCancel(context.Background()) defer cancel() - if err := a.init(ctx); err != nil { - var dataAlreadyExported DataAlreadyExportedError + if err := a.init(ctx, runtimeSettings); err != nil { + var dataAlreadyExported *DataAlreadyExportedError if errors.As(err, &dataAlreadyExported) { logger.Info(err.Error()) logger.Info("Shutting down ledger-exporter") - return + return nil } - logger.WithError(err).Fatal("Stopping ledger-exporter") + logger.WithError(err).Error("Stopping ledger-exporter") + return err } defer a.close() @@ -254,12 +260,16 @@ func (a *App) Run() { logger.WithError(err).Warn("error in internalServer.Shutdown") } } + return nil } // newLedgerBackend Creates and initializes captive core ledger backend // Currently, only supports captive-core as ledger backend func newLedgerBackend(config *Config, prometheusRegistry *prometheus.Registry) (ledgerbackend.LedgerBackend, error) { - captiveConfig, err := config.generateCaptiveCoreConfig() + // best effort check on a core bin available from PATH to provide as default if + // no core bin is provided from config. + coreBinFromPath, _ := exec.LookPath("stellar-core") + captiveConfig, err := config.GenerateCaptiveCoreConfig(coreBinFromPath) if err != nil { return nil, err } diff --git a/exp/services/ledgerexporter/internal/app_test.go b/exp/services/ledgerexporter/internal/app_test.go index 2063fd21a2..bb715baa6f 100644 --- a/exp/services/ledgerexporter/internal/app_test.go +++ b/exp/services/ledgerexporter/internal/app_test.go @@ -12,7 +12,7 @@ import ( func TestApplyResumeHasStartError(t *testing.T) { ctx := context.Background() app := &App{} - app.config = &Config{StartLedger: 10, EndLedger: 19, Resume: true} + app.config = &Config{StartLedger: 10, EndLedger: 19, Mode: Append} mockResumableManager := &datastore.MockResumableManager{} mockResumableManager.On("FindStart", ctx, uint32(10), uint32(19)).Return(uint32(0), false, errors.New("start error")).Once() @@ -24,7 +24,7 @@ func TestApplyResumeHasStartError(t *testing.T) { func TestApplyResumeDatastoreComplete(t *testing.T) { ctx := context.Background() app := &App{} - app.config = &Config{StartLedger: 10, EndLedger: 19, Resume: true} + app.config = &Config{StartLedger: 10, EndLedger: 19, Mode: Append} mockResumableManager := &datastore.MockResumableManager{} mockResumableManager.On("FindStart", ctx, uint32(10), uint32(19)).Return(uint32(0), false, nil).Once() @@ -38,10 +38,10 @@ func TestApplyResumeInvalidDataStoreLedgersPerFileBoundary(t *testing.T) { ctx := context.Background() app := &App{} app.config = &Config{ - StartLedger: 3, - EndLedger: 9, - Resume: true, - LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 10, FilesPerPartition: 50}, + StartLedger: 3, + EndLedger: 9, + Mode: Append, + DataStoreConfig: datastore.DataStoreConfig{Schema: datastore.DataStoreSchema{LedgersPerFile: 10, FilesPerPartition: 50}}, } mockResumableManager := &datastore.MockResumableManager{} // simulate the datastore has inconsistent data, @@ -58,10 +58,10 @@ func TestApplyResumeWithPartialRemoteDataPresent(t *testing.T) { ctx := context.Background() app := &App{} app.config = &Config{ - StartLedger: 10, - EndLedger: 99, - Resume: true, - LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 10, FilesPerPartition: 50}, + StartLedger: 10, + EndLedger: 99, + Mode: Append, + DataStoreConfig: datastore.DataStoreConfig{Schema: datastore.DataStoreSchema{LedgersPerFile: 10, FilesPerPartition: 50}}, } mockResumableManager := &datastore.MockResumableManager{} // simulates a data store that had ledger files populated up to seq=49, so the first absent ledger would be 50 @@ -77,10 +77,10 @@ func TestApplyResumeWithNoRemoteDataPresent(t *testing.T) { ctx := context.Background() app := &App{} app.config = &Config{ - StartLedger: 10, - EndLedger: 99, - Resume: true, - LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 10, FilesPerPartition: 50}, + StartLedger: 10, + EndLedger: 99, + Mode: Append, + DataStoreConfig: datastore.DataStoreConfig{Schema: datastore.DataStoreSchema{LedgersPerFile: 10, FilesPerPartition: 50}}, } mockResumableManager := &datastore.MockResumableManager{} // simulates a data store that had no data in the requested range @@ -99,10 +99,10 @@ func TestApplyResumeWithNoRemoteDataAndRequestFromGenesis(t *testing.T) { ctx := context.Background() app := &App{} app.config = &Config{ - StartLedger: 2, - EndLedger: 99, - Resume: true, - LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 10, FilesPerPartition: 50}, + StartLedger: 2, + EndLedger: 99, + Mode: Append, + DataStoreConfig: datastore.DataStoreConfig{Schema: datastore.DataStoreSchema{LedgersPerFile: 10, FilesPerPartition: 50}}, } mockResumableManager := &datastore.MockResumableManager{} // simulates a data store that had no data in the requested range diff --git a/exp/services/ledgerexporter/internal/config.go b/exp/services/ledgerexporter/internal/config.go index ef062867f4..ff0ffbe2bf 100644 --- a/exp/services/ledgerexporter/internal/config.go +++ b/exp/services/ledgerexporter/internal/config.go @@ -4,6 +4,7 @@ import ( "context" _ "embed" "fmt" + "os" "os/exec" "strings" @@ -16,20 +17,42 @@ import ( "github.com/stellar/go/support/datastore" "github.com/stellar/go/support/errors" "github.com/stellar/go/support/ordered" + "github.com/stellar/go/support/storage" ) -const Pubnet = "pubnet" -const Testnet = "testnet" +const ( + Pubnet = "pubnet" + Testnet = "testnet" + UserAgent = "ledgerexporter" +) + +type Mode int + +const ( + _ Mode = iota + ScanFill Mode = iota + Append +) + +func (mode Mode) Name() string { + switch mode { + case ScanFill: + return "Scan and Fill" + case Append: + return "Append" + } + return "none" +} -type Flags struct { +type RuntimeSettings struct { StartLedger uint32 EndLedger uint32 ConfigFilePath string - Resume bool - AdminPort uint + Mode Mode } type StellarCoreConfig struct { + Network string `toml:"network"` NetworkPassphrase string `toml:"network_passphrase"` HistoryArchiveUrls []string `toml:"history_archive_urls"` StellarCoreBinaryPath string `toml:"stellar_core_binary_path"` @@ -39,115 +62,126 @@ type StellarCoreConfig struct { type Config struct { AdminPort int `toml:"admin_port"` - Network string `toml:"network"` - DataStoreConfig datastore.DataStoreConfig `toml:"datastore_config"` - LedgerBatchConfig datastore.LedgerBatchConfig `toml:"exporter_config"` - StellarCoreConfig StellarCoreConfig `toml:"stellar_core_config"` + DataStoreConfig datastore.DataStoreConfig `toml:"datastore_config"` + StellarCoreConfig StellarCoreConfig `toml:"stellar_core_config"` + UserAgent string `toml:"user_agent"` StartLedger uint32 EndLedger uint32 - Resume bool + Mode Mode - CoreVersion string + CoreVersion string + SerializedCaptiveCoreToml []byte } -// This will generate the config based on commandline flags and toml +// This will generate the config based on settings // -// flags - command line flags +// settings - requested settings // // return - *Config or an error if any range validation failed. -func NewConfig(flags Flags) (*Config, error) { +func NewConfig(settings RuntimeSettings) (*Config, error) { config := &Config{} - config.StartLedger = uint32(flags.StartLedger) - config.EndLedger = uint32(flags.EndLedger) - config.Resume = flags.Resume + config.StartLedger = uint32(settings.StartLedger) + config.EndLedger = uint32(settings.EndLedger) + config.Mode = settings.Mode - logger.Infof("Requested ledger range start=%d, end=%d, resume=%v", config.StartLedger, config.EndLedger, config.Resume) + logger.Infof("Requested export mode of %v with start=%d, end=%d", settings.Mode.Name(), config.StartLedger, config.EndLedger) var err error - if err = config.processToml(flags.ConfigFilePath); err != nil { + if err = config.processToml(settings.ConfigFilePath); err != nil { return nil, err } - logger.Infof("Config: %v", *config) + logger.Infof("Network Config Archive URLs: %v", config.StellarCoreConfig.HistoryArchiveUrls) + logger.Infof("Network Config Archive Passphrase: %v", config.StellarCoreConfig.NetworkPassphrase) + logger.Infof("Network Config Archive Stellar Core Binary Path: %v", config.StellarCoreConfig.StellarCoreBinaryPath) + logger.Infof("Network Config Archive Stellar Core Toml Config: %v", string(config.SerializedCaptiveCoreToml)) return config, nil } +func (config *Config) Resumable() bool { + return config.Mode == Append +} + // Validates requested ledger range, and will automatically adjust it // to be ledgers-per-file boundary aligned func (config *Config) ValidateAndSetLedgerRange(ctx context.Context, archive historyarchive.ArchiveInterface) error { + + if config.StartLedger < 2 { + return errors.New("invalid start value, must be greater than one.") + } + + if config.Mode == ScanFill && config.EndLedger == 0 { + return errors.New("invalid end value, unbounded mode not supported, end must be greater than start.") + } + + if config.EndLedger != 0 && config.EndLedger <= config.StartLedger { + return errors.New("invalid end value, must be greater than start") + } + latestNetworkLedger, err := datastore.GetLatestLedgerSequenceFromHistoryArchives(archive) + latestNetworkLedger = latestNetworkLedger + (datastore.GetHistoryArchivesCheckPointFrequency() * 2) if err != nil { return errors.Wrap(err, "Failed to retrieve the latest ledger sequence from history archives.") } - logger.Infof("Latest %v ledger sequence was detected as %d", config.Network, latestNetworkLedger) + logger.Infof("Latest ledger sequence was detected as %d", latestNetworkLedger) if config.StartLedger > latestNetworkLedger { - return errors.Errorf("--start %d exceeds latest network ledger %d", + return errors.Errorf("start %d exceeds latest network ledger %d", config.StartLedger, latestNetworkLedger) } - if config.EndLedger != 0 { // Bounded mode - if config.EndLedger < config.StartLedger { - return errors.New("invalid --end value, must be >= --start") - } - if config.EndLedger > latestNetworkLedger { - return errors.Errorf("--end %d exceeds latest network ledger %d", - config.EndLedger, latestNetworkLedger) - } + if config.EndLedger > latestNetworkLedger { + return errors.Errorf("end %d exceeds latest network ledger %d", + config.EndLedger, latestNetworkLedger) } config.adjustLedgerRange() return nil } -func (config *Config) generateCaptiveCoreConfig() (ledgerbackend.CaptiveCoreConfig, error) { - coreConfig := &config.StellarCoreConfig +func (config *Config) GenerateHistoryArchive(ctx context.Context) (historyarchive.ArchiveInterface, error) { + return historyarchive.NewArchivePool(config.StellarCoreConfig.HistoryArchiveUrls, historyarchive.ArchiveOptions{ + ConnectOptions: storage.ConnectOptions{ + UserAgent: config.UserAgent, + Context: ctx, + }, + }) +} - // Look for stellar-core binary in $PATH, if not supplied - if config.StellarCoreConfig.StellarCoreBinaryPath == "" { - var err error - if config.StellarCoreConfig.StellarCoreBinaryPath, err = exec.LookPath("stellar-core"); err != nil { - return ledgerbackend.CaptiveCoreConfig{}, errors.Wrap(err, "Failed to find stellar-core binary") - } - } +// coreBinDefaultPath - a default value to use for core binary path on system. +// +// this will be used if StellarCoreConfig.StellarCoreBinaryPath is not specified +func (config *Config) GenerateCaptiveCoreConfig(coreBinFromPath string) (ledgerbackend.CaptiveCoreConfig, error) { + var err error - if err := config.setCoreVersionInfo(); err != nil { - return ledgerbackend.CaptiveCoreConfig{}, fmt.Errorf("failed to set stellar-core version info: %w", err) + if config.StellarCoreConfig.StellarCoreBinaryPath == "" && coreBinFromPath == "" { + return ledgerbackend.CaptiveCoreConfig{}, errors.New("Invalid captive core config, no stellar-core binary path was provided.") } - var captiveCoreConfig []byte - // Default network config - switch config.Network { - case Pubnet: - coreConfig.NetworkPassphrase = network.PublicNetworkPassphrase - coreConfig.HistoryArchiveUrls = network.PublicNetworkhistoryArchiveURLs - captiveCoreConfig = ledgerbackend.PubnetDefaultConfig - - case Testnet: - coreConfig.NetworkPassphrase = network.TestNetworkPassphrase - coreConfig.HistoryArchiveUrls = network.TestNetworkhistoryArchiveURLs - captiveCoreConfig = ledgerbackend.TestnetDefaultConfig + if config.StellarCoreConfig.StellarCoreBinaryPath == "" { + config.StellarCoreConfig.StellarCoreBinaryPath = coreBinFromPath + } - default: - logger.Fatalf("Invalid network %s", config.Network) + if err = config.setCoreVersionInfo(); err != nil { + return ledgerbackend.CaptiveCoreConfig{}, fmt.Errorf("failed to set stellar-core version info: %w", err) } params := ledgerbackend.CaptiveCoreTomlParams{ - NetworkPassphrase: coreConfig.NetworkPassphrase, - HistoryArchiveURLs: coreConfig.HistoryArchiveUrls, + NetworkPassphrase: config.StellarCoreConfig.NetworkPassphrase, + HistoryArchiveURLs: config.StellarCoreConfig.HistoryArchiveUrls, UseDB: true, } - captiveCoreToml, err := ledgerbackend.NewCaptiveCoreTomlFromData(captiveCoreConfig, params) + captiveCoreToml, err := ledgerbackend.NewCaptiveCoreTomlFromData(config.SerializedCaptiveCoreToml, params) if err != nil { return ledgerbackend.CaptiveCoreConfig{}, errors.Wrap(err, "Failed to create captive-core toml") } return ledgerbackend.CaptiveCoreConfig{ - BinaryPath: coreConfig.StellarCoreBinaryPath, + BinaryPath: config.StellarCoreConfig.StellarCoreBinaryPath, NetworkPassphrase: params.NetworkPassphrase, HistoryArchiveURLs: params.HistoryArchiveURLs, CheckpointFrequency: datastore.GetHistoryArchivesCheckPointFrequency(), @@ -186,34 +220,75 @@ func (config *Config) processToml(tomlPath string) error { // Load config TOML file cfg, err := toml.LoadFile(tomlPath) if err != nil { - return err + return errors.Wrapf(err, "config file %v was not found", tomlPath) } // Unmarshal TOML data into the Config struct - if err := cfg.Unmarshal(config); err != nil { + if err = cfg.Unmarshal(config); err != nil { return errors.Wrap(err, "Error unmarshalling TOML config.") } - // validate TOML data - if config.Network == "" { - return errors.New("Invalid TOML config, 'network' must be set, supported values are 'testnet' or 'pubnet'") + if config.UserAgent == "" { + config.UserAgent = UserAgent } + + if config.StellarCoreConfig.Network == "" && (len(config.StellarCoreConfig.HistoryArchiveUrls) == 0 || config.StellarCoreConfig.NetworkPassphrase == "" || config.StellarCoreConfig.CaptiveCoreTomlPath == "") { + return errors.New("Invalid captive core config, the 'network' parameter must be set to pubnet or testnet or " + + "'stellar_core_config.history_archive_urls' and 'stellar_core_config.network_passphrase' and 'stellar_core_config.captive_core_toml_path' must be set.") + } + + // network config values are an overlay, with network preconfigured values being first if network is present + // and then toml settings specific for passphrase, archiveurls, core toml file can override lastly. + var networkPassPhrase string + var networkArchiveUrls []string + switch config.StellarCoreConfig.Network { + case "": + + case Pubnet: + networkPassPhrase = network.PublicNetworkPassphrase + networkArchiveUrls = network.PublicNetworkhistoryArchiveURLs + config.SerializedCaptiveCoreToml = ledgerbackend.PubnetDefaultConfig + + case Testnet: + networkPassPhrase = network.TestNetworkPassphrase + networkArchiveUrls = network.TestNetworkhistoryArchiveURLs + config.SerializedCaptiveCoreToml = ledgerbackend.TestnetDefaultConfig + + default: + return errors.New("invalid captive core config, " + + "preconfigured_network must be set to 'pubnet' or 'testnet' or network_passphrase, history_archive_urls," + + " and captive_core_toml_path must be set") + } + + if config.StellarCoreConfig.NetworkPassphrase == "" { + config.StellarCoreConfig.NetworkPassphrase = networkPassPhrase + } + + if len(config.StellarCoreConfig.HistoryArchiveUrls) < 1 { + config.StellarCoreConfig.HistoryArchiveUrls = networkArchiveUrls + } + + if config.StellarCoreConfig.CaptiveCoreTomlPath != "" { + if config.SerializedCaptiveCoreToml, err = os.ReadFile(config.StellarCoreConfig.CaptiveCoreTomlPath); err != nil { + return errors.Wrap(err, "Failed to load captive-core-toml-path file") + } + } + return nil } func (config *Config) adjustLedgerRange() { - // Check if either the start or end ledger does not fall on the "LedgersPerFile" boundary // and adjust the start and end ledger accordingly. // Align the start ledger to the nearest "LedgersPerFile" boundary. - config.StartLedger = config.LedgerBatchConfig.GetSequenceNumberStartBoundary(config.StartLedger) + config.StartLedger = config.DataStoreConfig.Schema.GetSequenceNumberStartBoundary(config.StartLedger) // Ensure that the adjusted start ledger is at least 2. config.StartLedger = ordered.Max(2, config.StartLedger) // Align the end ledger (for bounded cases) to the nearest "LedgersPerFile" boundary. if config.EndLedger != 0 { - config.EndLedger = config.LedgerBatchConfig.GetSequenceNumberEndBoundary(config.EndLedger) + config.EndLedger = config.DataStoreConfig.Schema.GetSequenceNumberEndBoundary(config.EndLedger) } logger.Infof("Computed effective export boundary ledger range: start=%d, end=%d", config.StartLedger, config.EndLedger) diff --git a/exp/services/ledgerexporter/internal/config_test.go b/exp/services/ledgerexporter/internal/config_test.go index a4ce76cfe5..37dc574012 100644 --- a/exp/services/ledgerexporter/internal/config_test.go +++ b/exp/services/ledgerexporter/internal/config_test.go @@ -7,118 +7,304 @@ import ( "os/exec" "testing" + "github.com/stellar/go/network" + "github.com/stellar/go/support/datastore" + "github.com/stretchr/testify/require" "github.com/stellar/go/historyarchive" "github.com/stellar/go/support/errors" ) -func TestNewConfigResumeEnabled(t *testing.T) { +func TestNewConfig(t *testing.T) { ctx := context.Background() mockArchive := &historyarchive.MockArchive{} mockArchive.On("GetRootHAS").Return(historyarchive.HistoryArchiveState{CurrentLedger: 5}, nil).Once() - config, err := NewConfig(Flags{StartLedger: 1, EndLedger: 2, ConfigFilePath: "test/test.toml", Resume: true}) - config.ValidateAndSetLedgerRange(ctx, mockArchive) + config, err := NewConfig( + RuntimeSettings{StartLedger: 2, EndLedger: 3, ConfigFilePath: "test/test.toml", Mode: Append}) + + require.NoError(t, err) + err = config.ValidateAndSetLedgerRange(ctx, mockArchive) require.NoError(t, err) + require.Equal(t, config.StellarCoreConfig.Network, "pubnet") require.Equal(t, config.DataStoreConfig.Type, "ABC") - require.Equal(t, config.LedgerBatchConfig.FilesPerPartition, uint32(1)) - require.Equal(t, config.LedgerBatchConfig.LedgersPerFile, uint32(3)) - require.True(t, config.Resume) + require.Equal(t, config.DataStoreConfig.Schema.FilesPerPartition, uint32(1)) + require.Equal(t, config.DataStoreConfig.Schema.LedgersPerFile, uint32(3)) + require.Equal(t, config.UserAgent, "ledgerexporter") + require.True(t, config.Resumable()) url, ok := config.DataStoreConfig.Params["destination_bucket_path"] require.True(t, ok) - require.Equal(t, url, "your-bucket-name/subpath") + require.Equal(t, url, "your-bucket-name/subpath/testnet") + mockArchive.AssertExpectations(t) } -func TestNewConfigResumeDisabled(t *testing.T) { +func TestGenerateHistoryArchiveFromPreconfiguredNetwork(t *testing.T) { + ctx := context.Background() + config, err := NewConfig( + RuntimeSettings{StartLedger: 2, EndLedger: 3, ConfigFilePath: "test/valid_captive_core_preconfigured.toml", Mode: Append}) + require.NoError(t, err) - mockArchive := &historyarchive.MockArchive{} - mockArchive.On("GetRootHAS").Return(historyarchive.HistoryArchiveState{CurrentLedger: 5}, nil).Once() + _, err = config.GenerateHistoryArchive(ctx) + require.NoError(t, err) +} + +func TestGenerateHistoryArchiveFromManulConfiguredNetwork(t *testing.T) { + ctx := context.Background() + config, err := NewConfig( + RuntimeSettings{StartLedger: 2, EndLedger: 3, ConfigFilePath: "test/valid_captive_core_manual.toml", Mode: Append}) + require.NoError(t, err) + + _, err = config.GenerateHistoryArchive(ctx) + require.NoError(t, err) +} + +func TestNewConfigUserAgent(t *testing.T) { + config, err := NewConfig( + RuntimeSettings{StartLedger: 2, EndLedger: 3, ConfigFilePath: "test/useragent.toml"}) + require.NoError(t, err) + require.Equal(t, config.UserAgent, "useragent_x") +} + +func TestResumeDisabled(t *testing.T) { + // resumable is only enabled when mode is Append + config, err := NewConfig( + RuntimeSettings{StartLedger: 2, EndLedger: 3, ConfigFilePath: "test/test.toml", Mode: ScanFill}) + require.NoError(t, err) + require.False(t, config.Resumable()) +} + +func TestInvalidConfigFilePath(t *testing.T) { + _, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/notfound.toml"}) + require.ErrorContains(t, err, "config file test/notfound.toml was not found") +} + +func TestNoCaptiveCoreBin(t *testing.T) { + cfg, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/no_core_bin.toml"}) + require.NoError(t, err) + + _, err = cfg.GenerateCaptiveCoreConfig("") + require.ErrorContains(t, err, "Invalid captive core config, no stellar-core binary path was provided.") +} + +func TestDefaultCaptiveCoreBin(t *testing.T) { + cfg, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/no_core_bin.toml"}) + require.NoError(t, err) + + cmdOut = "v20.2.0-2-g6e73c0a88\n" + ccConfig, err := cfg.GenerateCaptiveCoreConfig("/test/default/stellar-core") + require.NoError(t, err) + require.Equal(t, ccConfig.BinaryPath, "/test/default/stellar-core") +} + +func TestInvalidCaptiveCorePreconfiguredNetwork(t *testing.T) { + _, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/invalid_preconfigured_network.toml"}) + + require.ErrorContains(t, err, "invalid captive core config") +} + +func TestValidCaptiveCorePreconfiguredNetwork(t *testing.T) { + cfg, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/valid_captive_core_preconfigured.toml"}) + require.NoError(t, err) + + require.Equal(t, cfg.StellarCoreConfig.NetworkPassphrase, network.PublicNetworkPassphrase) + require.Equal(t, cfg.StellarCoreConfig.HistoryArchiveUrls, network.PublicNetworkhistoryArchiveURLs) + + cmdOut = "v20.2.0-2-g6e73c0a88\n" + ccConfig, err := cfg.GenerateCaptiveCoreConfig("") + require.NoError(t, err) + + // validates that ingest/ledgerbackend/configs/captive-core-pubnet.cfg was loaded + require.Equal(t, ccConfig.BinaryPath, "test/stellar-core") + require.Equal(t, ccConfig.NetworkPassphrase, network.PublicNetworkPassphrase) + require.Equal(t, ccConfig.HistoryArchiveURLs, network.PublicNetworkhistoryArchiveURLs) + require.Empty(t, ccConfig.Toml.HistoryEntries) + require.Len(t, ccConfig.Toml.Validators, 23) + require.Equal(t, ccConfig.Toml.Validators[0].Name, "Boötes") +} - // resume disabled by default - config, err := NewConfig(Flags{StartLedger: 1, EndLedger: 2, ConfigFilePath: "test/test.toml"}) +func TestValidCaptiveCoreManualNetwork(t *testing.T) { + cfg, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/valid_captive_core_manual.toml"}) require.NoError(t, err) - require.False(t, config.Resume) + require.Equal(t, cfg.CoreVersion, "") + require.Equal(t, cfg.StellarCoreConfig.NetworkPassphrase, "test") + require.Equal(t, cfg.StellarCoreConfig.HistoryArchiveUrls, []string{"http://testarchive"}) + + cmdOut = "v20.2.0-2-g6e73c0a88\n" + ccConfig, err := cfg.GenerateCaptiveCoreConfig("") + require.NoError(t, err) + + require.Equal(t, ccConfig.BinaryPath, "test/stellar-core") + require.Equal(t, ccConfig.NetworkPassphrase, "test") + require.Equal(t, ccConfig.HistoryArchiveURLs, []string{"http://testarchive"}) + require.Empty(t, ccConfig.Toml.HistoryEntries) + require.Len(t, ccConfig.Toml.Validators, 1) + require.Equal(t, ccConfig.Toml.Validators[0].Name, "local_core") + require.Equal(t, cfg.CoreVersion, "v20.2.0-2-g6e73c0a88") } -func TestInvalidTomlConfig(t *testing.T) { +func TestValidCaptiveCoreOverridenToml(t *testing.T) { + cfg, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/valid_captive_core_override.toml"}) + require.NoError(t, err) + require.Equal(t, cfg.StellarCoreConfig.NetworkPassphrase, network.PublicNetworkPassphrase) + require.Equal(t, cfg.StellarCoreConfig.HistoryArchiveUrls, network.PublicNetworkhistoryArchiveURLs) + + cmdOut = "v20.2.0-2-g6e73c0a88\n" + ccConfig, err := cfg.GenerateCaptiveCoreConfig("") + require.NoError(t, err) - _, err := NewConfig(Flags{StartLedger: 1, EndLedger: 2, ConfigFilePath: "test/no_network.toml", Resume: true}) - require.ErrorContains(t, err, "Invalid TOML config") + // the external core cfg file should have applied over the preconf'd network config + require.Equal(t, ccConfig.BinaryPath, "test/stellar-core") + require.Equal(t, ccConfig.NetworkPassphrase, network.PublicNetworkPassphrase) + require.Equal(t, ccConfig.HistoryArchiveURLs, network.PublicNetworkhistoryArchiveURLs) + require.Empty(t, ccConfig.Toml.HistoryEntries) + require.Len(t, ccConfig.Toml.Validators, 1) + require.Equal(t, ccConfig.Toml.Validators[0].Name, "local_core") + require.Equal(t, cfg.CoreVersion, "v20.2.0-2-g6e73c0a88") +} + +func TestValidCaptiveCoreOverridenArchiveUrls(t *testing.T) { + cfg, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/valid_captive_core_override_archives.toml"}) + require.NoError(t, err) + + require.Equal(t, cfg.StellarCoreConfig.NetworkPassphrase, network.PublicNetworkPassphrase) + require.Equal(t, cfg.StellarCoreConfig.HistoryArchiveUrls, []string{"http://testarchive"}) + + cmdOut = "v20.2.0-2-g6e73c0a88\n" + ccConfig, err := cfg.GenerateCaptiveCoreConfig("") + require.NoError(t, err) + + // validates that ingest/ledgerbackend/configs/captive-core-pubnet.cfg was loaded + require.Equal(t, ccConfig.BinaryPath, "test/stellar-core") + require.Equal(t, ccConfig.NetworkPassphrase, network.PublicNetworkPassphrase) + require.Equal(t, ccConfig.HistoryArchiveURLs, []string{"http://testarchive"}) + require.Empty(t, ccConfig.Toml.HistoryEntries) + require.Len(t, ccConfig.Toml.Validators, 23) + require.Equal(t, ccConfig.Toml.Validators[0].Name, "Boötes") +} + +func TestInvalidCaptiveCoreTomlPath(t *testing.T) { + _, err := NewConfig( + RuntimeSettings{ConfigFilePath: "test/invalid_captive_core_toml_path.toml"}) + require.ErrorContains(t, err, "Failed to load captive-core-toml-path file") } func TestValidateStartAndEndLedger(t *testing.T) { - const latestNetworkLedger = uint32(20000) + latestNetworkLedger := uint32(20000) + latestNetworkLedgerPadding := datastore.GetHistoryArchivesCheckPointFrequency() * 2 tests := []struct { name string startLedger uint32 endLedger uint32 errMsg string + mode Mode + mockHas bool }{ { name: "End ledger same as latest ledger", startLedger: 512, endLedger: 512, - errMsg: "", + mode: ScanFill, + errMsg: "invalid end value, must be greater than start", + mockHas: false, }, { name: "End ledger greater than start ledger", startLedger: 512, endLedger: 600, + mode: ScanFill, errMsg: "", + mockHas: true, }, { - name: "No end ledger provided, unbounded mode", + name: "No end ledger provided, append mode, no error", startLedger: 512, endLedger: 0, + mode: Append, errMsg: "", + mockHas: true, + }, + { + name: "No end ledger provided, scan-and-fill error", + startLedger: 512, + endLedger: 0, + mode: ScanFill, + errMsg: "invalid end value, unbounded mode not supported, end must be greater than start.", }, { name: "End ledger before start ledger", startLedger: 512, endLedger: 2, - errMsg: "invalid --end value, must be >= --start", + mode: ScanFill, + errMsg: "invalid end value, must be greater than start", }, { name: "End ledger exceeds latest ledger", startLedger: 512, - endLedger: latestNetworkLedger + 1, - errMsg: fmt.Sprintf("--end %d exceeds latest network ledger %d", - latestNetworkLedger+1, latestNetworkLedger), + endLedger: latestNetworkLedger + latestNetworkLedgerPadding + 1, + mode: ScanFill, + mockHas: true, + errMsg: fmt.Sprintf("end %d exceeds latest network ledger %d", + latestNetworkLedger+latestNetworkLedgerPadding+1, latestNetworkLedger+latestNetworkLedgerPadding), }, { name: "Start ledger 0", startLedger: 0, endLedger: 2, - errMsg: "", + mode: ScanFill, + errMsg: "invalid start value, must be greater than one.", + }, + { + name: "Start ledger 1", + startLedger: 1, + endLedger: 2, + mode: ScanFill, + errMsg: "invalid start value, must be greater than one.", }, { name: "Start ledger exceeds latest ledger", - startLedger: latestNetworkLedger + 1, - endLedger: 0, - errMsg: fmt.Sprintf("--start %d exceeds latest network ledger %d", - latestNetworkLedger+1, latestNetworkLedger), + startLedger: latestNetworkLedger + latestNetworkLedgerPadding + 1, + endLedger: latestNetworkLedger + latestNetworkLedgerPadding + 2, + mode: ScanFill, + mockHas: true, + errMsg: fmt.Sprintf("start %d exceeds latest network ledger %d", + latestNetworkLedger+latestNetworkLedgerPadding+1, latestNetworkLedger+latestNetworkLedgerPadding), }, } ctx := context.Background() mockArchive := &historyarchive.MockArchive{} - mockArchive.On("GetRootHAS").Return(historyarchive.HistoryArchiveState{CurrentLedger: latestNetworkLedger}, nil).Times(len(tests)) + mockArchive.On("GetRootHAS").Return(historyarchive.HistoryArchiveState{CurrentLedger: latestNetworkLedger}, nil) + mockedHasCtr := 0 for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - config, err := NewConfig(Flags{StartLedger: tt.startLedger, EndLedger: tt.endLedger, ConfigFilePath: "test/validate_start_end.toml"}) + if tt.mockHas { + mockedHasCtr++ + } + config, err := NewConfig( + RuntimeSettings{StartLedger: tt.startLedger, EndLedger: tt.endLedger, ConfigFilePath: "test/validate_start_end.toml", Mode: tt.mode}) require.NoError(t, err) err = config.ValidateAndSetLedgerRange(ctx, mockArchive) if tt.errMsg != "" { + require.Error(t, err) require.Equal(t, tt.errMsg, err.Error()) } else { require.NoError(t, err) } }) } + mockArchive.AssertNumberOfCalls(t, "GetRootHAS", mockedHasCtr) } func TestAdjustedLedgerRangeBoundedMode(t *testing.T) { @@ -130,27 +316,19 @@ func TestAdjustedLedgerRangeBoundedMode(t *testing.T) { expectedStart uint32 expectedEnd uint32 }{ - { - name: "Min start ledger 2", - configFile: "test/1perfile.toml", - start: 0, - end: 10, - expectedStart: 2, - expectedEnd: 10, - }, { name: "No change, 1 ledger per file", configFile: "test/1perfile.toml", start: 2, - end: 2, + end: 3, expectedStart: 2, - expectedEnd: 2, + expectedEnd: 3, }, { name: "Min start ledger2, round up end ledger, 10 ledgers per file", configFile: "test/10perfile.toml", - start: 0, - end: 1, + start: 2, + end: 3, expectedStart: 2, expectedEnd: 9, }, @@ -186,7 +364,9 @@ func TestAdjustedLedgerRangeBoundedMode(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - config, err := NewConfig(Flags{StartLedger: tt.start, EndLedger: tt.end, ConfigFilePath: tt.configFile}) + config, err := NewConfig( + RuntimeSettings{StartLedger: tt.start, EndLedger: tt.end, ConfigFilePath: tt.configFile, Mode: ScanFill}) + require.NoError(t, err) err = config.ValidateAndSetLedgerRange(ctx, mockArchive) require.NoError(t, err) @@ -194,6 +374,7 @@ func TestAdjustedLedgerRangeBoundedMode(t *testing.T) { require.EqualValues(t, tt.expectedEnd, config.EndLedger) }) } + mockArchive.AssertExpectations(t) } func TestAdjustedLedgerRangeUnBoundedMode(t *testing.T) { @@ -205,14 +386,6 @@ func TestAdjustedLedgerRangeUnBoundedMode(t *testing.T) { expectedStart uint32 expectedEnd uint32 }{ - { - name: "Min start ledger 2", - configFile: "test/1perfile.toml", - start: 0, - end: 0, - expectedStart: 2, - expectedEnd: 0, - }, { name: "No change, 1 ledger per file", configFile: "test/1perfile.toml", @@ -254,7 +427,8 @@ func TestAdjustedLedgerRangeUnBoundedMode(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - config, err := NewConfig(Flags{StartLedger: tt.start, EndLedger: tt.end, ConfigFilePath: tt.configFile}) + config, err := NewConfig( + RuntimeSettings{StartLedger: tt.start, EndLedger: tt.end, ConfigFilePath: tt.configFile, Mode: Append}) require.NoError(t, err) err = config.ValidateAndSetLedgerRange(ctx, mockArchive) require.NoError(t, err) @@ -262,6 +436,7 @@ func TestAdjustedLedgerRangeUnBoundedMode(t *testing.T) { require.EqualValues(t, tt.expectedEnd, config.EndLedger) }) } + mockArchive.AssertExpectations(t) } var cmdOut = "" @@ -273,15 +448,20 @@ func fakeExecCommand(command string, args ...string) *exec.Cmd { return cmd } +func init() { + execCommand = fakeExecCommand +} + func TestExecCmdHelperProcess(t *testing.T) { if os.Getenv("GO_EXEC_CMD_HELPER_PROCESS") != "1" { return } - fmt.Fprintf(os.Stdout, os.Getenv("CMD_OUT")) + fmt.Fprint(os.Stdout, os.Getenv("CMD_OUT")) os.Exit(0) } func TestSetCoreVersionInfo(t *testing.T) { + execCommand = fakeExecCommand tests := []struct { name string commandOutput string @@ -315,9 +495,7 @@ func TestSetCoreVersionInfo(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { config := Config{} - cmdOut = tt.commandOutput - execCommand = fakeExecCommand err := config.setCoreVersionInfo() if tt.expectedError != nil { diff --git a/exp/services/ledgerexporter/internal/exportmanager.go b/exp/services/ledgerexporter/internal/exportmanager.go index ae85c072d6..af2633d6be 100644 --- a/exp/services/ledgerexporter/internal/exportmanager.go +++ b/exp/services/ledgerexporter/internal/exportmanager.go @@ -8,21 +8,29 @@ import ( "github.com/prometheus/client_golang/prometheus" "github.com/stellar/go/ingest/ledgerbackend" + "github.com/stellar/go/support/datastore" "github.com/stellar/go/xdr" ) type ExportManager struct { - config *Config + dataStoreSchema datastore.DataStoreSchema ledgerBackend ledgerbackend.LedgerBackend currentMetaArchive *xdr.LedgerCloseMetaBatch queue UploadQueue latestLedgerMetric *prometheus.GaugeVec + networkPassPhrase string + coreVersion string } // NewExportManager creates a new ExportManager with the provided configuration. -func NewExportManager(config *Config, backend ledgerbackend.LedgerBackend, queue UploadQueue, prometheusRegistry *prometheus.Registry) (*ExportManager, error) { - if config.LedgerBatchConfig.LedgersPerFile < 1 { - return nil, errors.Errorf("Invalid ledgers per file (%d): must be at least 1", config.LedgerBatchConfig.LedgersPerFile) +func NewExportManager(dataStoreSchema datastore.DataStoreSchema, + backend ledgerbackend.LedgerBackend, + queue UploadQueue, + prometheusRegistry *prometheus.Registry, + networkPassPhrase string, + coreVersion string) (*ExportManager, error) { + if dataStoreSchema.LedgersPerFile < 1 { + return nil, errors.Errorf("Invalid ledgers per file (%d): must be at least 1", dataStoreSchema.LedgersPerFile) } latestLedgerMetric := prometheus.NewGaugeVec(prometheus.GaugeOpts{ @@ -32,10 +40,12 @@ func NewExportManager(config *Config, backend ledgerbackend.LedgerBackend, queue prometheusRegistry.MustRegister(latestLedgerMetric) return &ExportManager{ - config: config, + dataStoreSchema: dataStoreSchema, ledgerBackend: backend, queue: queue, latestLedgerMetric: latestLedgerMetric, + networkPassPhrase: networkPassPhrase, + coreVersion: coreVersion, }, nil } @@ -44,16 +54,16 @@ func (e *ExportManager) AddLedgerCloseMeta(ctx context.Context, ledgerCloseMeta ledgerSeq := ledgerCloseMeta.LedgerSequence() // Determine the object key for the given ledger sequence - objectKey := e.config.LedgerBatchConfig.GetObjectKeyFromSequenceNumber(ledgerSeq) + objectKey := e.dataStoreSchema.GetObjectKeyFromSequenceNumber(ledgerSeq) if e.currentMetaArchive == nil { - endSeq := ledgerSeq + e.config.LedgerBatchConfig.LedgersPerFile - 1 - if ledgerSeq < e.config.LedgerBatchConfig.LedgersPerFile { + endSeq := ledgerSeq + e.dataStoreSchema.LedgersPerFile - 1 + if ledgerSeq < e.dataStoreSchema.LedgersPerFile { // Special case: Adjust the end ledger sequence for the first batch. // Since the start ledger is 2 instead of 0, we want to ensure that the end ledger sequence // does not exceed LedgersPerFile. // For example, if LedgersPerFile is 64, the file name for the first batch should be 0-63, not 2-66. - endSeq = e.config.LedgerBatchConfig.LedgersPerFile - 1 + endSeq = e.dataStoreSchema.LedgersPerFile - 1 } // Create a new LedgerCloseMetaBatch @@ -65,7 +75,7 @@ func (e *ExportManager) AddLedgerCloseMeta(ctx context.Context, ledgerCloseMeta } if ledgerSeq >= uint32(e.currentMetaArchive.EndSequence) { - ledgerMetaArchive, err := NewLedgerMetaArchiveFromXDR(e.config, objectKey, *e.currentMetaArchive) + ledgerMetaArchive, err := NewLedgerMetaArchiveFromXDR(e.networkPassPhrase, e.coreVersion, objectKey, *e.currentMetaArchive) if err != nil { return err } diff --git a/exp/services/ledgerexporter/internal/exportmanager_test.go b/exp/services/ledgerexporter/internal/exportmanager_test.go index b74af2e19e..7845186c06 100644 --- a/exp/services/ledgerexporter/internal/exportmanager_test.go +++ b/exp/services/ledgerexporter/internal/exportmanager_test.go @@ -8,6 +8,7 @@ import ( "github.com/prometheus/client_golang/prometheus" "github.com/stretchr/testify/mock" + "github.com/stretchr/testify/require" "github.com/stretchr/testify/suite" @@ -58,18 +59,18 @@ func (s *ExportManagerSuite) TearDownTest() { } func (s *ExportManagerSuite) TestInvalidExportConfig() { - config := &Config{LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 0, FilesPerPartition: 10}} + config := datastore.DataStoreSchema{LedgersPerFile: 0, FilesPerPartition: 10} registry := prometheus.NewRegistry() queue := NewUploadQueue(1, registry) - _, err := NewExportManager(config, &s.mockBackend, queue, registry) + _, err := NewExportManager(config, &s.mockBackend, queue, registry, "passphrase", "coreversion") s.Require().Error(err) } func (s *ExportManagerSuite) TestRun() { - config := &Config{LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 64, FilesPerPartition: 10}} + config := datastore.DataStoreSchema{LedgersPerFile: 64, FilesPerPartition: 10} registry := prometheus.NewRegistry() queue := NewUploadQueue(1, registry) - exporter, err := NewExportManager(config, &s.mockBackend, queue, registry) + exporter, err := NewExportManager(config, &s.mockBackend, queue, registry, "passphrase", "coreversion") s.Require().NoError(err) start := uint32(0) @@ -79,7 +80,7 @@ func (s *ExportManagerSuite) TestRun() { for i := start; i <= end; i++ { s.mockBackend.On("GetLedger", s.ctx, i). Return(createLedgerCloseMeta(i), nil) - key := config.LedgerBatchConfig.GetObjectKeyFromSequenceNumber(i) + key := config.GetObjectKeyFromSequenceNumber(i) expectedKeys.Add(key) } @@ -116,10 +117,11 @@ func (s *ExportManagerSuite) TestRun() { } func (s *ExportManagerSuite) TestRunContextCancel() { - config := &Config{LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 1, FilesPerPartition: 1}} + config := datastore.DataStoreSchema{LedgersPerFile: 1, FilesPerPartition: 1} + registry := prometheus.NewRegistry() queue := NewUploadQueue(1, registry) - exporter, err := NewExportManager(config, &s.mockBackend, queue, registry) + exporter, err := NewExportManager(config, &s.mockBackend, queue, registry, "passphrase", "coreversion") s.Require().NoError(err) ctx, cancel := context.WithCancel(context.Background()) @@ -146,10 +148,11 @@ func (s *ExportManagerSuite) TestRunContextCancel() { } func (s *ExportManagerSuite) TestRunWithCanceledContext() { - config := &Config{LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 1, FilesPerPartition: 10}} + config := datastore.DataStoreSchema{LedgersPerFile: 1, FilesPerPartition: 10} + registry := prometheus.NewRegistry() queue := NewUploadQueue(1, registry) - exporter, err := NewExportManager(config, &s.mockBackend, queue, registry) + exporter, err := NewExportManager(config, &s.mockBackend, queue, registry, "passphrase", "coreversion") s.Require().NoError(err) ctx, cancel := context.WithCancel(context.Background()) @@ -165,10 +168,11 @@ func (s *ExportManagerSuite) TestRunWithCanceledContext() { } func (s *ExportManagerSuite) TestAddLedgerCloseMeta() { - config := &Config{LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 1, FilesPerPartition: 10}} + config := datastore.DataStoreSchema{LedgersPerFile: 1, FilesPerPartition: 10} + registry := prometheus.NewRegistry() queue := NewUploadQueue(1, registry) - exporter, err := NewExportManager(config, &s.mockBackend, queue, registry) + exporter, err := NewExportManager(config, &s.mockBackend, queue, registry, "passphrase", "coreversion") s.Require().NoError(err) expectedKeys := set.NewSet[string](10) @@ -193,7 +197,7 @@ func (s *ExportManagerSuite) TestAddLedgerCloseMeta() { for i := start; i <= end; i++ { s.Require().NoError(exporter.AddLedgerCloseMeta(context.Background(), createLedgerCloseMeta(i))) - key := config.LedgerBatchConfig.GetObjectKeyFromSequenceNumber(i) + key := config.GetObjectKeyFromSequenceNumber(i) expectedKeys.Add(key) } @@ -203,10 +207,10 @@ func (s *ExportManagerSuite) TestAddLedgerCloseMeta() { } func (s *ExportManagerSuite) TestAddLedgerCloseMetaContextCancel() { - config := &Config{LedgerBatchConfig: datastore.LedgerBatchConfig{LedgersPerFile: 1, FilesPerPartition: 10}} + config := datastore.DataStoreSchema{LedgersPerFile: 1, FilesPerPartition: 10} registry := prometheus.NewRegistry() queue := NewUploadQueue(1, registry) - exporter, err := NewExportManager(config, &s.mockBackend, queue, registry) + exporter, err := NewExportManager(config, &s.mockBackend, queue, registry, "passphrase", "coreversion") s.Require().NoError(err) ctx, cancel := context.WithCancel(context.Background()) @@ -215,7 +219,7 @@ func (s *ExportManagerSuite) TestAddLedgerCloseMetaContextCancel() { cancel() }() - s.Require().NoError(exporter.AddLedgerCloseMeta(ctx, createLedgerCloseMeta(1))) + require.NoError(s.T(), exporter.AddLedgerCloseMeta(ctx, createLedgerCloseMeta(1))) err = exporter.AddLedgerCloseMeta(ctx, createLedgerCloseMeta(2)) - s.Require().EqualError(err, "context canceled") + require.EqualError(s.T(), err, "context canceled") } diff --git a/exp/services/ledgerexporter/internal/ledger_meta_archive.go b/exp/services/ledgerexporter/internal/ledger_meta_archive.go index 583f6a3ec4..f63a77f28b 100644 --- a/exp/services/ledgerexporter/internal/ledger_meta_archive.go +++ b/exp/services/ledgerexporter/internal/ledger_meta_archive.go @@ -14,7 +14,7 @@ type LedgerMetaArchive struct { } // NewLedgerMetaArchiveFromXDR creates a new LedgerMetaArchive instance. -func NewLedgerMetaArchiveFromXDR(config *Config, key string, data xdr.LedgerCloseMetaBatch) (*LedgerMetaArchive, error) { +func NewLedgerMetaArchiveFromXDR(networkPassPhrase string, coreVersion string, key string, data xdr.LedgerCloseMetaBatch) (*LedgerMetaArchive, error) { startLedger, err := data.GetLedger(uint32(data.StartSequence)) if err != nil { return &LedgerMetaArchive{}, err @@ -33,10 +33,10 @@ func NewLedgerMetaArchiveFromXDR(config *Config, key string, data xdr.LedgerClos EndLedger: endLedger.LedgerSequence(), StartLedgerCloseTime: startLedger.LedgerCloseTime(), EndLedgerCloseTime: endLedger.LedgerCloseTime(), - Network: config.Network, + NetworkPassPhrase: networkPassPhrase, CompressionType: compressxdr.DefaultCompressor.Name(), ProtocolVersion: endLedger.ProtocolVersion(), - CoreVersion: config.CoreVersion, + CoreVersion: coreVersion, Version: version, }, }, nil diff --git a/exp/services/ledgerexporter/internal/ledger_meta_archive_test.go b/exp/services/ledgerexporter/internal/ledger_meta_archive_test.go index 3cf263d71b..152f2c6496 100644 --- a/exp/services/ledgerexporter/internal/ledger_meta_archive_test.go +++ b/exp/services/ledgerexporter/internal/ledger_meta_archive_test.go @@ -10,10 +10,6 @@ import ( ) func TestNewLedgerMetaArchiveFromXDR(t *testing.T) { - config := &Config{ - Network: "testnet", - CoreVersion: "v1.2.3", - } data := xdr.LedgerCloseMetaBatch{ StartSequence: 1234, EndSequence: 1234, @@ -22,7 +18,7 @@ func TestNewLedgerMetaArchiveFromXDR(t *testing.T) { }, } - archive, err := NewLedgerMetaArchiveFromXDR(config, "key", data) + archive, err := NewLedgerMetaArchiveFromXDR("testnet", "v1.2.3", "key", data) require.NoError(t, err) require.NotNil(t, archive) @@ -33,7 +29,7 @@ func TestNewLedgerMetaArchiveFromXDR(t *testing.T) { EndLedger: 1234, StartLedgerCloseTime: 1234 * 100, EndLedgerCloseTime: 1234 * 100, - Network: "testnet", + NetworkPassPhrase: "testnet", CompressionType: "zstd", ProtocolVersion: 21, CoreVersion: "v1.2.3", @@ -53,7 +49,7 @@ func TestNewLedgerMetaArchiveFromXDR(t *testing.T) { }, } - archive, err = NewLedgerMetaArchiveFromXDR(config, "key", data) + archive, err = NewLedgerMetaArchiveFromXDR("testnet", "v1.2.3", "key", data) require.NoError(t, err) require.NotNil(t, archive) @@ -64,7 +60,7 @@ func TestNewLedgerMetaArchiveFromXDR(t *testing.T) { EndLedger: 1237, StartLedgerCloseTime: 1234 * 100, EndLedgerCloseTime: 1237 * 100, - Network: "testnet", + NetworkPassPhrase: "testnet", CompressionType: "zstd", ProtocolVersion: 21, CoreVersion: "v1.2.3", diff --git a/exp/services/ledgerexporter/internal/main.go b/exp/services/ledgerexporter/internal/main.go new file mode 100644 index 0000000000..d1409eb89c --- /dev/null +++ b/exp/services/ledgerexporter/internal/main.go @@ -0,0 +1,94 @@ +package ledgerexporter + +import ( + "fmt" + + "github.com/spf13/cobra" + "github.com/spf13/pflag" + "github.com/spf13/viper" + "github.com/stellar/go/support/strutils" +) + +var ( + ledgerExporterCmdRunner = func(runtimeSettings RuntimeSettings) error { + app := NewApp() + return app.Run(runtimeSettings) + } + rootCmd, scanAndFillCmd, appendCmd *cobra.Command +) + +func Execute() error { + defineCommands() + return rootCmd.Execute() +} + +func defineCommands() { + rootCmd = &cobra.Command{ + Use: "ledgerexporter", + Short: "Export Stellar network ledger data to a remote data store", + Long: "Converts ledger meta data from Stellar network into static data and exports it remote data storage.", + + RunE: func(cmd *cobra.Command, args []string) error { + return fmt.Errorf("please specify one of the availble sub-commands to initiate export") + }, + } + scanAndFillCmd = &cobra.Command{ + Use: "scan-and-fill", + Short: "scans the entire bounded requested range between 'start' and 'end' flags and exports only the ledgers which are missing from the data lake.", + Long: "scans the entire bounded requested range between 'start' and 'end' flags and exports only the ledgers which are missing from the data lake.", + RunE: func(cmd *cobra.Command, args []string) error { + settings := bindCliParameters(cmd.PersistentFlags().Lookup("start"), + cmd.PersistentFlags().Lookup("end"), + cmd.PersistentFlags().Lookup("config-file"), + ) + settings.Mode = ScanFill + return ledgerExporterCmdRunner(settings) + }, + } + appendCmd = &cobra.Command{ + Use: "append", + Short: "export ledgers beginning with the first missing ledger after the specified 'start' ledger and resumes exporting from there", + Long: "export ledgers beginning with the first missing ledger after the specified 'start' ledger and resumes exporting from there", + RunE: func(cmd *cobra.Command, args []string) error { + settings := bindCliParameters(cmd.PersistentFlags().Lookup("start"), + cmd.PersistentFlags().Lookup("end"), + cmd.PersistentFlags().Lookup("config-file"), + ) + settings.Mode = Append + return ledgerExporterCmdRunner(settings) + }, + } + + rootCmd.AddCommand(scanAndFillCmd) + rootCmd.AddCommand(appendCmd) + + scanAndFillCmd.PersistentFlags().Uint32P("start", "s", 0, "Starting ledger (inclusive), must be set to a value greater than 1") + scanAndFillCmd.PersistentFlags().Uint32P("end", "e", 0, "Ending ledger (inclusive), must be set to value greater than 'start' and less than the network's current ledger") + scanAndFillCmd.PersistentFlags().String("config-file", "config.toml", "Path to the TOML config file. Defaults to 'config.toml' on runtime working directory path.") + viper.BindPFlags(scanAndFillCmd.PersistentFlags()) + + appendCmd.PersistentFlags().Uint32P("start", "s", 0, "Starting ledger (inclusive), must be set to a value greater than 1") + appendCmd.PersistentFlags().Uint32P("end", "e", 0, "Ending ledger (inclusive), optional, setting to non-zero means bounded mode, "+ + "only export ledgers from 'start' up to 'end' value which must be greater than 'start' and less than the network's current ledger. "+ + "If 'end' is absent or '0' means unbounded mode, exporter will continue to run indefintely and export the latest closed ledgers from network as they are generated in real time.") + appendCmd.PersistentFlags().String("config-file", "config.toml", "Path to the TOML config file. Defaults to 'config.toml' on runtime working directory path.") + viper.BindPFlags(appendCmd.PersistentFlags()) +} + +func bindCliParameters(startFlag *pflag.Flag, endFlag *pflag.Flag, configFileFlag *pflag.Flag) RuntimeSettings { + settings := RuntimeSettings{} + + viper.BindPFlag(startFlag.Name, startFlag) + viper.BindEnv(startFlag.Name, strutils.KebabToConstantCase(startFlag.Name)) + settings.StartLedger = viper.GetUint32(startFlag.Name) + + viper.BindPFlag(endFlag.Name, endFlag) + viper.BindEnv(endFlag.Name, strutils.KebabToConstantCase(endFlag.Name)) + settings.EndLedger = viper.GetUint32(endFlag.Name) + + viper.BindPFlag(configFileFlag.Name, configFileFlag) + viper.BindEnv(configFileFlag.Name, strutils.KebabToConstantCase(configFileFlag.Name)) + settings.ConfigFilePath = viper.GetString(configFileFlag.Name) + + return settings +} diff --git a/exp/services/ledgerexporter/internal/main_test.go b/exp/services/ledgerexporter/internal/main_test.go new file mode 100644 index 0000000000..4c9e5412f3 --- /dev/null +++ b/exp/services/ledgerexporter/internal/main_test.go @@ -0,0 +1,116 @@ +package ledgerexporter + +import ( + "bytes" + "io" + "testing" + + "github.com/pkg/errors" + "github.com/stretchr/testify/assert" +) + +func TestFlagsOutput(t *testing.T) { + var testResultSettings RuntimeSettings + appRunnerSuccess := func(runtimeSettings RuntimeSettings) error { + testResultSettings = runtimeSettings + return nil + } + + appRunnerError := func(runtimeSettings RuntimeSettings) error { + return errors.New("test error") + } + + testCases := []struct { + name string + commandArgs []string + expectedErrOutput string + appRunner func(runtimeSettings RuntimeSettings) error + expectedSettings RuntimeSettings + }{ + { + name: "no sub-command", + commandArgs: []string{"--start", "4", "--end", "5", "--config-file", "myfile"}, + expectedErrOutput: "Error: ", + }, + { + name: "append sub-command with start and end present", + commandArgs: []string{"append", "--start", "4", "--end", "5", "--config-file", "myfile"}, + expectedErrOutput: "", + appRunner: appRunnerSuccess, + expectedSettings: RuntimeSettings{ + StartLedger: 4, + EndLedger: 5, + ConfigFilePath: "myfile", + Mode: Append, + }, + }, + { + name: "append sub-command with start and end absent", + commandArgs: []string{"append", "--config-file", "myfile"}, + expectedErrOutput: "", + appRunner: appRunnerSuccess, + expectedSettings: RuntimeSettings{ + StartLedger: 0, + EndLedger: 0, + ConfigFilePath: "myfile", + Mode: Append, + }, + }, + { + name: "append sub-command prints app error", + commandArgs: []string{"append", "--start", "4", "--end", "5", "--config-file", "myfile"}, + expectedErrOutput: "test error", + appRunner: appRunnerError, + }, + { + name: "scanfill sub-command with start and end present", + commandArgs: []string{"scan-and-fill", "--start", "4", "--end", "5", "--config-file", "myfile"}, + expectedErrOutput: "", + appRunner: appRunnerSuccess, + expectedSettings: RuntimeSettings{ + StartLedger: 4, + EndLedger: 5, + ConfigFilePath: "myfile", + Mode: ScanFill, + }, + }, + { + name: "scanfill sub-command with start and end absent", + commandArgs: []string{"scan-and-fill", "--config-file", "myfile"}, + expectedErrOutput: "", + appRunner: appRunnerSuccess, + expectedSettings: RuntimeSettings{ + StartLedger: 0, + EndLedger: 0, + ConfigFilePath: "myfile", + Mode: ScanFill, + }, + }, + { + name: "scanfill sub-command prints app error", + commandArgs: []string{"scan-and-fill", "--start", "4", "--end", "5", "--config-file", "myfile"}, + expectedErrOutput: "test error", + appRunner: appRunnerError, + }, + } + for _, testCase := range testCases { + t.Run(testCase.name, func(t *testing.T) { + // mock the ledger exporter's cmd runner to be this test's mock routine instead of real app + ledgerExporterCmdRunner = testCase.appRunner + defineCommands() + rootCmd.SetArgs(testCase.commandArgs) + var errWriter io.Writer = &bytes.Buffer{} + var outWriter io.Writer = &bytes.Buffer{} + rootCmd.SetErr(errWriter) + rootCmd.SetOut(outWriter) + rootCmd.Execute() + + errOutput := errWriter.(*bytes.Buffer).String() + if testCase.expectedErrOutput != "" { + assert.Contains(t, errOutput, testCase.expectedErrOutput) + } else { + assert.Equal(t, testCase.expectedSettings, testResultSettings) + } + }) + } +} diff --git a/exp/services/ledgerexporter/internal/test/10perfile.toml b/exp/services/ledgerexporter/internal/test/10perfile.toml index 9b96927804..cae3d9f9ea 100644 --- a/exp/services/ledgerexporter/internal/test/10perfile.toml +++ b/exp/services/ledgerexporter/internal/test/10perfile.toml @@ -1,5 +1,6 @@ -network = "test" +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" -[exporter_config] -ledgers_per_file = 10 -file_suffix = ".xdr.gz" \ No newline at end of file +[datastore_config.schema] +ledgers_per_file = 10 \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/15perfile.toml b/exp/services/ledgerexporter/internal/test/15perfile.toml index 94df87a2e2..e3e4ee9d44 100644 --- a/exp/services/ledgerexporter/internal/test/15perfile.toml +++ b/exp/services/ledgerexporter/internal/test/15perfile.toml @@ -1,5 +1,6 @@ -network = "test" +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" -[exporter_config] -ledgers_per_file = 15 -file_suffix = ".xdr.gz" \ No newline at end of file +[datastore_config.schema] +ledgers_per_file = 15 \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/1perfile.toml b/exp/services/ledgerexporter/internal/test/1perfile.toml index a15dc9bf41..f8e88de478 100644 --- a/exp/services/ledgerexporter/internal/test/1perfile.toml +++ b/exp/services/ledgerexporter/internal/test/1perfile.toml @@ -1,5 +1,6 @@ -network = "test" +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" -[exporter_config] -ledgers_per_file = 1 -file_suffix = ".xdr.gz" \ No newline at end of file +[datastore_config.schema] +ledgers_per_file = 1 \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/64perfile.toml b/exp/services/ledgerexporter/internal/test/64perfile.toml index 8e8d122fcc..769546afaf 100644 --- a/exp/services/ledgerexporter/internal/test/64perfile.toml +++ b/exp/services/ledgerexporter/internal/test/64perfile.toml @@ -1,5 +1,6 @@ -network = "test" +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" -[exporter_config] -ledgers_per_file = 64 -file_suffix = ".xdr.gz" \ No newline at end of file +[datastore_config.schema] +ledgers_per_file = 64 \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/captive-core-test.cfg b/exp/services/ledgerexporter/internal/test/captive-core-test.cfg new file mode 100644 index 0000000000..dac9369464 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/captive-core-test.cfg @@ -0,0 +1,12 @@ +PEER_PORT=11725 + +UNSAFE_QUORUM=true +FAILURE_SAFETY=0 + +[[VALIDATORS]] +NAME="local_core" +HOME_DOMAIN="core.local" +PUBLIC_KEY="GD5KD2KEZJIGTC63IGW6UMUSMVUVG5IHG64HUTFWCHVZH2N2IBOQN7PS" +ADDRESS="localhost" +HISTORY="curl -sf https://localhost/{0} -o {1}" +QUALITY="MEDIUM" \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/invalid_captive_core_toml_path.toml b/exp/services/ledgerexporter/internal/test/invalid_captive_core_toml_path.toml new file mode 100644 index 0000000000..580590b667 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/invalid_captive_core_toml_path.toml @@ -0,0 +1,5 @@ +[stellar_core_config] +captive_core_toml_path = "test/notfound.cfg" +stellar_core_binary_path = "test/stellar-core" +history_archive_urls = ["http://testarchive"] +network_passphrase = "test" diff --git a/exp/services/ledgerexporter/internal/test/invalid_empty.toml b/exp/services/ledgerexporter/internal/test/invalid_empty.toml new file mode 100644 index 0000000000..8b13789179 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/invalid_empty.toml @@ -0,0 +1 @@ + diff --git a/exp/services/ledgerexporter/internal/test/invalid_preconfigured_network.toml b/exp/services/ledgerexporter/internal/test/invalid_preconfigured_network.toml new file mode 100644 index 0000000000..8e09f05e55 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/invalid_preconfigured_network.toml @@ -0,0 +1,4 @@ +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "invalid" + diff --git a/exp/services/ledgerexporter/internal/test/no_core_bin.toml b/exp/services/ledgerexporter/internal/test/no_core_bin.toml new file mode 100644 index 0000000000..abbd1d9972 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/no_core_bin.toml @@ -0,0 +1,3 @@ +[stellar_core_config] +network = "testnet" + \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/no_network.toml b/exp/services/ledgerexporter/internal/test/no_network.toml deleted file mode 100644 index 1cb591cdd4..0000000000 --- a/exp/services/ledgerexporter/internal/test/no_network.toml +++ /dev/null @@ -1,11 +0,0 @@ - -[datastore_config] -type = "ABC" - -[datastore_config.params] -destination_bucket_path = "your-bucket-name/subpath" - -[exporter_config] -ledgers_per_file = 3 -files_per_partition = 1 -file_suffix = ".xdr.gz" \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/test.toml b/exp/services/ledgerexporter/internal/test/test.toml index 58b5fc6df6..6a6804c70f 100644 --- a/exp/services/ledgerexporter/internal/test/test.toml +++ b/exp/services/ledgerexporter/internal/test/test.toml @@ -1,12 +1,13 @@ -network = "test" +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" [datastore_config] type = "ABC" [datastore_config.params] -destination_bucket_path = "your-bucket-name/subpath" +destination_bucket_path = "your-bucket-name/subpath/testnet" -[exporter_config] +[datastore_config.schema] ledgers_per_file = 3 -files_per_partition = 1 -file_suffix = ".xdr.gz" \ No newline at end of file +files_per_partition = 1 \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/useragent.toml b/exp/services/ledgerexporter/internal/test/useragent.toml new file mode 100644 index 0000000000..209c04155b --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/useragent.toml @@ -0,0 +1,7 @@ +user_agent = "useragent_x" + +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" + + diff --git a/exp/services/ledgerexporter/internal/test/valid_captive_core_manual.toml b/exp/services/ledgerexporter/internal/test/valid_captive_core_manual.toml new file mode 100644 index 0000000000..24a4304844 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/valid_captive_core_manual.toml @@ -0,0 +1,5 @@ +[stellar_core_config] +captive_core_toml_path = "test/captive-core-test.cfg" +stellar_core_binary_path = "test/stellar-core" +history_archive_urls = ["http://testarchive"] +network_passphrase = "test" \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/test/valid_captive_core_override.toml b/exp/services/ledgerexporter/internal/test/valid_captive_core_override.toml new file mode 100644 index 0000000000..312ccb29bb --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/valid_captive_core_override.toml @@ -0,0 +1,4 @@ +[stellar_core_config] +network="pubnet" +captive_core_toml_path = "test/captive-core-test.cfg" +stellar_core_binary_path = "test/stellar-core" diff --git a/exp/services/ledgerexporter/internal/test/valid_captive_core_override_archives.toml b/exp/services/ledgerexporter/internal/test/valid_captive_core_override_archives.toml new file mode 100644 index 0000000000..9aebc153c2 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/valid_captive_core_override_archives.toml @@ -0,0 +1,4 @@ +[stellar_core_config] +network="pubnet" +history_archive_urls = ["http://testarchive"] +stellar_core_binary_path = "test/stellar-core" diff --git a/exp/services/ledgerexporter/internal/test/valid_captive_core_preconfigured.toml b/exp/services/ledgerexporter/internal/test/valid_captive_core_preconfigured.toml new file mode 100644 index 0000000000..cb1c3c5c52 --- /dev/null +++ b/exp/services/ledgerexporter/internal/test/valid_captive_core_preconfigured.toml @@ -0,0 +1,4 @@ +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" + diff --git a/exp/services/ledgerexporter/internal/test/validate_start_end.toml b/exp/services/ledgerexporter/internal/test/validate_start_end.toml index a15dc9bf41..8cbd9f37a9 100644 --- a/exp/services/ledgerexporter/internal/test/validate_start_end.toml +++ b/exp/services/ledgerexporter/internal/test/validate_start_end.toml @@ -1,5 +1,6 @@ -network = "test" - -[exporter_config] +[datastore_config.schema] ledgers_per_file = 1 -file_suffix = ".xdr.gz" \ No newline at end of file + +[stellar_core_config] +stellar_core_binary_path = "test/stellar-core" +network = "pubnet" \ No newline at end of file diff --git a/exp/services/ledgerexporter/internal/uploader_test.go b/exp/services/ledgerexporter/internal/uploader_test.go index bb3ca1e29a..612c9e8740 100644 --- a/exp/services/ledgerexporter/internal/uploader_test.go +++ b/exp/services/ledgerexporter/internal/uploader_test.go @@ -59,7 +59,7 @@ func (s *UploaderSuite) TestUploadWithMetadata() { EndLedgerCloseTime: 987654321, ProtocolVersion: 3, CoreVersion: "v1.2.3", - Network: "testnet", + NetworkPassPhrase: "testnet", CompressionType: "gzip", Version: "1.0.0", } diff --git a/exp/services/ledgerexporter/main.go b/exp/services/ledgerexporter/main.go index 63e094980f..6d38c69df9 100644 --- a/exp/services/ledgerexporter/main.go +++ b/exp/services/ledgerexporter/main.go @@ -1,25 +1,16 @@ package main import ( - "flag" + "fmt" + "os" exporter "github.com/stellar/go/exp/services/ledgerexporter/internal" ) func main() { - flags := exporter.Flags{} - startLedger := uint(0) - endLedger := uint(0) - flag.UintVar(&startLedger, "start", 0, "Starting ledger") - flag.UintVar(&endLedger, "end", 0, "Ending ledger (inclusive)") - flag.StringVar(&flags.ConfigFilePath, "config-file", "config.toml", "Path to the TOML config file") - flag.BoolVar(&flags.Resume, "resume", false, "Attempt to find a resumable starting point on remote data store") - flag.UintVar(&flags.AdminPort, "admin-port", 0, "Admin HTTP port for prometheus metrics") - - flag.Parse() - flags.StartLedger = uint32(startLedger) - flags.EndLedger = uint32(endLedger) - - app := exporter.NewApp(flags) - app.Run() + err := exporter.Execute() + if err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } } diff --git a/ingest/ledgerbackend/buffered_storage_backend.go b/ingest/ledgerbackend/buffered_storage_backend.go index 41ff4a942e..4a353bfe22 100644 --- a/ingest/ledgerbackend/buffered_storage_backend.go +++ b/ingest/ledgerbackend/buffered_storage_backend.go @@ -18,7 +18,7 @@ import ( var _ LedgerBackend = (*BufferedStorageBackend)(nil) type BufferedStorageBackendConfig struct { - LedgerBatchConfig datastore.LedgerBatchConfig + LedgerBatchConfig datastore.DataStoreSchema DataStore datastore.DataStore BufferSize uint32 NumWorkers uint32 diff --git a/ingest/ledgerbackend/buffered_storage_backend_test.go b/ingest/ledgerbackend/buffered_storage_backend_test.go index 1aca8306c8..f18329fffa 100644 --- a/ingest/ledgerbackend/buffered_storage_backend_test.go +++ b/ingest/ledgerbackend/buffered_storage_backend_test.go @@ -44,7 +44,7 @@ func createBufferedStorageBackendConfigForTesting() BufferedStorageBackendConfig param := make(map[string]string) param["destination_bucket_path"] = "testURL" - ledgerBatchConfig := datastore.LedgerBatchConfig{ + ledgerBatchConfig := datastore.DataStoreSchema{ LedgersPerFile: 1, FilesPerPartition: 64000, } diff --git a/services/horizon/docker/docker-compose.standalone.yml b/services/horizon/docker/docker-compose.standalone.yml index a537be0fb0..7d909dd6e0 100644 --- a/services/horizon/docker/docker-compose.standalone.yml +++ b/services/horizon/docker/docker-compose.standalone.yml @@ -14,7 +14,7 @@ services: core: platform: linux/amd64 - image: ${CORE_IMAGE:-stellar/stellar-core:19.11.0-1323.7fb6d5e88.focal} + image: ${CORE_IMAGE:-stellar/stellar-core:21} depends_on: - core-postgres - core-upgrade diff --git a/services/horizon/docker/start.sh b/services/horizon/docker/start.sh index 824fa19a0a..af098dda4f 100755 --- a/services/horizon/docker/start.sh +++ b/services/horizon/docker/start.sh @@ -2,20 +2,30 @@ set -e +# Use the dirname directly, without changing directories +if [[ $BASH_SOURCE = */* ]]; then + DOCKER_DIR=${BASH_SOURCE%/*}/ +else + DOCKER_DIR=./ +fi + +echo "Docker dir is $DOCKER_DIR" + NETWORK=${1:-testnet} case $NETWORK in standalone) - DOCKER_FLAGS="-f docker-compose.yml -f docker-compose.standalone.yml" + DOCKER_FLAGS="-f ${DOCKER_DIR}docker-compose.yml -f ${DOCKER_DIR}docker-compose.standalone.yml" echo "running on standalone network" ;; pubnet) - DOCKER_FLAGS="-f docker-compose.yml -f docker-compose.pubnet.yml" + DOCKER_FLAGS="-f ${DOCKER_DIR}docker-compose.yml -f ${DOCKER_DIR}docker-compose.pubnet.yml" echo "running on public network" ;; testnet) + DOCKER_FLAGS="-f ${DOCKER_DIR}docker-compose.yml" echo "running on test network" ;; diff --git a/services/horizon/internal/actions/submit_transaction.go b/services/horizon/internal/actions/submit_transaction.go index 00049a9172..703e7a554d 100644 --- a/services/horizon/internal/actions/submit_transaction.go +++ b/services/horizon/internal/actions/submit_transaction.go @@ -92,7 +92,18 @@ func (handler SubmitTransactionHandler) response(r *http.Request, info envelopeI } if result.Err == txsub.ErrTimeout { - return nil, &hProblem.Timeout + return nil, &problem.P{ + Type: "transaction_submission_timeout", + Title: "Transaction Submission Timeout", + Status: http.StatusGatewayTimeout, + Detail: "Your transaction submission request has timed out. This does not necessarily mean the submission has failed. " + + "Before resubmitting, please use the transaction hash provided in `extras.hash` to poll the GET /transactions endpoint for sometime and " + + "check if it was included in a ledger.", + Extras: map[string]interface{}{ + "hash": info.hash, + "envelope_xdr": info.raw, + }, + } } if result.Err == txsub.ErrCanceled { @@ -191,6 +202,17 @@ func (handler SubmitTransactionHandler) GetResource(w HeaderWriter, r *http.Requ if r.Context().Err() == context.Canceled { return nil, hProblem.ClientDisconnected } - return nil, hProblem.Timeout + return nil, &problem.P{ + Type: "transaction_submission_timeout", + Title: "Transaction Submission Timeout", + Status: http.StatusGatewayTimeout, + Detail: "Your transaction submission request has timed out. This does not necessarily mean the submission has failed. " + + "Before resubmitting, please use the transaction hash provided in `extras.hash` to poll the GET /transactions endpoint for sometime and " + + "check if it was included in a ledger.", + Extras: map[string]interface{}{ + "hash": info.hash, + "envelope_xdr": raw, + }, + } } } diff --git a/services/horizon/internal/actions/submit_transaction_test.go b/services/horizon/internal/actions/submit_transaction_test.go index eb1987bdea..8d9979ae4b 100644 --- a/services/horizon/internal/actions/submit_transaction_test.go +++ b/services/horizon/internal/actions/submit_transaction_test.go @@ -100,6 +100,19 @@ func TestTimeoutSubmission(t *testing.T) { form := url.Values{} form.Set("tx", "AAAAAAGUcmKO5465JxTSLQOQljwk2SfqAJmZSG6JH6wtqpwhAAABLAAAAAAAAAABAAAAAAAAAAEAAAALaGVsbG8gd29ybGQAAAAAAwAAAAAAAAAAAAAAABbxCy3mLg3hiTqX4VUEEp60pFOrJNxYM1JtxXTwXhY2AAAAAAvrwgAAAAAAAAAAAQAAAAAW8Qst5i4N4Yk6l+FVBBKetKRTqyTcWDNSbcV08F4WNgAAAAAN4Lazj4x61AAAAAAAAAAFAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABLaqcIQAAAEBKwqWy3TaOxoGnfm9eUjfTRBvPf34dvDA0Nf+B8z4zBob90UXtuCqmQqwMCyH+okOI3c05br3khkH0yP4kCwcE") + expectedTimeoutResponse := &problem.P{ + Type: "transaction_submission_timeout", + Title: "Transaction Submission Timeout", + Status: http.StatusGatewayTimeout, + Detail: "Your transaction submission request has timed out. This does not necessarily mean the submission has failed. " + + "Before resubmitting, please use the transaction hash provided in `extras.hash` to poll the GET /transactions endpoint for sometime and " + + "check if it was included in a ledger.", + Extras: map[string]interface{}{ + "hash": "3389e9f0f1a65f19736cacf544c2e825313e8447f569233bb8db39aa607c8889", + "envelope_xdr": "AAAAAAGUcmKO5465JxTSLQOQljwk2SfqAJmZSG6JH6wtqpwhAAABLAAAAAAAAAABAAAAAAAAAAEAAAALaGVsbG8gd29ybGQAAAAAAwAAAAAAAAAAAAAAABbxCy3mLg3hiTqX4VUEEp60pFOrJNxYM1JtxXTwXhY2AAAAAAvrwgAAAAAAAAAAAQAAAAAW8Qst5i4N4Yk6l+FVBBKetKRTqyTcWDNSbcV08F4WNgAAAAAN4Lazj4x61AAAAAAAAAAFAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABLaqcIQAAAEBKwqWy3TaOxoGnfm9eUjfTRBvPf34dvDA0Nf+B8z4zBob90UXtuCqmQqwMCyH+okOI3c05br3khkH0yP4kCwcE", + }, + } + request, err := http.NewRequest( "POST", "https://horizon.stellar.org/transactions", @@ -115,7 +128,7 @@ func TestTimeoutSubmission(t *testing.T) { w := httptest.NewRecorder() _, err = handler.GetResource(w, request) assert.Error(t, err) - assert.Equal(t, hProblem.Timeout, err) + assert.Equal(t, expectedTimeoutResponse, err) } func TestClientDisconnectSubmission(t *testing.T) { diff --git a/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md b/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md index b076dc4dd4..cdbc1b97c7 100644 --- a/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md +++ b/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md @@ -6,13 +6,13 @@ This document describes how to build Horizon from source, so that you can test a - A [Unix-like](https://en.wikipedia.org/wiki/Unix-like) operating system with the common core commands (cp, tar, mkdir, bash, etc.) - Go (this repository is officially supported on the last [two releases of Go](https://go.dev/doc/devel/release)) - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) (to check out Horizon's source code) -- [mercurial](https://www.mercurial-scm.org/) (needed for `go-dep`) - [Docker](https://www.docker.com/products/docker-desktop) +- [stellar-core](#building-stellar-core) ## The Go Monorepo All the code for Horizon resides in our Go monorepo. ```bash -git clone https://github.com/go.git +git clone https://github.com/stellar/go.git ``` If you want to contribute to the project, consider forking the repository and cloning the fork instead. @@ -20,11 +20,11 @@ If you want to contribute to the project, consider forking the repository and cl The [start.sh](/services/horizon/docker/start.sh) script builds horizon from current source, and then runs docker-compose to start the docker containers with runtime configs for horizon, postgres, and optionally core if the optional `standalone` network parameter was included. The script takes one optional parameter which configures the Stellar network used by the docker containers. If no parameter is supplied, the containers will run on the Stellar test network. Read more about the public and private networks in the [public documentation](https://developers.stellar.org/docs/fundamentals-and-concepts/testnet-and-pubnet#testnet) -`./start.sh pubnet` will run the containers on the Stellar public network. +`./services/horizon/docker/start.sh pubnet` will run the containers on the Stellar public network. -`./start.sh standalone` will run the containers on a private standalone Stellar network. +`./services/horizon/docker/start.sh standalone` will run the containers on a private standalone Stellar network. -`./start.sh testnet` will run the containers on the Stellar test network. +`./services/horizon/docker/start.sh testnet` will run the containers on the Stellar test network. The following ports will be exposed: - Horizon: **8000** @@ -42,47 +42,21 @@ We will now configure a development environment to run Horizon service locally w ### Building Stellar Core Horizon requires an instance of stellar-core binary on the same host. This is referred to as the `Captive Core`. Since, we are running horizon for dev purposes, we recommend considering two approaches to get the stellar-core binary, if saving time is top priority and your development machine is on a linux debian o/s, then consider installing the debian package, otherwise the next option available is to compile the core source directly to binary on your machine, refer to [INSTALL.md](https://github.com/stellar/stellar-core/blob/master/INSTALL.md) file for the instructions on both approaches. -### Building Horizon - -1. Change to the horizon services directory - `cd go/services/horizon/`. -2. Compile the Horizon binary: `go build -o stellar-horizon && go install`. You should see the resulting `stellar-horizon` executable in `go/services/horizon`. -3. Add the executable to your PATH in your `~/.bashrc` or equivalent, for easy access: `export PATH=$PATH:{absolute-path-to-horizon-folder}` - -Open a new terminal. Confirm everything worked by running `stellar-horizon --help` successfully. You should see an informative message listing the command line options supported by Horizon. - ### Database Setup -Horizon uses a Postgres database backend to record information ingested from an associated Stellar Core. The unit and integration tests will also attempt to reference a Postgres db server at ``localhost:5432`` with trust auth method enabled by default for ``postgres`` user. You can either install the server locally or run any type of docker container that hosts the database server. We recommend using the [docker-compose.yml](/services/horizon/docker/docker-compose.yml) file in the ``docker`` folder: +Horizon uses a Postgres database to record information ingested from Stellar Core. The unit and integration tests also expect a Postgres DB to be running at ``localhost:5432`` with trust auth method enabled by default for the ``postgres`` user. You can run the following command to spin up a Horizon database as a docker container: ```bash -docker-compose -f ./docker/docker-compose.yml up horizon-postgres +docker-compose -f ./services/horizon/docker/docker-compose.yml up -d horizon-postgres ``` -This starts a Horizon Postgres docker container and exposes it on the port 5432. Note that while Horizon will run locally, it's PostgresQL db will run in docker. +The docker container will accept database connections on port 5432. Note that while Horizon will run locally, it's PostgresQL db will run in docker. To shut down all docker containers and free up resources, run the following command: ```bash -docker-compose -f ./docker/docker-compose.yml down -``` - -### Run tests -At this point you should be able to run Horizon's unit tests: -```bash -cd go/services/horizon/ -go test ./... +docker-compose -f ./services/horizon/docker/docker-compose.yml down --remove-orphans -v ``` -To run the integration tests, you need to set some environment variables: +### Running Horizon in an IDE -```bash -export HORIZON_INTEGRATION_TESTS_ENABLED=true -export HORIZON_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL=19 -export HORIZON_INTEGRATION_TESTS_DOCKER_IMG=stellar/stellar-core:19.11.0-1323.7fb6d5e88.focal -go test -race -timeout 25m -v ./services/horizon/internal/integration/... -``` -Note that this will also require a Postgres instance running on port 5432 either locally or exposed through a docker container. Also note that the ``POSTGRES_HOST_AUTH_METHOD`` has been enabled. - -### Setup Debug Configuration in IDE - -#### Code Debug Add a debug configuration in your IDE to attach a debugger to the local Horizon process and set breakpoints in your code. Here is an example configuration for VS Code: ```json @@ -94,9 +68,8 @@ Add a debug configuration in your IDE to attach a debugger to the local Horizon "program": "${workspaceRoot}/services/horizon/main.go", "env": { "DATABASE_URL": "postgres://postgres@localhost:5432/horizon?sslmode=disable", - "CAPTIVE_CORE_CONFIG_APPEND_PATH": "./ingest/ledgerbackend/configs/captive-core-testnet.cfg", - "HISTORY_ARCHIVE_URLS": "https://history.stellar.org/prd/core-testnet/core_testnet_001,https://history.stellar.org/prd/core-testnet/core_testnet_002", - "NETWORK_PASSPHRASE": "Test SDF Network ; September 2015", + "APPLY_MIGRATIONS": "true", + "NETWORK": "testnet", "PER_HOUR_RATE_LIMIT": "0" }, "args": [] @@ -104,8 +77,36 @@ Add a debug configuration in your IDE to attach a debugger to the local Horizon ``` If all is well, you should see ingest logs written to standard out. You can read more about configuring the different environment variables in [Configuring](https://developers.stellar.org/docs/run-api-server/configuring) section of our public documentation. -#### Test Debug -You can also use a similar configuration to debug the integration and unit tests. For e.g. here is a configuration for debugging the ```TestFilteringAccountWhiteList``` integration test. +### Building Horizon Binary + +1. Change to the horizon services directory - `cd go/services/horizon/`. +2. Compile the Horizon binary: `go build -o stellar-horizon && go install`. You should see the resulting `stellar-horizon` executable in `go/services/horizon`. +3. Add the executable to your PATH in your `~/.bashrc` or equivalent, for easy access: `export PATH=$PATH:{absolute-path-to-horizon-folder}` + +Open a new terminal. Confirm everything worked by running `stellar-horizon --help` successfully. You should see an informative message listing the command line options supported by Horizon. + +### Run tests + +Once you have [installed stellar-core](#building-stellar-core) on your machine and have the +[Horizon database](#database-setup) up and running, you should be able to run Horizon's unit tests: + +```bash +cd go/services/horizon/ +go test ./... +``` + +To run the integration tests, you need to set some environment variables: + +```bash +export HORIZON_INTEGRATION_TESTS_ENABLED=true +export HORIZON_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL=21 +export HORIZON_INTEGRATION_TESTS_DOCKER_IMG=stellar/stellar-core:21 +go test -race -timeout 25m -v ./services/horizon/internal/integration/... +``` + +#### Running tests in IDE + +You can debug integration and unit tests in your IDE. For example, here is a VS Code configuration for debugging the ```TestFilteringAccountWhiteList``` integration test. ```json { "name": "Debug Test Function", @@ -115,8 +116,8 @@ You can also use a similar configuration to debug the integration and unit tests "program": "${workspaceRoot}/services/horizon/internal/integration", "env": { "HORIZON_INTEGRATION_TESTS_ENABLED": "true", - "HORIZON_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL": "19", - "HORIZON_INTEGRATION_TESTS_DOCKER_IMG": "stellar/stellar-core:19.11.0-1323.7fb6d5e88.focal" + "HORIZON_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL": "21", + "HORIZON_INTEGRATION_TESTS_DOCKER_IMG": "stellar/stellar-core:21" }, "args": [ "-test.run", @@ -166,18 +167,18 @@ this customization is only applicable when running a standalone network, as it r ## Using a specific version of Stellar Core -By default, the Docker Compose file is configured to use version 19 of Protocol and Stellar Core. You can specify optional environment variables from the command shell for stating version overrides for either the docker-compose or start.sh invocations. +By default, the Docker Compose file is configured to use version 21 of Protocol and Stellar Core. You can specify optional environment variables from the command shell for stating version overrides for either the docker-compose or start.sh invocations. ```bash -export PROTOCOL_VERSION="19" -export CORE_IMAGE="stellar/stellar-core:19.11.0-1323.7fb6d5e88.focal" -export STELLAR_CORE_VERSION="19.11.0-1323.7fb6d5e88.focal" +export PROTOCOL_VERSION="21" +export CORE_IMAGE="stellar/stellar-core:21" +export STELLAR_CORE_VERSION="21.0.0-1872.c6f474133.focal" ``` Example: -Runs Stellar Protocol and Core version 19, for any mode of testnet, standalone, pubnet +Runs Stellar Protocol and Core version 21, for any mode of testnet, standalone, pubnet ```bash -PROTOCOL_VERSION=19 CORE_IMAGE=stellar/stellar-core:19.11.0-1323.7fb6d5e88.focal STELLAR_CORE_VERSION=19.11.0-1323.7fb6d5e88.focal ./start.sh [standalone|pubnet] +PROTOCOL_VERSION=21 CORE_IMAGE=stellar/stellar-core:21 STELLAR_CORE_VERSION=21.0.0-1872.c6f474133.focal ./start.sh [standalone|pubnet] ``` ## **Logging** diff --git a/services/horizon/internal/docs/SDK_API_GUIDE.md b/services/horizon/internal/docs/SDK_API_GUIDE.md deleted file mode 100644 index bc8268ddb1..0000000000 --- a/services/horizon/internal/docs/SDK_API_GUIDE.md +++ /dev/null @@ -1,17 +0,0 @@ -# **Horizon SDK and API Guide** - -Now, let's get familiar with Horizon's API, SDK and the tooling around them. The [API documentation](https://developers.stellar.org/api/) is particularly useful and you will find yourself consulting it often. - -Spend a few hours reading before getting your hands dirty writing code: - -- Skim through the [developer documentation](https://developers.stellar.org/docs/) in general. -- Try to understand what an [Account](https://developers.stellar.org/docs/glossary/accounts/) is. -- Try to understand what a [Ledger](https://developers.stellar.org/docs/glossary/ledger/), [Transaction](https://developers.stellar.org/docs/glossary/transactions/) and [Operation](https://developers.stellar.org/docs/glossary/operations/) is and their hierarchical nature. Make sure you understand how sequence numbers work. -- Go through the different [Operation](https://developers.stellar.org/docs/start/list-of-operations/) types. Take a look at the Go SDK machinery for the [Account Creation](https://godoc.org/github.com/stellar/go/txnbuild#CreateAccount) and [Payment](https://godoc.org/github.com/stellar/go/txnbuild#Payment) operations and read the documentation examples. -- You will use the Testnet network frequently during Horizon's development. Get familiar with [what it is and how it is useful](https://developers.stellar.org/docs/glossary/testnet/). Try to understand what [Friendbot](https://github.com/stellar/go/tree/master/services/friendbot) is. -- Read Horizon's API [introduction](https://developers.stellar.org/api/introduction/) and make sure you understand what's HAL and XDR. Also, make sure you understand how streaming responses work. -- Get familiar with Horizon's REST API endpoints. There are two type of endpoints: - - **Querying Endpoints**. They give you information about the network status. The output is based on the information obtained from Core or derived from it. These endpoints refer to resources. These resources can: - - Exist in the Stellar network. Take a look at the [endpoints associated with each resource](https://developers.stellar.org/api/resources/). - - Are abstractions which don't exist in the Stellar network but they are useful to the end user. Take a look at their [endpoints](https://developers.stellar.org/api/aggregations/). - - **Submission Endpoints**. There is only one, the [transaction submission endpoint](https://www.stellar.org/developers/horizon/reference/endpoints/transactions-create.html). You will be using it explicitly next. \ No newline at end of file diff --git a/services/horizon/internal/docs/TESTING_NOTES.md b/services/horizon/internal/docs/TESTING_NOTES.md index 42577173ce..c7db9cd465 100644 --- a/services/horizon/internal/docs/TESTING_NOTES.md +++ b/services/horizon/internal/docs/TESTING_NOTES.md @@ -15,8 +15,8 @@ go test github.com/stellar/go/services/horizon/... Before running integration tests, you also need to set some environment variables: ```bash export HORIZON_INTEGRATION_TESTS_ENABLED=true -export HORIZON_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL=19 -export HORIZON_INTEGRATION_TESTS_DOCKER_IMG=stellar/stellar-core:19.11.0-1323.7fb6d5e88.focal +export HORIZON_INTEGRATION_TESTS_CORE_MAX_SUPPORTED_PROTOCOL=21 +export HORIZON_INTEGRATION_TESTS_DOCKER_IMG=stellar/stellar-core:21.0.0-1872.c6f474133.focal ``` Make sure to check [horizon.yml](/.github/workflows/horizon.yml) for the latest core image version. diff --git a/services/horizon/internal/docs/plans/images/adapters.png b/services/horizon/internal/docs/plans/images/adapters.png deleted file mode 100644 index 807cd46242..0000000000 Binary files a/services/horizon/internal/docs/plans/images/adapters.png and /dev/null differ diff --git a/services/horizon/internal/docs/plans/images/historyarchive.png b/services/horizon/internal/docs/plans/images/historyarchive.png deleted file mode 100644 index e28f0df415..0000000000 Binary files a/services/horizon/internal/docs/plans/images/historyarchive.png and /dev/null differ diff --git a/services/horizon/internal/docs/plans/images/io.png b/services/horizon/internal/docs/plans/images/io.png deleted file mode 100644 index 5f49556fb4..0000000000 Binary files a/services/horizon/internal/docs/plans/images/io.png and /dev/null differ diff --git a/services/horizon/internal/docs/plans/images/ledgerbackend.png b/services/horizon/internal/docs/plans/images/ledgerbackend.png deleted file mode 100644 index 39990c77da..0000000000 Binary files a/services/horizon/internal/docs/plans/images/ledgerbackend.png and /dev/null differ diff --git a/services/horizon/internal/docs/plans/images/pipeline.png b/services/horizon/internal/docs/plans/images/pipeline.png deleted file mode 100644 index 98e535d452..0000000000 Binary files a/services/horizon/internal/docs/plans/images/pipeline.png and /dev/null differ diff --git a/services/horizon/internal/docs/plans/images/system.png b/services/horizon/internal/docs/plans/images/system.png deleted file mode 100644 index 3a26c414d4..0000000000 Binary files a/services/horizon/internal/docs/plans/images/system.png and /dev/null differ diff --git a/services/horizon/internal/docs/plans/new_horizon_ingest.md b/services/horizon/internal/docs/plans/new_horizon_ingest.md deleted file mode 100644 index 615d671948..0000000000 --- a/services/horizon/internal/docs/plans/new_horizon_ingest.md +++ /dev/null @@ -1,181 +0,0 @@ -# New Horizon Ingest - -This describes the goals, design, and implementation plan for the new Horizon ingestion system. - -## Project Goals - -- Handle need for Horizon to re-ingest, catch up after outage, or fill gaps -- No more stellar-core DB access from Horizon -- Full history ingestion of Stellar Public Network ledger shouldn’t take longer than 24h on x1.32xlarge AWS machine -- Horizon maintains own state of the ledger. Order books, at least, need to be kept in-memory to allow fast pathfinding. -- Multi-writer ingestion is provided for re-ingestion (speed) and for ledger stream (high availability) -- Ingestion is a collection of micro-services (trade aggregations, trades, txn history, etc…) -- Support plugins, so 3rd parties can implement custom ingestion schemes and easily plug them in -- Can run as standalone process, separate from Horizon -- Has clear API for building clients on top of it - -## Design - -### Inputs - -The ingestion system will read data from two sources: - -1. A History Archive [1](https://www.stellar.org/developers/stellar-core/software/admin.html#history-archives),[2](https://github.com/stellar/stellar-core/blob/master/docs/history.md), which is generated by `stellar-core` and provides a complete copy of a recent [ledger](https://www.stellar.org/developers/guides/concepts/ledger.html) as well as a history of `TransactionResult` XDR objects, which in turn contain [operation results](https://github.com/stellar/stellar-core/blob/master/src/xdr/Stellar-transaction.x#L382-L834). -2. A full ledger reader, which provides random and up-to-date access to the transaction sets & [`TransactionMeta`](https://github.com/stellar/stellar-core/blob/master/src/xdr/Stellar-ledger.x#L271-L318) in each ledger close. `TransactionMeta` info is essential for keeping a view of the ledger state up to date, as it describes the changes to ledger state that result from each operation. - -#### History Archive Reader - -The ingestion system needs to provide a full copy of current ledger state so that Horizon and other consumers of the ingestion system have no need to access the `stellar-core` database. The history archive reader allows ingestion to read the (near) current ledger state from a history archive. The advantage of this approach is that ingestion puts no load on the `stellar-core` database to pull in ledger state, since it reads entirely from a history archive, which is often stored in S3 or a separate file system. - -For context, a `stellar-core` can be configured to write out a history archive, which stores snapshots of the ledger state every 64 ledgers (approximately every 5 minutes). We envision that an administrator will run a `stellar-core`, configure it to write out a history archive, and then point the ingestion system at that history archive. This has two advantages: - -1. The ingestion does not put load on any external service (like SDF's history archives) -2. The administrator does not need to trust third party history archives - -Typically, the ingestion system will only access the history archive on startup to get a full copy of ledger state, and will then keep that copy of ledger state up to date using data from the separate ledger transaction set backend. However, the ingestion system could access older snapshots to construct a history of ledger state, or it could periodically re-ingest the full ledger state to detect any errors that accumulate over time from updating the ledger state. - -The history archive reader supports multiple backends to handle different ways that a history archive can be stored: - -1. S3 backend -2. HTTP backend -3. File backend - -UML Class diagram - -![History Archive Reader Class Diagram](images/historyarchive.png) - -Example of reading a history archive using `stellar-core`: - -```sh -wget http://history.stellar.org/prd/core-live/core_live_001/results/01/4d/f7/results-014df7ff.xdr.gz -gunzip results-014df7ff.xdr.gz -~/src/stellar-core/src/stellar-core dump-xdr results-014df7ff.xdr | head -n 40 -``` - -#### Full Ledger Reader - -The ingestion system needs a way to keep the current ledger state up to date, as well as a way to construct a history of events (typically transactions, operations, and effects) that have occurred over time on the Stellar network. The full ledger reader provides this ability. Specifically, it allows the ingestion system to access a stream of transaction metadata that encode state changes that happen as a result of every transaction. This information is missing from the history archives, and is also updated after every ledger close (vs. after every 64 in the history archives). The full ledger reader also has access to transaction sets for each ledger. - -Here's a summary of the features provided by the full ledger reader vs. the history archive reader: - -| Reader | txn resultsets | ledger state snapshots | transaction metadata | near-realtime (updates at every ledger close) | -| --- |:---:|:---:|:---:|:---:| -| history archive | X | X | | | -| full ledger | X | | X | X | - -The long term plan for the full ledger reader is for `stellar-core` to write transaction metadata out to an S3 bucket, which will allow the following: - -1. Reading transaction metadata without creating load on `stellar-core`'s database -2. Fast, parallel access to historical transaction metadata (allowing fast `CATCHUP_COMPLETE` ingestion) -3. Multiple `stellar-core`s writing the latest update to the same S3 object. This allows redundancy: one `stellar-core` can fail, and the stream of S3 objects will continue uninterrupted. - -However, this requires a change to `stellar-core`, which is estimated to happen in Q3 2019. Until then, the ingestion system will read from the `txfeehistory` and [`txhistory`](https://github.com/stellar/stellar-core/blob/master/src/transactions/TransactionFrame.cpp#L683) tables in the `stellar-core` database as it does currently. Unfortunately, we won't get any of the benefits listed above until the change is made to `stellar-core`. - -The full ledger reader will support multiple backends: - -1. `stellar-core` database reader (this will be implemented first, and is exactly what happens now) -2. File backend -3. S3 backend - -UML Class diagram - -![Full Ledger Reader Class Diagram](images/ledgerbackend.png) - -### Data Transformation - -The ingestion system has a data transformation pipeline in between its inputs (full ledger backend + history archive backend), and its outputs. - -#### Input Adapters - -The first step is to adapt the format of the data flowing from the two input backends into a format & interface that is easy for the ingestion system to use for both random access, and accessing the latest data. - -UML Class diagram - -![Input Adapters Class Diagram](images/adapters.png) - -Notes: - -- the `HistoryArchiveAdapter` supports both reading a ledger transaction result set via `GetLedger()` and reading ledger state via `GetState()`. -- Both adapters support `GetLatestLedgerSequence()`, which allows a consumer to look up the most recent ledger information in the backend. -- The adapters, rather than returning state and ledgers as objects stored in memory, return them as `ReadCloser` objects. This is because the ledger state or a particular transaction state may not fit in memory, and must be processed as a stream. - -Both `ReadCloser` and `WriteCloser` interfaces include `Close()` method. When `Close()` is called on `ReadCloser` it tells the reader that no more data is needed and it should stop streaming, ex. close buffered channels, close network connections, etc. When `Close` is is called on `WriteCloser` it means that no more data will be written to it. This is especially helpful when writer is writing to a pipe so the reader on the other end knows that no more objects will be streamed and can return `EOF`. - -The `ReadCloser` structs come from the `ingest/io` package, shown in the UML class diagram below: - -![IO package](images/io.png) - -#### Ingestion Pipeline - -At the center of ingestion is a `Pipeline`, which is initialized with a series of processors for each kind of data that ingestion handles (ledger state, a full ledger update, and an archive ledger update). Each processor implements a function that reads data from a `ReadCloser`, processes/filters it, and writes it to a `WriteCloser`. A few example processors: - -- A processor that passes on only information about a certain account -- A processor that only looks at certain kinds of events, such as offers being placed -- A processor sending a mobile notification for incoming payments -- A processor saving data to a database or in-memory store. - -See the rough UML diagram: - -![Filter package](images/pipeline.png) - -Notes: - -- The processors form a tree and are processed from root to leaves. -- Processing does not change the type of the data, but it can remove or change fields in the data -- Processors can write/read artifacts (ex. average balances) in a `Store` that is shared between all processors in a pipeline. `Store` is ephemeral, its contents is removed when pipeline processing is done. - -### Tying it all together - -The ingestion system can run as a stand-alone process or as part of a larger process like Horizon. It can handle three different kinds of sessions: - -- `IngestRangeSession`: ingest data over a range of ledgers. Used for ingesting historical data in parallel -- `LiveSession`: ingest the latest ledgers as soon as the close. This is the standard operating mode for a live Horizon instance -- `CheckpointsOnlySession`: ingest only history archive checkpoint data. - -Sessions are responsible for coordinating pipelines and ensuring data is in sync. When processors write to a single storage type, keeping data in sync is trivial. For example, for Postgres processors can share a single transaction object and commit when processing is done. However, there's also a significant challenge keeping data in sync when processors are writing to different storage types: any read operation that reads across stores or across data updated by multiple `Processes`s is at risk of reading inconsistent values. `System` or `Session` objects (TBD) should be responsible by keeping different stores in sync. For example: they can ensure that all queries sent to stores have the latest ledger sequence that was successfully saved all stores appended. This probably requires stores to keep data for the two (2) latest ledgers. - -![ingest package](images/system.png) - -## Open questions - -There are several open questions, and the design above isn't comprehensive. A few questions below: - -- What is the story around ingestion plugins? How do developers use the ingestion system in their own projects? -- How do we enable ingestion via multiple languages? -- Will we split Horizon into an ingestion process and an API server process, or keep a single process? -- Should a stand-alone ingestion process expose an RPC server or a more standard REST API? - - What's the exact API that an ingestion server exposes? -- Where is parallel ingestion logic handled? -- How exactly do we organize `Store`s, `ProcessingPipeline`, and `Process`es? -- How do we keep reads from multiple stores consistent? -- How do we make the `Store`s and `Process`es in `ingest/stores` reusable? - -## Implementation Plan - -This gives an overview of how we could move Horizon over to using the new ingestion system. - -### As we implement components - -We can create a command-line tool that computes basic stats and exercises all the components of ingestion to prove that they work together. For example, the tool can compute the total number of accounts every 5 minutes, or compute the number of transactions per second. - -### The proof of concept - -We can implement [accounts for signer](https://github.com/stellar/go/issues/432) using the new ingestion system. It's a good candidate because it's something we urgently need, and it's a new feature, so we don't risk breaking anything existing if there's an issue with the system. - -### Chunks that can be broken off and implemented separately - -- The projects below depend on the `io` package interfaces, which should be pretty minimal to add. -- History Archive Backend and History Archive Adapter (Nikhil is already on this) - - command-line tool takes a history archive file and prints out basic stats like # of accounts and transactions per second -- `DatabaseBackend` implementation of `LedgerBackend` and `LedgerBackendAdapter` - - command-line tool takes a database URI and computes stats like # of transactions in the latest ledger (it runs live and updates with each new ledger in the `DatabaseBackend`) -- `ingest/pipeline`: - - command-line tool that implements a few demo processors and given a DB URL and/or a historyarchive file location, streams out the data that passes the filter - -Once the above are all done, put together a basic ingestion server as laid out in the top-level `ingest` package. - -At this point, we'll have a full end-to-end implementation! Next, we start filling in the extra features we didn't need for the proof of concept. Once it's reasonably stable, we can release Horizon with the new `accoutns for signer` feature to get some real-world testing. - -### Porting the rest of Horizon over - -Once the proof of concept is functional, tables / features can be ported over one by one. Features that depend on `stellar-core` tables currently can be moved to equivalent tables maintained by Horizon. I imagine most features will still use postgres, but a few, such as pathfinding, will need in-memory storage for speed. If pathfinding can maintain a copy of order books [in memory](https://github.com/stellar/go/issues/849) it should run orders of magnitude faster. Horizon should be split out into a microservices architecture, with each feature implemented using a different `StateInitProcess` or `LedgerProcess` object. diff --git a/services/horizon/internal/docs/reference/endpoints/accounts-single.md b/services/horizon/internal/docs/reference/endpoints/accounts-single.md deleted file mode 100644 index ca0ccfdcf9..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/accounts-single.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Account Details -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=accounts&endpoint=single -replacement: https://developers.stellar.org/api/resources/accounts/single/ ---- - -Returns information and links relating to a single [account](../resources/account.md). - -The balances section in the returned JSON will also list all the -[trustlines](https://www.stellar.org/developers/learn/concepts/assets.html) this account -established. Note this will only return trustlines that have the necessary authorization to work. -Meaning if an account `A` trusts another account `B` that has the -[authorization required](https://www.stellar.org/developers/guides/concepts/accounts.html#flags) -flag set, the trustline won't show up until account `B` -[allows](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#allow-trust) -account `A` to hold its assets. - -## Request - -``` -GET /accounts/{account} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `account` | required, string | Account ID | GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.accounts() - .accountId("GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB") - .call() - .then(function (accountResult) { - console.log(accountResult); - }) - .catch(function (err) { - console.error(err); - }) -``` - -## Response - -This endpoint responds with the details of a single account for a given ID. See [account resource](../resources/account.md) for reference. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB" - }, - "transactions": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/transactions{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/operations{?cursor,limit,order}", - "templated": true - }, - "payments": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/payments{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/effects{?cursor,limit,order}", - "templated": true - }, - "offers": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/offers{?cursor,limit,order}", - "templated": true - }, - "trades": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/trades{?cursor,limit,order}", - "templated": true - }, - "data": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/data/{key}", - "templated": true - } - }, - "id": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "paging_token": "", - "account_id": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "sequence": 7275146318446606, - "last_modified_ledger": 22379074, - "subentry_count": 4, - "thresholds": { - "low_threshold": 0, - "med_threshold": 0, - "high_threshold": 0 - }, - "flags": { - "auth_required": false, - "auth_revocable": false, - "auth_immutable": false - }, - "balances": [ - { - "balance": "1000000.0000000", - "limit": "922337203685.4775807", - "buying_liabilities": "0.0000000", - "selling_liabilities": "0.0000000", - "last_modified_ledger": 632070, - "is_authorized": true, - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR" - }, - { - "balance": "10000.0000000", - "buying_liabilities": "0.0000000", - "selling_liabilities": "0.0000000", - "asset_type": "native" - } - ], - "signers": [ - { - "public_key": "GDLEPBJBC2VSKJCLJB264F2WDK63X4NKOG774A3QWVH2U6PERGDPUCS4", - "weight": 1, - "key": "GDLEPBJBC2VSKJCLJB264F2WDK63X4NKOG774A3QWVH2U6PERGDPUCS4", - "type": "ed25519_public_key" - }, - { - "public_key": "GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K", - "weight": 1, - "key": "GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K", - "type": "sha256_hash" - }, - { - "public_key": "GDUDIN23QQTB23Q3Q6GUL6I7CEAQY4CWCFVRXFWPF4UJAQO47SPUFCXG", - "weight": 1, - "key": "GDUDIN23QQTB23Q3Q6GUL6I7CEAQY4CWCFVRXFWPF4UJAQO47SPUFCXG", - "type": "preauth_tx" - }, - { - "public_key": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "weight": 1, - "key": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "type": "ed25519_public_key" - } - ], - "data": { - "best_friend": "c3Ryb29weQ==" - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no account whose ID matches the `account` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/accounts.md b/services/horizon/internal/docs/reference/endpoints/accounts.md deleted file mode 100644 index 29bfd2bd40..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/accounts.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Accounts -replacement: https://developers.stellar.org/api/resources/accounts/ ---- - -This endpoint allows filtering accounts who have a given `signer` or have a trustline to an `asset`. The result is a list of [accounts](../resources/account.md). - -To find all accounts who are trustees to an asset, pass the query parameter `asset` using the canonical representation for an issued assets which is `Code:IssuerAccountID`. Read more about canonical representation of assets in [SEP-0011](https://github.com/stellar/stellar-protocol/blob/0c675fb3a482183dcf0f5db79c12685acf82a95c/ecosystem/sep-0011.md#values). - -### Notes -- The default behavior when filtering by `asset` is to return accounts with `authorized` and `unauthorized` trustlines. - -## Request - -``` -GET /accounts{?signer,asset,cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?signer` | optional, string | Account ID | GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB | -| `?asset` | optional, string | An issued asset represented as "Code:IssuerAccountID". | `USD:GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V,native` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts?signer=GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K" -``` - - - - - - - - - - - - - - - - - -## Response - -This endpoint responds with the details of all accounts matching the filters. See [account resource](../resources/account.md) for reference. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts?cursor=\u0026limit=10\u0026order=asc\u0026signer=GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/accounts?cursor=GDRREYWHQWJDICNH4SAH4TT2JRBYRPTDYIMLK4UWBDT3X3ZVVYT6I4UQ\u0026limit=10\u0026order=asc\u0026signer=GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/accounts?cursor=GDRREYWHQWJDICNH4SAH4TT2JRBYRPTDYIMLK4UWBDT3X3ZVVYT6I4UQ\u0026limit=10\u0026order=desc\u0026signer=GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB" - }, - "transactions": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/transactions{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/operations{?cursor,limit,order}", - "templated": true - }, - "payments": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/payments{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/effects{?cursor,limit,order}", - "templated": true - }, - "offers": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/offers{?cursor,limit,order}", - "templated": true - }, - "trades": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/trades{?cursor,limit,order}", - "templated": true - }, - "data": { - "href": "https://horizon-testnet.stellar.org/accounts/GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB/data/{key}", - "templated": true - } - }, - "id": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "paging_token": "", - "account_id": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "sequence": 7275146318446606, - "last_modified_ledger": 22379074, - "subentry_count": 4, - "thresholds": { - "low_threshold": 0, - "med_threshold": 0, - "high_threshold": 0 - }, - "flags": { - "auth_required": false, - "auth_revocable": false, - "auth_immutable": false - }, - "balances": [ - { - "balance": "1000000.0000000", - "limit": "922337203685.4775807", - "buying_liabilities": "0.0000000", - "selling_liabilities": "0.0000000", - "last_modified_ledger": 632070, - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "is_authorized": true - }, - { - "balance": "10000.0000000", - "buying_liabilities": "0.0000000", - "selling_liabilities": "0.0000000", - "asset_type": "native" - } - ], - "signers": [ - { - "public_key": "GDLEPBJBC2VSKJCLJB264F2WDK63X4NKOG774A3QWVH2U6PERGDPUCS4", - "weight": 1, - "key": "GDLEPBJBC2VSKJCLJB264F2WDK63X4NKOG774A3QWVH2U6PERGDPUCS4", - "type": "ed25519_public_key" - }, - { - "public_key": "GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K", - "weight": 1, - "key": "GBPOFUJUHOFTZHMZ63H5GE6NX5KVKQRD6N3I2E5AL3T2UG7HSLPLXN2K", - "type": "sha256_hash" - }, - { - "public_key": "GDUDIN23QQTB23Q3Q6GUL6I7CEAQY4CWCFVRXFWPF4UJAQO47SPUFCXG", - "weight": 1, - "key": "GDUDIN23QQTB23Q3Q6GUL6I7CEAQY4CWCFVRXFWPF4UJAQO47SPUFCXG", - "type": "preauth_tx" - }, - { - "public_key": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "weight": 1, - "key": "GD42RQNXTRIW6YR3E2HXV5T2AI27LBRHOERV2JIYNFMXOBA234SWLQQB", - "type": "ed25519_public_key" - } - ], - "data": { - "best_friend": "c3Ryb29weQ==" - } - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). diff --git a/services/horizon/internal/docs/reference/endpoints/assets-all.md b/services/horizon/internal/docs/reference/endpoints/assets-all.md deleted file mode 100644 index c5281a6b32..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/assets-all.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: All Assets -clientData: - laboratoryUrl: -replacement: https://developers.stellar.org/api/resources/assets/ ---- - -This endpoint represents all [assets](../resources/asset.md). -It will give you all the assets in the system along with various statistics about each. - -## Request - -``` -GET /assets{?asset_code,asset_issuer,cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?asset_code` | optional, string, default _null_ | Code of the Asset to filter by | `USD` | -| `?asset_issuer` | optional, string, default _null_ | Issuer of the Asset to filter by | `GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36` | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. | `1` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc", ordered by asset_code then by asset_issuer. | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -# Retrieve the 200 assets, ordered alphabetically: -curl "https://horizon-testnet.stellar.org/assets?limit=200" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.assets() - .call() - .then(function (result) { - console.log(result.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -If called normally this endpoint responds with a [page](../resources/page.md) of assets. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "/assets?order=asc\u0026limit=10\u0026cursor=" - }, - "next": { - "href": "/assets?order=asc\u0026limit=10\u0026cursor=3" - }, - "prev": { - "href": "/assets?order=desc\u0026limit=10\u0026cursor=1" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "toml": { - "href": "https://www.stellar.org/.well-known/stellar.toml" - } - }, - "asset_type": "credit_alphanum12", - "asset_code": "BANANA", - "asset_issuer": "GDSBCQO34HWPGUGQSP3QBFEXVTSR2PW46UIGTHVWGWJGQKH3AFNHXHXN", - "paging_token": "BANANA_GDSBCQO34HWPGUGQSP3QBFEXVTSR2PW46UIGTHVWGWJGQKH3AFNHXHXN_credit_alphanum4", - "accounts": { - "authorized": 2126, - "authorized_to_maintain_liabilities": 32, - "unauthorized": 5, - "claimable_balances": 18 - }, - "balances": { - "authorized": "10000.0000000", - "authorized_to_maintain_liabilities": "3000.0000000", - "unauthorized": "4000.0000000", - "claimable_balances": "2380.0000000" - }, - "flags": { - "auth_required": true, - "auth_revocable": false - } - }, - { - "_links": { - "toml": { - "href": "https://www.stellar.org/.well-known/stellar.toml" - } - }, - "asset_type": "credit_alphanum4", - "asset_code": "BTC", - "asset_issuer": "GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG", - "paging_token": "BTC_GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG_credit_alphanum4", - "accounts": { - "authorized": 32, - "authorized_to_maintain_liabilities": 124, - "unauthorized": 6, - "claimable_balances": 18 - }, - "balances": { - "authorized": "5000.0000000", - "authorized_to_maintain_liabilities": "8000.0000000", - "unauthorized": "2000.0000000", - "claimable_balances": "1200.0000000" - }, - "flags": { - "auth_required": false, - "auth_revocable": false - } - }, - { - "_links": { - "toml": { - "href": "https://www.stellar.org/.well-known/stellar.toml" - } - }, - "asset_type": "credit_alphanum4", - "asset_code": "USD", - "asset_issuer": "GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG", - "paging_token": "USD_GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG_credit_alphanum4", - "accounts": { - "authorized": 91547871, - "authorized_to_maintain_liabilities": 45773935, - "unauthorized": 22886967, - "claimable_balances": 11443483 - }, - "balances": { - "authorized": "1000000000.0000000", - "authorized_to_maintain_liabilities": "500000000.0000000", - "unauthorized": "250000000.0000000", - "claimable_balances": "12500000.0000000" - }, - "flags": { - "auth_required": false, - "auth_revocable": false - } - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/data-for-account.md b/services/horizon/internal/docs/reference/endpoints/data-for-account.md deleted file mode 100644 index 98ff017623..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/data-for-account.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Data for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=data&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/data/ ---- - -This endpoint represents a single [data](../resources/data.md) associated with a given [account](../resources/account.md). - -## Request - -``` -GET /accounts/{account}/data/{key} -``` - -### Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `key`| required, string | Key name | `user-id`| - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36/data/user-id" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.accounts() - .accountId("GAKLBGHNHFQ3BMUYG5KU4BEWO6EYQHZHAXEWC33W34PH2RBHZDSQBD75") - .call() - .then(function (account) { - return account.data({key: 'user-id'}) - }) - .then(function(dataValue) { - console.log(dataValue) - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a value of the data field for the given account. See [data resource](../resources/data.md) for reference. - -### Example Response - -```json -{ - "value": "MTAw" -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no account whose ID matches the `account` argument or there is no data field with a given key. diff --git a/services/horizon/internal/docs/reference/endpoints/effects-all.md b/services/horizon/internal/docs/reference/endpoints/effects-all.md deleted file mode 100644 index 3150ed6fd7..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/effects-all.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: All Effects -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=effects&endpoint=all -replacement: https://developers.stellar.org/api/resources/effects/list/ ---- - -This endpoint represents all [effects](../resources/effect.md). - -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to listen for new effects as transactions happen in the Stellar network. -If called in streaming mode Horizon will start at the earliest known effect unless a `cursor` is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only stream effects created since your request time. - -## Request - -``` -GET /effects{?cursor,limit,order} -``` - -## Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/effects" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.effects() - .call() - .then(function (effectResults) { - //page 1 - console.log(effectResults.records) - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var effectHandler = function (effectResponse) { - console.log(effectResponse); -}; - -var es = server.effects() - .cursor('now') - .stream({ - onmessage: effectHandler - }) -``` - -## Response - -The list of effects. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "operation": { - "href": "/operations/279172878337" - }, - "precedes": { - "href": "/effects?cursor=279172878337-1\u0026order=asc" - }, - "succeeds": { - "href": "/effects?cursor=279172878337-1\u0026order=desc" - } - }, - "account": "GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K", - "paging_token": "279172878337-1", - "starting_balance": "10000000.0", - "type_i": 0, - "type": "account_created" - }, - { - "_links": { - "operation": { - "href": "/operations/279172878337" - }, - "precedes": { - "href": "/effects?cursor=279172878337-2\u0026order=asc" - }, - "succeeds": { - "href": "/effects?cursor=279172878337-2\u0026order=desc" - } - }, - "account": "GBRPYHIL2CI3FNQ4BXLFMNDLFJUNPU2HY3ZMFSHONUCEOASW7QC7OX2H", - "amount": "10000000.0", - "asset_type": "native", - "paging_token": "279172878337-2", - "type_i": 3, - "type": "account_debited" - } - ] - }, - "_links": { - "next": { - "href": "/effects?order=asc\u0026limit=2\u0026cursor=279172878337-2" - }, - "prev": { - "href": "/effects?order=desc\u0026limit=2\u0026cursor=279172878337-1" - }, - "self": { - "href": "/effects?order=asc\u0026limit=2\u0026cursor=" - } - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there are no effects for the given account. diff --git a/services/horizon/internal/docs/reference/endpoints/effects-for-account.md b/services/horizon/internal/docs/reference/endpoints/effects-for-account.md deleted file mode 100644 index b60fbdacd8..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/effects-for-account.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Effects for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=effects&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/effects/ ---- - -This endpoint represents all [effects](../resources/effect.md) that changed a given -[account](../resources/account.md). It will return relevant effects from the creation of the -account to the current ledger. - -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to -listen for new effects as transactions happen in the Stellar network. -If called in streaming mode Horizon will start at the earliest known effect unless a `cursor` is -set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only -stream effects created since your request time. - -## Request - -``` -GET /accounts/{account}/effects{?cursor,limit,order} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `account` | required, string | Account ID | `GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36/effects?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.effects() - .forAccount("GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36") - .call() - .then(function (effectResults) { - // page 1 - console.log(effectResults.records) - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var effectHandler = function (effectResponse) { - console.log(effectResponse); -}; - -var es = server.effects() - .forAccount("GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36") - .cursor('now') - .stream({ - onmessage: effectHandler - }) -``` - -## Response - -The list of effects. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts/GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36/effects?cursor=&limit=1&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/accounts/GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36/effects?cursor=1919197546291201-1&limit=1&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/accounts/GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36/effects?cursor=1919197546291201-1&limit=1&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-1" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-1" - } - }, - "id": "0001919197546291201-0000000001", - "paging_token": "1919197546291201-1", - "account": "GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36", - "type": "account_created", - "type_i": 0, - "created_at": "2019-03-25T22:43:38Z", - "starting_balance": "10000.0000000" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there are no effects for the given account. diff --git a/services/horizon/internal/docs/reference/endpoints/effects-for-ledger.md b/services/horizon/internal/docs/reference/endpoints/effects-for-ledger.md deleted file mode 100644 index a40f49e1f2..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/effects-for-ledger.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Effects for Ledger -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=effects&endpoint=for_ledger ---- - -Effects are the specific ways that the ledger was changed by any operation. - -This endpoint represents all [effects](../resources/effect.md) that occurred in the given [ledger](../resources/ledger.md). - -## Request - -``` -GET /ledgers/{sequence}/effects{?cursor,limit,order} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `sequence` | required, number | Ledger Sequence Number | `680777` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/ledgers/680777/effects?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.effects() - .forLedger("680777") - .call() - .then(function (effectResults) { - //page 1 - console.log(effectResults.records) - }) - .catch(function (err) { - console.log(err) - }) - -``` - -## Response - -This endpoint responds with a list of effects that occurred in the ledger. See [effect resource](../resources/effect.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/ledgers/680777/effects?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/ledgers/680777/effects?cursor=2923914950873089-3&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/ledgers/680777/effects?cursor=2923914950873089-1&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/2923914950873089" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2923914950873089-1" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2923914950873089-1" - } - }, - "id": "0002923914950873089-0000000001", - "paging_token": "2923914950873089-1", - "account": "GC4ALQ3GTT5BTHTOULHCJGAT4P3MUSPLU4OEE74BAVIJ6K443O6RVLRT", - "type": "account_created", - "type_i": 0, - "created_at": "2019-04-08T20:47:22Z", - "starting_balance": "10000.0000000" - }, - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/2923914950873089" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2923914950873089-2" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2923914950873089-2" - } - }, - "id": "0002923914950873089-0000000002", - "paging_token": "2923914950873089-2", - "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "type": "account_debited", - "type_i": 3, - "created_at": "2019-04-08T20:47:22Z", - "asset_type": "native", - "amount": "10000.0000000" - }, - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/2923914950873089" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2923914950873089-3" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2923914950873089-3" - } - }, - "id": "0002923914950873089-0000000003", - "paging_token": "2923914950873089-3", - "account": "GC4ALQ3GTT5BTHTOULHCJGAT4P3MUSPLU4OEE74BAVIJ6K443O6RVLRT", - "type": "signer_created", - "type_i": 10, - "created_at": "2019-04-08T20:47:22Z", - "weight": 1, - "public_key": "GC4ALQ3GTT5BTHTOULHCJGAT4P3MUSPLU4OEE74BAVIJ6K443O6RVLRT", - "key": "" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there are no effects for a given ledger. diff --git a/services/horizon/internal/docs/reference/endpoints/effects-for-operation.md b/services/horizon/internal/docs/reference/endpoints/effects-for-operation.md deleted file mode 100644 index dd6b880442..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/effects-for-operation.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Effects for Operation -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=effects&endpoint=for_operation -replacement: https://developers.stellar.org/api/resources/operations/effects/ ---- - -This endpoint represents all [effects](../resources/effect.md) that occurred as a result of a given [operation](../resources/operation.md). - -## Request - -``` -GET /operations/{id}/effects{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `id` | required, number | An operation ID | `1919197546291201` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/operations/1919197546291201/effects" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.effects() - .forOperation("1919197546291201") - .call() - .then(function (effectResults) { - // page 1 - console.log(effectResults.records) - }) - .catch(function (err) { - console.log(err) - }) - -``` - -## Response - -This endpoint responds with a list of effects on the ledger as a result of a given operation. See [effect resource](../resources/effect.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201/effects?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201/effects?cursor=1919197546291201-3&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201/effects?cursor=1919197546291201-1&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-1" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-1" - } - }, - "id": "0001919197546291201-0000000001", - "paging_token": "1919197546291201-1", - "account": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "type": "account_created", - "type_i": 0, - "created_at": "2019-03-25T22:43:38Z", - "starting_balance": "10000.0000000" - }, - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-2" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-2" - } - }, - "id": "0001919197546291201-0000000002", - "paging_token": "1919197546291201-2", - "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "type": "account_debited", - "type_i": 3, - "created_at": "2019-03-25T22:43:38Z", - "asset_type": "native", - "amount": "10000.0000000" - }, - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-3" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-3" - } - }, - "id": "0001919197546291201-0000000003", - "paging_token": "1919197546291201-3", - "account": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "type": "signer_created", - "type_i": 10, - "created_at": "2019-03-25T22:43:38Z", - "weight": 1, - "public_key": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "key": "" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` errors will be returned if there are no effects for operation whose ID matches the `id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/effects-for-transaction.md b/services/horizon/internal/docs/reference/endpoints/effects-for-transaction.md deleted file mode 100644 index 8bdc302d1b..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/effects-for-transaction.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Effects for Transaction -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=effects&endpoint=for_transaction -replacement: https://developers.stellar.org/api/resources/transactions/effects/ ---- - -This endpoint represents all [effects](../resources/effect.md) that occurred as a result of a given [transaction](../resources/transaction.md). - -## Request - -``` -GET /transactions/{hash}/effects{?cursor,limit,order} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `hash` | required, string | A transaction hash, hex-encoded, lowercase. | `7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/transactions/7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088/effects?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.effects() - .forTransaction("7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088") - .call() - .then(function (effectResults) { - //page 1 - console.log(effectResults.records) - }) - .catch(function (err) { - console.log(err) - }) - -``` - -## Response - -This endpoint responds with a list of effects on the ledger as a result of a given transaction. See [effect resource](../resources/effect.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088/effects?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/transactions/7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088/effects?cursor=1919197546291201-3&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/transactions/7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088/effects?cursor=1919197546291201-1&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-1" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-1" - } - }, - "id": "0001919197546291201-0000000001", - "paging_token": "1919197546291201-1", - "account": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "type": "account_created", - "type_i": 0, - "created_at": "2019-03-25T22:43:38Z", - "starting_balance": "10000.0000000" - }, - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-2" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-2" - } - }, - "id": "0001919197546291201-0000000002", - "paging_token": "1919197546291201-2", - "account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "type": "account_debited", - "type_i": 3, - "created_at": "2019-03-25T22:43:38Z", - "asset_type": "native", - "amount": "10000.0000000" - }, - { - "_links": { - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201-3" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201-3" - } - }, - "id": "0001919197546291201-0000000003", - "paging_token": "1919197546291201-3", - "account": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "type": "signer_created", - "type_i": 10, - "created_at": "2019-03-25T22:43:38Z", - "weight": 1, - "public_key": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "key": "" - } - ] - } -} -``` - -## Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there are no effects for transaction whose hash matches the `hash` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/fee-stats.md b/services/horizon/internal/docs/reference/endpoints/fee-stats.md deleted file mode 100644 index 1f8be226fc..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/fee-stats.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Fee Stats -clientData: - laboratoryUrl: -replacement: https://developers.stellar.org/api/aggregations/fee-stats/ ---- - -This endpoint gives useful information about per-operation fee stats in the last 5 ledgers. It can be used to -predict a fee set on the transaction that will be submitted to the network. - -## Request - -``` -GET /fee_stats -``` - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/fee_stats" -``` - -## Response - -Response contains the following fields: - -| Field | | -| - | - | -| last_ledger | Last ledger sequence number | -| last_ledger_base_fee | Base fee as defined in the last ledger | -| ledger_capacity_usage | Average capacity usage over the last 5 ledgers. (0 is no usage, 1.0 is completely full ledgers) | -| fee_charged | fee charged object | -| max_fee | max fee object | - -### Fee Charged Object - -Information about the fee charged for transactions in the last 5 ledgers. - -| Field | | -| - | - | -| min | Minimum fee charged over the last 5 ledgers. | -| mode | Mode fee charged over the last 5 ledgers. | -| p10 | 10th percentile fee charged over the last 5 ledgers. | -| p20 | 20th percentile fee charged over the last 5 ledgers. | -| p30 | 30th percentile fee charged over the last 5 ledgers. | -| p40 | 40th percentile fee charged over the last 5 ledgers. | -| p50 | 50th percentile fee charged over the last 5 ledgers. | -| p60 | 60th percentile fee charged over the last 5 ledgers. | -| p70 | 70th percentile fee charged over the last 5 ledgers. | -| p80 | 80th percentile fee charged over the last 5 ledgers. | -| p90 | 90th percentile fee charged over the last 5 ledgers. | -| p95 | 95th percentile fee charged over the last 5 ledgers. | -| p99 | 99th percentile fee charged over the last 5 ledgers. | - -Note: The difference between `fee_charged` and `max_fee` is that the former -represents the actual fee paid for the transaction while `max_fee` represents -the maximum bid the transaction creator was willing to pay for the transaction. - -### Max Fee Object - -Information about max fee bid for transactions over the last 5 ledgers. - -| Field | | -| - | - | -| min | Minimum (lowest) value of the maximum fee bid over the last 5 ledgers. | -| mode | Mode max fee over the last 5 ledgers. | -| p10 | 10th percentile max fee over the last 5 ledgers. | -| p20 | 20th percentile max fee over the last 5 ledgers. | -| p30 | 30th percentile max fee over the last 5 ledgers. | -| p40 | 40th percentile max fee over the last 5 ledgers. | -| p50 | 50th percentile max fee over the last 5 ledgers. | -| p60 | 60th percentile max fee over the last 5 ledgers. | -| p70 | 70th percentile max fee over the last 5 ledgers. | -| p80 | 80th percentile max fee over the last 5 ledgers. | -| p90 | 90th percentile max fee over the last 5 ledgers. | -| p95 | 95th percentile max fee over the last 5 ledgers. | -| p99 | 99th percentile max fee over the last 5 ledgers. | - - -### Example Response - -```json -{ - "last_ledger": "22606298", - "last_ledger_base_fee": "100", - "ledger_capacity_usage": "0.97", - "fee_charged": { - "max": "100", - "min": "100", - "mode": "100", - "p10": "100", - "p20": "100", - "p30": "100", - "p40": "100", - "p50": "100", - "p60": "100", - "p70": "100", - "p80": "100", - "p90": "100", - "p95": "100", - "p99": "100" - }, - "max_fee": { - "max": "100000", - "min": "100", - "mode": "100", - "p10": "100", - "p20": "100", - "p30": "100", - "p40": "100", - "p50": "100", - "p60": "100", - "p70": "100", - "p80": "100", - "p90": "15000", - "p95": "100000", - "p99": "100000" - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/ledgers-all.md b/services/horizon/internal/docs/reference/endpoints/ledgers-all.md deleted file mode 100644 index 242c0df697..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/ledgers-all.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: All Ledgers -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=ledgers&endpoint=all -replacement: https://developers.stellar.org/api/resources/ledgers/ ---- - -This endpoint represents all [ledgers](../resources/ledger.md). -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to get notifications as ledgers are closed by the Stellar network. -If called in streaming mode Horizon will start at the earliest known ledger unless a `cursor` is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only stream ledgers created since your request time. - -## Request - -``` -GET /ledgers{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -# Retrieve the 200 latest ledgers, ordered chronologically -curl "https://horizon-testnet.stellar.org/ledgers?limit=200&order=desc" -``` - -### JavaScript Example Request - -```javascript -server.ledgers() - .call() - .then(function (ledgerResult) { - // page 1 - console.log(ledgerResult.records) - return ledgerResult.next() - }) - .then(function (ledgerResult) { - // page 2 - console.log(ledgerResult.records) - }) - .catch(function(err) { - console.log(err) - }) -``` - - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var ledgerHandler = function (ledgerResponse) { - console.log(ledgerResponse); -}; - -var es = server.ledgers() - .cursor('now') - .stream({ - onmessage: ledgerHandler -}) -``` - -## Response - -This endpoint responds with a list of ledgers. See [ledger resource](../resources/ledger.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "effects": { - "href": "/ledgers/1/effects/{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "/ledgers/1/operations/{?cursor,limit,order}", - "templated": true - }, - "self": { - "href": "/ledgers/1" - }, - "transactions": { - "href": "/ledgers/1/transactions/{?cursor,limit,order}", - "templated": true - } - }, - "id": "e8e10918f9c000c73119abe54cf089f59f9015cc93c49ccf00b5e8b9afb6e6b1", - "paging_token": "4294967296", - "hash": "e8e10918f9c000c73119abe54cf089f59f9015cc93c49ccf00b5e8b9afb6e6b1", - "sequence": 1, - "transaction_count": 0, - "successful_transaction_count": 0, - "failed_transaction_count": 0, - "operation_count": 0, - "tx_set_operation_count": 0, - "closed_at": "1970-01-01T00:00:00Z", - "total_coins": "100000000000.0000000", - "fee_pool": "0.0000000", - "base_fee_in_stroops": 100, - "base_reserve_in_stroops": 100000000, - "max_tx_set_size": 50 - }, - { - "_links": { - "effects": { - "href": "/ledgers/2/effects/{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "/ledgers/2/operations/{?cursor,limit,order}", - "templated": true - }, - "self": { - "href": "/ledgers/2" - }, - "transactions": { - "href": "/ledgers/2/transactions/{?cursor,limit,order}", - "templated": true - } - }, - "id": "e12e5809ab8c59d8256e691cb48a024dd43960bc15902d9661cd627962b2bc71", - "paging_token": "8589934592", - "hash": "e12e5809ab8c59d8256e691cb48a024dd43960bc15902d9661cd627962b2bc71", - "prev_hash": "e8e10918f9c000c73119abe54cf089f59f9015cc93c49ccf00b5e8b9afb6e6b1", - "sequence": 2, - "transaction_count": 0, - "successful_transaction_count": 0, - "failed_transaction_count": 0, - "operation_count": 0, - "closed_at": "2015-07-16T23:49:00Z", - "total_coins": "100000000000.0000000", - "fee_pool": "0.0000000", - "base_fee_in_stroops": 100, - "base_reserve_in_stroops": 100000000, - "max_tx_set_size": 100 - } - ] - }, - "_links": { - "next": { - "href": "/ledgers?order=asc&limit=2&cursor=8589934592" - }, - "prev": { - "href": "/ledgers?order=desc&limit=2&cursor=4294967296" - }, - "self": { - "href": "/ledgers?order=asc&limit=2&cursor=" - } - } -} -``` - -### Example Streaming Event - -```json -{ - "_links": { - "effects": { - "href": "/ledgers/69859/effects/{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "/ledgers/69859/operations/{?cursor,limit,order}", - "templated": true - }, - "self": { - "href": "/ledgers/69859" - }, - "transactions": { - "href": "/ledgers/69859/transactions/{?cursor,limit,order}", - "templated": true - } - }, - "id": "4db1e4f145e9ee75162040d26284795e0697e2e84084624e7c6c723ebbf80118", - "paging_token": "300042120331264", - "hash": "4db1e4f145e9ee75162040d26284795e0697e2e84084624e7c6c723ebbf80118", - "prev_hash": "4b0b8bace3b2438b2404776ce57643966855487ba6384724a3c664c7aa4cd9e4", - "sequence": 69859, - "transaction_count": 0, - "successful_transaction_count": 0, - "failed_transaction_count": 0, - "operation_count": 0, - "closed_at": "2015-07-20T15:51:52Z", - "total_coins": "100000000000.0000000", - "fee_pool": "0.0025600", - "base_fee_in_stroops": 100, - "base_reserve_in_stroops": "100000000", - "max_tx_set_size": 50 -} -``` - -## Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/ledgers-single.md b/services/horizon/internal/docs/reference/endpoints/ledgers-single.md deleted file mode 100644 index f16c9485d8..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/ledgers-single.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Ledger Details -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=ledgers&endpoint=single -replacement: https://developers.stellar.org/api/resources/ledgers/single/ ---- - -The ledger details endpoint provides information on a single [ledger](../resources/ledger.md). - -## Request - -``` -GET /ledgers/{sequence} -``` - -### Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `sequence` | required, number | Ledger Sequence | `69859` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/ledgers/69859" -``` - -### JavaScript Example Request - -```js -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.ledgers() - .ledger('69858') - .call() - .then(function(ledgerResult) { - console.log(ledgerResult) - }) - .catch(function(err) { - console.log(err) - }) - -``` -## Response - -This endpoint responds with a single Ledger. See [ledger resource](../resources/ledger.md) for reference. - -### Example Response - -```json -{ - "_links": { - "effects": { - "href": "/ledgers/69859/effects/{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "/ledgers/69859/operations/{?cursor,limit,order}", - "templated": true - }, - "self": { - "href": "/ledgers/69859" - }, - "transactions": { - "href": "/ledgers/69859/transactions/{?cursor,limit,order}", - "templated": true - } - }, - "id": "4db1e4f145e9ee75162040d26284795e0697e2e84084624e7c6c723ebbf80118", - "paging_token": "300042120331264", - "hash": "4db1e4f145e9ee75162040d26284795e0697e2e84084624e7c6c723ebbf80118", - "prev_hash": "4b0b8bace3b2438b2404776ce57643966855487ba6384724a3c664c7aa4cd9e4", - "sequence": 69859, - "transaction_count": 0, - "successful_transaction_count": 0, - "failed_transaction_count": 0, - "operation_count": 0, - "tx_set_operation_count": 0, - "closed_at": "2015-07-20T15:51:52Z", - "total_coins": "100000000000.0000000", - "fee_pool": "0.0025600", - "base_fee_in_stroops": 100, - "base_reserve_in_stroops": 100000000, - "max_tx_set_size": 50 -} -``` - -## Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no ledger whose sequence number matches the `sequence` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/metrics.md b/services/horizon/internal/docs/reference/endpoints/metrics.md deleted file mode 100644 index c0d1fba62b..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/metrics.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Metrics ---- - -The metrics endpoint returns a host of [Prometheus](https://prometheus.io/) metrics for monitoring the health of the underlying Horizon process. - -There is an [official Grafana Dashboard](https://grafana.com/grafana/dashboards/13793) to easily visualize those metrics. - -Since Horizon 1.0.0 this endpoint is not part of the public API. It's available in the internal server (listening on the internal port set via `ADMIN_PORT` env variable or `--admin-port` CLI param). - -## Request - -``` -GET /metrics -``` - -### curl Example Request - -Assuming a local Horizon instance is running with an admin port of 9090 (i.e. `ADMIN_PORT=9090` env variable or `--admin-port=9090`) - -```sh -curl "https://localhost:9090/metrics" -``` - - -## Response - -The `/metrics` endpoint returns a [Prometheus text-formated](https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format) response. It is meant to be scraped by Prometheus. - -Below, each section of related data points are grouped together and annotated (***note**: this endpoint returns ALL this data in one response*). - - -#### Goroutines - -Horizon utilizes Go's built in concurrency primitives ([goroutines](https://gobyexample.com/goroutines) and [channels](https://gobyexample.com/channels)). The `goroutine` metric monitors the number of currently running goroutines on this Horizon's process. - - -#### History - -Horizon maintains its own database (postgres), a verbose and user friendly account of activity on the Stellar network. - -| Metric | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| history.elder_ledger | The sequence number of the oldest ledger recorded in Horizon's database. | -| history.latest_ledger | The sequence number of the youngest (most recent) ledger recorded in Horizon's database. | -| history.open_connections | The number of open connections to the Horizon database. | - - -#### Ingester - -Ingester represents metrics specific to Horizon's [ingestion](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/reference/admin.md#ingesting-stellar-core-data) process, or the process by which Horizon consumes transaction results from a connected Stellar Core instance. - -| Metric | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| ingester.clear_ledger | The count and rate of clearing (per ledger) for this Horizon process. | -| ingester.ingest_ledger | The count and rate of ingestion (per ledger) for this Horizon process. | - -These metrics contain useful [sub metrics](#sub-metrics). - - -#### Logging - -Horizon utilizes the standard `debug`, `error`, etc. levels of logging. This metric outputs stats for each level of log message produced, useful for a high-level monitoring of "is my Horizon instance functioning properly?" In order of increasing severity: - -* logging.debug -* logging.info -* logging.warning -* logging.error -* logging.panic - -These metrics contain useful [sub metrics](#sub-metrics). - -#### Requests - -Requests represent an overview of Horizon's incoming traffic. - -These metrics contain useful [sub metrics](#sub-metrics). - -| Metric | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| requests.failed | Failed requests are those that return a status code in [400, 600). | -| requests.succeeded | Successful requests are those that return a status code in [200, 400). | -| requests.total | Total number of received requests. | - -#### Stellar Core -As noted above, Horizon relies on Stellar Core to stay in sync with the Stellar network. These metrics are specific to the underlying Stellar Core instance. - -| Metric | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| stellar_core.latest_ledger | The sequence number of the latest (most recent) ledger recorded in Stellar Core's database. | -| stellar_core.open_connections | The number of open connections to the Stellar Core postgres database. | - -#### Transaction Submission - -Horizon does not submit transactions directly to the Stellar network. Instead, it sequences transactions and sends the base64 encoded, XDR serialized blob to its connected Stellar Core instance. - -##### Horizon Transaction Sequencing and Submission - -The following is a simplified version of the transaction submission process that glosses over the finer details. To dive deeper, check out the [source code](https://github.com/stellar/go/tree/master/services/horizon/internal/txsub). - -Horizon's sequencing mechanism consists of a [manager](https://github.com/stellar/go/blob/master/services/horizon/internal/txsub/sequence/manager.go) that keeps track of [submission queues](https://github.com/stellar/go/blob/master/services/horizon/internal/txsub/sequence/queue.go) for a set of addresses. A submission queue is a priority queue, prioritized by minimum transaction sequence number, that holds a set of pending transactions for an account. A pending transaction is represented as an object with a sequence number and a channel. Periodically, this queue is updated, popping off finished transactions, sending down the transaction's channel a successful/failure response. - -These metrics contain useful [sub metrics](#sub-metrics). - - -| Metric | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| txsub.buffered | The count of submissions buffered behind this Horizon's submission queue. | -| txsub.failed | The rate of failed transactions that have been submitted to this Horizon. | -| txsub.open | The count of "open" submissions (i.e.) submissions whose transactions haven't been confirmed successful or failed. | -| txsub.succeeded | The rate of successful transactions that have been submitted to this Horizon. | -| txsub.total | Both the rate and count of all transactions submitted to this Horizon. | - -### Sub Metrics -Various sub metrics related to a certain metric's performance. - -| Metric | Description | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `1m.rate`, `5min.rate`, `etc.` | The per-minute moving average rate of events per second at the given time interval. | -| `75%`, `95%`, `etc.` | Counts at different percentiles. | -| `count` | Sum total of a certain metric value. | -| `max`, `mean`, `etc.` | Common statistic calculations. | - - - - diff --git a/services/horizon/internal/docs/reference/endpoints/offer-details.md b/services/horizon/internal/docs/reference/endpoints/offer-details.md deleted file mode 100644 index 978d88f5f4..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/offer-details.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Offer Details -replacement: https://developers.stellar.org/api/resources/offers/ ---- - -Returns information and links relating to a single [offer](../resources/offer.md). - -## Request - -``` -GET /offers/{offer} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `offer` | required, string | Offer ID | `126628073` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/offers/1347876" -``` - - - -## Response - -This endpoint responds with the details of a single offer for a given ID. See [offer resource](../resources/offer.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/offers/1347876" - }, - "offer_maker": { - "href": "https://horizon-testnet.stellar.org/accounts/GAQHWQYBBW272OOXNQMMLCA5WY2XAZPODGB7Q3S5OKKIXVESKO55ZQ7C" - } - }, - "id": "1347876", - "paging_token": "1347876", - "seller": "GAQHWQYBBW272OOXNQMMLCA5WY2XAZPODGB7Q3S5OKKIXVESKO55ZQ7C", - "selling": { - "asset_type": "credit_alphanum4", - "asset_code": "DSQ", - "asset_issuer": "GBDQPTQJDATT7Z7EO4COS4IMYXH44RDLLI6N6WIL5BZABGMUOVMLWMQF" - }, - "buying": { - "asset_type": "credit_alphanum4", - "asset_code": "USD", - "asset_issuer": "GAA4MFNZGUPJAVLWWG6G5XZJFZDHLKQNG3Q6KB24BAD6JHNNVXDCF4XG" - }, - "amount": "60.4544008", - "price_r": { - "n": 84293, - "d": 2000000 - }, - "price": "0.0421465", - "last_modified_ledger": 1429506, - "last_modified_time": "2019-10-29T22:08:23Z" -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no offer whose ID matches the `offer` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/offers-for-account.md b/services/horizon/internal/docs/reference/endpoints/offers-for-account.md deleted file mode 100644 index 906e302b6a..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/offers-for-account.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Offers for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=offers&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/offers/ ---- - -People on the Stellar network can make [offers](../resources/offer.md) to buy or sell assets. This -endpoint represents all the offers a particular account makes. - -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to -listen as offers are processed in the Stellar network. If called in streaming mode Horizon will -start at the earliest known offer unless a `cursor` is set. In that case it will start from the -`cursor`. You can also set `cursor` value to `now` to only stream offers created since your request -time. - -## Request - -``` -GET /accounts/{account}/offers{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `account` | required, string | Account ID | `GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF` | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/offers" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.offers('accounts', 'GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF') - .call() - .then(function (offerResult) { - console.log(offerResult); - }) - .catch(function (err) { - console.error(err); - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var offerHandler = function (offerResponse) { - console.log(offerResponse); -}; - -var es = server.offers('accounts', 'GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF') - .cursor('now') - .stream({ - onmessage: offerHandler - }) -``` - -## Response - -The list of offers. - -**Note:** a response of 200 with an empty records array may either mean there are no offers for -`account_id` or `account_id` does not exist. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/offers?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/offers?cursor=5443256&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/offers?cursor=5443256&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/offers/5443256" - }, - "offer_maker": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF" - } - }, - "id": "5443256", - "paging_token": "5443256", - "seller": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "selling": { - "asset_type": "native" - }, - "buying": { - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR" - }, - "amount": "10.0000000", - "price_r": { - "n": 1, - "d": 1 - }, - "price": "1.0000000", - "last_modified_ledger": 694974, - "last_modified_time": "2019-04-09T17:14:22Z" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/offers.md b/services/horizon/internal/docs/reference/endpoints/offers.md deleted file mode 100644 index 6f8273487e..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/offers.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Offers -replacement: https://developers.stellar.org/api/resources/offers/list/ ---- - -People on the Stellar network can make [offers](../resources/offer.md) to buy or sell assets. This -endpoint represents all the current offers, allowing filtering by `seller`, `selling_asset` or `buying_asset`. - -## Request - -``` -GET /offers{?selling_asset_type,selling_asset_issuer,selling_asset_code,buying_asset_type,buying_asset_issuer,buying_asset_code,seller,cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?seller` | optional, string | Account ID of the offer creator | `GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36` | -| `?selling` | optional, string | Asset being sold | `native` or `EUR:GD6VWBXI6NY3AOOR55RLVQ4MNIDSXE5JSAVXUTF35FRRI72LYPI3WL6Z` | -| `?buying` | optional, string | Asset being bought | `native` or `USD:GD6VWBXI6NY3AOOR55RLVQ4MNIDSXE5JSAVXUTF35FRRI72LYPI3WL6Z` | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/offers{?selling_asset_type,selling_asset_issuer,selling_asset_code,buying_asset_type,buying_asset_issuer,buying_asset_code,seller,cursor,limit,order}" -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -## Response - -The list of offers. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/offers?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/offers?cursor=5443256&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/offers?cursor=5443256&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/offers/5443256" - }, - "offer_maker": { - "href": "https://horizon-testnet.stellar.org/" - } - }, - "id": "5443256", - "paging_token": "5443256", - "seller": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "selling": { - "asset_type": "native" - }, - "buying": { - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR" - }, - "amount": "10.0000000", - "price_r": { - "n": 1, - "d": 1 - }, - "price": "1.0000000", - "last_modified_ledger": 694974, - "last_modified_time": "2019-04-09T17:14:22Z" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/operations-all.md b/services/horizon/internal/docs/reference/endpoints/operations-all.md deleted file mode 100644 index c44f9f4fc6..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/operations-all.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: All Operations -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=operations&endpoint=all -replacement: https://developers.stellar.org/api/resources/operations/ ---- - -This endpoint represents [operations](../resources/operation.md) that are part of successfully validated [transactions](../resources/transaction.md). -Please note that this endpoint returns operations that are part of failed transactions if `include_failed` parameter is `true` -and Horizon is ingesting failed transactions. -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to listen as operations are processed in the Stellar network. -If called in streaming mode Horizon will start at the earliest known operation unless a `cursor` is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only stream operations created since your request time. - -## Request - -``` -GET /operations{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include operations of failed transactions in results. | `true` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the operations in the response. | `transactions` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/operations?limit=200&order=desc" -``` - -### JavaScript Example Request - -```js -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.operations() - .call() - .then(function (operationsResult) { - //page 1 - console.log(operationsResult.records) - return operationsResult.next() - }) - .then(function (operationsResult) { - //page 2 - console.log(operationsResult.records) - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var operationHandler = function (operationResponse) { - console.log(operationResponse); -}; - -var es = server.operations() - .cursor('now') - .stream({ - onmessage: operationHandler - }) -``` - -## Response - -This endpoint responds with a list of operations. See [operation resource](../resources/operation.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "effects": { - "href": "/operations/77309415424/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=77309415424&order=asc" - }, - "self": { - "href": "/operations/77309415424" - }, - "succeeds": { - "href": "/operations?cursor=77309415424&order=desc" - }, - "transactions": { - "href": "/transactions/77309415424" - } - }, - "account": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "funder": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "id": 77309415424, - "paging_token": "77309415424", - "starting_balance": "1000.0000000", - "transaction_successful": true, - "type_i": 0, - "type": "create_account" - }, - { - "_links": { - "effects": { - "href": "/operations/463856472064/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=463856472064&order=asc" - }, - "self": { - "href": "/operations/463856472064" - }, - "succeeds": { - "href": "/operations?cursor=463856472064&order=desc" - }, - "transactions": { - "href": "/transactions/463856472064" - } - }, - "account": "GC2ADYAIPKYQRGGUFYBV2ODJ54PY6VZUPKNCWWNX2C7FCJYKU4ZZNKVL", - "funder": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "id": 463856472064, - "paging_token": "463856472064", - "starting_balance": "1000.0000000", - "transaction_successful": true, - "type_i": 0, - "type": "create_account" - } - ] - }, - "_links": { - "next": { - "href": "/operations?order=asc&limit=2&cursor=463856472064" - }, - "prev": { - "href": "/operations?order=desc&limit=2&cursor=77309415424" - }, - "self": { - "href": "/operations?order=asc&limit=2&cursor=" - } - } -} -``` - -### Example Streaming Event - -```json -{ - "_links": { - "effects": { - "href": "/operations/77309415424/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=77309415424&order=asc" - }, - "self": { - "href": "/operations/77309415424" - }, - "succeeds": { - "href": "/operations?cursor=77309415424&order=desc" - }, - "transactions": { - "href": "/transactions/77309415424" - } - }, - "account": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "funder": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "id": 77309415424, - "paging_token": "77309415424", - "starting_balance": "1000.0000000", - "transaction_successful": true, - "type_i": 0, - "type": "create_account" -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/operations-for-account.md b/services/horizon/internal/docs/reference/endpoints/operations-for-account.md deleted file mode 100644 index 0b44988134..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/operations-for-account.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Operations for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=operations&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/offers/ ---- - -This endpoint represents successful [operations](../resources/operation.md) that were included in valid [transactions](../resources/transaction.md) that affected a particular [account](../resources/account.md). - -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to listen for new operations that affect a given account as they happen. -If called in streaming mode Horizon will start at the earliest known operation unless a `cursor` is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only stream operations created since your request time. - -## Request - -``` -GET /accounts/{account}/operations{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `account`| required, string | Account ID | `GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36`| -| `?cursor`| optional, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc`| The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include operations of failed transactions in results. | `true` | | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the operations in the response. | `transactions` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36/operations" -``` - -### JavaScript Example Request - -```js -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.operations() - .forAccount("GAKLBGHNHFQ3BMUYG5KU4BEWO6EYQHZHAXEWC33W34PH2RBHZDSQBD75") - .call() - .then(function (operationsResult) { - console.log(operationsResult.records) - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var operationHandler = function (operationResponse) { - console.log(operationResponse); -}; - -var es = server.operations() - .forAccount("GAKLBGHNHFQ3BMUYG5KU4BEWO6EYQHZHAXEWC33W34PH2RBHZDSQBD75") - .cursor('now') - .stream({ - onmessage: operationHandler - }) -``` - -## Response - -This endpoint responds with a list of operations that affected the given account. See [operation resource](../resources/operation.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "effects": { - "href": "/operations/46316927324160/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=46316927324160&order=asc" - }, - "self": { - "href": "/operations/46316927324160" - }, - "succeeds": { - "href": "/operations?cursor=46316927324160&order=desc" - }, - "transactions": { - "href": "/transactions/46316927324160" - } - }, - "account": "GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB", - "funder": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "id": 46316927324160, - "paging_token": "46316927324160", - "starting_balance": 1e+09, - "transaction_successful": true, - "type_i": 0, - "type": "create_account" - } - ] - }, - "_links": { - "next": { - "href": "/accounts/GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB/operations?order=asc&limit=10&cursor=46316927324160" - }, - "prev": { - "href": "/accounts/GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB/operations?order=desc&limit=10&cursor=46316927324160" - }, - "self": { - "href": "/accounts/GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB/operations?order=asc&limit=10&cursor=" - } - } -} -``` - -### Example Streaming Event - -```json -{ - "_links": { - "effects": { - "href": "/operations/77309415424/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=77309415424&order=asc" - }, - "self": { - "href": "/operations/77309415424" - }, - "succeeds": { - "href": "/operations?cursor=77309415424&order=desc" - }, - "transactions": { - "href": "/transactions/77309415424" - } - }, - "account": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "funder": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "id": 77309415424, - "paging_token": "77309415424", - "starting_balance": "1000.0000000", - "transaction_successful": true, - "type_i": 0, - "type": "create_account" -} -``` - - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no account whose ID matches the `account` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/operations-for-ledger.md b/services/horizon/internal/docs/reference/endpoints/operations-for-ledger.md deleted file mode 100644 index 85155a5726..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/operations-for-ledger.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Operations for Ledger -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=operations&endpoint=for_ledger -replacement: https://developers.stellar.org/api/resources/ledgers/operations/ ---- - -This endpoint returns successful [operations](../resources/operation.md) that occurred in a given [ledger](../resources/ledger.md). - -## Request - -``` -GET /ledgers/{sequence}/operations{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `sequence` | required, number | Ledger Sequence | `681637` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include operations of failed transactions in results. | `true` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the operations in the response. | `transactions` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/ledgers/681637/operations?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.operations() - .forLedger("681637") - .call() - .then(function (operationsResult) { - console.log(operationsResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a list of operations in a given ledger. See [operation resource](../resources/operation.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/ledgers/681637/operations?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/ledgers/681637/operations?cursor=2927608622751745&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/ledgers/681637/operations?cursor=2927608622747649&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622747649" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622747649/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2927608622747649" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2927608622747649" - } - }, - "id": "2927608622747649", - "paging_token": "2927608622747649", - "transaction_successful": true, - "source_account": "GCGXZPH2QNKJP4GI2J77EFQQUMP3NYY4PCUZ4UPKHR2XYBKRUYKQ2DS6", - "type": "payment", - "type_i": 1, - "created_at": "2019-04-08T21:59:27Z", - "transaction_hash": "4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a", - "asset_type": "native", - "from": "GCGXZPH2QNKJP4GI2J77EFQQUMP3NYY4PCUZ4UPKHR2XYBKRUYKQ2DS6", - "to": "GDGEQS64ISS6Y2KDM5V67B6LXALJX4E7VE4MIA54NANSUX5MKGKBZM5G", - "amount": "404.0000000" - }, - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622751745" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/fdabcee816bd439dd1d20bcb0abab5aa939c15cca5fccc1db060ba6096a5e0ed" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622751745/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2927608622751745" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2927608622751745" - } - }, - "id": "2927608622751745", - "paging_token": "2927608622751745", - "transaction_successful": true, - "source_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "type": "create_account", - "type_i": 0, - "created_at": "2019-04-08T21:59:27Z", - "transaction_hash": "fdabcee816bd439dd1d20bcb0abab5aa939c15cca5fccc1db060ba6096a5e0ed", - "starting_balance": "10000.0000000", - "funder": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "account": "GCD5UL3DHC5TQRQVJKFTM66CLFTHGULOQ2HEAXNSA2JWUGBCT36BP55F" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no ledger whose ID matches the `id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/operations-for-transaction.md b/services/horizon/internal/docs/reference/endpoints/operations-for-transaction.md deleted file mode 100644 index 14ef13f850..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/operations-for-transaction.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Operations for Transaction -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=operations&endpoint=for_transaction -replacement: https://developers.stellar.org/api/resources/transactions/operations/ ---- - -This endpoint represents successful [operations](../resources/operation.md) that are part of a given [transaction](../resources/transaction.md). - -### Warning - failed transactions - -The "Operations for Transaction" endpoint returns a list of operations in a successful or failed -transaction. Make sure to always check the operation status in this endpoint using -`transaction_successful` field! - -## Request - -``` -GET /transactions/{hash}/operations{?cursor,limit,order} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `hash` | required, string | A transaction hash, hex-encoded, lowercase. | `4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the operations in the response. | `transactions` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a/operations?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.operations() - .forTransaction("4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a") - .call() - .then(function (operationsResult) { - console.log(operationsResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a list of operations that are part of a given transaction. See [operation resource](../resources/operation.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a/operations?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a/operations?cursor=2927608622747649&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a/operations?cursor=2927608622747649&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622747649" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622747649/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2927608622747649" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2927608622747649" - } - }, - "id": "2927608622747649", - "paging_token": "2927608622747649", - "transaction_successful": true, - "source_account": "GCGXZPH2QNKJP4GI2J77EFQQUMP3NYY4PCUZ4UPKHR2XYBKRUYKQ2DS6", - "type": "payment", - "type_i": 1, - "created_at": "2019-04-08T21:59:27Z", - "transaction_hash": "4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a", - "asset_type": "native", - "from": "GCGXZPH2QNKJP4GI2J77EFQQUMP3NYY4PCUZ4UPKHR2XYBKRUYKQ2DS6", - "to": "GDGEQS64ISS6Y2KDM5V67B6LXALJX4E7VE4MIA54NANSUX5MKGKBZM5G", - "amount": "404.0000000" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no account whose ID matches the `hash` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/operations-single.md b/services/horizon/internal/docs/reference/endpoints/operations-single.md deleted file mode 100644 index 2693cd4d41..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/operations-single.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Operation Details -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=operations&endpoint=single -replacement: https://developers.stellar.org/api/resources/operations/single/ ---- - -The operation details endpoint provides information on a single -[operation](../resources/operation.md). The operation ID provided in the `id` argument specifies -which operation to load. - -### Warning - failed transactions - -Operations can be part of successful or failed transactions (failed transactions are also included -in Stellar ledger). Always check operation status using `transaction_successful` field! - -## Request - -``` -GET /operations/{id} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `id` | required, number | An operation ID. | 2927608622747649 | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the operations in the response. | `transactions` | - -### curl Example Request - -```sh -curl https://horizon-testnet.stellar.org/operations/2927608622747649 -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.operations() - .operation('2927608622747649') - .call() - .then(function (operationsResult) { - console.log(operationsResult) - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a single Operation. See [operation resource](../resources/operation.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622747649" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2927608622747649/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2927608622747649" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2927608622747649" - } - }, - "id": "2927608622747649", - "paging_token": "2927608622747649", - "transaction_successful": true, - "source_account": "GCGXZPH2QNKJP4GI2J77EFQQUMP3NYY4PCUZ4UPKHR2XYBKRUYKQ2DS6", - "type": "payment", - "type_i": 1, - "created_at": "2019-04-08T21:59:27Z", - "transaction_hash": "4a3365180521e16b478d9f0c9198b97a9434fc9cb07b34f83ecc32fc54d0ca8a", - "asset_type": "native", - "from": "GCGXZPH2QNKJP4GI2J77EFQQUMP3NYY4PCUZ4UPKHR2XYBKRUYKQ2DS6", - "to": "GDGEQS64ISS6Y2KDM5V67B6LXALJX4E7VE4MIA54NANSUX5MKGKBZM5G", - "amount": "404.0000000" -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if the - there is no operation that matches the ID argument, i.e. the operation does not exist. diff --git a/services/horizon/internal/docs/reference/endpoints/orderbook-details.md b/services/horizon/internal/docs/reference/endpoints/orderbook-details.md deleted file mode 100644 index f408aef7df..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/orderbook-details.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Orderbook Details -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=order_book&endpoint=details -replacement: https://developers.stellar.org/api/aggregations/order-books/ ---- - -People on the Stellar network can make [offers](../resources/offer.md) to buy or sell assets. -These offers are summarized by the assets being bought and sold in -[orderbooks](../resources/orderbook.md). - -Horizon will return, for each orderbook, a summary of the orderbook and the bids and asks -associated with that orderbook. - -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to -listen as offers are processed in the Stellar network. If called in streaming mode Horizon will -start at the earliest known offer unless a `cursor` is set. In that case it will start from the -`cursor`. You can also set `cursor` value to `now` to only stream offers created since your request -time. - -## Request - -``` -GET /order_book?selling_asset_type={selling_asset_type}&selling_asset_code={selling_asset_code}&selling_asset_issuer={selling_asset_issuer}&buying_asset_type={buying_asset_type}&buying_asset_code={buying_asset_code}&buying_asset_issuer={buying_asset_issuer}&limit={limit} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `selling_asset_type` | required, string | Type of the Asset being sold | `native` | -| `selling_asset_code` | optional, string | Code of the Asset being sold | `USD` | -| `selling_asset_issuer` | optional, string | Account ID of the issuer of the Asset being sold | `GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36` | -| `buying_asset_type` | required, string | Type of the Asset being bought | `credit_alphanum4` | -| `buying_asset_code` | optional, string | Code of the Asset being bought | `BTC` | -| `buying_asset_issuer` | optional, string | Account ID of the issuer of the Asset being bought | `GD6VWBXI6NY3AOOR55RLVQ4MNIDSXE5JSAVXUTF35FRRI72LYPI3WL6Z` | -| `limit` | optional, string | Limit the number of items returned | `20` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/order_book?selling_asset_type=native&buying_asset_type=credit_alphanum4&buying_asset_code=FOO&buying_asset_issuer=GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG&limit=20" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.orderbook(new StellarSdk.Asset.native(), new StellarSdk.Asset('FOO', 'GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG')) - .call() - .then(function(resp) { - console.log(resp); - }) - .catch(function(err) { - console.log(err); - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var orderbookHandler = function (orderbookResponse) { - console.log(orderbookResponse); -}; - -var es = server.orderbook(new StellarSdk.Asset.native(), new StellarSdk.Asset('FOO', 'GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG')) - .cursor('now') - .stream({ - onmessage: orderbookHandler - }) -``` - -## Response - -The summary of the orderbook and its bids and asks. - -## Example Response -```json -{ - "bids": [ - { - "price_r": { - "n": 100000000, - "d": 12953367 - }, - "price": "7.7200005", - "amount": "12.0000000" - } - ], - "asks": [ - { - "price_r": { - "n": 194, - "d": 25 - }, - "price": "7.7600000", - "amount": "238.4804125" - } - ], - "base": { - "asset_type": "native" - }, - "counter": { - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG" - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/path-finding-strict-receive.md b/services/horizon/internal/docs/reference/endpoints/path-finding-strict-receive.md deleted file mode 100644 index 8e8444878d..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/path-finding-strict-receive.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Strict Receive Payment Paths -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=paths&endpoint=all -replacement: https://developers.stellar.org/api/aggregations/paths/strict-receive/ ---- - -The Stellar Network allows payments to be made across assets through _path payments_. A path -payment specifies a series of assets to route a payment through, from source asset (the asset -debited from the payer) to destination asset (the asset credited to the payee). - -A [Path Payment Strict Receive](../../../guides/concepts/list-of-operations.html#path-payment-strict-receive) allows a user to specify the *amount of the asset received*. The amount sent varies based on offers in the order books. If you would like to search for a path specifying the amount to be sent, use the [Find Payment Paths (Strict Send)](./path-finding-strict-send.html). - -A strict receive path search is specified using: - -- The source account id or source assets. -- The asset and amount that the destination account should receive. - -As part of the search, horizon will load a list of assets available to the source account id and -will find any payment paths from those source assets to the desired destination asset. The search's -amount parameter will be used to determine if a given path can satisfy a payment of the -desired amount. - -## Request - -``` -GET /paths/strict-receive?source_account={sa}&destination_asset_type={at}&destination_asset_code={ac}&destination_asset_issuer={di}&destination_amount={amount}&destination_account={da} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?source_account` | string | The sender's account id. Any returned path must use an asset that the sender has a trustline to. | `GARSFJNXJIHO6ULUBK3DBYKVSIZE7SC72S5DYBCHU7DKL22UXKVD7MXP` | -| `?source_assets` | string | A comma separated list of assets. Any returned path must use an asset included in this list | `USD:GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V,native` | -| `?destination_account` | string | The destination account that any returned path should use | `GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V` | -| `?destination_asset_type` | string | The type of the destination asset | `credit_alphanum4` | -| `?destination_asset_code` | required if `destination_asset_type` is not `native`, string | The destination asset code, if destination_asset_type is not "native" | `USD` | -| `?destination_asset_issuer` | required if `destination_asset_type` is not `native`, string | The issuer for the destination asset, if destination_asset_type is not "native" | `GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V` | -| `?destination_amount` | string | The amount, denominated in the destination asset, that any returned path should be able to satisfy | `10.1` | - -The endpoint will not allow requests which provide both a `source_account` and a `source_assets` parameter. All requests must provide one or the other. -The assets in `source_assets` are expected to be encoded using the following format: - -XLM should be represented as `"native"`. Issued assets should be represented as `"Code:IssuerAccountID"`. `"Code"` must consist of alphanumeric ASCII characters. - - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/paths/strict-receive?destination_account=GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V&source_account=GARSFJNXJIHO6ULUBK3DBYKVSIZE7SC72S5DYBCHU7DKL22UXKVD7MXP&destination_asset_type=native&destination_amount=20" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var sourceAccount = "GARSFJNXJIHO6ULUBK3DBYKVSIZE7SC72S5DYBCHU7DKL22UXKVD7MXP"; -var destinationAsset = StellarSdk.Asset.native(); -var destinationAmount = "20"; - -server.paths(sourceAccount, destinationAsset, destinationAmount) - .call() - .then(function (pathResult) { - console.log(pathResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a page of path resources. See [path resource](../resources/path.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "source_asset_type": "credit_alphanum4", - "source_asset_code": "FOO", - "source_asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "source_amount": "100.0000000", - "destination_asset_type": "credit_alphanum4", - "destination_asset_code": "FOO", - "destination_asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "destination_amount": "100.0000000", - "path": [] - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if no paths could be found to fulfill this payment request diff --git a/services/horizon/internal/docs/reference/endpoints/path-finding-strict-send.md b/services/horizon/internal/docs/reference/endpoints/path-finding-strict-send.md deleted file mode 100644 index ff2ad9d444..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/path-finding-strict-send.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Strict Send Payment Paths -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=paths&endpoint=all -replacement: https://developers.stellar.org/api/aggregations/paths/strict-send/ ---- - -The Stellar Network allows payments to be made across assets through _path payments_. A path -payment specifies a series of assets to route a payment through, from source asset (the asset -debited from the payer) to destination asset (the asset credited to the payee). - -A [Path Payment Strict Send](../../../guides/concepts/list-of-operations.html#path-payment-strict-send) allows a user to specify the amount of the asset to send. The amount received will vary based on offers in the order books. - - -A path payment strict send search is specified using: - -- The destination account id or destination assets. -- The source asset. -- The source amount. - -As part of the search, horizon will load a list of assets available to the source account id or use the assets passed in the request and will find any payment paths from those source assets to the desired destination asset. The source's amount parameter will be used to determine if a given path can satisfy a payment of the desired amount. - -## Request - -``` -https://horizon-testnet.stellar.org/paths/strict-send?&source_amount={sa}&source_asset_type={at}&source_asset_code={ac}&source_asset_issuer={ai}&destination_account={da} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?source_amount` | string | The amount, denominated in the source asset, that any returned path should be able to satisfy | `10.1` | -| `?source_asset_type` | string | The type of the source asset | `credit_alphanum4` | -| `?source_asset_code` | string, required if `source_asset_type` is not `native`, string | The source asset code, if source_asset_type is not "native" | `USD` | -| `?source_asset_issuer` | string, required if `source_asset_type` is not `native`, string | The issuer for the source asset, if source_asset_type is not "native" | `GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V` | -| `?destination_account` | string optional | The destination account that any returned path should use | `GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V` | -| `?destination_assets` | string optional | A comma separated list of assets. Any returned path must use an asset included in this list | `USD:GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V,native` | - -The endpoint will not allow requests which provide both a `destination_account` and `destination_assets` parameter. All requests must provide one or the other. -The assets in `destination_assets` are expected to be encoded using the following format: - -XLM should be represented as `"native"`. Issued assets should be represented as `"Code:IssuerAccountID"`. `"Code"` must consist of alphanumeric ASCII characters. - - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/paths/strict-send?&source_amount=10&source_asset_type=native&destination_assets=MXN:GC2GFGZ5CZCFCDJSQF3YYEAYBOS3ZREXJSPU7LUJ7JU3LP3BQNHY7YKS" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var sourceAsset = StellarSdk.Asset.native(); -var sourceAmount = "20"; -var destinationAsset = new StellarSdk.Asset( - 'USD', - 'GDSBCQO34HWPGUGQSP3QBFEXVTSR2PW46UIGTHVWGWJGQKH3AFNHXHXN' -) - - -server.strictSendPaths(sourceAsset, sourceAmount, [destinationAsset]) - .call() - .then(function (pathResult) { - console.log(pathResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a page of path resources. See [path resource](../resources/path.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "source_asset_type": "credit_alphanum4", - "source_asset_code": "FOO", - "source_asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "source_amount": "100.0000000", - "destination_asset_type": "credit_alphanum4", - "destination_asset_code": "FOO", - "destination_asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "destination_amount": "100.0000000", - "path": [] - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if no paths could be found to fulfill this payment request diff --git a/services/horizon/internal/docs/reference/endpoints/path-finding.md b/services/horizon/internal/docs/reference/endpoints/path-finding.md deleted file mode 100644 index 356ec40f0f..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/path-finding.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Find Payment Paths -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=paths&endpoint=all -replacement: https://developers.stellar.org/api/aggregations/paths/ ---- - -**Note**: This endpoint will be deprecated, use [/path/strict-receive](./path-finding-strict-receive.md) instead. There are no differences between both endpoints, `/paths` is an alias for `/path/strict-receive`. - - -The Stellar Network allows payments to be made across assets through _path payments_. A path -payment specifies a series of assets to route a payment through, from source asset (the asset -debited from the payer) to destination asset (the asset credited to the payee). - -A path search is specified using: - -- The destination account id -- The source account id -- The asset and amount that the destination account should receive - -As part of the search, horizon will load a list of assets available to the source account id and -will find any payment paths from those source assets to the desired destination asset. The search's -amount parameter will be used to determine if there a given path can satisfy a payment of the -desired amount. - -## Request - -``` -GET /paths?destination_account={da}&source_account={sa}&destination_asset_type={at}&destination_asset_code={ac}&destination_asset_issuer={di}&destination_amount={amount} -``` - -## Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?destination_account` | string | The destination account that any returned path should use | `GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V` | -| `?destination_asset_type` | string | The type of the destination asset | `credit_alphanum4` | -| `?destination_asset_code` | string | The destination asset code, if destination_asset_type is not "native" | `USD` | -| `?destination_asset_issuer` | string | The issuer for the destination, if destination_asset_type is not "native" | `GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V` | -| `?destination_amount` | string | The amount, denominated in the destination asset, that any returned path should be able to satisfy | `10.1` | -| `?source_account` | string | The sender's account id. Any returned path must use a source that the sender can hold | `GARSFJNXJIHO6ULUBK3DBYKVSIZE7SC72S5DYBCHU7DKL22UXKVD7MXP` | -| `?source_assets` | string | A comma separated list of assets. Any returned path must use a source included in this list | `USD:GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V,native` | - -The endpoint will not allow requests which provide both a `source_account` and a `source_assets` parameter. All requests must provide one or the other. -The assets in `source_assets` are expected to be encoded using the following format: - -The native asset should be represented as `"native"`. Issued assets should be represented as `"Code:IssuerAccountID"`. `"Code"` must consist of alphanumeric ASCII characters. - - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/paths?destination_account=GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V&source_account=GARSFJNXJIHO6ULUBK3DBYKVSIZE7SC72S5DYBCHU7DKL22UXKVD7MXP&destination_asset_type=native&destination_amount=20" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var source_account = "GARSFJNXJIHO6ULUBK3DBYKVSIZE7SC72S5DYBCHU7DKL22UXKVD7MXP"; -var destination_account = "GAEDTJ4PPEFVW5XV2S7LUXBEHNQMX5Q2GM562RJGOQG7GVCE5H3HIB4V"; -var destination_asset = StellarSdk.Asset.native(); -var destination_amount = "20"; - -server.paths(source_account, destination_account, destination_asset, destination_amount) - .call() - .then(function (pathResult) { - console.log(pathResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a page of path resources. See [path resource](../resources/path.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "source_asset_type": "credit_alphanum4", - "source_asset_code": "FOO", - "source_asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "source_amount": "100.0000000", - "destination_asset_type": "credit_alphanum4", - "destination_asset_code": "FOO", - "destination_asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "destination_amount": "100.0000000", - "path": [] - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if no paths could be found to fulfill this payment request diff --git a/services/horizon/internal/docs/reference/endpoints/payments-all.md b/services/horizon/internal/docs/reference/endpoints/payments-all.md deleted file mode 100644 index 4df10b3c81..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/payments-all.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: All Payments -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=payments&endpoint=all ---- - -This endpoint represents all payment-related [operations](../resources/operation.md) that are part -of validated [transactions](../resources/transaction.md). This endpoint can also be used in -[streaming](../streaming.md) mode so it is possible to use it to listen for new payments as they -get made in the Stellar network. - -If called in streaming mode Horizon will start at the earliest known payment unless a `cursor` is -set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only -stream payments created since your request time. - -The operations that can be returned in by this endpoint are: -- `create_account` -- `payment` -- `path_payment` -- `account_merge` - -## Request - -``` -GET /payments{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include payments of failed transactions in results. | `true` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the payments in the response. | `transactions` | - -### curl Example Request - -```sh -# Retrieve the first 200 payments, ordered chronologically. -curl "https://horizon-testnet.stellar.org/payments?limit=200" -``` - -```sh -# Retrieve a page of payments to occur immediately before the transaction -# specified by the paging token "1234". -curl "https://horizon-testnet.stellar.org/payments?cursor=1234&order=desc" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.payments() - .call() - .then(function (paymentResults) { - console.log(paymentResults.records) - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var paymentHandler = function (paymentResponse) { - console.log(paymentResponse); -}; - -var es = server.payments() - .cursor('now') - .stream({ - onmessage: paymentHandler - }) -``` - -## Response - -This endpoint responds with a list of payments. See [operation resource](../resources/operation.md) for more information about operations (and payment operations). - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "effects": { - "href": "/operations/77309415424/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=77309415424&order=asc" - }, - "self": { - "href": "/operations/77309415424" - }, - "succeeds": { - "href": "/operations?cursor=77309415424&order=desc" - }, - "transactions": { - "href": "/transactions/77309415424" - } - }, - "account": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "funder": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "id": 77309415424, - "paging_token": "77309415424", - "starting_balance": 1e+14, - "type_i": 0, - "type": "create_account" - }, - { - "_links": { - "effects": { - "href": "/operations/463856472064/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=463856472064&order=asc" - }, - "self": { - "href": "/operations/463856472064" - }, - "succeeds": { - "href": "/operations?cursor=463856472064&order=desc" - }, - "transactions": { - "href": "/transactions/463856472064" - } - }, - "account": "GC2ADYAIPKYQRGGUFYBV2ODJ54PY6VZUPKNCWWNX2C7FCJYKU4ZZNKVL", - "funder": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "id": 463856472064, - "paging_token": "463856472064", - "starting_balance": 1e+09, - "type_i": 0, - "type": "create_account" - } - ] - }, - "_links": { - "next": { - "href": "?order=asc&limit=2&cursor=463856472064" - }, - "prev": { - "href": "?order=desc&limit=2&cursor=77309415424" - }, - "self": { - "href": "?order=asc&limit=2&cursor=" - } - } -} -``` - -### Example Streaming Event - -```json -{ - "_links": { - "effects": { - "href": "/operations/77309415424/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=77309415424&order=asc" - }, - "self": { - "href": "/operations/77309415424" - }, - "succeeds": { - "href": "/operations?cursor=77309415424&order=desc" - }, - "transactions": { - "href": "/transactions/77309415424" - } - }, - "account": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "funder": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "id": 77309415424, - "paging_token": "77309415424", - "starting_balance": 1e+14, - "type_i": 0, - "type": "create_account" -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/payments-for-account.md b/services/horizon/internal/docs/reference/endpoints/payments-for-account.md deleted file mode 100644 index 3bd6bd4bb6..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/payments-for-account.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Payments for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=payments&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/payments/ ---- - -This endpoint responds with a collection of payment-related operations where the given -[account](../resources/account.md) was either the sender or receiver. - -This endpoint can also be used in [streaming](../streaming.md) mode so it is possible to use it to -listen for new payments to or from an account as they get made in the Stellar network. -If called in streaming mode Horizon will start at the earliest known payment unless a `cursor` is -set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only -stream payments created since your request time. - -The operations that can be returned in by this endpoint are: -- `create_account` -- `payment` -- `path_payment` -- `account_merge` - -## Request - -``` -GET /accounts/{id}/payments{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `id` | required, string | The account id of the account used to constrain results. | `GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ` | -| `?cursor` | optional, default _null_ | A payment paging token specifying from where to begin results. When streaming this can be set to `now` to stream object created since your request time. | `8589934592` | -| `?limit` | optional, number, default `10` | Specifies the count of records at most to return. | `200` | -| `?order` | optional, string, default `asc` | Specifies order of returned results. `asc` means older payments first, `desc` mean newer payments first. | `desc` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include payments of failed transactions in results. | `true` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the payments in the response. | `transactions` | - -### curl Example Request - -```bash -# Retrieve the 25 latest payments for a specific account. -curl "https://horizon-testnet.stellar.org/accounts/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?limit=25&order=desc" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.payments() - .forAccount("GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ") - .call() - .then(function (accountResult) { - console.log(accountResult); - }) - .catch(function (err) { - console.error(err); - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var paymentHandler = function (paymentResponse) { - console.log(paymentResponse); -}; - -var es = server.payments() - .forAccount("GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ") - .cursor('now') - .stream({ - onmessage: paymentHandler - }) -``` - -## Response - -This endpoint responds with a [page](../resources/page.md) of [payment operations](../resources/operation.md). - -### Example Response - -```json -{"_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "/operations/12884905984" - }, - "transaction": { - "href": "/transaction/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a" - }, - "precedes": { - "href": "/accounts/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=asc{?limit}", - "templated": true - }, - "succeeds": { - "href": "/accounts/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=desc{?limit}", - "templated": true - } - }, - "id": 12884905984, - "paging_token": "12884905984", - "type_i": 0, - "type": "payment", - "sender": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "receiver": "GCXKG6RN4ONIEPCMNFB732A436Z5PNDSRLGWK7GBLCMQLIFO4S7EYWVU", - "asset": { - "code": "XLM" - }, - "amount": 1000000000, - "amount_f": 100.00 - } - ] -}, -"_links": { - "next": { - "href": "/accounts/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=asc{?limit}", - "templated": true - }, - "self": { - "href": "/accounts/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments" - } -} -} -``` - -### Example Streaming Event - -```json -{ - "_links": { - "effects": { - "href": "/operations/77309415424/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=77309415424&order=asc" - }, - "self": { - "href": "/operations/77309415424" - }, - "succeeds": { - "href": "/operations?cursor=77309415424&order=desc" - }, - "transactions": { - "href": "/transactions/77309415424" - } - }, - "account": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "funder": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "id": 77309415424, - "paging_token": "77309415424", - "starting_balance": 1e+14, - "type_i": 0, - "type": "create_account" -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/payments-for-ledger.md b/services/horizon/internal/docs/reference/endpoints/payments-for-ledger.md deleted file mode 100644 index 52cc95ffb6..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/payments-for-ledger.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Payments for Ledger -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=payments&endpoint=for_ledger -replacement: https://developers.stellar.org/api/resources/ledgers/payments/ ---- - -This endpoint represents all payment-related [operations](../resources/operation.md) that are part -of a valid [transactions](../resources/transaction.md) in a given [ledger](../resources/ledger.md). - -The operations that can be returned in by this endpoint are: -- `create_account` -- `payment` -- `path_payment` -- `account_merge` - -## Request - -``` -GET /ledgers/{id}/payments{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `id` | required, number | Ledger ID | `696960` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include payments of failed transactions in results. | `true` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the payments in the response. | `transactions` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/ledgers/696960/payments?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.payments() - .forLedger("696960") - .call() - .then(function (paymentResult) { - console.log(paymentResult) - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a list of payment operations in a given ledger. See [operation -resource](../resources/operation.md) for more information about operations (and payment -operations). - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/ledgers/696960/payments?cursor=&limit=1&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/ledgers/696960/payments?cursor=2993420406628353&limit=1&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/ledgers/696960/payments?cursor=2993420406628353&limit=1&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2993420406628353" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2993420406628353/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2993420406628353" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2993420406628353" - } - }, - "id": "2993420406628353", - "paging_token": "2993420406628353", - "transaction_successful": true, - "source_account": "GAYB4GWPX2HUWR5QE7YX77QY6TSNFZIJZTYX2TDRW6YX6332BGD5SEAK", - "type": "payment", - "type_i": 1, - "created_at": "2019-04-09T20:00:54Z", - "transaction_hash": "f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5", - "asset_type": "native", - "from": "GAYB4GWPX2HUWR5QE7YX77QY6TSNFZIJZTYX2TDRW6YX6332BGD5SEAK", - "to": "GDGEQS64ISS6Y2KDM5V67B6LXALJX4E7VE4MIA54NANSUX5MKGKBZM5G", - "amount": "293.0000000" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no ledger whose ID matches the `id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/payments-for-transaction.md b/services/horizon/internal/docs/reference/endpoints/payments-for-transaction.md deleted file mode 100644 index 29b557eb4c..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/payments-for-transaction.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Payments for Transaction -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=payments&endpoint=for_transaction ---- - -This endpoint represents all payment-related [operations](../resources/operation.md) that are part -of a given [transaction](../resources/transaction.md). - -The operations that can be returned in by this endpoint are: -- `create_account` -- `payment` -- `path_payment` -- `account_merge` - -### Warning - failed transactions - -"Payments for Transaction" endpoint returns list of payments of successful or failed transactions -(that are also included in Stellar ledger). Always check the payment status in this endpoint using -`transaction_successful` field! - -## Request - -``` -GET /transactions/{hash}/payments{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `hash` | required, string | A transaction hash, hex-encoded, lowercase. | `f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | -| `?join` | optional, string, default: _null_ | Set to `transactions` to include the transactions which created each of the payments in the response. | `transactions` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/transactions/f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5/payments" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.payments() - .forTransaction("f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5") - .call() - .then(function (paymentResult) { - console.log(paymentResult.records); - }) - .catch(function (err) { - console.log(err); - }) -``` - -## Response - -This endpoint responds with a list of payments operations that are part of a given transaction. See -[operation resource](../resources/operation.md) for more information about operations (and payment -operations). - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5/payments?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/transactions/f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5/payments?cursor=2993420406628353&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/transactions/f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5/payments?cursor=2993420406628353&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2993420406628353" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2993420406628353/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2993420406628353" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2993420406628353" - } - }, - "id": "2993420406628353", - "paging_token": "2993420406628353", - "transaction_successful": true, - "source_account": "GAYB4GWPX2HUWR5QE7YX77QY6TSNFZIJZTYX2TDRW6YX6332BGD5SEAK", - "type": "payment", - "type_i": 1, - "created_at": "2019-04-09T20:00:54Z", - "transaction_hash": "f65278b36875d170e865853838da400515f59ca23836f072e8d62cac18b803e5", - "asset_type": "native", - "from": "GAYB4GWPX2HUWR5QE7YX77QY6TSNFZIJZTYX2TDRW6YX6332BGD5SEAK", - "to": "GDGEQS64ISS6Y2KDM5V67B6LXALJX4E7VE4MIA54NANSUX5MKGKBZM5G", - "amount": "293.0000000" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no - transaction whose ID matches the `hash` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/trade_aggregations.md b/services/horizon/internal/docs/reference/endpoints/trade_aggregations.md deleted file mode 100644 index 47a4c3fef8..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/trade_aggregations.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Trade Aggregations -replacement: https://developers.stellar.org/api/aggregations/trade-aggregations/ ---- - -Trade Aggregations are catered specifically for developers of trading clients. They facilitate -efficient gathering of historical trade data. This is done by dividing a given time range into -segments and aggregating statistics, for a given asset pair (`base`, `counter`) over each of these -segments. - -The duration of the segments is specified with the `resolution` parameter. The start and end of the -time range are given by `startTime` and `endTime` respectively, which are both rounded to the -nearest multiple of `resolution` since epoch. - -The individual segments are also aligned with multiples of `resolution` since epoch. If you want to -change this alignment, the segments can be offset by specifying the `offset` parameter. - - -## Request - -``` -GET /trade_aggregations?base_asset_type={base_asset_type}&base_asset_code={base_asset_code}&base_asset_issuer={base_asset_issuer}&counter_asset_type={counter_asset_type}&counter_asset_code={counter_asset_code}&counter_asset_issuer={counter_asset_issuer} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `start_time` | long | lower time boundary represented as millis since epoch | 1512689100000 | -| `end_time` | long | upper time boundary represented as millis since epoch | 1512775500000 | -| `resolution` | long | segment duration as millis. *Supported values are 1 minute (60000), 5 minutes (300000), 15 minutes (900000), 1 hour (3600000), 1 day (86400000) and 1 week (604800000).* | 300000 | -| `offset` | long | segments can be offset using this parameter. Expressed in milliseconds. Can only be used if the resolution is greater than 1 hour. *Value must be in whole hours, less than the provided resolution, and less than 24 hours.* | 3600000 (1 hour) | -| `base_asset_type` | string | Type of base asset | `native` | -| `base_asset_code` | string | Code of base asset, not required if type is `native` | `USD` | -| `base_asset_issuer` | string | Issuer of base asset, not required if type is `native` | 'GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36' | -| `counter_asset_type` | string | Type of counter asset | `credit_alphanum4` | -| `counter_asset_code` | string | Code of counter asset, not required if type is `native` | `BTC` | -| `counter_asset_issuer` | string | Issuer of counter asset, not required if type is `native` | 'GATEMHCCKCY67ZUCKTROYN24ZYT5GK4EQZ65JJLDHKHRUZI3EUEKMTCH' | -| `?order` | optional, string, default `asc` | The order, in terms of timeline, in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request -```sh -curl https://horizon.stellar.org/trade_aggregations?base_asset_type=native&counter_asset_code=SLT&counter_asset_issuer=GCKA6K5PCQ6PNF5RQBF7PQDJWRHO6UOGFMRLK3DYHDOI244V47XKQ4GP&counter_asset_type=credit_alphanum4&limit=200&order=asc&resolution=3600000&start_time=1517521726000&end_time=1517532526000 -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon.stellar.org'); - -var base = new StellarSdk.Asset.native(); -var counter = new StellarSdk.Asset("SLT", "GCKA6K5PCQ6PNF5RQBF7PQDJWRHO6UOGFMRLK3DYHDOI244V47XKQ4GP"); -var startTime = 1517521726000; -var endTime = 1517532526000; -var resolution = 3600000; -var offset = 0; - -server.tradeAggregation(base, counter, startTime, endTime, resolution, offset) - .call() - .then(function (tradeAggregation) { - console.log(tradeAggregation); - }) - .catch(function (err) { - console.log(err); - }) -``` - -## Response - -A list of collected trade aggregations. - -Note -- Segments that fit into the time range but have 0 trades in them, will not be included. -- Partial segments, in the beginning and end of the time range, will not be included. Thus if your - start time is noon Wednesday, your end time is noon Thursday, and your resolution is one day, you - will not receive back any data. Instead, you would want to either start at midnight Wednesday and - midnight Thursday, or shorten the resolution interval to better cover your time frame. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "https://horizon.stellar.org/trade_aggregations?base_asset_type=native\u0026counter_asset_code=SLT\u0026counter_asset_issuer=GCKA6K5PCQ6PNF5RQBF7PQDJWRHO6UOGFMRLK3DYHDOI244V47XKQ4GP\u0026counter_asset_type=credit_alphanum4\u0026limit=200\u0026order=asc\u0026resolution=3600000\u0026start_time=1517521726000\u0026end_time=1517532526000" - }, - "next": { - "href": "https://horizon.stellar.org/trade_aggregations?base_asset_type=native\u0026counter_asset_code=SLT\u0026counter_asset_issuer=GCKA6K5PCQ6PNF5RQBF7PQDJWRHO6UOGFMRLK3DYHDOI244V47XKQ4GP\u0026counter_asset_type=credit_alphanum4\u0026end_time=1517532526000\u0026limit=200\u0026order=asc\u0026resolution=3600000\u0026start_time=1517529600000" - } - }, - "_embedded": { - "records": [ - { - "timestamp": 1517522400000, - "trade_count": 26, - "base_volume": "27575.0201596", - "counter_volume": "5085.6410385", - "avg": "0.1844293", - "high": "0.1915709", - "high_r": { - "N": 50, - "D": 261 - }, - "low": "0.1506024", - "low_r": { - "N": 25, - "D": 166 - }, - "open": "0.1724138", - "open_r": { - "N": 5, - "D": 29 - }, - "close": "0.1506024", - "close_r": { - "N": 25, - "D": 166 - } - }, - { - "timestamp": 1517526000000, - "trade_count": 15, - "base_volume": "3913.8224543", - "counter_volume": "719.4993608", - "avg": "0.1838355", - "high": "0.1960784", - "high_r": { - "N": 10, - "D": 51 - }, - "low": "0.1506024", - "low_r": { - "N": 25, - "D": 166 - }, - "open": "0.1869159", - "open_r": { - "N": 20, - "D": 107 - }, - "close": "0.1515152", - "close_r": { - "N": 5, - "D": 33 - } - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/trades-for-account.md b/services/horizon/internal/docs/reference/endpoints/trades-for-account.md deleted file mode 100644 index 1290ac68ab..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/trades-for-account.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Trades for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=trades&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/trades/ ---- - -This endpoint represents all [trades](../resources/trade.md) that affect a given [account](../resources/account.md). - -This endpoint can also be used in [streaming](../streaming.md) mode, making it possible to listen for new trades that affect the given account as they occur on the Stellar network. -If called in streaming mode Horizon will start at the earliest known trade unless a `cursor` is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only stream trades created since your request time. - -## Request - -``` -GET /accounts/{account_id}/trades{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `account_id` | required, string | ID of an account | GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | 12884905984 | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR/trades?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.trades() - .forAccount("GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR") - .call() - .then(function (accountResult) { - console.log(accountResult); - }) - .catch(function (err) { - console.error(err); - }) -``` - - -## Response - -This endpoint responds with a list of trades that changed a given account's state. See the [trade resource](../resources/trade.md) for reference. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "/accounts/GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR/trades?cursor=\u0026limit=1\u0026order=asc" - }, - "next": { - "href": "/accounts/GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR/trades?cursor=940258535411713-0\u0026limit=1\u0026order=asc" - }, - "prev": { - "href": "/accounts/GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR/trades?cursor=940258535411713-0\u0026limit=1\u0026order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "" - }, - "base": { - "href": "/accounts/GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR" - }, - "counter": { - "href": "/accounts/GBOOAYCAJIN7YCUUAHEQJJARNQMRUP4P2WXVO6P4KAMAB27NGA3CYTZU" - }, - "operation": { - "href": "/operations/940258535411713" - } - }, - "id": "940258535411713-0", - "paging_token": "940258535411713-0", - "ledger_close_time": "2017-03-30T13:20:41Z", - "offer_id": "8", - "base_offer_id": "8", - "base_account": "GBYTR4MC5JAX4ALGUBJD7EIKZVM7CUGWKXIUJMRSMK573XH2O7VAK3SR", - "base_amount": "1.0000000", - "base_asset_type": "credit_alphanum4", - "base_asset_code": "BTC", - "base_asset_issuer": "GB6FN4C7ZLWKENAOZDLZOQHNIOK4RDMV6EKLR53LWCHEBR6LVXOEKDZH", - "counter_offer_id": "4611686044197195777", - "counter_account": "GBOOAYCAJIN7YCUUAHEQJJARNQMRUP4P2WXVO6P4KAMAB27NGA3CYTZU", - "counter_amount": "1.0000000", - "counter_asset_type": "native", - "base_is_seller": true, - "price": { - "n": 1, - "d": 1 - } - } - ] - } -} -``` - -## Example Streaming Event -``` -{ - _links: - { self: { href: '' }, - base: { href: '/accounts/GDICGE2CFCNM3ZWRUVOWDJB2RAO667UE7WOSJJ2Z3IMISUA7CJZCE3KO' }, - counter: { href: '/accounts/GBILENMVJPVPEPXUPUPRBUEAME5OUQWAHIGZAX7TQX65NIQW3G3DGUYX' }, - operation: { href: '/operations/47274327069954049' } }, - id: '47274327069954049-0', - paging_token: '47274327069954049-0', - ledger_close_time: '2018-09-12T00:00:34Z', - offer_id: '711437', - base_account: 'GDICGE2CFCNM3ZWRUVOWDJB2RAO667UE7WOSJJ2Z3IMISUA7CJZCE3KO', - base_amount: '13.0000000', - base_asset_type: 'native', - counter_account: 'GBILENMVJPVPEPXUPUPRBUEAME5OUQWAHIGZAX7TQX65NIQW3G3DGUYX', - counter_amount: '13.0000000', - counter_asset_type: 'credit_alphanum4', - counter_asset_code: 'CNY', - counter_asset_issuer: 'GAREELUB43IRHWEASCFBLKHURCGMHE5IF6XSE7EXDLACYHGRHM43RFOX', - base_is_seller: true, - price: { n: 1, d: 1 } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no account whose ID matches the `account_id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/trades-for-offer.md b/services/horizon/internal/docs/reference/endpoints/trades-for-offer.md deleted file mode 100644 index e6533e1cc1..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/trades-for-offer.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Trades for Offer -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=trades&endpoint=for_offer ---- - -This endpoint represents all [trades](../resources/trade.md) for a given [offer](../resources/offer.md). - -This endpoint can also be used in [streaming](../streaming.md) mode, making it possible to listen for new trades for the given offer as they occur on the Stellar network. -If called in streaming mode Horizon will start at the earliest known trade unless a `cursor` is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only stream trades created since your request time. -## Request - -``` -GET /offers/{offer_id}/trades{?cursor,limit,order} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `offer_id` | required, number | ID of an offer | 323223 | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. | 12884905984 | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/offers/323223/trades" -``` - -### JavaScript Example Request - -```js -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.trades() - .forOffer(323223) - .call() - .then(function (tradesResult) { - console.log(tradesResult); - }) - .catch(function (err) { - console.error(err); - }) -``` - - -## Response - -This endpoint responds with a list of trades that consumed a given offer. See the [trade resource](../resources/trade.md) for reference. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/offers/323223/trades?cursor=\u0026limit=10\u0026order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/offers/323223/trades?cursor=35789107779080193-0\u0026limit=10\u0026order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/offers/323223/trades?cursor=35789107779080193-0\u0026limit=10\u0026order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "" - }, - "base": { - "href": "https://horizon-testnet.stellar.org/accounts/GDRCFIQAUEFUQ6GXF5DPRO2M77E4UB7RW7EWI2FTKOW7CWYKZCHSI75K" - }, - "counter": { - "href": "https://horizon-testnet.stellar.org/accounts/GCUD7CBKTQI4D7ZR7IKHMGXZKKVABML7XFBHV4AIYBOEN5UQFZ5DSPPT" - }, - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/35789107779080193" - } - }, - "id": "35789107779080193-0", - "paging_token": "35789107779080193-0", - "ledger_close_time": "2018-04-08T05:58:37Z", - "base_offer_id": "323223", - "base_account": "GDRCFIQAUEFUQ6GXF5DPRO2M77E4UB7RW7EWI2FTKOW7CWYKZCHSI75K", - "base_amount": "912.6607285", - "base_asset_type": "native", - "counter_offer_id": "4611686044197195777", - "counter_account": "GCUD7CBKTQI4D7ZR7IKHMGXZKKVABML7XFBHV4AIYBOEN5UQFZ5DSPPT", - "counter_amount": "16.5200719", - "counter_asset_type": "credit_alphanum4", - "counter_asset_code": "CM10", - "counter_asset_issuer": "GBUJJAYHS64L4RDHPLURQJUKSHHPINSAYXYVMWPEF4LECHDKB2EFMKBX", - "base_is_seller": true, - "price": { - "n": 18101, - "d": 1000000 - } - } - ] - } -} -``` - -## Example Streaming Event -```cgo -{ _links: - { self: { href: '' }, - base: - { href: '/accounts/GDJNMHET4DTS7HUHU7IG5DB274OSMHUYA7TRRKOD6ZABHPUW5YWJ4SUD' }, - counter: - { href: '/accounts/GCALYDRCCJEUPMV24TAX2N2N3IBX7NUUYZNM7I5FQS5GIEQ4A7EVKUOP' }, - operation: { href: '/operations/47261068505915393' } }, - id: '47261068505915393-0', - paging_token: '47261068505915393-0', - ledger_close_time: '2018-09-11T19:42:04Z', - offer_id: '734529', - base_account: 'GDJNMHET4DTS7HUHU7IG5DB274OSMHUYA7TRRKOD6ZABHPUW5YWJ4SUD', - base_amount: '0.0175999', - base_asset_type: 'credit_alphanum4', - base_asset_code: 'BOC', - base_asset_issuer: 'GCTS32RGWRH6RJM62UVZ4UT5ZN5L6B2D3LPGO6Z2NM2EOGVQA7TA6SKO', - counter_account: 'GCALYDRCCJEUPMV24TAX2N2N3IBX7NUUYZNM7I5FQS5GIEQ4A7EVKUOP', - counter_amount: '0.0199998', - counter_asset_type: 'credit_alphanum4', - counter_asset_code: 'ABC', - counter_asset_issuer: 'GCTS32RGWRH6RJM62UVZ4UT5ZN5L6B2D3LPGO6Z2NM2EOGVQA7TA6SKO', - base_is_seller: true, - price: { n: 2840909, d: 2500000 } -} -``` -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no offer whose ID matches the `offer_id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/trades.md b/services/horizon/internal/docs/reference/endpoints/trades.md deleted file mode 100644 index ab7760f3e9..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/trades.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Trades -replacement: https://developers.stellar.org/api/resources/trades/ ---- - -People on the Stellar network can make [offers](../resources/offer.md) to buy or sell assets. When -an offer is fully or partially fulfilled, a [trade](../resources/trade.md) happens. - -Trades can be filtered for a specific orderbook, defined by an asset pair: `base` and `counter`. - -This endpoint can also be used in [streaming](../streaming.md) mode, making it possible to listen -for new trades as they occur on the Stellar network. - -If called in streaming mode Horizon will start at the earliest known trade unless a `cursor` is -set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to only -stream trades created since your request time. - -## Request - -``` -GET /trades?base_asset_type={base_asset_type}&base_asset_code={base_asset_code}&base_asset_issuer={base_asset_issuer}&counter_asset_type={counter_asset_type}&counter_asset_code={counter_asset_code}&counter_asset_issuer={counter_asset_issuer} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `base_asset_type` | optional, string | Type of base asset | `native` | -| `base_asset_code` | optional, string | Code of base asset, not required if type is `native` | `USD` | -| `base_asset_issuer` | optional, string | Issuer of base asset, not required if type is `native` | 'GA2HGBJIJKI6O4XEM7CZWY5PS6GKSXL6D34ERAJYQSPYA6X6AI7HYW36' | -| `counter_asset_type` | optional, string | Type of counter asset | `credit_alphanum4` | -| `counter_asset_code` | optional, string | Code of counter asset, not required if type is `native` | `BTC` | -| `counter_asset_issuer` | optional, string | Issuer of counter asset, not required if type is `native` | 'GD6VWBXI6NY3AOOR55RLVQ4MNIDSXE5JSAVXUTF35FRRI72LYPI3WL6Z' | -| `offer_id` | optional, string | filter for by a specific offer id | `283606` | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order, in terms of timeline, in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | - -### curl Example Request -```sh -curl https://horizon.stellar.org/trades?base_asset_type=native&counter_asset_code=SLT&counter_asset_issuer=GCKA6K5PCQ6PNF5RQBF7PQDJWRHO6UOGFMRLK3DYHDOI244V47XKQ4GP&counter_asset_type=credit_alphanum4&limit=2&order=desc -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.trades() - .call() - .then(function (tradesResult) { - console.log(tradesResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Example Streaming Request - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var tradesHandler = function (tradeResponse) { - console.log(tradeResponse); -}; - -var es = server.trades() - .cursor('now') - .stream({ - onmessage: tradesHandler -}) -``` - -## Response - -The list of trades. `base` and `counter` in the records will match the asset pair filter order. If an asset pair is not specified, the order is arbitrary. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/trades?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/trades?cursor=6025839120434-0&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/trades?cursor=6012954218535-0&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "" - }, - "base": { - "href": "https://horizon-testnet.stellar.org/accounts/GAQHWQYBBW272OOXNQMMLCA5WY2XAZPODGB7Q3S5OKKIXVESKO55ZQ7C" - }, - "counter": { - "href": "https://horizon-testnet.stellar.org/accounts/GCYN7MI6VXVRP74KR6MKBAW2ELLCXL6QCY5H4YQ62HVWZWMCE6Y232UC" - }, - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/6012954218535" - } - }, - "id": "6012954218535-0", - "paging_token": "6012954218535-0", - "ledger_close_time": "2019-02-27T11:54:53Z", - "offer_id": "37", - "base_offer_id": "4611692031381606439", - "base_account": "GAQHWQYBBW272OOXNQMMLCA5WY2XAZPODGB7Q3S5OKKIXVESKO55ZQ7C", - "base_amount": "25.6687300", - "base_asset_type": "credit_alphanum4", - "base_asset_code": "DSQ", - "base_asset_issuer": "GBDQPTQJDATT7Z7EO4COS4IMYXH44RDLLI6N6WIL5BZABGMUOVMLWMQF", - "counter_offer_id": "37", - "counter_account": "GCYN7MI6VXVRP74KR6MKBAW2ELLCXL6QCY5H4YQ62HVWZWMCE6Y232UC", - "counter_amount": "1.0265563", - "counter_asset_type": "credit_alphanum4", - "counter_asset_code": "USD", - "counter_asset_issuer": "GAA4MFNZGUPJAVLWWG6G5XZJFZDHLKQNG3Q6KB24BAD6JHNNVXDCF4XG", - "base_is_seller": false, - "price": { - "n": 10000000, - "d": 250046977 - } - }, - { - "_links": { - "self": { - "href": "" - }, - "base": { - "href": "https://horizon-testnet.stellar.org/accounts/GAQHWQYBBW272OOXNQMMLCA5WY2XAZPODGB7Q3S5OKKIXVESKO55ZQ7C" - }, - "counter": { - "href": "https://horizon-testnet.stellar.org/accounts/GCYN7MI6VXVRP74KR6MKBAW2ELLCXL6QCY5H4YQ62HVWZWMCE6Y232UC" - }, - "operation": { - "href": "https://horizon-testnet.stellar.org/operations/6025839120385" - } - }, - "id": "6025839120385-0", - "paging_token": "6025839120385-0", - "ledger_close_time": "2019-02-27T11:55:09Z", - "offer_id": "1", - "base_offer_id": "4611692044266508289", - "base_account": "GAQHWQYBBW272OOXNQMMLCA5WY2XAZPODGB7Q3S5OKKIXVESKO55ZQ7C", - "base_amount": "1434.4442973", - "base_asset_type": "credit_alphanum4", - "base_asset_code": "DSQ", - "base_asset_issuer": "GBDQPTQJDATT7Z7EO4COS4IMYXH44RDLLI6N6WIL5BZABGMUOVMLWMQF", - "counter_offer_id": "1", - "counter_account": "GCYN7MI6VXVRP74KR6MKBAW2ELLCXL6QCY5H4YQ62HVWZWMCE6Y232UC", - "counter_amount": "0.5622050", - "counter_asset_type": "credit_alphanum4", - "counter_asset_code": "SXRT", - "counter_asset_issuer": "GAIOQ3UYK5NYIZY5ZFAG4JBN4O37NAVFKZM5YDYEB6YEFBZSZ5KDCUFO", - "base_is_seller": false, - "price": { - "n": 642706, - "d": 1639839483 - } - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/transactions-all.md b/services/horizon/internal/docs/reference/endpoints/transactions-all.md deleted file mode 100644 index aac65c4950..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/transactions-all.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: All Transactions -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=transactions&endpoint=all -replacement: https://developers.stellar.org/api/resources/transactions/single/ ---- - -This endpoint represents all successful [transactions](../resources/transaction.md). -Please note that this endpoint returns failed transactions that are included in the ledger if -`include_failed` parameter is `true` and Horizon is ingesting failed transactions. -This endpoint can also be used in [streaming](../streaming.md) mode. This makes it possible to use -it to listen for new transactions as they get made in the Stellar network. If called in streaming -mode Horizon will start at the earliest known transaction unless a `cursor` is set. In that case it -will start from the `cursor`. You can also set `cursor` value to `now` to only stream transaction -created since your request time. - -## Request - -``` -GET /transactions{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include failed transactions in results. | `true` | - -### curl Example Request - -```sh -# Retrieve the 200 latest transactions, ordered chronologically: -curl "https://horizon-testnet.stellar.org/transactions?limit=200&order=desc" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.transactions() - .call() - .then(function (transactionResult) { - //page 1 - console.log(transactionResult.records); - return transactionResult.next(); - }) - .then(function (transactionResult) { - console.log(transactionResult.records); - }) - .catch(function (err) { - console.log(err) - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var txHandler = function (txResponse) { - console.log(txResponse); -}; - -var es = server.transactions() - .cursor('now') - .stream({ - onmessage: txHandler - }) -``` - -## Response - -If called normally this endpoint responds with a [page](../resources/page.md) of transactions. -If called in streaming mode the transaction resources are returned individually. -See [transaction resource](../resources/transaction.md) for reference. - -### Example Response - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "account": { - "href": "/accounts/GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K" - }, - "effects": { - "href": "/transactions/fa78cb43d72171fdb2c6376be12d57daa787b1fa1a9fdd0e9453e1f41ee5f15a/effects{?cursor,limit,order}", - "templated": true - }, - "ledger": { - "href": "/ledgers/146970" - }, - "operations": { - "href": "/transactions/fa78cb43d72171fdb2c6376be12d57daa787b1fa1a9fdd0e9453e1f41ee5f15a/operations{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/transactions?cursor=631231343497216\u0026order=asc" - }, - "self": { - "href": "/transactions/fa78cb43d72171fdb2c6376be12d57daa787b1fa1a9fdd0e9453e1f41ee5f15a" - }, - "succeeds": { - "href": "/transactions?cursor=631231343497216\u0026order=desc" - } - }, - "id": "fa78cb43d72171fdb2c6376be12d57daa787b1fa1a9fdd0e9453e1f41ee5f15a", - "paging_token": "631231343497216", - "successful": true, - "hash": "fa78cb43d72171fdb2c6376be12d57daa787b1fa1a9fdd0e9453e1f41ee5f15a", - "ledger": 146970, - "created_at": "2015-09-24T10:07:09Z", - "account": "GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K", - "account_sequence": 279172874343, - "max_fee": 100, - "fee_charged": 100, - "operation_count": 1, - "envelope_xdr": "AAAAAGXNhLrhGtltTwCpmqlarh7s1DB2hIkbP//jgzn4Fos/AAAACgAAAEEAAABnAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAA2ddmTOFAgr21Crs2RXRGLhiAKxicZb/IERyEZL/Y2kUAAAAXSHboAAAAAAAAAAAB+BaLPwAAAECDEEZmzbgBr5fc3mfJsCjWPDtL6H8/vf16me121CC09ONyWJZnw0PUvp4qusmRwC6ZKfLDdk8F3Rq41s+yOgQD", - "result_xdr": "AAAAAAAAAAoAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAAAAAAEAAAACAAAAAAACPhoAAAAAAAAAANnXZkzhQIK9tQq7NkV0Ri4YgCsYnGW/yBEchGS/2NpFAAAAF0h26AAAAj4aAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAQACPhoAAAAAAAAAAGXNhLrhGtltTwCpmqlarh7s1DB2hIkbP//jgzn4Fos/AABT8kS2c/oAAABBAAAAZwAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAA" - }, - { - "_links": { - "account": { - "href": "/accounts/GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K" - }, - "effects": { - "href": "/transactions/90ad6cfc9b0911bdbf202cace78ae7ecf50989c424288670dadb69bf8237c1b3/effects{?cursor,limit,order}", - "templated": true - }, - "ledger": { - "href": "/ledgers/144798" - }, - "operations": { - "href": "/transactions/90ad6cfc9b0911bdbf202cace78ae7ecf50989c424288670dadb69bf8237c1b3/operations{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/transactions?cursor=621902674530304\u0026order=asc" - }, - "self": { - "href": "/transactions/90ad6cfc9b0911bdbf202cace78ae7ecf50989c424288670dadb69bf8237c1b3" - }, - "succeeds": { - "href": "/transactions?cursor=621902674530304\u0026order=desc" - } - }, - "id": "90ad6cfc9b0911bdbf202cace78ae7ecf50989c424288670dadb69bf8237c1b3", - "paging_token": "621902674530304", - "successful": false, - "hash": "90ad6cfc9b0911bdbf202cace78ae7ecf50989c424288670dadb69bf8237c1b3", - "ledger": 144798, - "created_at": "2015-09-24T07:49:38Z", - "account": "GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K", - "account_sequence": 279172874342, - "max_fee": 100, - "fee_charged": 100, - "operation_count": 1, - "envelope_xdr": "AAAAAGXNhLrhGtltTwCpmqlarh7s1DB2hIkbP//jgzn4Fos/AAAACgAAAEEAAABmAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAMPT7P7buwqnMueFS4NV10vE2q3C/mcAy4jx03/RdSGsAAAAXSHboAAAAAAAAAAAB+BaLPwAAAEBPWWMNSWyPBbQlhRheXyvAFDVx1rnf68fdDOUHPdDIkHdUczBpzvCjpdgwhQ2NYOX5ga1ZgOIWLy789YNnuIcL", - "result_xdr": "AAAAAAAAAAoAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAAAAAAEAAAACAAAAAAACNZ4AAAAAAAAAADD0+z+27sKpzLnhUuDVddLxNqtwv5nAMuI8dN/0XUhrAAAAF0h26AAAAjWeAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAQACNZ4AAAAAAAAAAGXNhLrhGtltTwCpmqlarh7s1DB2hIkbP//jgzn4Fos/AABUCY0tXAQAAABBAAAAZgAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAA" - } - ] - }, - "_links": { - "next": { - "href": "/transactions?order=desc\u0026limit=2\u0026cursor=621902674530304" - }, - "prev": { - "href": "/transactions?order=asc\u0026limit=2\u0026cursor=631231343497216" - }, - "self": { - "href": "/transactions?order=desc\u0026limit=2\u0026cursor=" - } - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#standard-errors). diff --git a/services/horizon/internal/docs/reference/endpoints/transactions-create.md b/services/horizon/internal/docs/reference/endpoints/transactions-create.md deleted file mode 100644 index 1801bb5c12..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/transactions-create.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Post Transaction -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=transactions&endpoint=create -replacement: https://developers.stellar.org/api/resources/transactions/post/ ---- - -Posts a new [transaction](../resources/transaction.md) to the Stellar Network. -Note that creating a valid transaction and signing it properly is the -responsibility of your client library. - -Transaction submission and the subsequent validation and inclusion into the -Stellar Network's ledger is a [complicated and asynchronous -process](https://www.stellar.org/developers/learn/concepts/transactions.html#life-cycle). -To reduce the complexity, horizon manages these asynchronous processes for the -client and will wait to hear results from the Stellar Network before returning -an HTTP response to a client. - -Transaction submission to horizon aims to be -[idempotent](https://en.wikipedia.org/wiki/Idempotence#Computer_science_meaning): -a client can submit a given transaction to horizon more than once and horizon -will behave the same each time. If the transaction has already been -successfully applied to the ledger, horizon will simply return the saved result -and not attempt to submit the transaction again. Only in cases where a -transaction's status is unknown (and thus will have a chance of being included -into a ledger) will a resubmission to the network occur. - -Information about [building transactions](https://www.stellar.org/developers/js-stellar-base/reference/building-transactions.html) in JavaScript. - -### Timeout - -If you are encountering this error it means that either: - -* Horizon has not received a confirmation from the Core server that the transaction you are trying to submit to the network was included in a ledger in a timely manner or: -* Horizon has not sent a response to a reverse-proxy before in a specified time. - -The former case may happen because there was no room for your transaction in the 3 consecutive ledgers. In such case, Core server removes a transaction from a queue. To solve this you can either: - -* Keep resubmitting the same transaction (with the same sequence number) and wait until it finally is added to a new ledger or: -* Increase the [fee](../../../guides/concepts/fees.html). - -## Request - -``` -POST /transactions -``` - -### Arguments - -| name | loc | notes | example | description | -| ---- | ---- | -------- | ---------------------- | ----------- | -| `tx` | body | required | `AAAAAO`....`f4yDBA==` | Base64 representation of transaction envelope [XDR](../xdr.md) | - - -### curl Example Request - -```sh -curl -X POST \ - -F "tx=AAAAAOo1QK/3upA74NLkdq4Io3DQAQZPi4TVhuDnvCYQTKIVAAAACgAAH8AAAAABAAAAAAAAAAAAAAABAAAAAQAAAADqNUCv97qQO+DS5HauCKNw0AEGT4uE1Ybg57wmEEyiFQAAAAEAAAAAZc2EuuEa2W1PAKmaqVquHuzUMHaEiRs//+ODOfgWiz8AAAAAAAAAAAAAA+gAAAAAAAAAARBMohUAAABAPnnZL8uPlS+c/AM02r4EbxnZuXmP6pQHvSGmxdOb0SzyfDB2jUKjDtL+NC7zcMIyw4NjTa9Ebp4lvONEf4yDBA==" \ - "https://horizon-testnet.stellar.org/transactions" -``` - -## Response - -A successful response (i.e. any response with a successful HTTP response code) -indicates that the transaction was successful and has been included into the -ledger. - -If the transaction failed or errored, then an error response will be returned. Please see the errors section below. - -### Attributes - -The response will include all fields from the [transaction resource](../resources/transaction.md). - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c" - }, - "account": { - "href": "https://horizon-testnet.stellar.org/accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR" - }, - "ledger": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121" - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c/operations{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/transactions?order=asc&cursor=2994111896358912" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/transactions?order=desc&cursor=2994111896358912" - } - }, - "id": "264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c", - "paging_token": "2994111896358912", - "successful": true, - "hash": "264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c", - "ledger": 697121, - "created_at": "2019-04-09T20:14:25Z", - "source_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "fee_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "source_account_sequence": "4660039994869", - "fee_charged": 100, - "max_fee": 100, - "operation_count": 1, - "envelope_xdr": "AAAAABB90WssODNIgi6BHveqzxTRmIpvAFRyVNM+Hm2GVuCcAAAAZAAABD0AB031AAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAFIMRkFZ9gZifhRSlklQpsz/9P04Earv0dzS3MkIM1cYAAAAXSHboAAAAAAAAAAABhlbgnAAAAEA+biIjrDy8yi+SvhFElIdWGBRYlDscnSSHkPchePy2JYDJn4wvJYDBumXI7/NmttUey3+cGWbBFfnnWh1H5EoD", - "result_xdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAQAAAAIAAAADAAqjIQAAAAAAAAAAEH3Rayw4M0iCLoEe96rPFNGYim8AVHJU0z4ebYZW4JwBOLmYhGq/IAAABD0AB030AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAqjIQAAAAAAAAAAEH3Rayw4M0iCLoEe96rPFNGYim8AVHJU0z4ebYZW4JwBOLmYhGq/IAAABD0AB031AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAAAAwAAAAMACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar8gAAAEPQAHTfUAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uYE789cgAAAEPQAHTfUAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAACqMhAAAAAAAAAAAUgxGQVn2BmJ+FFKWSVCmzP/0/TgRqu/R3NLcyQgzVxgAAABdIdugAAAqjIQAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "fee_meta_xdr": "AAAAAgAAAAMACqMgAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar+EAAAEPQAHTfQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar8gAAAEPQAHTfQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "memo_type": "none", - "signatures": [ - "Pm4iI6w8vMovkr4RRJSHVhgUWJQ7HJ0kh5D3IXj8tiWAyZ+MLyWAwbplyO/zZrbVHst/nBlmwRX551odR+RKAw==" - ] -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard_Errors). -- [transaction_failed](../errors/transaction-failed.md): The transaction failed and could not be applied to the ledger. -- [transaction_malformed](../errors/transaction-malformed.md): The transaction could not be decoded and was not submitted to the network. -- [timeout](../errors/timeout.md): No response from the Core server in a timely manner. Please check "Timeout" section above. diff --git a/services/horizon/internal/docs/reference/endpoints/transactions-for-account.md b/services/horizon/internal/docs/reference/endpoints/transactions-for-account.md deleted file mode 100644 index 375c281698..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/transactions-for-account.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Transactions for Account -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=transactions&endpoint=for_account -replacement: https://developers.stellar.org/api/resources/accounts/transactions/ ---- - -This endpoint represents successful [transactions](../resources/transaction.md) that affected a -given [account](../resources/account.md). This endpoint can also be used in -[streaming](../streaming.md) mode so it is possible to use it to listen for new transactions that -affect a given account as they get made in the Stellar network. - -If called in streaming mode Horizon will start at the earliest known transaction unless a `cursor` -is set. In that case it will start from the `cursor`. You can also set `cursor` value to `now` to -only stream transaction created since your request time. - -## Request - -``` -GET /accounts/{account_id}/transactions{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ---- | ----- | ----------- | ------- | -| `account_id` | required, string | ID of an account | GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K | -| `?cursor` | optional, any, default _null_ | A paging token, specifying where to start returning records from. When streaming this can be set to `now` to stream object created since your request time. | 12884905984 | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default: `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include failed transactions in results. | `true` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/accounts/GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K/transactions?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.transactions() - .forAccount("GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K") - .call() - .then(function (accountResult) { - console.log(accountResult); - }) - .catch(function (err) { - console.error(err); - }) -``` - -### JavaScript Streaming Example - -```javascript -var StellarSdk = require('stellar-sdk') -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -var txHandler = function (txResponse) { - console.log(txResponse); -}; - -var es = server.transactions() - .forAccount("GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K") - .cursor('now') - .stream({ - onmessage: txHandler - }) -``` - -## Response - -This endpoint responds with a list of transactions that changed a given account's state. See -[transaction resource](../resources/transaction.md) for reference. - -### Example Response -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/payments?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/payments?cursor=2714719978786817&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/accounts/GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF/payments?cursor=1919197546291201&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/1919197546291201/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=1919197546291201" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=1919197546291201" - } - }, - "id": "1919197546291201", - "paging_token": "1919197546291201", - "transaction_successful": true, - "source_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "type": "create_account", - "type_i": 0, - "created_at": "2019-03-25T22:43:38Z", - "transaction_hash": "7e2050abc676003efc3eaadd623c927f753b7a6c37f50864bf284f4e1510d088", - "starting_balance": "10000.0000000", - "funder": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "account": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF" - }, - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/operations/2714719978786817" - }, - "transaction": { - "href": "https://horizon-testnet.stellar.org/transactions/7cea6abe90654578b42ee696e823187d89d91daa157a1077b542ee7c77413ce3" - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/operations/2714719978786817/effects" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/effects?order=desc&cursor=2714719978786817" - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/effects?order=asc&cursor=2714719978786817" - } - }, - "id": "2714719978786817", - "paging_token": "2714719978786817", - "transaction_successful": true, - "source_account": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "type": "payment", - "type_i": 1, - "created_at": "2019-04-05T23:07:42Z", - "transaction_hash": "7cea6abe90654578b42ee696e823187d89d91daa157a1077b542ee7c77413ce3", - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "from": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR", - "to": "GBYUUJHG6F4EPJGNLERINATVQLNDOFRUD7SGJZ26YZLG5PAYLG7XUSGF", - "amount": "1000000.0000000" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no account whose ID matches the `account_id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/transactions-for-ledger.md b/services/horizon/internal/docs/reference/endpoints/transactions-for-ledger.md deleted file mode 100644 index 7f1f5e4693..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/transactions-for-ledger.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Transactions for Ledger -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=transactions&endpoint=for_ledger -replacement: https://developers.stellar.org/api/resources/ledgers/transactions/ ---- - -This endpoint represents successful [transactions](../resources/transaction.md) in a given [ledger](../resources/ledger.md). - -## Request - -``` -GET /ledgers/{id}/transactions{?cursor,limit,order,include_failed} -``` - -### Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `id` | required, number | Ledger ID | `697121` | -| `?cursor` | optional, default _null_ | A paging token, specifying where to start returning records from. | `12884905984` | -| `?order` | optional, string, default `asc` | The order in which to return rows, "asc" or "desc". | `asc` | -| `?limit` | optional, number, default `10` | Maximum number of records to return. | `200` | -| `?include_failed` | optional, bool, default: `false` | Set to `true` to include failed transactions in results. | `true` | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/ledgers/697121/transactions?limit=1" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.transactions() - .forLedger("697121") - .limit("1") - .call() - .then(function (accountResults) { - console.log(accountResults.records) - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a list of transactions in a given ledger. See [transaction -resource](../resources/transaction.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121/transactions?cursor=&limit=10&order=asc" - }, - "next": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121/transactions?cursor=2994111896367104&limit=10&order=asc" - }, - "prev": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121/transactions?cursor=2994111896358912&limit=10&order=desc" - } - }, - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c" - }, - "account": { - "href": "https://horizon-testnet.stellar.org/accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR" - }, - "ledger": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121" - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c/operations{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/transactions?order=asc&cursor=2994111896358912" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/transactions?order=desc&cursor=2994111896358912" - } - }, - "id": "264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c", - "paging_token": "2994111896358912", - "successful": true, - "hash": "264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c", - "ledger": 697121, - "created_at": "2019-04-09T20:14:25Z", - "source_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "source_account_sequence": "4660039994869", - "fee_charged": 100, - "max_fee": 100, - "operation_count": 1, - "envelope_xdr": "AAAAABB90WssODNIgi6BHveqzxTRmIpvAFRyVNM+Hm2GVuCcAAAAZAAABD0AB031AAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAFIMRkFZ9gZifhRSlklQpsz/9P04Earv0dzS3MkIM1cYAAAAXSHboAAAAAAAAAAABhlbgnAAAAEA+biIjrDy8yi+SvhFElIdWGBRYlDscnSSHkPchePy2JYDJn4wvJYDBumXI7/NmttUey3+cGWbBFfnnWh1H5EoD", - "result_xdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAQAAAAIAAAADAAqjIQAAAAAAAAAAEH3Rayw4M0iCLoEe96rPFNGYim8AVHJU0z4ebYZW4JwBOLmYhGq/IAAABD0AB030AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAqjIQAAAAAAAAAAEH3Rayw4M0iCLoEe96rPFNGYim8AVHJU0z4ebYZW4JwBOLmYhGq/IAAABD0AB031AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAAAAwAAAAMACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar8gAAAEPQAHTfUAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uYE789cgAAAEPQAHTfUAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAACqMhAAAAAAAAAAAUgxGQVn2BmJ+FFKWSVCmzP/0/TgRqu/R3NLcyQgzVxgAAABdIdugAAAqjIQAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "fee_meta_xdr": "AAAAAgAAAAMACqMgAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar+EAAAEPQAHTfQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar8gAAAEPQAHTfQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "memo_type": "none", - "signatures": [ - "Pm4iI6w8vMovkr4RRJSHVhgUWJQ7HJ0kh5D3IXj8tiWAyZ+MLyWAwbplyO/zZrbVHst/nBlmwRX551odR+RKAw==" - ] - }, - { - "memo": "2A1V6J5703G47XHY", - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/f175108e5c64619705b112a99fa32884dfa0511d9a8986aade87905b08eabe5b" - }, - "account": { - "href": "https://horizon-testnet.stellar.org/accounts/GAZ4A54KE6MTMXYEPM7T3IDLZWGNCCKB5ME422NZ3MAMTHWWP37RPEBW" - }, - "ledger": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121" - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/transactions/f175108e5c64619705b112a99fa32884dfa0511d9a8986aade87905b08eabe5b/operations{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/transactions/f175108e5c64619705b112a99fa32884dfa0511d9a8986aade87905b08eabe5b/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/transactions?order=asc&cursor=2994111896363008" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/transactions?order=desc&cursor=2994111896363008" - } - }, - "id": "f175108e5c64619705b112a99fa32884dfa0511d9a8986aade87905b08eabe5b", - "paging_token": "2994111896363008", - "successful": true, - "hash": "f175108e5c64619705b112a99fa32884dfa0511d9a8986aade87905b08eabe5b", - "ledger": 697121, - "created_at": "2019-04-09T20:14:25Z", - "source_account": "GAZ4A54KE6MTMXYEPM7T3IDLZWGNCCKB5ME422NZ3MAMTHWWP37RPEBW", - "source_account_sequence": "2994107601387521", - "fee_charged": 100, - "max_fee": 100, - "operation_count": 1, - "envelope_xdr": "AAAAADPAd4onmTZfBHs/PaBrzYzRCUHrCc1pudsAyZ7Wfv8XAAAAZAAKoyAAAAABAAAAAAAAAAEAAAAQMkExVjZKNTcwM0c0N1hIWQAAAAEAAAABAAAAADPAd4onmTZfBHs/PaBrzYzRCUHrCc1pudsAyZ7Wfv8XAAAAAQAAAADMSEvcRKXsaUNna++Hy7gWm/CfqTjEA7xoGypfrFGUHAAAAAAAAAAAhFKDAAAAAAAAAAAB1n7/FwAAAEBJdXuYg13Glzx1RinVCXd/cc1usrhU/0f5HFZ7lyIR8kS3T6PRrW78TQDNqXz+ukUiPwlB1A8MqxoW/SAL5FIB", - "result_xdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAABAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAQAAAAIAAAADAAqjIQAAAAAAAAAAM8B3iieZNl8Eez89oGvNjNEJQesJzWm52wDJntZ+/xcAAAAXSHbnnAAKoyAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAqjIQAAAAAAAAAAM8B3iieZNl8Eez89oGvNjNEJQesJzWm52wDJntZ+/xcAAAAXSHbnnAAKoyAAAAABAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAAABAAAAAMACqMgAAAAAAAAAADMSEvcRKXsaUNna++Hy7gWm/CfqTjEA7xoGypfrFGUHAAAAANViducAABeBgAAoRQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAADMSEvcRKXsaUNna++Hy7gWm/CfqTjEA7xoGypfrFGUHAAAAAPZ3F6cAABeBgAAoRQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAMACqMhAAAAAAAAAAAzwHeKJ5k2XwR7Pz2ga82M0QlB6wnNabnbAMme1n7/FwAAABdIduecAAqjIAAAAAEAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAzwHeKJ5k2XwR7Pz2ga82M0QlB6wnNabnbAMme1n7/FwAAABbEJGScAAqjIAAAAAEAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "fee_meta_xdr": "AAAAAgAAAAMACqMgAAAAAAAAAAAzwHeKJ5k2XwR7Pz2ga82M0QlB6wnNabnbAMme1n7/FwAAABdIdugAAAqjIAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAzwHeKJ5k2XwR7Pz2ga82M0QlB6wnNabnbAMme1n7/FwAAABdIduecAAqjIAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "memo_type": "text", - "signatures": [ - "SXV7mINdxpc8dUYp1Ql3f3HNbrK4VP9H+RxWe5ciEfJEt0+j0a1u/E0Azal8/rpFIj8JQdQPDKsaFv0gC+RSAQ==" - ] - }, - { - "memo": "WHALE", - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/83b6ebf4b3aec5b36cab14ae0f438a23487746857903a9e0bb002564b4641e25" - }, - "account": { - "href": "https://horizon-testnet.stellar.org/accounts/GABRMXDIJCTDSMPC67J64NSAMWRSYXVCXYTXVFC73DTHBKELHNKWANXP" - }, - "ledger": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121" - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/transactions/83b6ebf4b3aec5b36cab14ae0f438a23487746857903a9e0bb002564b4641e25/operations{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/transactions/83b6ebf4b3aec5b36cab14ae0f438a23487746857903a9e0bb002564b4641e25/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/transactions?order=asc&cursor=2994111896367104" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/transactions?order=desc&cursor=2994111896367104" - } - }, - "id": "83b6ebf4b3aec5b36cab14ae0f438a23487746857903a9e0bb002564b4641e25", - "paging_token": "2994111896367104", - "successful": true, - "hash": "83b6ebf4b3aec5b36cab14ae0f438a23487746857903a9e0bb002564b4641e25", - "ledger": 697121, - "created_at": "2019-04-09T20:14:25Z", - "source_account": "GABRMXDIJCTDSMPC67J64NSAMWRSYXVCXYTXVFC73DTHBKELHNKWANXP", - "source_account_sequence": "122518237256298", - "fee_charged": 100, - "max_fee": 100, - "operation_count": 1, - "envelope_xdr": "AAAAAAMWXGhIpjkx4vfT7jZAZaMsXqK+J3qUX9jmcKiLO1VgAAAAZAAAb24AAppqAAAAAQAAAAAAAAAAAAAAAFys/kkAAAABAAAABVdIQUxFAAAAAAAAAQAAAAAAAAAAAAAAAKrN4k6edFMb0WEyPzEEjWUAji0pvvALw+BAH4OnekA5AAAAAAcnDgAAAAAAAAAAAYs7VWAAAABAYd9uIm+TjIcAjTU90YJoNg/r+6PU3Uss7ewUb1w3yMa+HyoSvDq8sDz/SYmDBH7F+0ACIeBF4kkVEKVBJMh0AQ==", - "result_xdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAQAAAAIAAAADAAqjIQAAAAAAAAAAAxZcaEimOTHi99PuNkBloyxeor4nepRf2OZwqIs7VWAAJBMYWVFGqAAAb24AApppAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAqjIQAAAAAAAAAAAxZcaEimOTHi99PuNkBloyxeor4nepRf2OZwqIs7VWAAJBMYWVFGqAAAb24AAppqAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAAAAwAAAAMACqMhAAAAAAAAAAADFlxoSKY5MeL30+42QGWjLF6ivid6lF/Y5nCoiztVYAAkExhZUUaoAABvbgACmmoAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAADFlxoSKY5MeL30+42QGWjLF6ivid6lF/Y5nCoiztVYAAkExhSKjioAABvbgACmmoAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAACqMhAAAAAAAAAACqzeJOnnRTG9FhMj8xBI1lAI4tKb7wC8PgQB+Dp3pAOQAAAAAHJw4AAAqjIQAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "fee_meta_xdr": "AAAAAgAAAAMACqMfAAAAAAAAAAADFlxoSKY5MeL30+42QGWjLF6ivid6lF/Y5nCoiztVYAAkExhZUUcMAABvbgACmmkAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAADFlxoSKY5MeL30+42QGWjLF6ivid6lF/Y5nCoiztVYAAkExhZUUaoAABvbgACmmkAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "memo_type": "text", - "signatures": [ - "Yd9uIm+TjIcAjTU90YJoNg/r+6PU3Uss7ewUb1w3yMa+HyoSvDq8sDz/SYmDBH7F+0ACIeBF4kkVEKVBJMh0AQ==" - ], - "valid_after": "1970-01-01T00:00:00Z", - "valid_before": "2019-04-09T20:19:21Z" - } - ] - } -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no ledgers whose sequence matches the `id` argument. diff --git a/services/horizon/internal/docs/reference/endpoints/transactions-single.md b/services/horizon/internal/docs/reference/endpoints/transactions-single.md deleted file mode 100644 index 99aa29e376..0000000000 --- a/services/horizon/internal/docs/reference/endpoints/transactions-single.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Transaction Details -clientData: - laboratoryUrl: https://www.stellar.org/laboratory/#explorer?resource=transactions&endpoint=single -replacement: https://developers.stellar.org/api/resources/transactions/single/ ---- - -The transaction details endpoint provides information on a single -[transaction](../resources/transaction.md). The transaction hash provided in the `hash` argument -specifies which transaction to load. - -### Warning - failed transactions - -Transaction can be successful or failed (failed transactions are also included in Stellar ledger). -Always check it's status using `successful` field! - -## Request - -``` -GET /transactions/{hash} -``` - -### Arguments - -| name | notes | description | example | -| ------ | ------- | ----------- | ------- | -| `hash` | required, string | A transaction hash, hex-encoded, lowercase. | 264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c | - -### curl Example Request - -```sh -curl "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c" -``` - -### JavaScript Example Request - -```javascript -var StellarSdk = require('stellar-sdk'); -var server = new StellarSdk.Server('https://horizon-testnet.stellar.org'); - -server.transactions() - .transaction("264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c") - .call() - .then(function (transactionResult) { - console.log(transactionResult) - }) - .catch(function (err) { - console.log(err) - }) -``` - -## Response - -This endpoint responds with a single Transaction. See [transaction resource](../resources/transaction.md) for reference. - -### Example Response - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c" - }, - "account": { - "href": "https://horizon-testnet.stellar.org/accounts/GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR" - }, - "ledger": { - "href": "https://horizon-testnet.stellar.org/ledgers/697121" - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c/operations{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/transactions/264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/transactions?order=asc&cursor=2994111896358912" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/transactions?order=desc&cursor=2994111896358912" - } - }, - "id": "264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c", - "paging_token": "2994111896358912", - "successful": true, - "hash": "264226cb06af3b86299031884175155e67a02e0a8ad0b3ab3a88b409a8c09d5c", - "ledger": 697121, - "created_at": "2019-04-09T20:14:25Z", - "source_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "fee_account": "GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR", - "source_account_sequence": "4660039994869", - "fee_charged": 100, - "max_fee": 100, - "operation_count": 1, - "envelope_xdr": "AAAAABB90WssODNIgi6BHveqzxTRmIpvAFRyVNM+Hm2GVuCcAAAAZAAABD0AB031AAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAFIMRkFZ9gZifhRSlklQpsz/9P04Earv0dzS3MkIM1cYAAAAXSHboAAAAAAAAAAABhlbgnAAAAEA+biIjrDy8yi+SvhFElIdWGBRYlDscnSSHkPchePy2JYDJn4wvJYDBumXI7/NmttUey3+cGWbBFfnnWh1H5EoD", - "result_xdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAQAAAAIAAAADAAqjIQAAAAAAAAAAEH3Rayw4M0iCLoEe96rPFNGYim8AVHJU0z4ebYZW4JwBOLmYhGq/IAAABD0AB030AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAqjIQAAAAAAAAAAEH3Rayw4M0iCLoEe96rPFNGYim8AVHJU0z4ebYZW4JwBOLmYhGq/IAAABD0AB031AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAAAAwAAAAMACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar8gAAAEPQAHTfUAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uYE789cgAAAEPQAHTfUAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAACqMhAAAAAAAAAAAUgxGQVn2BmJ+FFKWSVCmzP/0/TgRqu/R3NLcyQgzVxgAAABdIdugAAAqjIQAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "fee_meta_xdr": "AAAAAgAAAAMACqMgAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar+EAAAEPQAHTfQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEACqMhAAAAAAAAAAAQfdFrLDgzSIIugR73qs8U0ZiKbwBUclTTPh5thlbgnAE4uZiEar8gAAAEPQAHTfQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "memo_type": "none", - "signatures": [ - "Pm4iI6w8vMovkr4RRJSHVhgUWJQ7HJ0kh5D3IXj8tiWAyZ+MLyWAwbplyO/zZrbVHst/nBlmwRX551odR+RKAw==" - ] -} -``` - -## Possible Errors - -- The [standard errors](../errors.md#Standard-Errors). -- [not_found](../errors/not-found.md): A `not_found` error will be returned if there is no - transaction whose ID matches the `hash` argument. diff --git a/services/horizon/internal/docs/reference/errors.md b/services/horizon/internal/docs/reference/errors.md deleted file mode 100644 index f95a922a4e..0000000000 --- a/services/horizon/internal/docs/reference/errors.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Errors -replacement: https://developers.stellar.org/api/errors/ ---- - -In the event that an error occurs while processing a request to horizon, an -**error** response will be returned to the client. This error response will -contain information detailing why the request couldn't complete successfully. - -Like HAL for successful responses, horizon uses a standard to specify how we -communicate errors to the client. Specifically, horizon uses the [Problem -Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) draft specification. The specification is short, so we recommend -you read it. In summary, when an error occurs on the server we respond with a -json document with the following attributes: - -| name | type | description | -| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | url | The identifier for the error, expressed as a url. Visiting the url in a web browser will redirect you to the additional documentation for the problem. | -| title | string | A short title describing the error. | -| status | number | An HTTP status code that maps to the error. An error that is triggered due to client input will be in the 400-499 range of status code, for example. | -| detail | string | A longer description of the error meant the further explain the error to developers. | -| instance | string | A token that uniquely identifies this request. Allows server administrators to correlate a client report with server log files | - - -## Standard Errors - -There are a set of errors that can occur in any request to horizon which we -call **standard errors**. These errors are: - -- [Server Error](../reference/errors/server-error.md) -- [Rate Limit Exceeded](../reference/errors/rate-limit-exceeded.md) -- [Forbidden](../reference/errors/forbidden.md) diff --git a/services/horizon/internal/docs/reference/errors/bad-request.md b/services/horizon/internal/docs/reference/errors/bad-request.md deleted file mode 100644 index 56cf369136..0000000000 --- a/services/horizon/internal/docs/reference/errors/bad-request.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Bad Request -replacement: https://developers.stellar.org/api/errors/http-status-codes/standard/ ---- - -If Horizon cannot understand a request due to invalid parameters, it will return a `bad_request` -error. This is analogous to the -[HTTP 400 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -If you are encountering this error, check the `invalid_field` attribute on the `extras` object to -see what field is triggering the error. - -## Attributes - -As with all errors Horizon returns, `bad_request` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```shell -$ curl -X GET "https://horizon-testnet.stellar.org/ledgers?limit=invalidlimit" -{ - "type": "https://stellar.org/horizon-errors/bad_request", - "title": "Bad Request", - "status": 400, - "detail": "The request you sent was invalid in some way", - "extras": { - "invalid_field": "limit", - "reason": "unparseable value" - } -} -``` - -## Related - -- [Malformed Transaction](./transaction-malformed.md) diff --git a/services/horizon/internal/docs/reference/errors/before-history.md b/services/horizon/internal/docs/reference/errors/before-history.md deleted file mode 100644 index 2e1dd7cc68..0000000000 --- a/services/horizon/internal/docs/reference/errors/before-history.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Before History -replacement: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/ ---- - -A horizon server may be configured to only keep a portion of the stellar network's history stored -within its database. This error will be returned when a client requests a piece of information -(such as a page of transactions or a single operation) that the server can positively identify as -falling outside the range of recorded history. - -This error returns a -[HTTP 410 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -## Attributes - -As with all errors Horizon returns, `before_history` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```shell -$ curl -X GET "https://horizon-testnet.stellar.org/transactions?cursor=1&order=desc" -{ - "type": "https://stellar.org/horizon-errors/before_history", - "title": "Data Requested Is Before Recorded History", - "status": 410, - "detail": "This horizon instance is configured to only track a portion of the stellar network's latest history. This request is asking for results prior to the recorded history known to this horizon instance." -} -``` - -## Related - -- [Not Found](./not-found.md) diff --git a/services/horizon/internal/docs/reference/errors/not-acceptable.md b/services/horizon/internal/docs/reference/errors/not-acceptable.md deleted file mode 100644 index d58305492a..0000000000 --- a/services/horizon/internal/docs/reference/errors/not-acceptable.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Not Acceptable -replacement: https://developers.stellar.org/api/errors/http-status-codes/standard/ ---- - -When your client only accepts certain formats of data from Horizon and Horizon cannot fulfill that -request, Horizon will return a `not_acceptable` error. This is analogous to a -[HTTP 406 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -For example, if your client only accepts an XML response (`Accept: application/xml`), Horizon will -respond with a `not_acceptable` error. - -If you are encountering this error, please check to make sure the criteria for content you’ll -accept is correct. - -## Attributes - -As with all errors Horizon returns, `not_acceptable` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```shell -$ curl -X GET -H "Accept: application/xml" "https://horizon-testnet.stellar.org/accounts/GALWEV6GY73RJ255JC7XUOZ2L7WZ5JJDTKATB2MUK7F3S67DVT2A6R5G" -{ - "type": "https://stellar.org/horizon-errors/not_acceptable", - "title": "An acceptable response content-type could not be provided for this request", - "status": 406 -} -``` - -## Related - -- [Not Found](./not-found.md) diff --git a/services/horizon/internal/docs/reference/errors/not-found.md b/services/horizon/internal/docs/reference/errors/not-found.md deleted file mode 100644 index f431b5eef2..0000000000 --- a/services/horizon/internal/docs/reference/errors/not-found.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Not Found -replacement: https://developers.stellar.org/api/errors/http-status-codes/standard/ ---- - -When Horizon can't find whatever data you are requesting, it will return a `not_found` error. This -is similar to a -[HTTP 404 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes) error -response. - -Incorrect URL path parameters or missing data are the common reasons for this error. If you -navigate using a link from a valid response, you should never receive this error message. - -## Attributes - -As with all errors Horizon returns, `not_found` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```shell -$ curl -X GET "https://horizon-testnet.stellar.org/accounts/accountthatdoesntexist" -{ - "type": "https://stellar.org/horizon-errors/bad_request", - "title": "Bad Request", - "status": 400, - "detail": "The request you sent was invalid in some way", - "extras": { - "invalid_field": "account_id", - "reason": "invalid address" - } -} -``` - -## Related - -- [Not Acceptable](./not-acceptable.md) diff --git a/services/horizon/internal/docs/reference/errors/not-implemented.md b/services/horizon/internal/docs/reference/errors/not-implemented.md deleted file mode 100644 index 41d1852ede..0000000000 --- a/services/horizon/internal/docs/reference/errors/not-implemented.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Not Implemented -replacement: https://developers.stellar.org/api/errors/http-status-codes/standard/ ---- - -If your [request method](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) is not supported by -Horizon, Horizon will return a `not_implemented` error. Likewise, if functionality that is intended -but does not exist (thus reserving the endpoint for future use), it will also return a -`not_implemented` error. This is analogous to a -[HTTP 501 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -If you are encountering this error, Horizon does not have the functionality you are requesting. - -## Attributes - -As with all errors Horizon returns, `not_implemented` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```shell -$ curl -X GET "https://horizon-testnet.stellar.org/offers/1234" -{ - "type": "https://stellar.org/horizon-errors/not_implemented", - "title": "Resource Not Yet Implemented", - "status": 404, - "detail": "While the requested URL is expected to eventually point to a valid resource, the work to implement the resource has not yet been completed." -} -``` - -## Related - -- [Server Error](./server-error.md) diff --git a/services/horizon/internal/docs/reference/errors/rate-limit-exceeded.md b/services/horizon/internal/docs/reference/errors/rate-limit-exceeded.md deleted file mode 100644 index 1a6399466e..0000000000 --- a/services/horizon/internal/docs/reference/errors/rate-limit-exceeded.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Rate Limit Exceeded -replacement: https://developers.stellar.org/api/errors/http-status-codes/standard/ ---- - -When a single user makes too many requests to Horizon in a one hour time frame, Horizon returns a -`rate_limit_exceeded` error. By default, Horizon allows 3600 requests per hour -- an average of one -request per second. This is analogous to a -[HTTP 429 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -If you are encountering this error, please reduce your request speed. Here are some strategies for -doing so: -* For collection endpoints, try specifying larger page sizes. -* Try streaming responses to watch for new data instead of pulling data every time. -* Cache immutable data, such as transaction details, locally. - -See the [Rate Limiting Guide](../../reference/rate-limiting.md) for more info. - -## Attributes - -As with all errors Horizon returns, `rate_limit_exceeded` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```json -{ - "type": "https://stellar.org/horizon-errors/rate_limit_exceeded", - "title": "Rate Limit Exceeded", - "status": 429, - "details": "The rate limit for the requesting IP address is over its alloted limit. The allowed limit and requests left per time period are communicated to clients via the http response headers 'X-RateLimit-*' headers." -} -``` diff --git a/services/horizon/internal/docs/reference/errors/server-error.md b/services/horizon/internal/docs/reference/errors/server-error.md deleted file mode 100644 index 7fe88bef91..0000000000 --- a/services/horizon/internal/docs/reference/errors/server-error.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Internal Server Error -replacement: https://developers.stellar.org/api/errors/http-status-codes/standard/ ---- - -If there's an internal error within Horizon, Horizon will return a -`server_error` response. This response is a catch-all, and can refer to many -possible errors in the Horizon server: a configuration mistake, a database -connection error, etc. This is analogous to a -[HTTP 500 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -Horizon does not expose information such as stack traces or raw error messages -to a client, as doing so may reveal sensitive configuration data such as secret -keys. If you are encountering this error on a server you control, please check the -Horizon log files for more details. The logs should contain detailed -information to help you discover the root issue. - -If you are encountering this error on the public Stellar infrastructure, please -report an error on [Horizon's issue tracker](https://github.com/stellar/go/issues) -and include as much information about the request that triggered the response -as you can (especially the time of the request). - -## Attributes - -As with all errors Horizon returns, `server_error` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Examples -```json -{ - "type": "https://stellar.org/horizon-errors/server_error", - "title": "Internal Server Error", - "status": 500, - "details": "An error occurred while processing this request. This is usually due to a bug within the server software. Trying this request again may succeed if the bug is transient, otherwise please report this issue to the issue tracker at: https://github.com/stellar/go/issues. Please include this response in your issue." -} -``` - -## Related - -- [Not Implemented](./not-implemented.md) diff --git a/services/horizon/internal/docs/reference/errors/stale-history.md b/services/horizon/internal/docs/reference/errors/stale-history.md deleted file mode 100644 index 041ef11723..0000000000 --- a/services/horizon/internal/docs/reference/errors/stale-history.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stale History -replacement: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/ ---- - -A horizon server may be configured to reject historical requests when the history is known to be -further out of date than the configured threshold. In such cases, this error is returned. To -resolve this error (provided you are the horizon instance's operator) please ensure that the -ingestion system is running correctly and importing new ledgers. This error returns a -[HTTP 503 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -## Attributes - -As with all errors Horizon returns, `stale_history` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example - -```json -{ - - "type": "https://stellar.org/horizon-errors/stale_history", - "title": "Historical DB Is Too Stale", - "status": 503, - "detail": "This horizon instance is configured to reject client requests when it can determine that the history database is lagging too far behind the connected instance of stellar-core. If you operate this server, please ensure that the ingestion system is properly running." -} -``` - -## Related - -- [Internal Server Error](./server-error.md) diff --git a/services/horizon/internal/docs/reference/errors/timeout.md b/services/horizon/internal/docs/reference/errors/timeout.md deleted file mode 100644 index dca8cf4d64..0000000000 --- a/services/horizon/internal/docs/reference/errors/timeout.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Timeout -replacement: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/ ---- - -If you are encountering this error it means that either: - -* Horizon has not received a confirmation from the Stellar Core server that the transaction you are - trying to submit to the network was included in a ledger in a timely manner. -* Horizon has not sent a response to a reverse-proxy before a specified amount of time has elapsed. - -The former case may happen because there was no room for your transaction for 3 consecutive -ledgers. This is because Stellar Core removes each submitted transaction from a queue. To solve -this you can: - -* Keep resubmitting the same transaction (with the same sequence number) and wait until it finally - is added to a new ledger. -* Increase the [fee](../../../guides/concepts/fees.md) in order to prioritize the transaction. - -This error returns a -[HTTP 504 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -## Attributes - -As with all errors Horizon returns, `timeout` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -## Example -```json -{ - "type": "https://stellar.org/horizon-errors/timeout", - "title": "Timeout", - "status": 504, - "detail": "Your request timed out before completing. Please try your request again. If you are submitting a transaction make sure you are sending exactly the same transaction (with the same sequence number)." -} -``` - -## Related - -- [Not Acceptable](./not-acceptable.md) -- [Transaction Failed](./transaction-failed.md) diff --git a/services/horizon/internal/docs/reference/errors/transaction-failed.md b/services/horizon/internal/docs/reference/errors/transaction-failed.md deleted file mode 100644 index fa84178d3a..0000000000 --- a/services/horizon/internal/docs/reference/errors/transaction-failed.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Transaction Failed -replacement: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/ ---- - -The `transaction_failed` error occurs when a client submits a transaction that was well-formed but -was not included into the ledger due to some other failure. For example, a transaction may fail if: - -- The source account for transaction cannot pay the minimum fee. -- The sequence number is incorrect. -- One of the contained operations has failed such as a payment operation that overdraws on the - paying account. - -In almost every case, this error indicates that the transaction submitted in the initial request -will never succeed. There is one exception: a transaction that fails with the `tx_bad_seq` result -code (as expressed in the `result_code` field of the error) may become valid in the future if the -sequence number it used was too high. - -This error returns a -[HTTP 400 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -## Attributes - -As with all errors Horizon returns, `transaction_failed` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -In addition, the following additional data is provided in the `extras` field of the error: - -| Attribute | Type | Description | -|----------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| -| `envelope_xdr` | String | A base64-encoded representation of the TransactionEnvelope XDR whose failure triggered this response. | -| `result_xdr` | String | A base64-encoded representation of the TransactionResult XDR returned by stellar-core when submitting this transaction. | -| `result_codes.transaction` | String | The transaction result code returned by Stellar Core. | -| `result_codes.operations` | Array | An array of strings, representing the operation result codes for each operation in the submitted transaction, if available. | - - -## Examples - -### No Source Account -```json -{ - "type": "https://stellar.org/horizon-errors/transaction_failed", - "title": "Transaction Failed", - "status": 400, - "detail": "The transaction failed when submitted to the stellar network. The `extras.result_codes` field on this response contains further details. Descriptions of each code can be found at: https://www.stellar.org/developers/learn/concepts/list-of-operations.html", - "extras": { - "envelope_xdr": "AAAAANNVpdQ9vctZdAJ67sFmNe1KDzaj51dAdkW3vKKM51H3AAAAZAAAAABJlgLSAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAA01Wl1D29y1l0AnruwWY17UoPNqPnV0B2Rbe8ooznUfcAAAAAAAAAAAL68IAAAAAAAAAAAA==", - "result_codes": { - "transaction": "tx_no_source_account" - }, - "result_xdr": "AAAAAAAAAAD////4AAAAAA==" - } -} -``` - -### Bad Authentication -```json -{ - "type": "https://stellar.org/horizon-errors/transaction_failed", - "title": "Transaction Failed", - "status": 400, - "detail": "The transaction failed when submitted to the stellar network. The `extras.result_codes` field on this response contains further details. Descriptions of each code can be found at: https://www.stellar.org/developers/learn/concepts/list-of-operations.html", - "extras": { - "envelope_xdr": "AAAAAPORy3CoX6ox2ilbeiVjBA5WlpCSZRcjZ7VE9Wf4QVk7AAAAZAAAQz0AAAACAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAA85HLcKhfqjHaKVt6JWMEDlaWkJJlFyNntUT1Z/hBWTsAAAAAAAAAAAL68IAAAAAAAAAAARN17BEAAABAA9Ad7OKc7y60NT/JuobaHOfmuq8KbZqcV6G/es94u9yT84fi0aI7tJsFMOyy8cZ4meY3Nn908OU+KfRWV40UCw==", - "result_codes": { - "transaction": "tx_bad_auth" - }, - "result_xdr": "AAAAAAAAAGT////6AAAAAA==" - } -} -``` - -## Related - -- [Transaction Malformed](./transaction-malformed.md) diff --git a/services/horizon/internal/docs/reference/errors/transaction-malformed.md b/services/horizon/internal/docs/reference/errors/transaction-malformed.md deleted file mode 100644 index 24983047c0..0000000000 --- a/services/horizon/internal/docs/reference/errors/transaction-malformed.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Transaction Malformed -replacement: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/ ---- - -When you submit a malformed transaction to Horizon, Horizon will return a `transaction_malformed` -error. There are many ways in which a transaction could be malformed, including: - -- You submitted an empty string. -- Your base64-encoded string is invalid. -- Your [XDR](../xdr.md) structure is invalid. -- You have leftover bytes in your [XDR](../xdr.md) structure. - -If you are encountering this error, please check the contents of the transaction you are -submitting. This error returns a -[HTTP 400 Error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Response_codes). - -## Attributes - -As with all errors Horizon returns, `transaction_malformed` follows the -[Problem Details for HTTP APIs](https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-00) -draft specification guide and thus has the following attributes: - -| Attribute | Type | Description | -| ----------- | ------ | ------------------------------------------------------------------------------- | -| `type` | URL | The identifier for the error. This is a URL that can be visited in the browser.| -| `title` | String | A short title describing the error. | -| `status` | Number | An HTTP status code that maps to the error. | -| `detail` | String | A more detailed description of the error. | - -In addition, the following additional data is provided in the `extras` field of the error: - -| Attribute | Type | Description | -|----------------|--------|----------------------------------------------------| -| `envelope_xdr` | String | The submitted data that was malformed in some way. | - -## Example - -```json -{ - "type": "https://stellar.org/horizon-errors/transaction_malformed", - "title": "Transaction Malformed", - "status": 400, - "detail": "Horizon could not decode the transaction envelope in this request. A transaction should be an XDR TransactionEnvelope struct encoded using base64. The envelope read from this request is echoed in the `extras.envelope_xdr` field of this response for your convenience.", - "extras": { - "envelope_xdr": "BBBBBPORy3CoX6ox2ilbeiVjBA5WlpCSZRcjZ7VE9Wf4QVk7AAAAZAAAQz0AAAACAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAA85HLcKhfqjHaKVt6JWMEDlaWkJJlFyNntUT1Z/hBWTsAAAAAAAAAAAL68IAAAAAAAAAAARN17BEAAABAA9Ad7OKc7y60NT/JuobaHOfmuq8KbZqcV6G/es94u9yT84fi0aI7tJsFMOyy8cZ4meY3Nn908OU+KfRWV40UCw==" - } -} -``` - -## Related - -- [Bad Request](./bad-request.md) diff --git a/services/horizon/internal/docs/reference/paging.md b/services/horizon/internal/docs/reference/paging.md deleted file mode 100644 index d2c8db0dda..0000000000 --- a/services/horizon/internal/docs/reference/paging.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Paging -replacement: https://developers.stellar.org/api/introduction/pagination/ ---- - -The Stellar network contains a lot of data and it would be infeasible to return it all at once. The paging system allows -a user to request a "page" of data containing only a limited number of results. Then, the user can use the paging system -to request results adjacent to the current page where they left off at. - -Read about the [page resource](../reference/resources/page.md) for information on the paging system's usage and representation. - - diff --git a/services/horizon/internal/docs/reference/rate-limiting.md b/services/horizon/internal/docs/reference/rate-limiting.md deleted file mode 100644 index 642412fbed..0000000000 --- a/services/horizon/internal/docs/reference/rate-limiting.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Rate Limiting -replacement: https://developers.stellar.org/api/introduction/rate-limiting/ ---- - -In order to provide service stability, Horizon limits the number of requests a -client (single IP) can perform within a one hour window. By default this is set to 3600 -requests per hour—an average of one request per second. Also, while streaming -every update of the stream (what happens every time there's a new ledger) is -counted. Ex. if there were 12 new ledgers in a minute, 12 requests will be -subtracted from the limit. - -Horizon is using [GCRA](https://brandur.org/rate-limiting#gcra) algorithm. - -## Response headers for rate limiting - -Every response from Horizon sets advisory headers to inform clients of their -standing with rate limiting system: - -| Header | Description | -| ----------------------- | ------------------------------------------------------------------------ | -| `X-RateLimit-Limit` | The maximum number of requests that the current client can make in one hour. | -| `X-RateLimit-Remaining` | The number of remaining requests for the current window. | -| `X-RateLimit-Reset` | Seconds until a new window starts. | - -In addition, a `Retry-After` header will be set when the current client is being -throttled. diff --git a/services/horizon/internal/docs/reference/readme.md b/services/horizon/internal/docs/reference/readme.md deleted file mode 100644 index 0e4f4cbc32..0000000000 --- a/services/horizon/internal/docs/reference/readme.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Overview ---- - -Horizon is an API server for the Stellar ecosystem. It acts as the interface between [stellar-core](https://github.com/stellar/stellar-core) and applications that want to access the Stellar network. It allows you to submit transactions to the network, check the status of accounts, subscribe to event streams, etc. See [an overview of the Stellar ecosystem](https://www.stellar.org/developers/guides/) for details of where Horizon fits in. - -Horizon provides a RESTful API to allow client applications to interact with the Stellar network. You can communicate with Horizon using cURL or just your web browser. However, if you're building a client application, you'll likely want to use a Stellar SDK in the language of your client. -SDF provides a [JavaScript SDK](https://www.stellar.org/developers/js-stellar-sdk/reference/index.html) for clients to use to interact with Horizon. - -SDF runs a instance of Horizon that is connected to the test net: [https://horizon-testnet.stellar.org/](https://horizon-testnet.stellar.org/) and one that is connected to the public Stellar network: -[https://horizon.stellar.org/](https://horizon.stellar.org/). - -## Libraries - -SDF maintained libraries:
-- [JavaScript](https://github.com/stellar/js-stellar-sdk) -- [Go](https://github.com/stellar/go/tree/master/clients/horizonclient) -- [Java](https://github.com/stellar/java-stellar-sdk) - -Community maintained libraries for interacting with Horizon in other languages:
-- [Python](https://github.com/StellarCN/py-stellar-base) -- [C# .NET Core 2.x](https://github.com/elucidsoft/dotnetcore-stellar-sdk) -- [Ruby](https://github.com/astroband/ruby-stellar-sdk) -- [iOS and macOS](https://github.com/Soneso/stellar-ios-mac-sdk) -- [Scala SDK](https://github.com/synesso/scala-stellar-sdk) -- [C++ SDK](https://github.com/bnogalm/StellarQtSDK) diff --git a/services/horizon/internal/docs/reference/resources/account.md b/services/horizon/internal/docs/reference/resources/account.md deleted file mode 100644 index 8e90e78f77..0000000000 --- a/services/horizon/internal/docs/reference/resources/account.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Account -replacement: https://developers.stellar.org/api/resources/accounts/ ---- - -In the Stellar network, users interact using **accounts** which can be controlled by a corresponding keypair that can authorize transactions. One can create a new account with the [Create Account](./operation.md#create-account) operation. - -To learn more about the concept of accounts in the Stellar network, take a look at the [Stellar account concept guide](https://www.stellar.org/developers/learn/concepts/accounts.html). - -When horizon returns information about an account it uses the following format: - -## Attributes -| Attribute | Type | Description | -|----------------|------------------|------------------------------------------------------------------------------------------------------------------------ | -| id | string | The canonical id of this account, suitable for use as the :id parameter for url templates that require an account's ID. | -| account_id | string | The account's public key encoded into a base32 string representation. | -| sequence | number | The current sequence number that can be used when submitting a transaction from this account. | -| subentry_count | number | The number of [account subentries](https://www.stellar.org/developers/guides/concepts/ledger.html#ledger-entries). | -| balances | array of objects | An array of the native asset or credits this account holds. | -| thresholds | object | An object of account thresholds. | -| flags | object | The flags denote the enabling/disabling of certain asset issuer privileges. | -| signers | array of objects | An array of [account signers](https://www.stellar.org/developers/guides/concepts/multi-sig.html#additional-signing-keys) with their weights. | -| data | object | An array of account [data](./data.md) fields. | - -### Signer Object -| Attribute | Type | Description | -|------------|--------|------------------------------------------------------------------------------------------------------------------| -| weight | number | The numerical weight of a signer, necessary to determine whether a transaction meets the threshold requirements. | -| key | string | Different depending on the type of the signer. | -| type | string | See below. | - -### Possible Signer Types -| Type | Description | -|--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ed25519_public_key | A normal Stellar public key. | -| sha256_hash | The SHA256 hash of some arbitrary `x`. Adding a signature of this type allows anyone who knows `x` to sign a transaction from this account. *Note: Once this transaction is broadcast, `x` will be known publicly.* | -| preauth_tx | The hash of a pre-authorized transaction. This signer is automatically removed from the account when a matching transaction is properly applied. | -### Balances Object -| Attribute | Type | | -|---------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| balance | string | How much of an asset is owned. | -| buying_liabilities | string | The total amount of an asset offered to buy aggregated over all offers owned by this account. | -| selling_liabilities | string | The total amount of an asset offered to sell aggregated over all offers owned by this account. | -| limit | optional, number | The maximum amount of an asset that this account is willing to accept (this is specified when an account opens a trustline). | -| asset_type | string | Either native, credit_alphanum4, or credit_alphanum12. | -| asset_code | optional, string | The code for the asset. | -| asset_issuer | optional, string | The stellar address of the given asset's issuer. | -| is_authorized | optional, bool | The trustline status for an `auth_required` asset. If true, the issuer of the asset has granted the account permission to send, receive, buy, or sell the asset. If false, the issuer has not, so the account cannot send, receive, buy, or sell the asset. | - -### Flag Object -| Attribute | Type | | -|----------------|------|--------------------------------------------------------------------------------------------------------------------------------| -| auth_immutable | bool | With this setting, none of the following authorization flags can be changed. | -| auth_required | bool | With this setting, an anchor must approve anyone who wants to hold its asset. | -| auth_revocable | bool | With this setting, an anchor can set the authorize flag of an existing trustline to freeze the assets held by an asset holder. | - -### Threshold Object -| Attribute | Type | | -|----------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| low_threshold | number | The weight required for a valid transaction including the [Allow Trust][allow_trust] and [Bump Sequence][bump_seq] operations. | -| med_threshold | number | The weight required for a valid transaction including the [Create Account][create_acc], [Payment][payment], [Path Payment Strict Send][path_payment_send], [Path Payment Strict Receive][path_payment_receive], [Manage Buy Offer][manage_buy_offer], [Manage Sell Offer][manage_sell_offer], [Create Passive Sell Offer][passive_sell_offer], [Change Trust][change_trust], [Inflation][inflation], and [Manage Data][manage_data] operations. | -| high_threshold | number | The weight required for a valid transaction including the [Account Merge][account_merge] and [Set Options]() operations. | - -[account_merge]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#account-merge -[allow_trust]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#allow-trust -[bump_seq]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#bump-sequence -[change_trust]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#change-trust -[create_acc]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#create-account -[inflation]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#inflation -[manage_data]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-data -[manage_buy_offer]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-buy-offer -[manage_sell_offer]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-sell-offer -[passive_sell_offer]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#create-passive-sell-offer -[path_payment_receive]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#path-payment-strict-receive -[path_payment_send]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#path-payment-strict-send -[payment]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#payment -[set_options]: https://www.stellar.org/developers/guides/concepts/list-of-operations.html#set-options - -## Links -| rel | Example | Description | `templated` | -|--------------|---------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|-------------| -| data | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/data/{key}` | [Data fields](./data.md) related to this account | true | -| effects | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/effects/{?cursor,limit,order}` | The [effects](./effect.md) related to this account | true | -| offers | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/offers/{?cursor,limit,order}` | The [offers](./offer.md) related to this account | true | -| operations | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/operations/{?cursor,limit,order}` | The [operations](./operation.md) related to this account | true | -| payments | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/payments/{?cursor,limit,order}` | The [payments](./payment.md) related to this account | true | -| trades | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/trades/{?cursor,limit,order}` | The [trades](./trade.md) related to this account | true | -| transactions | `/accounts/GAOEWNUEKXKNGB2AAOX6S6FEP6QKCFTU7KJH647XTXQXTMOAUATX2VF5/transactions/{?cursor,limit,order}` | The [transactions](./transaction.md) related to this account | true | - -## Example - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW" - }, - "transactions": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/transactions{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/operations{?cursor,limit,order}", - "templated": true - }, - "payments": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/payments{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/effects{?cursor,limit,order}", - "templated": true - }, - "offers": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/offers{?cursor,limit,order}", - "templated": true - }, - "trades": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/trades{?cursor,limit,order}", - "templated": true - }, - "data": { - "href": "https://horizon-testnet.stellar.org/accounts/GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW/data/{key}", - "templated": true - } - }, - "id": "GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW", - "paging_token": "", - "account_id": "GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW", - "sequence": "43692723777044483", - "subentry_count": 3, - "thresholds": { - "low_threshold": 0, - "med_threshold": 0, - "high_threshold": 0 - }, - "flags": { - "auth_required": false, - "auth_revocable": false, - "auth_immutable": false - }, - "balances": [ - { - "balance": "1000000.0000000", - "limit": "922337203685.4775807", - "buying_liabilities": "0.0000000", - "selling_liabilities": "0.0000000", - "last_modified_ledger": 632070, - "asset_type": "credit_alphanum4", - "asset_code": "FOO", - "asset_issuer": "GAGLYFZJMN5HEULSTH5CIGPOPAVUYPG5YSWIYDJMAPIECYEBPM2TA3QR" - }, - { - "balance": "10000.0000000", - "buying_liabilities": "0.0000000", - "selling_liabilities": "0.0000000", - "asset_type": "native" - } - ], - "signers": [ - { - "public_key": "GDLEPBJBC2VSKJCLJB264F2WDK63X4NKOG774A3QWVH2U6PERGDPUCS4", - "weight": 1, - "key": "GDLEPBJBC2VSKJCLJB264F2WDK63X4NKOG774A3QWVH2U6PERGDPUCS4", - "type": "ed25519_public_key" - }, - { - "public_key": "XCPNCUKYDHPMMH6TMHK73K5VP5A6ZTQ2L7Q74JR3TDANNFB3TMRS5OKG", - "weight": 1, - "key": "XCPNCUKYDHPMMH6TMHK73K5VP5A6ZTQ2L7Q74JR3TDANNFB3TMRS5OKG", - "type": "sha256_hash" - }, - { - "public_key": "TABGGIW6EXOVOSNJ2O27U2DUX7RWHSRBGOKQLGYDTOXPANEX6LXBX7O7", - "weight": 1, - "key": "TABGGIW6EXOVOSNJ2O27U2DUX7RWHSRBGOKQLGYDTOXPANEX6LXBX7O7", - "type": "preauth_tx" - }, - { - "public_key": "GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW", - "weight": 1, - "key": "GBWRID7MPYUDBTNQPEHUN4XOBVVDPJOHYXAVW3UTOD2RG7BDAY6O3PHW", - "type": "ed25519_public_key" - } - ], - "data": {} -} -``` - -## Endpoints -| Resource | Type | Resource URI Template | -|------------------------------------------------------------------|------------|--------------------------------------| -| [Account Details](../endpoints/accounts-single.md) | Single | `/accounts/:id` | -| [Account Data](../endpoints/data-for-account.md) | Single | `/accounts/:id/data/:key` | -| [Account Transactions](../endpoints/transactions-for-account.md) | Collection | `/accounts/:account_id/transactions` | -| [Account Operations](../endpoints/operations-for-account.md) | Collection | `/accounts/:account_id/operations` | -| [Account Payments](../endpoints/payments-for-account.md) | Collection | `/accounts/:account_id/payments` | -| [Account Effects](../endpoints/effects-for-account.md) | Collection | `/accounts/:account_id/effects` | -| [Account Offers](../endpoints/offers-for-account.md) | Collection | `/accounts/:account_id/offers` | diff --git a/services/horizon/internal/docs/reference/resources/asset.md b/services/horizon/internal/docs/reference/resources/asset.md deleted file mode 100644 index 730b0de73a..0000000000 --- a/services/horizon/internal/docs/reference/resources/asset.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Asset -replacement: https://developers.stellar.org/api/resources/assets/ ---- - -**Assets** are the units that are traded on the Stellar Network. - -An asset consists of an type, code, and issuer. - -To learn more about the concept of assets in the Stellar network, take a look at the [Stellar assets concept guide](https://www.stellar.org/developers/guides/concepts/assets.html). - -## Attributes - -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| asset_type | string | The type of this asset: "credit_alphanum4", or "credit_alphanum12". | -| asset_code | string | The code of this asset. | -| asset_issuer | string | The issuer of this asset. | -| accounts | object | The number of accounts and claimable balances holding this asset. Accounts are summarized by each state of the trust line flags. | -| balances | object | The number of units of credit issued, summarized by each state of the trust line flags, or if they are in a claimable balance. | -| flags | object | The flags denote the enabling/disabling of certain asset issuer privileges. | -| paging_token | string | A [paging token](./page.md) suitable for use as the `cursor` parameter to transaction collection resources. | - -#### Flag Object -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| auth_immutable | bool | With this setting, none of the following authorization flags can be changed. | -| auth_required | bool | With this setting, an anchor must approve anyone who wants to hold its asset. | -| auth_revocable | bool | With this setting, an anchor can set the authorize flag of an existing trustline to freeze the assets held by an asset holder. | - -## Links -| rel | Example | Description -|--------------|---------------------------------------------------------------------------------------------------|------------------------------------------------------------ -| toml | `https://www.stellar.org/.well-known/stellar.toml`| Link to the TOML file for this issuer | - -## Example - -```json -{ - "_links": { - "toml": { - "href": "https://www.stellar.org/.well-known/stellar.toml" - } - }, - "asset_type": "credit_alphanum4", - "asset_code": "USD", - "asset_issuer": "GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG", - "paging_token": "USD_GBAUUA74H4XOQYRSOW2RZUA4QL5PB37U3JS5NE3RTB2ELJVMIF5RLMAG_credit_alphanum4", - "accounts": { - "authorized": 91547871, - "authorized_to_maintain_liabilities": 45773935, - "unauthorized": 22886967, - "claimable_balances": 11443483 - }, - "balances": { - "authorized": "100.0000000", - "authorized_to_maintain_liabilities": "50.0000000", - "unauthorized": "25.0000000", - "claimable_balances": "12.5000000" - }, - "flags": { - "auth_required": false, - "auth_revocable": false - } -} -``` - -## Endpoints - -| Resource | Type | Resource URI Template | -| ---------------------------------------- | ---------- | ---------------------------- | -| [All Assets](../endpoints/assets-all.md) | Collection | `/assets` (`GET`) | diff --git a/services/horizon/internal/docs/reference/resources/data.md b/services/horizon/internal/docs/reference/resources/data.md deleted file mode 100644 index fb79d26d7b..0000000000 --- a/services/horizon/internal/docs/reference/resources/data.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Data -replacement: https://developers.stellar.org/api/resources/accounts/data/ ---- - -Each account in Stellar network can contain multiple key/value pairs associated with it. Horizon can be used to retrieve value of each data key. - -When horizon returns information about a single account data key it uses the following format: - -## Attributes - -| Attribute | Type | | -| --- | --- | --- | -| value | base64-encoded string | The base64-encoded value for the key | - -## Example - -```json -{ - "value": "MTAw" -} -``` diff --git a/services/horizon/internal/docs/reference/resources/effect.md b/services/horizon/internal/docs/reference/resources/effect.md deleted file mode 100644 index 8eb2c29452..0000000000 --- a/services/horizon/internal/docs/reference/resources/effect.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Effect -replacement: https://developers.stellar.org/api/resources/effects/ ---- - -A successful operation will yield zero or more **effects**. These effects -represent specific changes that occur in the ledger, but are not necessarily -directly reflected in the [ledger](https://www.stellar.org/developers/learn/concepts/ledger.html) or [history](https://github.com/stellar/stellar-core/blob/master/docs/history.md), as [transactions](https://www.stellar.org/developers/learn/concepts/transactions.html) and [operations](https://www.stellar.org/developers/learn/concepts/operations.html) are. - -## Effect types - -We can distinguish 6 effect groups: -- Account effects -- Signer effects -- Trustline effects -- Trading effects -- Data effects -- Misc effects - -### Account effects - -| Type | Operation | -|---------------------------------------|------------------------------------------------------| -| Account Created | create_account | -| Account Removed | merge_account | -| Account Credited | create_account, payment, path_payment, merge_account | -| Account Debited | create_account, payment, path_payment, merge_account | -| Account Thresholds Updated | set_options | -| Account Home Domain Updated | set_options | -| Account Flags Updated | set_options | -| Account Inflation Destination Updated | set_options | - -### Signer effects - -| Type | Operation | -|----------------|-------------| -| Signer Created | set_options | -| Signer Removed | set_options | -| Signer Updated | set_options | - -### Trustline effects - -| Type | Operation | -|------------------------|---------------------------| -| Trustline Created | change_trust | -| Trustline Removed | change_trust | -| Trustline Updated | change_trust, allow_trust | -| Trustline Authorized | allow_trust | -| Trustline Deauthorized | allow_trust | - -### Trading effects - -| Type | Operation | -|---------------|------------------------------------------------------------------------------| -| Offer Created | manage_buy_offer, manage_sell_offer, create_passive_sell_offer | -| Offer Removed | manage_buy_offer, manage_sell_offer, create_passive_sell_offer, path_payment | -| Offer Updated | manage_buy_offer, manage_sell_offer, create_passive_sell_offer, path_payment | -| Trade | manage_buy_offer, manage_sell_offer, create_passive_sell_offer, path_payment | -### Data effects - -| Type | Operation | -|--------------|-------------| -| Data Created | manage_data | -| Data Removed | manage_data | -| Data Updated | manage_data | -### Misc effects - -| Type | Operation | -|-----------------|---------------| -| Sequence Bumped | bump_sequence | - -## Attributes - -Attributes depend on effect type. - -## Links - -| rel | Example | Relation | -|-----------|---------------------------------------------------------------|-----------------------------------| -| self | `/effects?order=asc\u0026limit=1` | | -| prev | `/effects?order=desc\u0026limit=1\u0026cursor=141733924865-1` | | -| next | `/effects?order=asc\u0026limit=1\u0026cursor=141733924865-1` | | -| operation | `/operations/141733924865` | Operation that created the effect | - -## Example - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "operation": { - "href": "/operations/141733924865" - }, - "precedes": { - "href": "/effects?cursor=141733924865-1\u0026order=asc" - }, - "succeeds": { - "href": "/effects?cursor=141733924865-1\u0026order=desc" - } - }, - "account": "GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K", - "paging_token": "141733924865-1", - "starting_balance": "10000000.0", - "type_i": 0, - "type": "account_created" - } - ] - }, - "_links": { - "next": { - "href": "/effects?order=asc\u0026limit=1\u0026cursor=141733924865-1" - }, - "prev": { - "href": "/effects?order=desc\u0026limit=1\u0026cursor=141733924865-1" - }, - "self": { - "href": "/effects?order=asc\u0026limit=1\u0026cursor=" - } - } -} -``` - -## Endpoints - -| Resource | Type | Resource URI Template | -|--------------------------------------------------------------------------------------------------------------------------------------------|------------|---------------------------------| -| [All Effects](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/reference/endpoints/effects-all.md) | Collection | `/effects` | -| [Operation Effects](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/reference/endpoints/effects-for-operation.md) | Collection | `/operations/:id/effects` | -| [Account Effects](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/reference/endpoints/effects-for-account.md) | Collection | `/accounts/:account_id/effects` | -| [Ledger Effects](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/reference/endpoints/effects-for-ledger.md) | Collection | `/ledgers/:ledger_id/effects` | diff --git a/services/horizon/internal/docs/reference/resources/ledger.md b/services/horizon/internal/docs/reference/resources/ledger.md deleted file mode 100644 index 23632cc1da..0000000000 --- a/services/horizon/internal/docs/reference/resources/ledger.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Ledger -replacement: https://developers.stellar.org/api/resources/ledgers/ ---- - -A **ledger** resource contains information about a given ledger. - -To learn more about the concept of ledgers in the Stellar network, take a look at the [Stellar ledger concept guide](https://www.stellar.org/developers/learn/concepts/ledger.html). - -## Attributes - -| Attribute | Type | | -|------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------| -| id | string | The id is a unique identifier for this ledger. | -| paging_token | number | A [paging token](./page.md) suitable for use as a `cursor` parameter. | -| hash | string | A hex-encoded, lowercase SHA-256 hash of the ledger's [XDR](../../learn/xdr.md)-encoded form. | -| prev_hash | string | The hash of the ledger that chronologically came before this one. | -| sequence | number | Sequence number of this ledger, suitable for use as the as the :id parameter for url templates that require a ledger number. | -| successful_transaction_count | number | The number of successful transactions in this ledger. | -| failed_transaction_count | number | The number of failed transactions in this ledger. | -| operation_count | number | The number of operations applied in this ledger. | -| tx_set_operation_count | number | The number of operations in this ledger. This number includes operations from failed and successful transactions. | -| closed_at | string | An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted string of when this ledger was closed. | -| total_coins | string | The total number of lumens in circulation. | -| fee_pool | string | The sum of all transaction fees *(in lumens)* since the last inflation operation. They are redistributed during [inflation]. | -| base_fee | number | The [fee] the network charges per operation in a transaction. | -| base_reserve | string | The [reserve][fee] the network uses when calculating an account's minimum balance. | -| max_tx_set_size | number | The maximum number of transactions validators have agreed to process in a given ledger. | -| protocol_version | number | The protocol version that the stellar network was running when this ledger was committed. | -| header_xdr | string | A base64 encoded string of the raw `LedgerHeader` xdr struct for this ledger. | -| base_fee_in_stroops | number | The [fee] the network charges per operation in a transaction. Expressed in stroops. | -| base_reserve_in_stroops | number | The [reserve][fee] the network uses when calculating an account's minimum balance. Expressed in stroops. | - -## Links -| | Example | Relation | templated | -|--------------|---------------------------------------------------|---------------------------------|-----------| -| self | `/ledgers/500` | | | -| effects | `/ledgers/500/effects/{?cursor,limit,order}` | The effects in this transaction | true | -| operations | `/ledgers/500/operations/{?cursor,limit,order}` | The operations in this ledger | true | -| transactions | `/ledgers/500/transactions/{?cursor,limit,order}` | The transactions in this ledger | true | - - -## Example - -```json -{ - "_links": { - "effects": { - "href": "/ledgers/500/effects/{?cursor,limit,order}", - "templated": true - }, - "operations": { - "href": "/ledgers/500/operations/{?cursor,limit,order}", - "templated": true - }, - "self": { - "href": "/ledgers/500" - }, - "transactions": { - "href": "/ledgers/500/transactions/{?cursor,limit,order}", - "templated": true - } - }, - "id": "689f00d4824b8e69330bf4ad7eb10092ff2f8fdb76d4668a41eebb9469ef7f30", - "paging_token": "2147483648000", - "hash": "689f00d4824b8e69330bf4ad7eb10092ff2f8fdb76d4668a41eebb9469ef7f30", - "prev_hash": "b608e110c7cc58200c912140f121af50dc5ef407aabd53b76e1741080aca1cf0", - "sequence": 500, - "transaction_count": 0, - "successful_transaction_count": 0, - "failed_transaction_count": 0, - "operation_count": 0, - "tx_set_operation_count": 0, - "closed_at": "2015-07-09T21:39:28Z", - "total_coins": "100000000000.0000000", - "fee_pool": "0.0025600", - "base_fee": 100, - "base_reserve": "10.0000000", - "max_tx_set_size": 50, - "protocol_version": 8, - "header_xdr": "...", - "base_fee_in_stroops": 100, - "base_reserve_in_stroops": 100000000 -} -``` - -## Endpoints -| Resource | Type | Resource URI Template | -|-------------------------|------------|------------------------------------| -| [All ledgers](../endpoints/ledgers-all.md) | Collection | `/ledgers` | -| [Single Ledger](../endpoints/ledgers-single.md) | Single | `/ledgers/:id` | -| [Ledger Transactions](../endpoints/transactions-for-ledger.md) | Collection | `/ledgers/:ledger_id/transactions` | -| [Ledger Operations](../endpoints/operations-for-ledger.md) | Collection | `/ledgers/:ledger_id/operations` | -| [Ledger Payments](../endpoints/payments-for-ledger.md) | Collection | `/ledgers/:ledger_id/payments` | -| [Ledger Effects](../endpoints/effects-for-ledger.md) | Collection | `/ledgers/:ledger_id/effects` | - - - -[inflation]: https://www.stellar.org/developers/learn/concepts/inflation.html -[fee]: https://www.stellar.org/developers/learn/concepts/fees.html diff --git a/services/horizon/internal/docs/reference/resources/offer.md b/services/horizon/internal/docs/reference/resources/offer.md deleted file mode 100644 index 14c2a8cb96..0000000000 --- a/services/horizon/internal/docs/reference/resources/offer.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Offer -replacement: https://developers.stellar.org/api/resources/offers/ ---- - -Accounts on the Stellar network can make [offers](http://stellar.org/developers/learn/concepts/exchange.html) to buy or sell assets. Users can create offers with the [Manage Offer](http://stellar.org/developers/learn/concepts/list-of-operations.html) operation. - -Horizon only returns offers that belong to a particular account. When it does, it uses the following format: - -## Attributes -| Attribute | Type | | -|----------------------|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| id | string | The ID of this offer. | -| paging_token | string | A [paging token](./page.md) suitable for use as a `cursor` parameter. | -| seller | string | Account id of the account making this offer. | -| selling | [Asset](http://stellar.org/developers/learn/concepts/assets.html) | The Asset this offer wants to sell. | -| buying | [Asset](http://stellar.org/developers/learn/concepts/assets.html) | The Asset this offer wants to buy. | -| amount | string | The amount of `selling` the account making this offer is willing to sell. | -| price_r | object | An object of a number numerator and number denominator that represent the buy and sell price of the currencies on offer. | -| price | string | How many units of `buying` it takes to get 1 unit of `selling`. A number representing the decimal form of `price_r`. | -| last_modified_ledger | integer | sequence number for the latest ledger in which this offer was modified. | -| last_modified_time | string | An ISO 8601 formatted string of last modification time. | - -#### Price_r Object -Price_r is a more precise representation of a bid/ask offer. - -| Attribute | Type | | -|-----------|--------|------------------| -| n | number | The numerator. | -| d | number | The denominator. | - -Thus to get price you would take n / d. - - - -## Links -| rel | Example | Description | `templated` | -|--------|------------------------------------------|---------------------------------------------------------|-------------| -| seller | `/accounts/{seller}?cursor,limit,order}` | Link to details about the account that made this offer. | true | - -## Example - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/offers/2611" - }, - "offer_maker": { - "href": "https://horizon-testnet.stellar.org/accounts/GDG3NOK5YI7A4FCBHE6SKI4L65R7UPRBZUZVBT44IBTQBWGUSTJDDKBQ" - } - }, - "id": "2611", - "paging_token": "2611", - "seller": "GDG3NOK5YI7A4FCBHE6SKI4L65R7UPRBZUZVBT44IBTQBWGUSTJDDKBQ", - "selling": { - "asset_type": "credit_alphanum12", - "asset_code": "USD", - "asset_issuer": "GCL3BJDFYQ2KAV7ARC4YCTERNJFOBOBQXSG556TX4YMOPKGEDV5K6LCQ" - }, - "buying": { - "asset_type": "native" - }, - "amount": "1.0000000", - "price_r": { - "n": 1463518003, - "d": 25041627 - }, - "price": "58.4434072", - "last_modified_ledger": 196458, - "last_modified_time": "2020-02-10T18:51:42Z" -} -``` - -## Endpoints - -| Resource | Type | Resource URI Template | -|------------------------------------------------------|------------|--------------------------------| -| [Offers](../endpoints/offers.md) | Collection | `/offers` | -| [Account Offers](../endpoints/offers-for-account.md) | Collection | `/accounts/:account_id/offers` | -| [Offers Details](../endpoints/offer-details.md) | Single | `/offers/:offer_id` | diff --git a/services/horizon/internal/docs/reference/resources/operation.md b/services/horizon/internal/docs/reference/resources/operation.md deleted file mode 100644 index 887bd277c2..0000000000 --- a/services/horizon/internal/docs/reference/resources/operation.md +++ /dev/null @@ -1,840 +0,0 @@ ---- -title: Operation -replacement: https://developers.stellar.org/api/resources/operations/ ---- - -[Operations](https://www.stellar.org/developers/learn/concepts/operations.html) are objects that represent a desired change to the ledger: payments, -offers to exchange currency, changes made to account options, etc. Operations -are submitted to the Stellar network grouped in a [Transaction](./transaction.md). - -To learn more about the concept of operations in the Stellar network, take a look at the [Stellar operations concept guide](https://www.stellar.org/developers/learn/concepts/operations.html). - -## Operation Types - -| type | type_i | description | -|---------------------------------------------------------|--------|------------------------------------------------------------------------------------------------------------| -| [CREATE_ACCOUNT](#create-account) | 0 | Creates a new account in Stellar network. | -| [PAYMENT](#payment) | 1 | Sends a simple payment between two accounts in Stellar network. | -| [PATH_PAYMENT_STRICT_RECEIVE](#path-payment) | 2 | Sends a path payment strict receive between two accounts in the Stellar network. | -| [PATH_PAYMENT_STRICT_SEND](#path-payment-strict-send) | 13 | Sends a path payment strict send between two accounts in the Stellar network. | -| [MANAGE_SELL_OFFER](#manage-sell-offer) | 3 | Creates, updates or deletes a sell offer in the Stellar network. | -| [MANAGE_BUY_OFFER](#manage-buy-offer) | 12 | Creates, updates or deletes a buy offer in the Stellar network. | -| [CREATE_PASSIVE_SELL_OFFER](#create-passive-sell-offer) | 4 | Creates an offer that won't consume a counter offer that exactly matches this offer. | -| [SET_OPTIONS](#set-options) | 5 | Sets account options (inflation destination, adding signers, etc.) | -| [CHANGE_TRUST](#change-trust) | 6 | Creates, updates or deletes a trust line. | -| [ALLOW_TRUST](#allow-trust) | 7 | Updates the "authorized" flag of an existing trust line this is called by the issuer of the related asset. | -| [ACCOUNT_MERGE](#account-merge) | 8 | Deletes account and transfers remaining balance to destination account. | -| [INFLATION](#inflation) | 9 | Runs inflation. | -| [MANAGE_DATA](#manage-data) | 10 | Set, modify or delete a Data Entry (name/value pair) for an account. | -| [BUMP_SEQUENCE](#bump-sequence) | 11 | Bumps forward the sequence number of an account. | - - -Every operation type shares a set of common attributes and links, some operations also contain -additional attributes and links specific to that operation type. - - - -## Common Attributes - -| | Type | | -|------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------| -| id | number | The canonical id of this operation, suitable for use as the :id parameter for url templates that require an operation's ID. | -| paging_token | any | A [paging token](./page.md) suitable for use as a `cursor` parameter. | -| transaction_successful | bool | Indicates if this operation is part of successful transaction. | -| type | string | A string representation of the type of operation. | -| type_i | number | Specifies the type of operation, See "Types" section below for reference. | - -## Common Links - -| | Relation | -|-------------|---------------------------------------------------------------------------| -| self | Relative link to the current operation | -| succeeds | Relative link to the list of operations succeeding the current operation. | -| precedes | Relative link to the list of operations preceding the current operation. | -| effects | The effects this operation triggered | -| transaction | The transaction this operation is part of | - - -Each operation type will have a different set of attributes, in addition to the -common attributes listed above. - - -### Create Account - -Create Account operation represents a new account creation. - -#### Attributes - -| Field | Type | Description | -|------------------|--------|------------------------------------| -| account | string | A new account that was funded. | -| funder | string | Account that funded a new account. | -| starting_balance | string | Amount the account was funded. | - - -#### Example -```json -{ - "_links": { - "effects": { - "href": "/operations/402494270214144/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=402494270214144&order=asc" - }, - "self": { - "href": "/operations/402494270214144" - }, - "succeeds": { - "href": "/operations?cursor=402494270214144&order=desc" - }, - "transactions": { - "href": "/transactions/402494270214144" - } - }, - "account": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "funder": "GBIA4FH6TV64KSPDAJCNUQSM7PFL4ILGUVJDPCLUOPJ7ONMKBBVUQHRO", - "id": "402494270214144", - "paging_token": "402494270214144", - "starting_balance": "10000.0", - "type_i": 0, - "type": "create_account" -} -``` - - -### Payment - -A payment operation represents a payment from one account to another. This payment -can be either a simple native asset payment or a fiat asset payment. - -#### Attributes - -| Field | Type | Description | -|--------------|--------|----------------------------------------------| -| from | string | Sender of a payment. | -| to | string | Destination of a payment. | -| asset_type | string | Asset type (native / alphanum4 / alphanum12) | -| asset_code | string | Code of the destination asset. | -| asset_issuer | string | Asset issuer. | -| amount | string | Amount sent. | - -#### Links - -| | Example | Relation | -|----------|--------------------------------------------------------------------|-------------------| -| sender | /accounts/GA5WBPYA5Y4WAEHXWR2UKO2UO4BUGHUQ74EUPKON2QHV4WRHOIRNKKH2 | Sending account | -| receiver | /accounts/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ | Receiving account | - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/58402965295104/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=58402965295104&order=asc" - }, - "self": { - "href": "/operations/58402965295104" - }, - "succeeds": { - "href": "/operations?cursor=58402965295104&order=desc" - }, - "transactions": { - "href": "/transactions/58402965295104" - } - }, - "amount": "200.0", - "asset_type": "native", - "from": "GAKLBGHNHFQ3BMUYG5KU4BEWO6EYQHZHAXEWC33W34PH2RBHZDSQBD75", - "id": "58402965295104", - "paging_token": "58402965295104", - "to": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "transaction_successful": true, - "type_i": 1, - "type": "payment" -} -``` - - -### Path Payment Strict Receive - -A path payment strict receive operation represents a payment from one account to another through a path. This type of payment starts as one type of asset and ends as another type of asset. There can be other assets that are traded into and out of along the path. - - -#### Attributes - -| Field | Type | Description | -|---------------------|-------------------------------|-----------------------------------------------------------------------------| -| from | string | Sender of a payment. | -| to | string | Destination of a payment. | -| asset_code | string | Code of the destination asset. | -| asset_issuer | string | Destination asset issuer. | -| asset_type | string | Destination asset type (native / alphanum4 / alphanum12) | -| amount | string | Amount received. | -| source_asset_code | string | Code of the source asset. | -| source_asset_issuer | string | Source asset issuer. | -| source_asset_type | string | Source asset type (native / alphanum4 / alphanum12) | -| source_max | string | Max send amount. | -| source_amount | string | Amount sent. | -| path | array of [Assets](./asset.md) | Additional hops the operation went through to get to the destination asset. | - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/25769807873/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=25769807873\u0026order=asc" - }, - "self": { - "href": "/operations/25769807873" - }, - "succeeds": { - "href": "/operations?cursor=25769807873\u0026order=desc" - }, - "transaction": { - "href": "/transactions/25769807872" - } - }, - "amount": "10.0", - "asset_code": "EUR", - "asset_issuer": "GCQPYGH4K57XBDENKKX55KDTWOTK5WDWRQOH2LHEDX3EKVIQRLMESGBG", - "asset_type": "credit_alphanum4", - "from": "GCXKG6RN4ONIEPCMNFB732A436Z5PNDSRLGWK7GBLCMQLIFO4S7EYWVU", - "id": "25769807873", - "paging_token": "25769807873", - "source_asset_code": "USD", - "source_asset_issuer": "GC23QF2HUE52AMXUFUH3AYJAXXGXXV2VHXYYR6EYXETPKDXZSAW67XO4", - "source_asset_type": "credit_alphanum4", - "source_amount": "10.0", - "source_max": "10.0", - "to": "GA5WBPYA5Y4WAEHXWR2UKO2UO4BUGHUQ74EUPKON2QHV4WRHOIRNKKH2", - "transaction_successful": true, - "type_i": 2, - "type": "path_payment_strict_receive" -} -``` - - -### Path Payment Strict Send - -A path payment strict send operation represents a payment from one account to another through a path. This type of payment starts as one type of asset and ends as another type of asset. There can be other assets that are traded into and out of along the path. - -Unlike [path payment strict receive](#path-payment), this operation sends precisely the source amount, ensuring that the destination account receives at least the minimum specified amount (the amount received will vary based on offers in the order books). - - -#### Attributes - -| Field | Type | Description | -|---------------------|-------------------------------|-----------------------------------------------------------------------------| -| from | string | Sender of a payment. | -| to | string | Destination of a payment. | -| asset_type | string | Destination asset type (native / alphanum4 / alphanum12) | -| asset_code | string | Code of the destination asset. | -| asset_issuer | string | Destination asset issuer. | -| amount | string | Amount received. | -| source_asset_type | string | Source asset type (native / alphanum4 / alphanum12) | -| source_asset_code | string | Source asset code. | -| source_asset_issuer | string | Source asset issuer. | -| source_amount | string | Amount sent. | -| destination_min | string | The minimum amount of destination asset expected to be received. | -| path | array of [Assets](./asset.md) | Additional hops the operation went through to get to the destination asset. | - - -#### Example - -```json -{ - "_links": { - "self": { - "href": "/operations/120903307907612673" - }, - "transaction": { - "href": "/transactions/f60f32eff7f1dd0649cfe2986955d12f6ff45288357fe1526600642ea1b418aa" - }, - "effects": { - "href": "/operations/120903307907612673/effects" - }, - "succeeds": { - "href": "/effects?order=desc&cursor=120903307907612673" - }, - "precedes": { - "href": "/effects?order=asc&cursor=120903307907612673" - } - }, - "id": "120903307907612673", - "paging_token": "120903307907612673", - "transaction_successful": true, - "source_account": "GCXVEEBWI4YMRK6AFJQSEUBYDQL4PZ24ECAPJE2ZIAPIQZLZIBAX3LIF", - "type": "path_payment_strict_send", - "type_i": 13, - "created_at": "2020-02-09T20:32:53Z", - "transaction_hash": "f60f32eff7f1dd0649cfe2986955d12f6ff45288357fe1526600642ea1b418aa", - "asset_type": "native", - "from": "GCXVEEBWI4YMRK6AFJQSEUBYDQL4PZ24ECAPJE2ZIAPIQZLZIBAX3LIF", - "to": "GCXVEEBWI4YMRK6AFJQSEUBYDQL4PZ24ECAPJE2ZIAPIQZLZIBAX3LIF", - "amount": "0.0859000", - "path": [ - - ], - "source_amount": "1000.0000000", - "destination_min": "0.0859000", - "source_asset_type": "credit_alphanum4", - "source_asset_code": "KIN", - "source_asset_issuer": "GBDEVU63Y6NTHJQQZIKVTC23NWLQVP3WJ2RI2OTSJTNYOIGICST6DUXR" -} -``` - - -### Manage Sell Offer - -A "Manage Sell Offer" operation can create, update or delete a sell -offer to trade assets in the Stellar network. -It specifies an issuer, a price and amount of a given asset to -buy or sell. - -When this operation is applied to the ledger, trades can potentially be executed if -this offer crosses others that already exist in the ledger. - -In the event that there are not enough crossing orders to fill the order completely -a new "Offer" object will be created in the ledger. As other accounts make -offers or payments, this offer can potentially be filled. - -#### Sell Offer vs. Buy Offer - -A [sell offer](#manage-sell-offer) specifies a certain amount of the `selling` asset that should be sold in exchange for the maximum quantity of the `buying` asset. It additionally only crosses offers where the price is higher than `price`. - -A [buy offer](#manage-buy-offer) specifies a certain amount of the `buying` asset that should be bought in exchange for the minimum quantity of the `selling` asset. It additionally only crosses offers where the price is lower than `price`. - -Both will fill only partially (or not at all) if there are few (or no) offers that cross them. - -#### Attributes - -| Field | Type | Description | -|----------------------|--------|---------------------------------------------------------| -| offer_id | string | Offer ID. | -| amount | string | Amount of asset to be sold. | -| buying_asset_code | string | The code of asset to buy. | -| buying_asset_issuer | string | The issuer of asset to buy. | -| buying_asset_type | string | Type of asset to buy (native / alphanum4 / alphanum12) | -| price | string | Price of selling_asset in units of buying_asset | -| price_r | Object | n: price numerator, d: price denominator | -| selling_asset_code | string | The code of asset to sell. | -| selling_asset_issuer | string | The issuer of asset to sell. | -| selling_asset_type | string | Type of asset to sell (native / alphanum4 / alphanum12) | - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/592323234762753/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=592323234762753\u0026order=asc" - }, - "self": { - "href": "/operations/592323234762753" - }, - "succeeds": { - "href": "/operations?cursor=592323234762753\u0026order=desc" - }, - "transaction": { - "href": "/transactions/592323234762752" - } - }, - "amount": "100.0", - "buying_asset_code": "CHP", - "buying_asset_issuer": "GAC2ZUXVI5266NMMGDPBMXHH4BTZKJ7MMTGXRZGX2R5YLMFRYLJ7U5EA", - "buying_asset_type": "credit_alphanum4", - "id": "592323234762753", - "offer_id": "8", - "paging_token": "592323234762753", - "price": "2.0", - "price_r": { - "d": 1, - "n": 2 - }, - "selling_asset_code": "YEN", - "selling_asset_issuer": "GDVXG2FMFFSUMMMBIUEMWPZAIU2FNCH7QNGJMWRXRD6K5FZK5KJS4DDR", - "selling_asset_type": "credit_alphanum4", - "transaction_successful": true, - "type_i": 3, - "type": "manage_sell_offer" -} -``` - - -### Manage Buy Offer - -A "Manage Buy Offer" operation can create, update or delete a buy -offer to trade assets in the Stellar network. -It specifies an issuer, a price and amount of a given asset to -buy or sell. - -When this operation is applied to the ledger, trades can potentially be executed if -this offer crosses others that already exist in the ledger. - -In the event that there are not enough crossing orders to fill the order completely -a new "Offer" object will be created in the ledger. As other accounts make -offers or payments, this offer can potentially be filled. - -#### Attributes - -| Field | Type | Description | -|----------------------|--------|---------------------------------------------------------------| -| offer_id | string | Offer ID. | -| buy_amount | string | Amount of asset to be bought. | -| buying_asset_code | string | The code of asset to buy. | -| buying_asset_issuer | string | The issuer of asset to buy. | -| buying_asset_type | string | Type of asset to buy (native / alphanum4 / alphanum12) | -| price | string | Price of thing being bought in terms of what you are selling. | -| price_r | Object | n: price numerator, d: price denominator | -| selling_asset_code | string | The code of asset to sell. | -| selling_asset_issuer | string | The issuer of asset to sell. | -| selling_asset_type | string | Type of asset to sell (native / alphanum4 / alphanum12) | -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/592323234762753/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=592323234762753\u0026order=asc" - }, - "self": { - "href": "/operations/592323234762753" - }, - "succeeds": { - "href": "/operations?cursor=592323234762753\u0026order=desc" - }, - "transaction": { - "href": "/transactions/592323234762752" - } - }, - "amount": "100.0", - "buying_asset_code": "CHP", - "buying_asset_issuer": "GAC2ZUXVI5266NMMGDPBMXHH4BTZKJ7MMTGXRZGX2R5YLMFRYLJ7U5EA", - "buying_asset_type": "credit_alphanum4", - "id": "592323234762753", - "offer_id": "8", - "paging_token": "592323234762753", - "price": "2.0", - "price_r": { - "d": 1, - "n": 2 - }, - "selling_asset_code": "YEN", - "selling_asset_issuer": "GDVXG2FMFFSUMMMBIUEMWPZAIU2FNCH7QNGJMWRXRD6K5FZK5KJS4DDR", - "selling_asset_type": "credit_alphanum4", - "transaction_successful": true, - "type_i": 12, - "type": "manage_buy_offer" -} -``` - - -### Create Passive Sell Offer - -“Create Passive Sell Offer” operation creates an offer that won't consume a counter offer that exactly matches this offer. This is useful for offers just used as 1:1 exchanges for path payments. Use Manage Sell Offer to manage this offer after using this operation to create it. - -#### Attributes - -As in [Manage Sell Offer](#manage-sell-offer) operation. - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/1127729562914817/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=1127729562914817\u0026order=asc" - }, - "self": { - "href": "/operations/1127729562914817" - }, - "succeeds": { - "href": "/operations?cursor=1127729562914817\u0026order=desc" - }, - "transaction": { - "href": "/transactions/1127729562914816" - } - }, - "amount": "11.27827", - "buying_asset_code": "USD", - "buying_asset_issuer": "GDS5JW5E6DRSSN5XK4LW7E6VUMFKKE2HU5WCOVFTO7P2RP7OXVCBLJ3Y", - "buying_asset_type": "credit_alphanum4", - "id": "1127729562914817", - "offer_id": "9", - "paging_token": "1127729562914817", - "price": "1.0", - "price_r": { - "d": 1, - "n": 1 - }, - "selling_asset_type": "native", - "transaction_successful": true, - "type_i": 4, - "type": "create_passive_sell_offer" -} -``` - - - -### Set Options - -Use “Set Options” operation to set following options to your account: -* Set/clear account flags: - * AUTH_REQUIRED_FLAG (0x1) - if set, TrustLines are created with authorized set to `false` requiring the issuer to set it for each TrustLine. - * AUTH_REVOCABLE_FLAG (0x2) - if set, the authorized flag in TrustLines can be cleared. Otherwise, authorization cannot be revoked. -* Set the account’s inflation destination. -* Add new signers to the account. -* Set home domain. - - -#### Attributes - -| Field | Type | Description | -|-------------------|--------|------------------------------------------------------------------------------| -| signer_key | string | The public key of the new signer. | -| signer_weight | int | The weight of the new signer (1-255). | -| master_key_weight | int | The weight of the master key (1-255). | -| low_threshold | int | The sum weight for the low threshold. | -| med_threshold | int | The sum weight for the medium threshold. | -| high_threshold | int | The sum weight for the high threshold. | -| home_domain | string | The home domain used for reverse federation lookup | -| set_flags | array | The array of numeric values of flags that has been set in this operation | -| set_flags_s | array | The array of string values of flags that has been set in this operation | -| clear_flags | array | The array of numeric values of flags that has been cleared in this operation | -| clear_flags_s | array | The array of string values of flags that has been cleared in this operation | - - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/696867033714691/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=696867033714691\u0026order=asc" - }, - "self": { - "href": "/operations/696867033714691" - }, - "succeeds": { - "href": "/operations?cursor=696867033714691\u0026order=desc" - }, - "transaction": { - "href": "/transactions/696867033714688" - } - }, - "high_threshold": 3, - "home_domain": "stellar.org", - "id": "696867033714691", - "low_threshold": 0, - "med_threshold": 3, - "paging_token": "696867033714691", - "set_flags": [ - 1 - ], - "set_flags_s": [ - "auth_required_flag" - ], - "transaction_successful": true, - "type_i": 5, - "type": "set_options" -} -``` - - -### Change Trust - -Use “Change Trust” operation to create/update/delete a trust line from the source account to another. The issuer being trusted and the asset code are in the given Asset object. - -#### Attributes - -| Field | Type | Description | -|--------------|--------|----------------------------------------------| -| asset_code | string | Asset code. | -| asset_issuer | string | Asset issuer. | -| asset_type | string | Asset type (native / alphanum4 / alphanum12) | -| trustee | string | Trustee account. | -| trustor | string | Trustor account. | -| limit | string | The limit for the asset. | - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/574731048718337/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=574731048718337\u0026order=asc" - }, - "self": { - "href": "/operations/574731048718337" - }, - "succeeds": { - "href": "/operations?cursor=574731048718337\u0026order=desc" - }, - "transaction": { - "href": "/transactions/574731048718336" - } - }, - "asset_code": "CHP", - "asset_issuer": "GAC2ZUXVI5266NMMGDPBMXHH4BTZKJ7MMTGXRZGX2R5YLMFRYLJ7U5EA", - "asset_type": "credit_alphanum4", - "id": "574731048718337", - "limit": "5.0", - "paging_token": "574731048718337", - "trustee": "GAC2ZUXVI5266NMMGDPBMXHH4BTZKJ7MMTGXRZGX2R5YLMFRYLJ7U5EA", - "trustor": "GDVXG2FMFFSUMMMBIUEMWPZAIU2FNCH7QNGJMWRXRD6K5FZK5KJS4DDR", - "transaction_successful": true, - "type_i": 6, - "type": "change_trust" -} -``` - - -### Allow Trust - -Updates the "authorized" flag of an existing trust line this is called by the issuer of the asset. - -Heads up! Unless the issuing account has `AUTH_REVOCABLE_FLAG` set than the "authorized" flag can only be set and never cleared. - -#### Attributes - -| Field | Type | Description | -|--------------|--------|---------------------------------------------------------| -| asset_code | string | Asset code. | -| asset_issuer | string | Asset issuer. | -| asset_type | string | Asset type (native / alphanum4 / alphanum12) | -| authorize | bool | `true` when allowing trust, `false` when revoking trust | -| trustee | string | Trustee account. | -| trustor | string | Trustor account. | - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/34359742465/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=34359742465\u0026order=asc" - }, - "self": { - "href": "/operations/34359742465" - }, - "succeeds": { - "href": "/operations?cursor=34359742465\u0026order=desc" - }, - "transaction": { - "href": "/transactions/34359742464" - } - }, - "asset_code": "USD", - "asset_issuer": "GC23QF2HUE52AMXUFUH3AYJAXXGXXV2VHXYYR6EYXETPKDXZSAW67XO4", - "asset_type": "credit_alphanum4", - "authorize": true, - "id": "34359742465", - "paging_token": "34359742465", - "trustee": "GC23QF2HUE52AMXUFUH3AYJAXXGXXV2VHXYYR6EYXETPKDXZSAW67XO4", - "trustor": "GBXGQJWVLWOYHFLVTKWV5FGHA3LNYY2JQKM7OAJAUEQFU6LPCSEFVXON", - "transaction_successful": true, - "type_i": 7, - "type": "allow_trust" -} -``` - - -### Account Merge - -Removes the account and transfers all remaining XLM to the destination account. - -#### Attributes - -| Field | Type | Description | -|-------|--------|-------------------------------------------------------------| -| into | string | Account ID where funds of deleted account were transferred. | - -#### Example -```json -{ - "_links": { - "effects": { - "href": "/operations/799357838299137/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=799357838299137\u0026order=asc" - }, - "self": { - "href": "/operations/799357838299137" - }, - "succeeds": { - "href": "/operations?cursor=799357838299137\u0026order=desc" - }, - "transaction": { - "href": "/transactions/799357838299136" - } - }, - "account": "GBCR5OVQ54S2EKHLBZMK6VYMTXZHXN3T45Y6PRX4PX4FXDMJJGY4FD42", - "id": "799357838299137", - "into": "GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K", - "paging_token": "799357838299137", - "transaction_successful": true, - "type_i": 8, - "type": "account_merge" -} -``` - - -### Inflation - -Runs inflation. - -#### Example - -```json -{ - "_links": { - "effects": { - "href": "/operations/12884914177/effects/{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "/operations?cursor=12884914177\u0026order=asc" - }, - "self": { - "href": "/operations/12884914177" - }, - "succeeds": { - "href": "/operations?cursor=12884914177\u0026order=desc" - }, - "transaction": { - "href": "/transactions/12884914176" - } - }, - "id": "12884914177", - "paging_token": "12884914177", - "transaction_successful": true, - "type_i": 9, - "type": "inflation" -} -``` - - -### Manage Data - -Set, modify or delete a Data Entry (name/value pair) for an account. - -#### Example - -```json -{ - "_links": { - "self": { - "href": "/operations/5250180907536385" - }, - "transaction": { - "href": "/transactions/e0710d3e410fe6b1ba77fcfec9e3789e94ff29b2424f1f4bf51e530dbbdf221c" - }, - "effects": { - "href": "/operations/5250180907536385/effects" - }, - "succeeds": { - "href": "/effects?order=desc&cursor=5250180907536385" - }, - "precedes": { - "href": "/effects?order=asc&cursor=5250180907536385" - } - }, - "id": "5250180907536385", - "paging_token": "5250180907536385", - "source_account": "GCGG3CIRBG2TTBR4HYZJ7JLDRFKZIYOAHFXRWLU62CA2QN52P2SUQNPJ", - "type": "manage_data", - "type_i": 10, - "transaction_successful": true, - "name": "lang", - "value": "aW5kb25lc2lhbg==" -} -``` - - -### Bump Sequence - -Bumps forward the sequence number of the source account of the operation, allowing it to invalidate any transactions with a smaller sequence number. - -#### Attributes - -| Field | Type | Description | -|--------|--------|-------------------------------------------------------------------| -| bumpTo | number | Desired value for the operation’s source account sequence number. | - -#### Example -```json -{ - "_links": { - "self": { - "href": "/operations/1743756726273" - }, - "transaction": { - "href": "/transactions/328436a8dffaf6ca33c08a93279234c7d3eaf1c028804152614187dc76b7168d" - }, - "effects": { - "href": "/operations/1743756726273/effects" - }, - "succeeds": { - "href": "/effects?order=desc&cursor=1743756726273" - }, - "precedes": { - "href": "/effects?order=asc&cursor=1743756726273" - } - }, - "id": "1743756726273", - "paging_token": "1743756726273", - "source_account": "GBHPJ3VMVT3X7Y6HIIAPK7YPTZCF3CWO4557BKGX2GVO4O7EZHIBELLH", - "type": "bump_sequence", - "type_i": 11, - "transaction_hash": "328436a8dffaf6ca33c08a93279234c7d3eaf1c028804152614187dc76b7168d", - "bump_to": "1273737228" -} -``` - -## Endpoints - -| Resource | Type | Resource URI Template | -|----------------------------------------------------|------------|-------------------------------------------------| -| [All Operations](../endpoints/operations-all.md) | Collection | `/operations` | -| [Operations Details](../endpoints/operations-single.md) | Single | `/operations/:id` | -| [Ledger Operations](../endpoints/operations-for-ledger.md) | Collection | `/ledgers/{id}/operations{?cursor,limit,order}` | -| [Account Operations](../endpoints/operations-for-account.md) | Collection | `/accounts/:account_id/operations` | -| [Account Payments](../endpoints/payments-for-account.md) | Collection | `/accounts/:account_id/payments` | diff --git a/services/horizon/internal/docs/reference/resources/orderbook.md b/services/horizon/internal/docs/reference/resources/orderbook.md deleted file mode 100644 index c7e1e78b30..0000000000 --- a/services/horizon/internal/docs/reference/resources/orderbook.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Orderbook -replacement: https://developers.stellar.org/api/aggregations/order-books/ ---- - -[Orderbooks](https://www.stellar.org/developers/learn/concepts/exchange.html) are collections of offers for each issuer and currency pairs. Let's say you wanted to exchange EUR issued by a particular bank for BTC issued by a particular exchange. You would look at the orderbook and see who is buying `foo_bank/EUR` and selling `baz_exchange/BTC` and at what prices. - -## Attributes -| Attribute | Type | | -|--------------|------------------|------------------------------------------------------------------------------------------------------------------------| -| bids | object | Array of {`price_r`, `price`, `amount`} objects (see [offers](./offer.md)). These represent prices and amounts accounts are willing to buy for the given `selling` and `buying` pair. | -| asks | object | Array of {`price_r`, `price`, `amount`} objects (see [offers](./offer.md)). These represent prices and amounts accounts are willing to sell for the given `selling` and `buying` pair.| -| base | [Asset](http://stellar.org/developers/learn/concepts/assets.html) | The Asset this offer wants to sell.| -| counter | [Asset](http://stellar.org/developers/learn/concepts/assets.html) | The Asset this offer wants to buy.| - -#### Bid Object -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| price_r | object | An object of a number numerator and number denominator that represents the bid price. | -| price | string | The bid price of the asset. A number representing the decimal form of price_r | -| amount | string | The amount of asset bid offer. | - -#### Ask Object -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| price_r | object | An object of a number numerator and number denominator that represents the ask price. | -| price | string | The ask price of the asset. A number representing the decimal form of price_r | -| amount | string | The amount of asset ask offer. | - -#### Price_r Object -Price_r is a more precise representation of a bid/ask offer. - -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| n | number | The numerator. | -| d | number | The denominator. | - -Thus to get price you would take n / d. - -## Links - -This resource has no links. - - -## Endpoints - -| Resource | Type | Resource URI Template | -|--------------------------|------------|--------------------------------------| -| [Orderbook Details](../endpoints/orderbook-details.md) | Single | `/orderbook?{orderbook_params}` | -| [Trades](../endpoints/trades.md) | Collection | `/trades?{orderbook_params}` | diff --git a/services/horizon/internal/docs/reference/resources/page.md b/services/horizon/internal/docs/reference/resources/page.md deleted file mode 100644 index 6c90db63bf..0000000000 --- a/services/horizon/internal/docs/reference/resources/page.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Page -replacement: https://developers.stellar.org/api/introduction/pagination/page-arguments/ ---- - -Pages represent a subset of a larger collection of objects. -As an example, it would be unfeasible to provide the -[All Transactions](../endpoints/transactions-all.md) endpoint without paging. Over time there -will be millions of transactions in the Stellar network's ledger and returning -them all over a single request would be unfeasible. - -## Attributes - -A page itself exposes no attributes. It is merely a container for embedded -records and some links to aid in iterating the entire collection the page is -part of. - -## Cursor -A `cursor` is a number that points to a specific location in a collection of resources. - -The `cursor` attribute itself is an opaque value meaning that users should not try to parse it. - -## Embedded Resources - -A page contains an embedded set of `records`, regardless of the contained resource. - -## Links - -A page provides a couple of links to ease in iteration. - -| | Example | Relation | -| ---- | ------------------------------------------------------ | ---------------------------- | -| self | `/transactions` | | -| prev | `/transactions?cursor=12884905984&order=desc&limit=10` | The previous page of results | -| next | `/transactions?cursor=12884905984&order=asc&limit=10` | The next page of results | - -## Example - -```json -{ - "_embedded": { - "records": [ - { - "_links": { - "self": { - "href": "/operations/12884905984" - }, - "transaction": { - "href": "/transaction/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a" - }, - "precedes": { - "href": "/account/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=asc{?limit}", - "templated": true - }, - "succeeds": { - "href": "/account/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=desc{?limit}", - "templated": true - } - }, - "id": 12884905984, - "paging_token": "12884905984", - "type_i": 0, - "type": "payment", - "sender": "GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ", - "receiver": "GCXKG6RN4ONIEPCMNFB732A436Z5PNDSRLGWK7GBLCMQLIFO4S7EYWVU", - "asset": { - "code": "XLM" - }, - "amount": 1000000000, - "amount_f": 100.00 - } - ] - }, - "_links": { - "next": { - "href": "/account/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=asc&limit=100" - }, - "prev": { - "href": "/account/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?cursor=12884905984&order=desc&limit=100" - }, - "self": { - "href": "/account/GCEZWKCA5VLDNRLN3RPRJMRZOX3Z6G5CHCGSNFHEYVXM3XOJMDS674JZ/payments?limit=100" - } - } -} - -``` - -## Endpoints - -Any endpoint that provides a collection of resources will represent them as pages. - diff --git a/services/horizon/internal/docs/reference/resources/path.md b/services/horizon/internal/docs/reference/resources/path.md deleted file mode 100644 index 20c87b2bc9..0000000000 --- a/services/horizon/internal/docs/reference/resources/path.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Payment Path -replacement: https://developers.stellar.org/api/aggregations/paths/ ---- - -A **path** resource contains information about a payment path. A path can be used by code to populate necessary fields on path payment operation, such as `path` and `sendMax`. - - -## Attributes -| Attribute | Type | | -|--------------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------| -| path | array of objects | An array of assets that represents the intermediary assets this path hops through | -| source_amount | string | An estimated cost for making a payment of destination_amount on this path. Suitable for use in a path payments `sendMax` field | -| destination_amount | string | The destination amount specified in the search that found this path | -| destination_asset_type | string | The type for the destination asset specified in the search that found this path | -| destination_asset_code | optional, string | The code for the destination asset specified in the search that found this path | -| destination_asset_issuer | optional, string | The issuer for the destination asset specified in the search that found this path | -| source_asset_type | string | The type for the source asset specified in the search that found this path | -| source_asset_code | optional, string | The code for the source asset specified in the search that found this path | -| source_asset_issuer | optional, string | The issuer for the source asset specified in the search that found this path | - -#### Asset Object -| Attribute | Type | | -|--------------|------------------|------------------------------------------------------------------------------------------------------------------------ -| asset_code | optional, string | The code for the asset. | -| asset_type | string | Either native, credit_alphanum4, or credit_alphanum12. | -| asset_issuer | optional, string | The stellar address of the given asset's issuer. | - -## Example - -```json -{ - "destination_amount": "20.0000000", - "destination_asset_code": "EUR", - "destination_asset_issuer": "GDSBCQO34HWPGUGQSP3QBFEXVTSR2PW46UIGTHVWGWJGQKH3AFNHXHXN", - "destination_asset_type": "credit_alphanum4", - "path": [ - { - "asset_code": "1", - "asset_issuer": "GDSBCQO34HWPGUGQSP3QBFEXVTSR2PW46UIGTHVWGWJGQKH3AFNHXHXN", - "asset_type": "credit_alphanum4" - } - ], - "source_amount": "20.0000000", - "source_asset_code": "USD", - "source_asset_issuer": "GDSBCQO34HWPGUGQSP3QBFEXVTSR2PW46UIGTHVWGWJGQKH3AFNHXHXN", - "source_asset_type": "credit_alphanum4" -} -``` - -## Endpoints -| Resource | Type | Resource URI Template | -|------------------------------------------|------------|-----------------------| -| [Find Payment Paths](../endpoints/path-finding.md) | Collection | `/paths` | diff --git a/services/horizon/internal/docs/reference/resources/trade.md b/services/horizon/internal/docs/reference/resources/trade.md deleted file mode 100644 index 08434dcd63..0000000000 --- a/services/horizon/internal/docs/reference/resources/trade.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Trade ---- - -A trade represents a fulfilled offer. For example, let's say that there exists an offer to sell 9 `foo_bank/EUR` for 3 `baz_exchange/BTC` and you make an offer to buy 3 `foo_bank/EUR` for 1 `baz_exchange/BTC`. Since your offer and the existing one cross, a trade happens. After the trade completes: - -- you are 3 `foo_bank/EUR` richer and 1 `baz_exchange/BTC` poorer -- the maker of the other offer is 1 `baz_exchange/BTC` richer and 3 `foo_bank/EUR` poorer -- your offer is completely fulfilled and no longer exists -- the other offer is partially fulfilled and becomes an offer to sell 6 `foo_bank/EUR` for 2 `baz_exchange/BTC`. The price of that offer doesn't change, but the amount does. - -Trades can also be caused by successful [path payments](https://www.stellar.org/developers/learn/concepts/exchange.html), because path payments involve fulfilling offers. - -Payments are one-way in that afterwards, the source account has a smaller balance and the destination account of the payment has a bigger one. Trades are two-way; both accounts increase and decrease their balances. - -A trade occurs between two parties - `base` and `counter`. Which is either arbitrary or determined by the calling query. - -## Attributes -| Attribute | Type | | -|--------------|------------------|------------------------------------------------------------------------------------------------------------------------| -| id | string | The ID of this trade. | -| paging_token | string | A [paging token](./page.md) suitable for use as a `cursor` parameter.| -| ledger_close_time | string | An ISO 8601 formatted string of when the ledger with this trade was closed.| -| offer_id | string | DEPRECATED. the sell offer id. -| base_account | string | base party of this trade| -| base_offer_id | string | the base offer id. If this offer was immediately fully consumed this will be a synthetic id -| base_amount | string | amount of base asset that was moved from `base_account` to `counter_account`| -| base_asset_type | string | type of base asset| -| base_asset_code | string | code of base asset| -| base_asset_issuer | string | issuer of base asset| -| counter_offer_id | string | the counter offer id. If this offer was immediately fully consumed this will be a synthetic id -| counter_account | string | counter party of this trade| -| counter_amount | string | amount of counter asset that was moved from `counter_account` to `base_account`| -| counter_asset_type | string | type of counter asset| -| counter_asset_code | string | code of counter asset| -| counter_asset_issuer | string | issuer of counter asset| -| price | object | original offer price, expressed as a rational number. example: {n:7, d:3} -| base_is_seller | boolean | indicates which party of the trade made the sell offer| - -#### Price Object -Price is a precise representation of a bid/ask offer. - -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| n | number | The numerator. | -| d | number | The denominator. | - -Thus to get price you would take n / d. - -#### Synthetic Offer Ids -Offer ids in the horizon trade resource (base_offer_id, counter_offer_id) are synthetic and don't always reflect the respective stellar-core offer ids. This is due to the fact that stellar-core does not assign offer ids when an offer gets filled immediately. In these cases, Horizon synthetically generates an offer id for the buying offer, based on the total order id of the offer operation. This allows wallets to aggregate historical trades based on offer ids without adding special handling for edge cases. The exact encoding can be found [here](https://github.com/stellar/go/blob/master/services/horizon/internal/db2/history/synt_offer_id.go). - -## Links - -| rel | Example | Description | `templated` | -|--------------|---------------------------------------------------------------------------------------------------|------------------------------------------------------------|-------------| -| base | `/accounts/{base_account}` | Link to details about the base account| true | -| counter | `/accounts/{counter_account}` | Link to details about the counter account | true | -| operation | `/operation/{operation_id}` | Link to the operation of the assets bought and sold. | true | - -## Endpoints - -| Resource | Type | Resource URI Template | -|--------------------------|------------|--------------------------------------| -| [Trades](../endpoints/trades.md) | Collection | `/trades` | -| [Account Trades](../endpoints/trades-for-account.md) | Collection | `/accounts/:account_id/trades` | diff --git a/services/horizon/internal/docs/reference/resources/trade_aggregation.md b/services/horizon/internal/docs/reference/resources/trade_aggregation.md deleted file mode 100644 index d1019e7f0c..0000000000 --- a/services/horizon/internal/docs/reference/resources/trade_aggregation.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Trade Aggregation -replacement: https://developers.stellar.org/api/aggregations/trade-aggregations/ ---- - -A Trade Aggregation represents aggregated statistics on an asset pair (`base` and `counter`) for a specific time period. - -## Attributes -| Attribute | Type | | -|--------------|------------------|------------------------------------------------------------------------------------------------------------------------| -| timestamp | string | start time for this trade_aggregation. Represented as milliseconds since epoch.| -| trade_count | int | total number of trades aggregated.| -| base_volume | string | total volume of `base` asset.| -| counter_volume | string | total volume of `counter` asset.| -| avg | string | weighted average price of `counter` asset in terms of `base` asset.| -| high | string | highest price for this time period.| -| high_r | object | highest price for this time period as a rational number.| -| low | string | lowest price for this time period.| -| low_r | object | lowest price for this time period as a rational number.| -| open | string | price as seen on first trade aggregated.| -| open_r | object | price as seen on first trade aggregated as a rational number.| -| close | string | price as seen on last trade aggregated.| -| close_r | object | price as seen on last trade aggregated as a rational number.| - -#### Price_r Object -Price_r (high_r, low_r, open_r, close_r) is a more precise representation of a bid/ask offer. - -| Attribute | Type | | -| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| n | number | The numerator. | -| d | number | The denominator. | - -Thus to get price you would take n / d. - -## Endpoints - -| Resource | Type | Resource URI Template | -|--------------------------|------------|--------------------------------------| -| [Trade Aggregations](../endpoints/trade_aggregations.md) | Collection | `/trade_aggregations?{orderbook_params}` | diff --git a/services/horizon/internal/docs/reference/resources/transaction.md b/services/horizon/internal/docs/reference/resources/transaction.md deleted file mode 100644 index ac4c5b488b..0000000000 --- a/services/horizon/internal/docs/reference/resources/transaction.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Transaction -replacement: https://developers.stellar.org/api/resources/transactions/ ---- - -**Transactions** are the basic unit of change in the Stellar Network. - -A transaction is a grouping of [operations](./operation.md). - -To learn more about the concept of transactions in the Stellar network, take a look at the [Stellar transactions concept guide](https://www.stellar.org/developers/learn/concepts/transactions.html). - -## Attributes - -| Attribute | Type | | -|-------------------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------| -| id | string | The canonical id of this transaction, suitable for use as the :id parameter for url templates that require a transaction's ID. | -| paging_token | string | A [paging token](./page.md) suitable for use as the `cursor` parameter to transaction collection resources. | -| successful | bool | Indicates if transaction was successful or not. | -| hash | string | A hex-encoded, lowercase SHA-256 hash of the transaction's [XDR](../../learn/xdr.md)-encoded form. | -| ledger | number | Sequence number of the ledger in which this transaction was applied. | -| created_at | ISO8601 string | | -| fee_account | string | The account which paid for the transaction fees | -| source_account | string | | -| source_account_sequence | string | | -| max_fee | number | The the maximum fee the fee account was willing to pay. | -| fee_charged | number | The fee paid by the fee account of this transaction when the transaction was applied to the ledger. | -| operation_count | number | The number of operations that are contained within this transaction. | -| envelope_xdr | string | A base64 encoded string of the raw `TransactionEnvelope` xdr struct for this transaction | -| result_xdr | string | A base64 encoded string of the raw `TransactionResult` xdr struct for this transaction | -| result_meta_xdr | string | A base64 encoded string of the raw `TransactionMeta` xdr struct for this transaction | -| fee_meta_xdr | string | A base64 encoded string of the raw `LedgerEntryChanges` xdr struct produced by taking fees for this transaction. | -| memo_type | string | The type of memo set in the transaction. Possible values are `none`, `text`, `id`, `hash`, and `return`. | -| memo | string | The string representation of the memo set in the transaction. When `memo_type` is `id`, the `memo` is a decimal string representation of an unsigned 64 bit integer. When `memo_type` is `hash` or `return`, the `memo` is a base64 encoded string. When `memo_type` is `text`, the `memo` is a unicode string. However, if the original memo byte sequence in the transaction XDR is not valid unicode, Horizon will replace any invalid byte sequences with the utf-8 replacement character. Note this field is only present when `memo_type` is not `none`. | -| memo_bytes | string | A base64 encoded string of the memo bytes set in the transaction's xdr envelope. Note this field is only present when `memo_type` is `text`. | -| signatures | string[] | An array of signatures used to sign this transaction | -| valid_after | RFC3339 date-time string | | -| valid_before | RFC3339 date-time string | | -| fee_bump_transaction | object | This object is only present if the transaction is a fee bump transaction or is wrapped by a fee bump transaction. The object has two fields: `hash` (the hash of the fee bump transaction) and `signatures` (the signatures present in the fee bump transaction envelope) | -| inner_transaction | object | This object is only present if the transaction is a fee bump transaction or is wrapped by a fee bump transaction. The object has three fields: `hash` (the hash of the inner transaction wrapped by the fee bump transaction), `max_fee` (the max fee set in the inner transaction), and `signatures` (the signatures present in the inner transaction envelope) | - -## Links - -| rel | Example | Description | -|------------|------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| -| self | `https://horizon-testnet.stellar.org/transactions/cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f` | | -| account | `https://horizon-testnet.stellar.org/accounts/GCDLRUXOD6KA53G5ILL435TZAISNLPS4EKIHSOVY3MVD3DVJ333NO4DT` | The source [account](../endpoints/accounts-single.md) for this transaction. | -| ledger | `https://horizon-testnet.stellar.org/ledgers/2352988` | The [ledger](../endpoints/ledgers-single.md) in which this transaction was applied. | -| operations | `https://horizon-testnet.stellar.org/transactions/cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f/operations{?cursor,limit,order}"` | [Operations](../endpoints/operations-for-transaction.md) included in this transaction. | -| effects | `https://horizon-testnet.stellar.org/transactions/cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f/effects{?cursor,limit,order}"` | [Effects](../endpoints/effects-for-transaction.md) which resulted by operations in this transaction. | -| precedes | `https://horizon-testnet.stellar.org/transactions?order=asc&cursor=10106006507900928` | A collection of transactions that occur after this transaction. | -| succeeds | `https://horizon-testnet.stellar.org/transactions?order=desc&cursor=10106006507900928` | A collection of transactions that occur before this transaction. | - -## Example - -```json -{ - "_links": { - "self": { - "href": "https://horizon-testnet.stellar.org/transactions/cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f" - }, - "account": { - "href": "https://horizon-testnet.stellar.org/accounts/GCDLRUXOD6KA53G5ILL435TZAISNLPS4EKIHSOVY3MVD3DVJ333NO4DT" - }, - "ledger": { - "href": "https://horizon-testnet.stellar.org/ledgers/2352988" - }, - "operations": { - "href": "https://horizon-testnet.stellar.org/transactions/cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f/operations{?cursor,limit,order}", - "templated": true - }, - "effects": { - "href": "https://horizon-testnet.stellar.org/transactions/cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f/effects{?cursor,limit,order}", - "templated": true - }, - "precedes": { - "href": "https://horizon-testnet.stellar.org/transactions?order=asc&cursor=10106006507900928" - }, - "succeeds": { - "href": "https://horizon-testnet.stellar.org/transactions?order=desc&cursor=10106006507900928" - } - }, - "id": "cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f", - "paging_token": "10106006507900928", - "successful": true, - "hash": "cb9a25394acb6fe0d1d9bdea5afc01cafe2c6fde59a96ddceb2564a65780a81f", - "ledger": 2352988, - "created_at": "2019-02-21T21:44:13Z", - "source_account": "GCDLRUXOD6KA53G5ILL435TZAISNLPS4EKIHSOVY3MVD3DVJ333NO4DT", - "fee_account": "GCDLRUXOD6KA53G5ILL435TZAISNLPS4EKIHSOVY3MVD3DVJ333NO4DT", - "source_account_sequence": "10105916313567234", - "max_fee": 100, - "fee_charged":100, - "operation_count": 1, - "envelope_xdr": "AAAAAIa40u4flA7s3ULXzfZ5AiTVvlwikHk6uNsqPY6p3vbXAAAAZAAj50cAAAACAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAABAAAAB2Fmc2RmYXMAAAAAAQAAAAAAAAABAAAAAIa40u4flA7s3ULXzfZ5AiTVvlwikHk6uNsqPY6p3vbXAAAAAAAAAAEqBfIAAAAAAAAAAAGp3vbXAAAAQKElK3CoNo1f8fWIGeJm98lw2AaFiyVVFhx3uFok0XVW3MHV9MubtEhfA+n1iLPrxmzHtHfmZsumWk+sOEQlSwI=", - "result_xdr": "AAAAAAAAAGQAAAAAAAAAAQAAAAAAAAABAAAAAAAAAAA=", - "result_meta_xdr": "AAAAAQAAAAIAAAADACPnXAAAAAAAAAAAhrjS7h+UDuzdQtfN9nkCJNW+XCKQeTq42yo9jqne9tcAAAAXSHbnOAAj50cAAAABAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABACPnXAAAAAAAAAAAhrjS7h+UDuzdQtfN9nkCJNW+XCKQeTq42yo9jqne9tcAAAAXSHbnOAAj50cAAAACAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAABAAAAAA==", - "fee_meta_xdr": "AAAAAgAAAAMAI+dTAAAAAAAAAACGuNLuH5QO7N1C1832eQIk1b5cIpB5OrjbKj2Oqd721wAAABdIduecACPnRwAAAAEAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAEAI+dcAAAAAAAAAACGuNLuH5QO7N1C1832eQIk1b5cIpB5OrjbKj2Oqd721wAAABdIduc4ACPnRwAAAAEAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAA==", - "memo_type": "text", - "memo": "afsdfas", - "valid_after": "1970-01-01T00:00:00Z", - "signatures": [ - "oSUrcKg2jV/x9YgZ4mb3yXDYBoWLJVUWHHe4WiTRdVbcwdX0y5u0SF8D6fWIs+vGbMe0d+Zmy6ZaT6w4RCVLAg==" - ] -} -``` - -## Endpoints - -| Resource | Type | Resource URI Template | -|--------------------------------------------------------|------------|--------------------------------------| -| [All Transactions](../endpoints/transactions-all.md) | Collection | `/transactions` (`GET`) | -| [Post Transaction](../endpoints/transactions-create.md) | Action | `/transactions` (`POST`) | -| [Transaction Details](../endpoints/transactions-single.md) | Single | `/transactions/:id` | -| [Account Transactions](../endpoints/transactions-for-account.md) | Collection | `/accounts/:account_id/transactions` | -| [Ledger Transactions](../endpoints/transactions-for-ledger.md) | Collection | `/ledgers/:ledger_id/transactions` | - - -## Submitting transactions -To submit a new transaction to Stellar network, it must first be built and signed locally. Then you can submit a hex representation of your transaction’s [XDR](../xdr.md) to the `/transactions` endpoint. Read more about submitting transactions in [Post Transaction](../endpoints/transactions-create.md) doc. diff --git a/services/horizon/internal/docs/reference/responses.md b/services/horizon/internal/docs/reference/responses.md deleted file mode 100644 index 151e11ca57..0000000000 --- a/services/horizon/internal/docs/reference/responses.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Response Format -replacement: https://developers.stellar.org/api/introduction/response-format/ ---- - -Rather than using a fully custom way of representing the resources we expose in -Horizon, we use [HAL](http://stateless.co/hal_specification.html). HAL is a -hypermedia format in JSON that remains simple while giving us a couple of -benefits such as simpler client integration for several languages. See [this -wiki page](https://github.com/mikekelly/hal_specification/wiki/Libraries) for a -list of libraries. - -## Attributes, Links, Embedded Resources - -At its simplest, a HAL response is just a JSON object with a couple of reserved -property names: `_links` is used for expressing links and `_embedded` is used -for bundling other HAL objects with the response. Other than links and embedded -objects, **HAL is just JSON**. - -### Links - -HAL is a hypermedia format, like HTML, in that it has a mechanism to express -links between documents. Let's look at a simple example: - -```json -{ - "_links": { - "self": { - "href": "/ledgers/1" - }, - "transactions": { - "href": "/ledgers/1/transactions{?cursor,limit,order}", - "templated": true - } - }, - "id": "43cf4db3741a7d6c2322e7b646320ce9d7b099a0b3501734dcf70e74a8a4e637", - "hash": "43cf4db3741a7d6c2322e7b646320ce9d7b099a0b3501734dcf70e74a8a4e637", - "prev_hash": "", - "sequence": 1, - "transaction_count": 0, - "operation_count": 0, - "closed_at": "0001-01-01T00:00:00Z", - "total_coins": "100000000000.0000000", - "fee_pool": "0.0000000", - "base_fee_in_stroops": 100, - "base_reserve_in_stroops": 100000000, - "max_tx_set_size": 50 -} -``` - -The above response is for the genesis ledger of the Stellar test network, and -the links in the `_links` attribute provide links to other relavant resources in -Horizon. Notice the object beneath the `transactions` key. The key of each -link specifies that links relation to the current resource, and in this case -`transactions` means "Transactions that occurred in this ledger". Logically, -you should expect that resource to respond with a collection of transactions -with all of the results having a `ledger_sequence` attribute equal to 1. - -The `transactions` link is also _templated_, which means that the `href` -attribute of the link is actually a URI template, as specified by [RFC -6570](https://tools.ietf.org/html/rfc6570). We use URI templates to show you -what parameters a given resource can take. You must evaluate the template to a -valid URI before navigating to it. - -## Pages - -Pages represent a subset of a larger collection of objects. -As an example, it would be unfeasible to provide the -[All Transactions](../reference/endpoints/transactions-all.md) endpoint without paging. -Over time there will be millions of transactions in the Stellar network's ledger -and returning them all over a single request would be unfeasible. - -Read more about paging in following docs: -- [Page](../reference/resources/page.md) -- [Paging](./paging.md) diff --git a/services/horizon/internal/docs/reference/streaming.md b/services/horizon/internal/docs/reference/streaming.md deleted file mode 100644 index 4cc4aee979..0000000000 --- a/services/horizon/internal/docs/reference/streaming.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Streaming -replacement: https://developers.stellar.org/api/introduction/streaming/ ---- - -## Streaming - -Certain endpoints in Horizon can be called in streaming mode using Server-Sent Events. This mode will keep the connection to Horizon open and Horizon will continue to return responses as ledgers close. All parameters for the endpoints that allow this mode are the same. The way a caller initiates this mode is by setting `Accept: text/event-stream` in the HTTP header when you make the request. -You can read an example of using the streaming mode in the [Follow Received Payments](./tutorials/follow-received-payments.md) tutorial. - -Endpoints that currently support streaming: -* [Account](./endpoints/accounts-single.md) -* [Effects](./endpoints/effects-all.md) -* [Ledgers](./endpoints/ledgers-all.md) -* [Offers](./endpoints/offers-for-account.md) -* [Operations](./endpoints/operations-all.md) -* [Orderbook](./endpoints/orderbook-details.md) -* [Payments](./endpoints/payments-all.md) -* [Transactions](./endpoints/transactions-all.md) -* [Trades](./endpoints/trades.md) diff --git a/services/horizon/internal/docs/reference/tutorials/follow-received-payments.md b/services/horizon/internal/docs/reference/tutorials/follow-received-payments.md deleted file mode 100644 index 667384ae68..0000000000 --- a/services/horizon/internal/docs/reference/tutorials/follow-received-payments.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: Follow Received Payments ---- - -This tutorial shows how easy it is to use Horizon to watch for incoming payments on an [account](../../reference/resources/account.md) -using JavaScript and `EventSource`. We will eschew using [`js-stellar-sdk`](https://github.com/stellar/js-stellar-sdk), the -high-level helper library, to show that it is possible for you to perform this -task on your own, with whatever programming language you would like to use. - -This tutorial assumes that you: - -- Have node.js installed locally on your machine. -- Have curl installed locally on your machine. -- Are running on Linux, OS X, or any other system that has access to a bash-like - shell. -- Are familiar with launching and running commands in a terminal. - -In this tutorial we will learn: - -- How to create a new account. -- How to fund your account using friendbot. -- How to follow payments to your account using curl and EventSource. - -## Project Skeleton - -Let's get started by building our project skeleton: - -```bash -$ mkdir follow_tutorial -$ cd follow_tutorial -$ npm install --save stellar-base -$ npm install --save eventsource -``` - -This should have created a `package.json` in the `follow_tutorial` directory. -You can check that everything went well by running the following command: - -```bash -$ node -e "require('stellar-base')" -``` - -Everything was successful if no output it generated from the above command. Now -let's write a script to create a new account. - -## Creating an account - -Create a new file named `make_account.js` and paste the following text into it: - -```javascript -var Keypair = require("stellar-base").Keypair; - -var newAccount = Keypair.random(); - -console.log("New key pair created!"); -console.log(" Account ID: " + newAccount.publicKey()); -console.log(" Secret: " + newAccount.secret()); -``` - -Save the file and run it: - -```bash -$ node make_account.js -New key pair created! - Account ID: GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3 - Secret: SCU36VV2OYTUMDSSU4EIVX4UUHY3XC7N44VL4IJ26IOG6HVNC7DY5UJO -$ -``` - -Before our account can do anything it must be funded. Indeed, before an account -is funded it does not truly exist! - -## Funding your account - -The Stellar test network provides the Friendbot, a tool that developers -can use to get testnet lumens for testing purposes. To fund your account, simply -execute the following curl command: - -```bash -$ curl "https://friendbot.stellar.org/?addr=GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3" -``` - -Don't forget to replace the account id above with your own. If the request -succeeds, you should see a response like: - -```json -{ - "hash": "ed9e96e136915103f5d8978cbb2036628e811f2c59c4c3d88534444cf504e360", - "result": "received", - "submission_result": "000000000000000a0000000000000001000000000000000000000000" -} -``` - -After a few seconds, the Stellar network will perform consensus, close the -ledger, and your account will have been created. Next up we will write a command -that watches for new payments to your account and outputs a message to the -terminal. - -## Following payments using `curl` - -To follow new payments connected to your account you simply need to send `Accept: text/event-stream` header to the [/payments](../../reference/endpoints/payments-all.md) endpoint. - -```bash -$ curl -H "Accept: text/event-stream" "https://horizon-testnet.stellar.org/accounts/GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3/payments" -``` - -As a result you will see something like: - -```bash -retry: 1000 -event: open -data: "hello" - -id: 713226564145153 -data: {"_links":{"effects":{"href":"/operations/713226564145153/effects/{?cursor,limit,order}","templated":true}, - "precedes":{"href":"/operations?cursor=713226564145153\u0026order=asc"}, - "self":{"href":"/operations/713226564145153"}, - "succeeds":{"href":"/operations?cursor=713226564145153\u0026order=desc"}, - "transactions":{"href":"/transactions/713226564145152"}}, - "account":"GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3", - "funder":"GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K", - "id":713226564145153, - "paging_token":"713226564145153", - "starting_balance":"10000", - "type_i":0, - "type":"create_account"} -``` - -Every time you receive a new payment you will get a new row of data. Payments is not the only endpoint that supports streaming. You can also stream transactions [/transactions](../../reference/endpoints/transactions-all.md) and operations [/operations](../../reference/endpoints/operations-all.md). - -## Following payments using `EventStream` - -> **Warning!** `EventSource` object does not reconnect for certain error types so it can stop working. -> If you need a reliable streaming connection please use our [SDK](https://github.com/stellar/js-stellar-sdk). - -Another way to follow payments is writing a simple JS script that will stream payments and print them to console. Create `stream_payments.js` file and paste the following code into it: - -```js -var EventSource = require('eventsource'); -var es = new EventSource('https://horizon-testnet.stellar.org/accounts/GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3/payments'); -es.onmessage = function(message) { - var result = message.data ? JSON.parse(message.data) : message; - console.log('New payment:'); - console.log(result); -}; -es.onerror = function(error) { - console.log('An error occurred!'); -} -``` -Now, run our script: `node stream_payments.js`. You should see following output: -```bash -New payment: -{ _links: - { effects: - { href: '/operations/713226564145153/effects/{?cursor,limit,order}', - templated: true }, - precedes: { href: '/operations?cursor=713226564145153&order=asc' }, - self: { href: '/operations/713226564145153' }, - succeeds: { href: '/operations?cursor=713226564145153&order=desc' }, - transactions: { href: '/transactions/713226564145152' } }, - account: 'GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3', - funder: 'GBS43BF24ENNS3KPACUZVKK2VYPOZVBQO2CISGZ777RYGOPYC2FT6S3K', - id: 713226564145153, - paging_token: '713226564145153', - starting_balance: '10000', - type_i: 0, - type: 'create_account' } -``` - -## Testing it out - -We now know how to get a stream of transactions to an account. Let's check if our solution actually works and if new payments appear. Let's watch as we send a payment ([`create_account` operation](../../../guides/concepts/list-of-operations.html#create-account)) from our account to another account. - -We use the `create_account` operation because we are sending payment to a new, unfunded account. If we were sending payment to an account that is already funded, we would use the [`payment` operation](../../../guides/concepts/list-of-operations.html#payment). - -First, let's check our account sequence number so we can create a payment transaction. To do this we send a request to horizon: - -```bash -$ curl "https://horizon-testnet.stellar.org/accounts/GB7JFK56QXQ4DVJRNPDBXABNG3IVKIXWWJJRJICHRU22Z5R5PI65GAK3" -``` - -Sequence number can be found under the `sequence` field. The current sequence number is `713226564141056`. Save this value somewhere. - -Now, create `make_payment.js` file and paste the following code into it: - -```js -var StellarBase = require("stellar-base"); -StellarBase.Network.useTestNetwork(); - -var keypair = StellarBase.Keypair.fromSecret('SCU36VV2OYTUMDSSU4EIVX4UUHY3XC7N44VL4IJ26IOG6HVNC7DY5UJO'); -var account = new StellarBase.Account(keypair.publicKey(), "713226564141056"); - -var amount = "100"; -var transaction = new StellarBase.TransactionBuilder(account) - .addOperation(StellarBase.Operation.createAccount({ - destination: StellarBase.Keypair.random().publicKey(), - startingBalance: amount - })) - .build(); - -transaction.sign(keypair); - -console.log(transaction.toEnvelope().toXDR().toString("base64")); -``` - -After running this script you should see a signed transaction blob. To submit this transaction we send it to horizon or stellar-core. But before we do, let's open a new console and start our previous script by `node stream_payments.js`. - -Now to send a transaction just use horizon: - -```bash -curl -H "Content-Type: application/json" -X POST -d '{"tx":"AAAAAH6Sq76F4cHVMWvGG4AtNtFVIvayUxSgR401rPY9ej3TAAAD6AACiK0AAAABAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAAKc1j3y10+nI+sxuXlmFz71JS35mp/RcPCP45Gw0obdAAAAAAAAAAAAExLQAAAAAAAAAAAT16PdMAAABAsJTBC5N5B9Q/9+ZKS7qkMd/wZHWlP6uCCFLzeD+JWT60/VgGFCpzQhZmMg2k4Vg+AwKJTwko3d7Jt3Y6WhjLCg=="}' "https://horizon-testnet.stellar.org/transactions" -``` - -You should see a new payment in a window running `stream_payments.js` script. diff --git a/services/horizon/internal/docs/reference/xdr.md b/services/horizon/internal/docs/reference/xdr.md deleted file mode 100644 index c80063394c..0000000000 --- a/services/horizon/internal/docs/reference/xdr.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: XDR -replacement: https://developers.stellar.org/api/introduction/xdr/ ---- - -**XDR**, also known as _External Data Representation_, is used extensively in -the Stellar Network, especially in the core protocol. The ledger, transactions, results, -history, and even the messages passed between computers running stellar-core -are encoded using XDR. - -XDR is specified in [RFC 4506](http://tools.ietf.org/html/rfc4506.html). - -Since XDR is a binary format and not known as widely as JSON for example, we try -to hide most of it from Horizon. Instead, we opt to interpret the XDR for you -and present the values as JSON attributes. That said, we also expose the XDR -to you so you can get access to the raw, canonical data. - -In general, Horizon will encode the XDR structures in base64 so that they can be -transmitted within a json body. You should decode the base64 string -into a byte stream, then decode the XDR into an in-memory data structure. - -## .X files - -Data structures in XDR are specified in an _interface definition file_ (IDL). -The IDL files used for the Stellar Network are available -[on GitHub](https://github.com/stellar/stellar-core/tree/master/src/xdr). diff --git a/support/datastore/datastore.go b/support/datastore/datastore.go index 0a92857b5c..e7e999345d 100644 --- a/support/datastore/datastore.go +++ b/support/datastore/datastore.go @@ -10,6 +10,7 @@ import ( type DataStoreConfig struct { Type string `toml:"type"` Params map[string]string `toml:"params"` + Schema DataStoreSchema `toml:"schema"` } // DataStore defines an interface for interacting with data storage @@ -24,14 +25,14 @@ type DataStore interface { } // NewDataStore factory, it creates a new DataStore based on the config type -func NewDataStore(ctx context.Context, datastoreConfig DataStoreConfig, network string) (DataStore, error) { +func NewDataStore(ctx context.Context, datastoreConfig DataStoreConfig) (DataStore, error) { switch datastoreConfig.Type { case "GCS": destinationBucketPath, ok := datastoreConfig.Params["destination_bucket_path"] if !ok { return nil, errors.Errorf("Invalid GCS config, no destination_bucket_path") } - return NewGCSDataStore(ctx, destinationBucketPath, network) + return NewGCSDataStore(ctx, destinationBucketPath) default: return nil, errors.Errorf("Invalid datastore type %v, not supported", datastoreConfig.Type) } diff --git a/support/datastore/datastore_test.go b/support/datastore/datastore_test.go index 12041729be..3482ef3204 100644 --- a/support/datastore/datastore_test.go +++ b/support/datastore/datastore_test.go @@ -8,6 +8,6 @@ import ( ) func TestInvalidStore(t *testing.T) { - _, err := NewDataStore(context.Background(), DataStoreConfig{Type: "unknown"}, "test") + _, err := NewDataStore(context.Background(), DataStoreConfig{Type: "unknown"}) require.Error(t, err) } diff --git a/support/datastore/gcs_datastore.go b/support/datastore/gcs_datastore.go index c6b22b0fca..cdedea086d 100644 --- a/support/datastore/gcs_datastore.go +++ b/support/datastore/gcs_datastore.go @@ -26,19 +26,19 @@ type GCSDataStore struct { prefix string } -func NewGCSDataStore(ctx context.Context, bucketPath string, network string) (DataStore, error) { +func NewGCSDataStore(ctx context.Context, bucketPath string) (DataStore, error) { client, err := storage.NewClient(ctx) if err != nil { return nil, err } - return FromGCSClient(ctx, client, bucketPath, network) + return FromGCSClient(ctx, client, bucketPath) } -func FromGCSClient(ctx context.Context, client *storage.Client, bucketPath string, network string) (DataStore, error) { +func FromGCSClient(ctx context.Context, client *storage.Client, bucketPath string) (DataStore, error) { // append the gcs:// scheme to enable usage of the url package reliably to // get parse bucket name which is first path segment as URL.Host - gcsBucketURL := fmt.Sprintf("gcs://%s/%s", bucketPath, network) + gcsBucketURL := fmt.Sprintf("gcs://%s", bucketPath) parsed, err := url.Parse(gcsBucketURL) if err != nil { return nil, err diff --git a/support/datastore/gcs_test.go b/support/datastore/gcs_test.go index 0ddf60ac99..8838e8dadb 100644 --- a/support/datastore/gcs_test.go +++ b/support/datastore/gcs_test.go @@ -24,7 +24,7 @@ func TestGCSExists(t *testing.T) { }) defer server.Stop() - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -52,7 +52,7 @@ func TestGCSSize(t *testing.T) { }) defer server.Stop() - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -86,7 +86,7 @@ func TestGCSPutFile(t *testing.T) { DefaultEventBasedHold: false, }) - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -138,7 +138,7 @@ func TestGCSPutFileIfNotExists(t *testing.T) { }) defer server.Stop() - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -187,7 +187,7 @@ func TestGCSPutFileWithMetadata(t *testing.T) { DefaultEventBasedHold: false, }) - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -198,7 +198,7 @@ func TestGCSPutFileWithMetadata(t *testing.T) { EndLedger: 1234, StartLedgerCloseTime: 1234, EndLedgerCloseTime: 1234, - Network: "testnet", + NetworkPassPhrase: "testnet", CompressionType: "zstd", ProtocolVersion: 21, CoreVersion: "v1.2.3", @@ -223,7 +223,7 @@ func TestGCSPutFileWithMetadata(t *testing.T) { EndLedger: 6789, StartLedgerCloseTime: 1622547800, EndLedgerCloseTime: 1622548900, - Network: "mainnet", + NetworkPassPhrase: "mainnet", CompressionType: "gzip", ProtocolVersion: 23, CoreVersion: "v1.4.0", @@ -255,7 +255,7 @@ func TestGCSPutFileIfNotExistsWithMetadata(t *testing.T) { }) defer server.Stop() - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -265,7 +265,7 @@ func TestGCSPutFileIfNotExistsWithMetadata(t *testing.T) { EndLedger: 1234, StartLedgerCloseTime: 1234, EndLedgerCloseTime: 1234, - Network: "testnet", + NetworkPassPhrase: "testnet", CompressionType: "zstd", ProtocolVersion: 21, CoreVersion: "v1.2.3", @@ -290,7 +290,7 @@ func TestGCSPutFileIfNotExistsWithMetadata(t *testing.T) { EndLedger: 6789, StartLedgerCloseTime: 1622547800, EndLedgerCloseTime: 1622548900, - Network: "mainnet", + NetworkPassPhrase: "mainnet", CompressionType: "gzip", ProtocolVersion: 23, CoreVersion: "v1.4.0", @@ -323,7 +323,7 @@ func TestGCSGetNonExistentFile(t *testing.T) { }) defer server.Stop() - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) @@ -365,7 +365,7 @@ func TestGCSGetFileValidatesCRC32C(t *testing.T) { }) defer server.Stop() - store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects", "testnet") + store, err := FromGCSClient(context.Background(), server.Client(), "test-bucket/objects/testnet") require.NoError(t, err) t.Cleanup(func() { require.NoError(t, store.Close()) diff --git a/support/datastore/history_archive.go b/support/datastore/history_archive.go index bc692fb77e..123240dc6f 100644 --- a/support/datastore/history_archive.go +++ b/support/datastore/history_archive.go @@ -10,10 +10,12 @@ import ( "github.com/stellar/go/support/storage" ) -const Pubnet = "pubnet" -const Testnet = "testnet" +const ( + Pubnet = "pubnet" + Testnet = "testnet" +) -func CreateHistoryArchiveFromNetworkName(ctx context.Context, networkName string) (historyarchive.ArchiveInterface, error) { +func CreateHistoryArchiveFromNetworkName(ctx context.Context, networkName string, userAgent string) (historyarchive.ArchiveInterface, error) { var historyArchiveUrls []string switch networkName { case Pubnet: @@ -26,7 +28,7 @@ func CreateHistoryArchiveFromNetworkName(ctx context.Context, networkName string return historyarchive.NewArchivePool(historyArchiveUrls, historyarchive.ArchiveOptions{ ConnectOptions: storage.ConnectOptions{ - UserAgent: "ledger-exporter", + UserAgent: userAgent, Context: ctx, }, }) diff --git a/support/datastore/ledgerbatch_config.go b/support/datastore/ledgerbatch_config.go index 4ebac0d110..e70bfb5fb0 100644 --- a/support/datastore/ledgerbatch_config.go +++ b/support/datastore/ledgerbatch_config.go @@ -7,24 +7,24 @@ import ( "github.com/stellar/go/support/compressxdr" ) -type LedgerBatchConfig struct { +type DataStoreSchema struct { LedgersPerFile uint32 `toml:"ledgers_per_file"` FilesPerPartition uint32 `toml:"files_per_partition"` } -func (ec LedgerBatchConfig) GetSequenceNumberStartBoundary(ledgerSeq uint32) uint32 { +func (ec DataStoreSchema) GetSequenceNumberStartBoundary(ledgerSeq uint32) uint32 { if ec.LedgersPerFile == 0 { return 0 } return (ledgerSeq / ec.LedgersPerFile) * ec.LedgersPerFile } -func (ec LedgerBatchConfig) GetSequenceNumberEndBoundary(ledgerSeq uint32) uint32 { +func (ec DataStoreSchema) GetSequenceNumberEndBoundary(ledgerSeq uint32) uint32 { return ec.GetSequenceNumberStartBoundary(ledgerSeq) + ec.LedgersPerFile - 1 } // GetObjectKeyFromSequenceNumber generates the object key name from the ledger sequence number based on configuration. -func (ec LedgerBatchConfig) GetObjectKeyFromSequenceNumber(ledgerSeq uint32) string { +func (ec DataStoreSchema) GetObjectKeyFromSequenceNumber(ledgerSeq uint32) string { var objectKey string if ec.FilesPerPartition > 1 { diff --git a/support/datastore/ledgerbatch_config_test.go b/support/datastore/ledgerbatch_config_test.go index bd79dd265d..f95fef168e 100644 --- a/support/datastore/ledgerbatch_config_test.go +++ b/support/datastore/ledgerbatch_config_test.go @@ -31,7 +31,7 @@ func TestGetObjectKeyFromSequenceNumber(t *testing.T) { for _, tc := range testCases { t.Run(fmt.Sprintf("LedgerSeq-%d-LedgersPerFile-%d", tc.ledgerSeq, tc.ledgersPerFile), func(t *testing.T) { - config := LedgerBatchConfig{FilesPerPartition: tc.filesPerPartition, LedgersPerFile: tc.ledgersPerFile} + config := DataStoreSchema{FilesPerPartition: tc.filesPerPartition, LedgersPerFile: tc.ledgersPerFile} key := config.GetObjectKeyFromSequenceNumber(tc.ledgerSeq) require.Equal(t, tc.expectedKey, key) }) @@ -39,7 +39,7 @@ func TestGetObjectKeyFromSequenceNumber(t *testing.T) { } func TestGetObjectKeyFromSequenceNumber_ObjectKeyDescOrder(t *testing.T) { - config := LedgerBatchConfig{ + config := DataStoreSchema{ LedgersPerFile: 1, FilesPerPartition: 10, } diff --git a/support/datastore/metadata.go b/support/datastore/metadata.go index db734bbd4d..bd943b1987 100644 --- a/support/datastore/metadata.go +++ b/support/datastore/metadata.go @@ -9,7 +9,7 @@ type MetaData struct { EndLedgerCloseTime int64 ProtocolVersion uint32 CoreVersion string - Network string + NetworkPassPhrase string CompressionType string Version string } @@ -22,7 +22,7 @@ func (m MetaData) ToMap() map[string]string { "end-ledger-close-time": strconv.FormatInt(m.EndLedgerCloseTime, 10), "protocol-version": strconv.FormatInt(int64(m.ProtocolVersion), 10), "core-version": m.CoreVersion, - "network": m.Network, + "network-passphrase": m.NetworkPassPhrase, "compression-type": m.CompressionType, "version": m.Version, } @@ -71,7 +71,7 @@ func NewMetaDataFromMap(data map[string]string) (MetaData, error) { } metaData.CoreVersion = data["core-version"] - metaData.Network = data["network"] + metaData.NetworkPassPhrase = data["network-passphrase"] metaData.CompressionType = data["compression-type"] metaData.Version = data["version"] diff --git a/support/datastore/metadata_test.go b/support/datastore/metadata_test.go index 6ec6a176b8..ffc92f4e51 100644 --- a/support/datastore/metadata_test.go +++ b/support/datastore/metadata_test.go @@ -22,7 +22,7 @@ func TestMetaDataToMap(t *testing.T) { EndLedgerCloseTime: 987654321, ProtocolVersion: 3, CoreVersion: "v1.2.3", - Network: "testnet", + NetworkPassPhrase: "testnet passphrase", CompressionType: "gzip", Version: "1.0.0", }, @@ -33,7 +33,7 @@ func TestMetaDataToMap(t *testing.T) { "end-ledger-close-time": "987654321", "protocol-version": "3", "core-version": "v1.2.3", - "network": "testnet", + "network-passphrase": "testnet passphrase", "compression-type": "gzip", "version": "1.0.0", }, @@ -48,7 +48,7 @@ func TestMetaDataToMap(t *testing.T) { EndLedgerCloseTime: tt.metaData.EndLedgerCloseTime, ProtocolVersion: tt.metaData.ProtocolVersion, CoreVersion: tt.metaData.CoreVersion, - Network: tt.metaData.Network, + NetworkPassPhrase: tt.metaData.NetworkPassPhrase, CompressionType: tt.metaData.CompressionType, Version: tt.metaData.Version, } @@ -66,7 +66,7 @@ func TestNewMetaDataFromMap(t *testing.T) { "end-ledger-close-time": "987654321", "protocol-version": "3", "core-version": "v1.2.3", - "network": "testnet", + "network-passphrase": "testnet passphrase", "compression-type": "gzip", "version": "1.0.0", } @@ -78,7 +78,7 @@ func TestNewMetaDataFromMap(t *testing.T) { EndLedgerCloseTime: 987654321, ProtocolVersion: 3, CoreVersion: "v1.2.3", - Network: "testnet", + NetworkPassPhrase: "testnet passphrase", CompressionType: "gzip", Version: "1.0.0", } diff --git a/support/datastore/resumablemanager_test.go b/support/datastore/resumablemanager_test.go index 2649a26033..4616f9e4ae 100644 --- a/support/datastore/resumablemanager_test.go +++ b/support/datastore/resumablemanager_test.go @@ -16,10 +16,9 @@ func TestResumability(t *testing.T) { name string startLedger uint32 endLedger uint32 - ledgerBatchConfig LedgerBatchConfig + dataStoreSchema DataStoreSchema absentLedger uint32 findStartOk bool - networkName string latestLedger uint32 errorSnippet string archiveError error @@ -31,11 +30,10 @@ func TestResumability(t *testing.T) { endLedger: 0, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", errorSnippet: "archive error", archiveError: errors.New("archive error"), registerMockCalls: func(store *MockDataStore) {}, @@ -46,11 +44,10 @@ func TestResumability(t *testing.T) { endLedger: 4, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFFF--0-9.xdr.zstd").Return(true, nil).Once() }, @@ -61,11 +58,10 @@ func TestResumability(t *testing.T) { endLedger: 14, absentLedger: 14, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFF5--10-19.xdr.zstd").Return(false, nil).Twice() }, @@ -76,11 +72,10 @@ func TestResumability(t *testing.T) { endLedger: 68, absentLedger: 64, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(100), LedgersPerFile: uint32(64), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFFF--0-6399/FFFFFFBF--64-127.xdr.zstd").Return(false, nil).Twice() }, @@ -91,11 +86,10 @@ func TestResumability(t *testing.T) { endLedger: 130, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(100), LedgersPerFile: uint32(64), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFFF--0-6399/FFFFFF7F--128-191.xdr.zstd").Return(true, nil).Once() }, @@ -106,11 +100,10 @@ func TestResumability(t *testing.T) { endLedger: 127, absentLedger: 2, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(100), LedgersPerFile: uint32(64), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFFF--0-6399/FFFFFFBF--64-127.xdr.zstd").Return(true, nil).Once() mockDataStore.On("Exists", ctx, "FFFFFFFF--0-6399/FFFFFFFF--0-63.xdr.zstd").Return(false, nil).Once() @@ -122,11 +115,10 @@ func TestResumability(t *testing.T) { endLedger: 24, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", errorSnippet: "datastore error happened", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFEB--20-29.xdr.zstd").Return(false, errors.New("datastore error happened")).Once() @@ -138,11 +130,10 @@ func TestResumability(t *testing.T) { endLedger: 50, absentLedger: 40, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFCD--50-59.xdr.zstd").Return(false, nil).Once() mockDataStore.On("Exists", ctx, "FFFFFFE1--30-39.xdr.zstd").Return(true, nil).Once() @@ -155,11 +146,10 @@ func TestResumability(t *testing.T) { endLedger: 85, absentLedger: 80, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFFB9--70-79.xdr.zstd").Return(true, nil).Once() mockDataStore.On("Exists", ctx, "FFFFFFAF--80-89.xdr.zstd").Return(false, nil).Twice() @@ -171,11 +161,10 @@ func TestResumability(t *testing.T) { endLedger: 275, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFEFB--260-269.xdr.zstd").Return(true, nil).Once() mockDataStore.On("Exists", ctx, "FFFFFEF1--270-279.xdr.zstd").Return(true, nil).Once() @@ -187,11 +176,10 @@ func TestResumability(t *testing.T) { endLedger: 125, absentLedger: 95, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFFF87--120-129.xdr.zstd").Return(false, nil).Once() mockDataStore.On("Exists", ctx, "FFFFFF91--110-119.xdr.zstd").Return(false, nil).Once() @@ -205,11 +193,10 @@ func TestResumability(t *testing.T) { endLedger: 10, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test", errorSnippet: "Invalid start value", registerMockCalls: func(store *MockDataStore) {}, }, @@ -219,11 +206,10 @@ func TestResumability(t *testing.T) { endLedger: 0, absentLedger: 1145, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test2", latestLedger: uint32(2000), registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFF9A1--1630-1639.xdr.zstd").Return(false, nil).Once() @@ -242,11 +228,10 @@ func TestResumability(t *testing.T) { endLedger: 0, absentLedger: 2250, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test3", latestLedger: uint32(3000), registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFF5B9--2630-2639.xdr.zstd").Return(false, nil).Once() @@ -264,11 +249,10 @@ func TestResumability(t *testing.T) { endLedger: 0, absentLedger: 4070, findStartOk: true, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test4", latestLedger: uint32(4000), registerMockCalls: func(mockDataStore *MockDataStore) { mockDataStore.On("Exists", ctx, "FFFFF1D1--3630-3639.xdr.zstd").Return(true, nil).Once() @@ -286,11 +270,10 @@ func TestResumability(t *testing.T) { endLedger: 0, absentLedger: 0, findStartOk: false, - ledgerBatchConfig: LedgerBatchConfig{ + dataStoreSchema: DataStoreSchema{ FilesPerPartition: uint32(1), LedgersPerFile: uint32(10), }, - networkName: "test5", latestLedger: uint32(5000), errorSnippet: "Invalid start value of 5129, it is greater than network's latest ledger of 5128", registerMockCalls: func(store *MockDataStore) {}, @@ -304,7 +287,7 @@ func TestResumability(t *testing.T) { mockDataStore := &MockDataStore{} tt.registerMockCalls(mockDataStore) - resumableManager := NewResumableManager(mockDataStore, tt.networkName, tt.ledgerBatchConfig, mockArchive) + resumableManager := NewResumableManager(mockDataStore, tt.dataStoreSchema, mockArchive) absentLedger, ok, err := resumableManager.FindStart(ctx, tt.startLedger, tt.endLedger) if tt.errorSnippet != "" { require.ErrorContains(t, err, tt.errorSnippet) diff --git a/support/datastore/resumeablemanager.go b/support/datastore/resumeablemanager.go index f552dcf106..35031d73f6 100644 --- a/support/datastore/resumeablemanager.go +++ b/support/datastore/resumeablemanager.go @@ -37,19 +37,16 @@ type ResumableManager interface { } type resumableManagerService struct { - network string - ledgerBatchConfig LedgerBatchConfig + ledgerBatchConfig DataStoreSchema dataStore DataStore archive historyarchive.ArchiveInterface } func NewResumableManager(dataStore DataStore, - network string, - ledgerBatchConfig LedgerBatchConfig, + ledgerBatchConfig DataStoreSchema, archive historyarchive.ArchiveInterface) ResumableManager { return &resumableManagerService{ ledgerBatchConfig: ledgerBatchConfig, - network: network, dataStore: dataStore, archive: archive, } @@ -60,7 +57,7 @@ func (rm resumableManagerService) FindStart(ctx context.Context, start, end uint return 0, false, errors.New("Invalid start value, must be greater than zero") } - log.WithField("start", start).WithField("end", end).WithField("network", rm.network) + log.WithField("start", start).WithField("end", end) networkLatest := uint32(0) if end < 1 { @@ -71,7 +68,7 @@ func (rm resumableManagerService) FindStart(ctx context.Context, start, end uint return 0, false, err } networkLatest = networkLatest + (GetHistoryArchivesCheckPointFrequency() * 2) - log.Infof("Resumability computed effective latest network ledger including padding of checkpoint frequency to be %d + for network=%v", networkLatest, rm.network) + log.Infof("Resumability computed effective latest network ledger including padding of checkpoint frequency to be %d", networkLatest) if start > networkLatest { // requested to start at a point beyond the latest network, resume not applicable.