Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📝 Refresh six classic guides #723

Draft
wants to merge 105 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
105 commits
Select commit Hold shift + click to select a range
a125983
🔁 Channel accounts: explain resolutions
JFWooten4 Jun 20, 2024
01424db
🔁 Channel accounts: simplify narrative
JFWooten4 Jun 22, 2024
37e38c3
🔁 Channel accounts: specify cards
JFWooten4 Jun 23, 2024
9ed2a0a
🔁 Channel accounts: finalize visuals
JFWooten4 Jun 23, 2024
44309a2
🔁 Channel accounts: simplify narrative
JFWooten4 Jun 26, 2024
dd7d761
🔁 Channel accounts: expand details
JFWooten4 Jun 26, 2024
c4a46dc
Merge branch 'stellar:main' into refresh-classic-guides
JFWooten4 Jul 5, 2024
68f165d
🔁 Channel accounts: hyperlinks, context
JFWooten4 Jul 7, 2024
07e613a
🔁 Channel accounts: initial diagrams
JFWooten4 Jul 9, 2024
bf6e15f
🔁 Channel accounts: reference configuration
JFWooten4 Jul 9, 2024
15d1288
🔁 Channel accounts: KaTeX formatting
JFWooten4 Jul 10, 2024
b874bc7
🔁 Channel accounts: context, links
JFWooten4 Jul 10, 2024
e290fb3
🔁 Channel accounts: conceptual images
JFWooten4 Jul 12, 2024
1f8a904
🔁 Channel accounts: simplify image
JFWooten4 Jul 12, 2024
46f49c6
🔁 Channel accounts: prioritize readability
JFWooten4 Jul 14, 2024
3f2e731
🔁 Channel accounts: overload example
JFWooten4 Jul 14, 2024
8a3d963
🔁 Channel accounts: configuration example
JFWooten4 Jul 15, 2024
cd7f447
🫴🏽 Claimable balances: first example
JFWooten4 Jul 18, 2024
e2248db
🫴🏽 Claimable balances: second example
JFWooten4 Jul 29, 2024
1992240
🫴🏽 Claimable balances: third example
JFWooten4 Jul 29, 2024
ee6175a
🫴🏽 Claimable balances: expand precomputation
JFWooten4 Aug 2, 2024
95ffe3c
🔎 Refresh: asset design considerations
JFWooten4 Aug 5, 2024
d93ae63
🦞 Clawbacks: confer readable diction
JFWooten4 Aug 5, 2024
e1611fc
🦞 Clawbacks: minor example diction
JFWooten4 Aug 5, 2024
03ac66d
🦞 Clawbacks: format account names
JFWooten4 Aug 5, 2024
86f3ca8
🦞 Clawbacks: format more names
JFWooten4 Aug 5, 2024
d1a9252
🦞 Clawbacks: apply name diction
JFWooten4 Aug 5, 2024
eb0e9be
🦞 Clawbacks: translate preamble example
JFWooten4 Aug 6, 2024
f4ad468
🦞 Clawbacks: expand example one
JFWooten4 Aug 6, 2024
e72e4a8
🦞 Clawbacks: translate next instances
JFWooten4 Aug 6, 2024
09fa456
🦞 Clawbacks: continue example dev
JFWooten4 Aug 6, 2024
b3e3230
💱 Trading examples: add lumenaut
JFWooten4 Aug 8, 2024
ee66e13
⏬ Prep for GH sync
JFWooten4 Aug 12, 2024
364f656
Merge remote-tracking branch 'upstream/main' into refresh-classic-guides
JFWooten4 Aug 12, 2024
6e866b7
Merge remote-tracking branch 'upstream/main' into refresh-classic-guides
JFWooten4 Aug 21, 2024
080ec03
💱 Trading examples: clarify narrative
JFWooten4 Sep 13, 2024
b529869
💱 Trading examples: contextualize sources
JFWooten4 Sep 13, 2024
127142e
↕️ Merge branch with self
JFWooten4 Sep 13, 2024
fea178f
🙌 Missed a reference link
JFWooten4 Sep 13, 2024
1a12877
💱 Trading examples: sell offers
JFWooten4 Sep 16, 2024
550b941
💱 Trading examples: level two
JFWooten4 Sep 16, 2024
fff2713
💱 Trading examples: time & sales
JFWooten4 Sep 16, 2024
06d249d
Merge remote-tracking branch 'upstream/main' into refresh-classic-guides
JFWooten4 Sep 30, 2024
4658706
🔁 Sync, move work items
JFWooten4 Sep 30, 2024
760d423
🔁 Clarify channel context links
JFWooten4 Oct 1, 2024
3d30353
🔁 Further advance text flow
JFWooten4 Oct 4, 2024
f6691fa
🔁 Start last code examples
JFWooten4 Oct 7, 2024
b273d71
🔁 Remove random channel generation
JFWooten4 Oct 7, 2024
954210d
🔁 Rest of authorization example
JFWooten4 Oct 7, 2024
ce8d61e
🔁 Remove adding channel custody
JFWooten4 Oct 7, 2024
7cb4b01
🔁 Clear up last tasks
JFWooten4 Oct 7, 2024
56c608a
🔁 Start state rotation example
JFWooten4 Oct 7, 2024
f83f4ad
🔁 Temporary merge, nonfinal publication
JFWooten4 Oct 11, 2024
1a91082
🔗 Minimum compilation link requirements
JFWooten4 Oct 15, 2024
11555a0
🖌️ Prettier compilation demo fixes
JFWooten4 Oct 15, 2024
d521205
🔁 Clarify base fee, miscellaneous 🤝🏻
JFWooten4 Oct 16, 2024
33f342e
Merge branch 'stellar:main' into refresh-classic-guides
JFWooten4 Oct 17, 2024
09fffca
👽 Translate java to JS
JFWooten4 Oct 19, 2024
03d2199
🔁 Last example java & go
JFWooten4 Oct 22, 2024
1c8851d
Merge branch 'stellar:main' into refresh-classic-guides
JFWooten4 Oct 22, 2024
cb9687a
🔁 Closing example explanation, diagrams
JFWooten4 Oct 22, 2024
06183cc
🔁 Put back `set timeouts`
JFWooten4 Oct 22, 2024
cbe3aca
🔁 Cleanup remaining frame items
JFWooten4 Oct 23, 2024
b45f8b2
🔁 Comment active-tense transitive verbs
JFWooten4 Oct 23, 2024
a73d966
🔁 Finalize the story flow
JFWooten4 Oct 23, 2024
a3c5d64
🔁 Polish off minor syntax
JFWooten4 Oct 23, 2024
eac05da
🔗 Remove depricated community link
JFWooten4 Oct 27, 2024
91b40fd
🔎 Clarify note on trustlines
JFWooten4 Oct 27, 2024
7109cb5
🫴🏽 Finish most cleaning up
JFWooten4 Nov 4, 2024
320de48
Merge branch 'main' into refresh-classic-guides
JFWooten4 Nov 4, 2024
0948700
🔗 Update simplified syntax reference
JFWooten4 Nov 4, 2024
19fbf45
🦞 Clean up final examples
JFWooten4 Nov 4, 2024
75a3ea0
💱 Remove items explicitly moved
JFWooten4 Nov 5, 2024
9bc3c63
💱 Remove duplicate placeholder drafts
JFWooten4 Nov 5, 2024
2a2638c
💱 Sidebar section intro description
JFWooten4 Nov 5, 2024
9d01898
💱 First rewrite run through
JFWooten4 Nov 6, 2024
32455bb
💱 Clean up scaffolding leftovers
JFWooten4 Nov 19, 2024
da7e8a3
💱 Translate starting AMM preamble
JFWooten4 Nov 19, 2024
a5c1874
💱 Capital pool > liquidity pool
JFWooten4 Nov 19, 2024
f8a304f
💱 Translate two AMM steps
JFWooten4 Nov 20, 2024
535b09b
📍 Follow up on this
JFWooten4 Nov 24, 2024
be7abb0
💱 Translate removing AMM liquidity
JFWooten4 Nov 24, 2024
eb18115
💱 Translate Java wrap-up example
JFWooten4 Nov 24, 2024
f871bab
💱 Last legacy, 535b09babed7a2afef37d58250f13ff01c2544fa fix
JFWooten4 Nov 24, 2024
b7f4a07
💱 Clean up go conclusion
JFWooten4 Nov 24, 2024
5492eb3
📌 Simplify starting frame, independence
JFWooten4 Nov 24, 2024
80784d8
💱 Seperate preliminary config, example
JFWooten4 Nov 25, 2024
f1a50e2
🖌️ Update prettier config note
JFWooten4 Nov 26, 2024
a4bdaeb
💱 Optimize, clarify global declarations
JFWooten4 Nov 26, 2024
ddd80c6
Merge branch 'main' into refresh-classic-guides
JFWooten4 Dec 6, 2024
81efcf5
💱 DEX code examples setup
JFWooten4 Dec 8, 2024
c7865bb
💱 Initial sell offer examples
JFWooten4 Dec 8, 2024
1f31ba4
💱 Example resolving limit OB
JFWooten4 Dec 8, 2024
34fb3b0
💱 Pricing point local calculation
JFWooten4 Dec 9, 2024
8417495
💱 Start prepping final flow
JFWooten4 Dec 10, 2024
d6d2335
💱 Continue on the intro
JFWooten4 Dec 11, 2024
2dc7db6
💱 Start of execution chat
JFWooten4 Dec 12, 2024
7f9bdc6
💱 Migrate some ancillary points
JFWooten4 Dec 12, 2024
909911a
💱 Introduce the OB outreach
JFWooten4 Dec 12, 2024
62b35af
💱 Translate pricing calculation examples
JFWooten4 Dec 13, 2024
24e3bb4
🖋 Some primative punctuation upgrades
JFWooten4 Dec 31, 2024
59d3686
💱 Remove elementary explanation diction
JFWooten4 Dec 31, 2024
873423e
Merge branch 'refresh-classic-guides' of https://github.com/JFWooten4…
JFWooten4 Dec 31, 2024
49477f8
🐛 Reinstate space line seperators
JFWooten4 Dec 31, 2024
2cbe9ab
Merge branch 'refresh-classic-guides' of https://github.com/JFWooten4…
JFWooten4 Dec 31, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
💱 Migrate some ancillary points
  • Loading branch information
