Skip to content

Commit

Permalink
Reorganize "network" section content (#686)
Browse files Browse the repository at this point in the history
* move core node docs into their own navbar item "Validators"

* fix some old links

* update and add redirects for validators section

* fix some more links

* remove core node from networks sidebar

* remove core-node from network dropdown

* we don't need to check for core-node in swizzled ApiItem component

* move anchor/disbursement platforms into their own root-level dir

* shuffling some things, styling navbar items

* use the ApiItem component for Horizon APIs

* use the right components and sidebar generators for horizon

* format horizon docs

* re-enable throwing errors on broken links

* change some links for anchor platform

* add redirects for moved content

* fix about a thousand broken links

* linting and formatting

* fix another broken link

* fix a couple older redirects

* add tools overview

still missing links to SDP and AP cause I can't find them

* add platform links in Tools readme

---------

Co-authored-by: Bri <[email protected]>
  • Loading branch information
ElliotFriend and briwylde08 authored Jun 20, 2024
1 parent 4130666 commit a5af7b3
Show file tree
Hide file tree
Showing 475 changed files with 1,992 additions and 1,892 deletions.
2 changes: 2 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# openapi generated pages
**/*.api.mdx
25 changes: 25 additions & 0 deletions docs/data/README.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
title: Data Overview
---

There are many ways you can retrieve data from the Stellar network.

## Horizon

Horizon is an API for interacting with the Stellar network.

This API serves the bridge between apps and Stellar Core. Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.

[Learn more about the Horizon API here!](./horizon/README.mdx)

## Hubble

Hubble is your go-to source for viewing, analyzing, and understanding historic data from the Stellar network.

[Learn more about Hubble here!](./hubble/README.mdx)

## RPC

If you are writing or interacting with smart contracts, you'll need to use RPC. This is the best platform to see current state of the Stellar network.

[Learn more about RPC here!](./rpc/README.mdx)
6 changes: 3 additions & 3 deletions network/READ_FIRST.md → docs/data/READ_FIRST.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,6 @@ draft: true
If you're here to make some fixes to Stellar's API documentation (first, thank
you!), you probably don't want to be in this location. Most of the API
documentation located here has been generated by the `.yml` files contained in
the `/openapi` directory. Unless you're working on something
that's _outside_ the `/api/resources` directory, you'll probably want to check
in `/openapi` instead of here.
the `/openapi` directory. Unless you're working on something that's _outside_
the `/api/resources` directory, you'll probably want to check in `/openapi`
instead of here.
11 changes: 5 additions & 6 deletions network/horizon/README.mdx → docs/data/horizon/README.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ Starting on August 1, 2024, SDF will be truncating historical data on SDF-owned

:::

Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by Stellar Core. This API serves the bridge between apps and [Stellar Core](../core-node/README.mdx). Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.
Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by Stellar Core. This API serves the bridge between apps and [Stellar Core](../../validators/README.mdx). Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.

Horizon can be accessed via cURL, a browser, or one of the [Stellar SDKs](/docs/tools/sdks). To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls.
Horizon can be accessed via cURL, a browser, or one of the [Stellar SDKs](../../tools/sdks/library.mdx). To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls.

This guide describes how to administer a production Horizon instance (refer to the [Developers' Blog](https://www.stellar.org/developers-blog/a-new-sun-on-the-horizon) for some background on the performance and architectural improvements of this major version bump). For information about developing on the Horizon codebase, check out the [Development Guide](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md).

Before we begin, it's worth reiterating the sentiment echoed in the [Core Node](../core-node/README.mdx) documentation: **we do not endorse running Horizon backed by a standalone Stellar Core instance**, and especially not by a _validating_ Stellar Core. These are two separate concerns, and decoupling them is important for both reliability and performance. Horizon instead manages its own, pared-down version of Stellar Core optimized for its own subset of needs (we'll refer to this as a "Captive Core" instance).
Before we begin, it's worth reiterating the sentiment echoed in the [Core Node](../../validators/README.mdx) documentation: **we do not endorse running Horizon backed by a standalone Stellar Core instance**, and especially not by a _validating_ Stellar Core. These are two separate concerns, and decoupling them is important for both reliability and performance. Horizon instead manages its own, pared-down version of Stellar Core optimized for its own subset of needs (we'll refer to this as a "Captive Core" instance).

## Why Run Horizon?

Expand All @@ -26,9 +26,8 @@ Running Horizon within your own infrastructure provides a number of benefits. Yo

The Stellar Development Foundation (SDF) runs two instances of Horizon:

- [https://horizon-testnet.stellar.org/](https://horizon-testnet.stellar.org/) for interacting with the [testnet](/docs/learn/fundamentals/networks)
- [https://horizon-futurenet.stellar.org/](https://horizon-futurenet.stellar.org/) for interacting with the [futurenet](/docs/learn/fundamentals/networks)

- [https://horizon-testnet.stellar.org/](https://horizon-testnet.stellar.org/) for interacting with the [testnet](../../learn/fundamentals/networks.mdx)
- [https://horizon-futurenet.stellar.org/](https://horizon-futurenet.stellar.org/) for interacting with the [futurenet](../../learn/fundamentals/networks.mdx)

## In These Docs

Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ If you have configured your deployment to perform the ingestion role, then it is

### `DISABLE_TX_SUB`

This config parameter is optional, set as FALSE by default. Controls whether Horizon will accept HTTP requests to the `/tx` API endpoint and forward to the network. Refer to [Channel Accounts](../../../docs/learn/encyclopedia/transactions-specialized/channel-accounts) for some recommendations on optional client transaction submission optimizations.
This config parameter is optional, set as FALSE by default. Controls whether Horizon will accept HTTP requests to the `/tx` API endpoint and forward to the network. Refer to [Channel Accounts](../../../learn/encyclopedia/transactions-specialized/channel-accounts.mdx) for some recommendations on optional client transaction submission optimizations.

- When set to FALSE, it requires **live** ingestion process to be running on the same database because Horizon depends on new ledgers from the network to confirm a transaction submission status, Horizon will report a startup error if it detects no **live** ingestion. Requires `INGEST=true` or `STELLAR_CORE_URL` to be defined for access to a Core instance.
- When transaction submission is disabled by setting it to TRUE, Horizon will return 405 on POSTs to /tx.
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Horizon is a central component of the Stellar platform: it provides an HTTP API

This guide describes how to administer a production Horizon instance (refer to the [Developers' Blog](https://www.stellar.org/developers-blog/a-new-sun-on-the-horizon) for some background on the performance and architectural improvements of this major version bump). For information about developing on the Horizon codebase, check out the [Development Guide](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md).

Before we begin, it's worth reiterating the sentiment echoed in the [Run a Core Node](../../core-node/README.mdx) guide: **we do not endorse running Horizon backed by a standalone Stellar Core instance**, and especially not by a _validating_ Stellar Core. These are two separate concerns, and decoupling them is important for both reliability and performance. Horizon instead manages its own, pared-down version of Stellar Core optimized for its own subset of needs (we'll refer to this as a "Captive Core" instance).
Before we begin, it's worth reiterating the sentiment echoed in the [Run a Core Node](../../../validators/README.mdx) guide: **we do not endorse running Horizon backed by a standalone Stellar Core instance**, and especially not by a _validating_ Stellar Core. These are two separate concerns, and decoupling them is important for both reliability and performance. Horizon instead manages its own, pared-down version of Stellar Core optimized for its own subset of needs (we'll refer to this as a "Captive Core" instance).

## Why Run Horizon?

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ To achieve high availability, redundancy, and high throughput, refer to the [sca

- Ensure that the Horizon instance can establish a connection with the PostgreSQL database instance. The default port for PostgreSQL is 5432.

- A stable and fast network connection with the Internet is required for any Horizon instance running the ingestion role. This is to ensure it has efficient outbound connectivity to remote hosts in the [quorum set](../../core-node/admin-guide/configuring.mdx#choosing-your-quorum-set) and [archive urls](../../core-node/admin-guide/configuring.mdx#history) for the chosen Stellar network. During ingestion, the Horizon instance communicates with these hosts, receiving network transaction data through its local captive core sub-process.
- A stable and fast network connection with the Internet is required for any Horizon instance running the ingestion role. This is to ensure it has efficient outbound connectivity to remote hosts in the [quorum set](../../../validators/admin-guide/configuring.mdx#choosing-your-quorum-set) and [archive urls](../../../validators/admin-guide/configuring.mdx#history) for the chosen Stellar network. During ingestion, the Horizon instance communicates with these hosts, receiving network transaction data through its local captive core sub-process.

:::note

Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ Horizon enables different logical tiers that can be scaled independently for inc

- Web service API (serving)
- Captive Core (ingestion and transaction submission)
- Database (storage)
- Database (storage)

## Single Instance Deployment

It is recommend to start with a [single instance deployment](./prerequisites.mdx), and scale up based on the needs of your particular use-case.
It is recommend to start with a [single instance deployment](./prerequisites.mdx), and scale up based on the needs of your particular use-case.

This [deployment](./configuring.mdx#single-instance-deployment) is intended for use with minimal history retention (<= 30 days) and minimal request volume.

Expand All @@ -27,9 +27,9 @@ There are a few reasons you may choose to scale to multiple instances of Horizon
- Redundancy enables zero downtime in the cases where Horizon requires downtime on upgrade (migrations, state rebuilds, etc)
- Protection against potential ingestion lag, which could result in downtime for end-users

Multiple instances of Horizon can be configured to point to the same database, and the ingestion process will not perform redundant work in these cases.
Multiple instances of Horizon can be configured to point to the same database, and the ingestion process will not perform redundant work in these cases.

When scaling Horizon, it is worth it to note that Horizon's [rate limiting](../api-reference/structure/rate-limiting.mdx) should be disabled and rate limiting should be managed external to Horizon within infrastructure. Horizon's rate limiting implementation is managed in-memory, so does not work with multiple instances.
When scaling Horizon, it is worth it to note that Horizon's [rate limiting](../api-reference/structure/rate-limiting.mdx) should be disabled and rate limiting should be managed external to Horizon within infrastructure. Horizon's rate limiting implementation is managed in-memory, so does not work with multiple instances.

![](/assets/horizon-scaling/Topology-multiple.png)

Expand All @@ -54,4 +54,4 @@ In the above example, ingestion is safely isolated from most API traffic, which

The below diagram illustrates how we could further isolate (and scale) transaction submission, by way of using core watcher instances, rather than Horizon instances running captive core. This allows us to further protect ingestion, preventing downtime and ingestion lag. It also makes it possible to horizontally scale transaction submission itself, independent of the rest of the API traffic.

![](/assets/horizon-scaling/Topology-ingestion-isolation.png)
![](/assets/horizon-scaling/Topology-ingestion-isolation.png)
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@ import DocCardList from "@theme/DocCardList";

View all Horizon API information.

<DocCardList />
<DocCardList />
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@ curl "https://horizon-testnet.stellar.org/fee_stats"

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

server
.feeStats()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { EndpointsTable } from "@site/src/components/EndpointsTable";

An order book is a collections of offers for a specific pair of assets.

Learn more about [order books](/docs/learn/glossary/#decentralized-exchange).
Learn more about [order books](../../../../../learn/glossary.mdx#decentralized-exchange).

<EndpointsTable title="Endpoints">

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,9 @@ curl "https://horizon-testnet.stellar.org/order_book?selling_asset_type=native&b

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

server
.orderbook(
Expand Down Expand Up @@ -167,7 +169,9 @@ server

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

var callback = function (resp) {
console.log(resp);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import { EndpointsTable } from "@site/src/components/EndpointsTable";

Paths provide information about potential path payments. A path can be used to populate the necessary fields for a path payment operation.

Learn more about the two types of path payment: [`path payment strict send`](../../../../../docs/learn/fundamentals/transactions/list-of-operations#path-payment-strict-send) and [`path payment strict receive`](../../../../../docs/learn/fundamentals/transactions/list-of-operations#path-payment-strict-receive)
Learn more about the two types of path payment: [`path payment strict send`](../../../../../learn/fundamentals/transactions/list-of-operations.mdx#path-payment-strict-send) and [`path payment strict receive`](../../../../../learn/fundamentals/transactions/list-of-operations.mdx#path-payment-strict-receive)

<EndpointsTable title="Endpoints">

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,9 @@ curl "https://horizon-testnet.stellar.org/paths/strict-receive?source_assets=CNY

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

server
.strictReceivePaths(
Expand Down Expand Up @@ -211,7 +213,9 @@ print(response)

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

var callback = function (resp) {
console.log(resp);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,9 @@ curl "https://horizon-testnet.stellar.org/paths/strict-send?source_asset_type=cr

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

server
.strictSendPaths(
Expand Down Expand Up @@ -573,7 +575,9 @@ print(response)

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

var callback = function (resp) {
console.log(resp);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,9 @@ curl "https://horizon-testnet.stellar.org/trade_aggregations?base_asset_type=nat

```js
var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");
var server = new StellarSdk.Horizon.Server(
"https://horizon-testnet.stellar.org",
);

var base = new StellarSdk.Asset.native();
var counter = new StellarSdk.Asset(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ Each of Stellar's operations have unique causes of failure, and these result cod

</MethodTable>

For operations that aren't in this list, you can usually refer to their corresponding entries in the [List of Operations](../../../../../../docs/learn/fundamentals/transactions/list-of-operations) which will enumerate the failure cases and corresponding result codes.
For operations that aren't in this list, you can usually refer to their corresponding entries in the [List of Operations](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx) which will enumerate the failure cases and corresponding result codes.
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { AttributeTable } from "@site/src/components/AttributeTable";

These are result codes that communicate success (200) or failure (400) specific to the `Account Merge` operation.

Learn more about the [`Account Merge` operation](../../../../../../docs/learn/fundamentals/transactions/list-of-operations#account-merge).
Learn more about the [`Account Merge` operation](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx#account-merge).

<AttributeTable>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { AttributeTable } from "@site/src/components/AttributeTable";

These are result codes that communicate success (200) or failure (400) specific to the `Allow Trust` operation.

Learn more about the [`Allow Trust` operation](../../../../../../docs/learn/fundamentals/transactions/list-of-operations#allow-trust).
Learn more about the [`Allow Trust` operation](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx#allow-trust).

<AttributeTable>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { AttributeTable } from "@site/src/components/AttributeTable";

These are result codes that communicate success (200) or failure (400) specific to the `Bump Sequence` operation.

Learn more about the [`Bump Sequence` operation](../../../../../../docs/learn/fundamentals/transactions/list-of-operations#bump-sequence).
Learn more about the [`Bump Sequence` operation](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx#bump-sequence).

<AttributeTable>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { AttributeTable } from "@site/src/components/AttributeTable";

These are result codes that communicate success (200) or failure (400) specific to the `Change Trust` operation.

Learn more about the [`Change Trust` operation](../../../../../../docs/learn/fundamentals/transactions/list-of-operations#change-trust)
Learn more about the [`Change Trust` operation](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx#change-trust)

<AttributeTable>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { AttributeTable } from "@site/src/components/AttributeTable";

These are result codes that communicate success (200) or failure (400) specific to the `Create Account` operation, which often fails because the new account does not meet the minimum reserve.

Learn more about the [`Create Account` operation](../../../../../../docs/learn/fundamentals/transactions/list-of-operations#create-account).
Learn more about the [`Create Account` operation](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx#create-account).

<AttributeTable>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { AttributeTable } from "@site/src/components/AttributeTable";

These are result codes that communicate success (200) or failure (400) specific to the `Create Passive Sell Offer` operation.

Learn more about the [`Create Passive Sell Offer` operation](../../../../../../docs/learn/fundamentals/transactions/list-of-operations#create-passive-sell-offer).
Learn more about the [`Create Passive Sell Offer` operation](../../../../../../learn/fundamentals/transactions/list-of-operations.mdx#create-passive-sell-offer).

<AttributeTable>

Expand Down
Loading

0 comments on commit a5af7b3

Please sign in to comment.