JFWooten4 committed Dec 12, 2024
commit 7f9bdc6c7ac7d2a0a7cbd1c5891a864f5e763b94
2 changes: 1 addition & 1 deletion docs/learn/encyclopedia/sdex/README.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,6 @@ sidebar_position: 90

import DocCardList from "@theme/DocCardList";

Native network markets, liquidity, and exchange for all assets.
The Stellar network lets users trade in a free market using [priced orders](../../fundamentals/transactions/list-of-operations.mdx#manage-sell-offer), [path payments](../transactions-specialized/path-payments.mdx), and [automated market makers](./liquidity-on-stellar-sdex-liquidity-pools.mdx#liquidity-pools-amm). These features leverage both the SDEX orderbooks from Protocol 1 and liquidity pools from Protocol 18. To learn about how the native exchanges work together to enable seamless cross-asset transactions, see our [Path Payments Encyclopedia Entry](../transactions-specialized/path-payments.mdx).

<DocCardList />
Original file line number Diff line number Diff line change
Expand Up @@ -7,101 +7,29 @@ import YouTube from "@site/src/components/YouTube";

<YouTube ID="YFca255hXj8" />

The Stellar ledger stores assets' buy and sell offers in its mission to be the world's payment system. Any [account](../../fundamentals/stellar-data-structures/accounts.mdx) can create a new trade on the network's decentralized, distributed exchange. This allows users to trade peer-to-peer, converting assets without financial intermediaries.[^restr]

[^restr]: With the marginal exception of [regulated assets](../../../tokens/control-asset-access.mdx#controlling-access-to-an-asset-with-flags), as detailed in a [coming section](#TODO-restrs).

The simplest way to interact with the SDEX is to post a limit (or priced) order between two assets. You can create an offer between any pairs and in any order, adding volume to the collection of other offers (into an [order book](https://wikipedia.org/wiki/Order_book)). Enture markets exist within these conversion pools, all based on you specifying how much you will pay (or "sell," if using stablecoins) for an asset.

If ypou've ever traded on any type of investment platform, the terminology here will be fairly familiar. You can use the [Manage Buy Offer](../../../data/horizon/api-reference/resources/operations/object/buy-offer.mdx) operation to specifcy exactly how much you want to purchase at a specific price. The protocol calculates the cost of the trade in terms of `amount * price` and locks up the `selling` asset you offer in exchange as collateral, until the trade is (partially) executed or cancelled.

Alternatively, you can specify exactly how much of an asset you want to seel at a specific price using the [Manage Sell Offer](../../../data/horizon/api-reference/resources/operations/object/sell-offer.mdx) operation. Orders are executed on a price-time priority, meaning validators first match orders based on price. For orders placed at the same price, the order that was received earlier is given priority and is executed before the newer one.

## Free Market Data

The Stellar ledger stores both the balances held by user accounts and orders that user accounts make to trade assets. [Validators](https://stellarbeat.io) track exactly which price these orders will accept and the quantity avaliable to transact.

When you convert one currency to another in traditional financial markets, your trade happens because of limit orders. These orders specify how much someone will pay for a certain amount of any asset. Thus, when you need to convert your dollars to yen, e.g., their order to sell yen for dollars counteracts and "fulfills" your trade.

Financial markets thrive because of liquidity, a result of deep [order books](https://wikipedia.org/wiki/Order_book). It's so to speak, of In a global [payments system](https://stellar.org/blog/foundation-news/introducing-stellar), this liquidity can be thought of as the grease that makes transaction cogs turn. Stellar is one of the very few platforms that accounts for liquidity at scale with no centralized party.

:::note

This page specifically covers liquidity from the Stellar Decentralized Exchange and Automated Market Makers built into the Stellar protocol. It does not include information regarding smart contracts. Rather, it explains the network's native layer-1 core atomic-swap infrastructure.

:::

## Reading Prices

Exmaple narrative assuming after the orderbook resolution later on:

Now that we have seen the depth of the market (up to the [paging token limit](HREF_TXN_RES_QUERY_LIM)), we can find the midpoint price. This number comes from the average of the best (highest) bid and (lowest) offer. To affirm the fairness of this price, we might also check the recent trade prices.

<CodeExample>

```python
# This ex should propb be moved somehwere else todo

# orderbook = server.orderbook(selling=astroPeso, buying=astroDollar).call()
def getMidpointPrice(orderbook);
try:
highestBid = float(orderbook['bids'][0]['price'])
lowestAsk = float(orderbook['asks'][0]['price'])
except IndexError:
print("Missing exusting buy or sell offers.")
return midpointPrice = (highestBid + lowestAsk) / 2

def getAverageRecentPrice():
trades = server.trades().for_asset_pair(
selling = astroPeso,
buying = astroDollar
).call() # This should really use at least .limit(25) TODO
recentPrices = [
float(trade['price'])
for trade
in trades['_embedded']['records'][:9]
]
if recentPrices:
return sum(recentPrices) / len(recentPrices)
else:
print("No recent trades available.")

def sanityCheckOK(midpointPrice, averageRecentPrice):
if abs(midpointPrice - averageRecentPrice) / midpointPrice <= 0.05:
return 1
else:
print("Warning: Midpoint and average recent trade prices differ by more than 5%.")
return 0

offerPrice = round(midpointPrice, 7)
$ in new offer op, price = str(id)
```

```js
This page specifically covers liquidity from the Stellar Decentralized Exchange and Automated Market Makers built into the Stellar protocol. It does not include information regarding smart contracts. Rather, it explains the network's native layer-1 core atomic-swap infrastructure.[^arb]

```

```java

```
[^arb]: Unless you have a specific need to leave the DEX, it is best practice to keep liquidity concentraded on the SDEX's public [Horizon endpoints](../../../data/horizon/api-reference/resources/README.mdx). This lets all users obtain quality real-time market data and make informed trading decisions. Stellar provides transparent access to price information, generally obviating the need for external oracles arbitraging between other chains, smart contracts, or off-chain systems.

```go
:::

```
The Stellar ledger stores assets' buy and sell offers in its mission to be the world's payment system. Any [account](../../fundamentals/stellar-data-structures/accounts.mdx) can create a new trade on the network's decentralized, distributed exchange. This allows users to trade peer-to-peer, converting assets without financial intermediaries.[^restr]

</CodeExample>
[^restr]: With the marginal exception of [regulated assets](../../../tokens/control-asset-access.mdx#controlling-access-to-an-asset-with-flags), as detailed in a [coming section](#TODO-restrs).

This section covers querying the live order book and accessing price data. By interacting with the SDEX's public [Horizon endpoints](../../../data/horizon/api-reference/resources/README.mdx), you can obtain real-time market data and make informed trading decisions. While Stellar provides transparent access to price information, external oracles can also be used when integrating with other systems or when off-chain data is required.
The simplest way to interact with the SDEX is to post a limit (or priced) order between two assets. You can create an offer between any pairs and in any order, adding volume to the collection of other offers (into an [order book](https://wikipedia.org/wiki/Order_book)). Enture markets exist within these conversion pools, all based on you specifying how much you will pay (or "sell," if using stablecoins) for an asset.

The Stellar network takes a crowdsourced approach to liquidity. Namely, the SDEX gives all users equal access to a global decentralized order book for any pair of assets on he network. Since launching with the genesis of the Stellar network in 2014, the SDEX has processed over 4.2 billion trades worth upwards of \$25 billion.
If ypou've ever traded on any type of investment platform, the terminology here will be fairly familiar. You can use the [Manage Buy Offer](../../../data/horizon/api-reference/resources/operations/object/buy-offer.mdx) operation to specifcy exactly how much you want to purchase at a specific price. The protocol calculates the cost of the trade in terms of `amount * price` and locks up the `selling` asset you offer in exchange as collateral, until the trade is (partially) executed or cancelled.

Users can trade assets across the Stellar network using [priced orders](../../fundamentals/transactions/list-of-operations.mdx#manage-sell-offer), [path payments](../transactions-specialized/path-payments.mdx), and [native AMMs](#liquidity-pools-amm). These features leverage both the SDEX order books and liquidity pools, introduced in Protocol 18. To learn about how the SDEX and liquidity pools work together to execute transactions, see our [Path Payments Encyclopedia Entry](../transactions-specialized/path-payments.mdx).
Alternatively, you can specify exactly how much of an asset you want to seel at a specific price using the [Manage Sell Offer](../../../data/horizon/api-reference/resources/operations/object/sell-offer.mdx) operation. Orders are executed on a price-time priority, meaning validators first match offers based on price. For orders placed at the same price, the order that was received earlier is given priority and is executed before the newer one.

## Protocol
## Free Market Data

The Stellar protocol facilitates cross-border payments and asset transfers by leveraging the SDEX. The SDEX allows for the seamless exchange of assets, enabling token settlement across all the network's different currencies and general assets.
You can read user orders on the Stellar ledger just as you might query account balances. Let's walk though an example of accessing the data you might need to trade assets. Thius guide uses the SDF's testnet server, but you might want to query a mainnet [Horizon](../../../data/horizon/README.mdx) instance from a [validator](https://stellarbeat.io) to realistically quote actual priced orders.

Trading Setups Info
Boefore we pull up conversion liquidity through our queries, we'll need a couple of setup primatives. These get used throughout this guide to demonstrate how Stellar leverages its built-in exchange for cross-border payments.

<CodeExample>

Expand Down Expand Up @@ -237,6 +165,76 @@ func newTxBuilder(publicKey string) (*txnbuild.Transaction, error) {

</CodeExample>

This setup gives us a simple keypair, transaction constructor, and trading assets. You might want to swap the [server URL](../../../data/horizon/horizon-providers.mdx) or [asset codes](../../fundamentals/stellar-data-structures/assets.mdx#asset-code) to follow along with live financial markets.

### Reading Orderbook Prices

Exmaple narrative assuming after the orderbook resolution later on:

Now that we have seen the depth of the market (up to the [paging token limit](HREF_TXN_RES_QUERY_LIM)), we can find the midpoint price. This number comes from the average of the best (highest) bid and (lowest) offer. To affirm the fairness of this price, we might also check the recent trade prices.

trade happens because of limit orders. These orders specify how much someone will pay for a certain amount of any asset. Thus, when you need to convert your dollars to yen, e.g., their order to sell yen for dollars counteracts and "fulfills" your trade.

this liquidity can be thought of as the grease that makes transaction cogs turn. Stellar is one of the very few platforms that accounts for liquidity at scale with no centralized party.

<CodeExample title="Python: Create a Sell Offer">

```python
# This ex should propb be moved somehwere else todo

# orderbook = server.orderbook(selling=astroPeso, buying=astroDollar).call()
def getMidpointPrice(orderbook);
try:
highestBid = float(orderbook['bids'][0]['price'])
lowestAsk = float(orderbook['asks'][0]['price'])
except IndexError:
print("Missing exusting buy or sell offers.")
return midpointPrice = (highestBid + lowestAsk) / 2

def getAverageRecentPrice():
trades = server.trades().for_asset_pair(
selling = astroPeso,
buying = astroDollar
).call() # This should really use at least .limit(25) TODO
recentPrices = [
float(trade['price'])
for trade
in trades['_embedded']['records'][:9]
]
if recentPrices:
return sum(recentPrices) / len(recentPrices)
else:
print("No recent trades available.")

def sanityCheckOK(midpointPrice, averageRecentPrice):
if abs(midpointPrice - averageRecentPrice) / midpointPrice <= 0.05:
return 1
else:
print("Warning: Midpoint and average recent trade prices differ by more than 5%.")
return 0

offerPrice = round(midpointPrice, 7)
$ in new offer op, price = str(id)
```

```js

```

```java

```

```go

```

</CodeExample>

## Protocol

Trading Setups Info

now that we have that set up, let's buy some Dollars with our Pesos:

<CodeExample>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ title: Path Payments
sidebar_position: 60
---

In a path payment, the asset received differs from the asset sent. Rather than the operation transferring assets directly from one account to another, path payments cross through the SDEX and/or liquidity pools before arriving at the destination account. For the path payment to succeed, there has to be a DEX offer or liquidity pool exchange path in existence. It can sometimes take several hops of conversion to succeed.
In a path payment, the asset received differs from the asset sent. Rather than the operation transferring assets directly from one account to another, path payments cross through the SDEX and/or liquidity pools before arriving at the destination account. For the path payment to succeed, there has to be a DEX offer or liquidity pool exchange path in existence. Conversions can take up to six independent hops to succeed at the best avaliable price.

For example:
### Example

Account A sells XLM → [buy XLM / sell ETH → buy ETH / sell BTC → buy BTC / sell USDC] → Account B receives USDC
Account A sells XLM → [buy XLM / sell ETH → buy ETH / sell BTC → buy BTC / sell USDC] → Account B receives USDC {/* Image required here for #944 */}

It is possible for path payments to fail if there are no viable exchange paths.

Expand Down
2 changes: 0 additions & 2 deletions src/components/CodeExample.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,7 @@ export const CodeExample = ({ children }) => (
{React.Children.map(children, (child, index) => {
const codeProps = child.props.children.props;
const { className = '' } = codeProps;

const [, language] = className.split('-');

return (
<TabItem
key={language || index}
Expand Down
Loading