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

[Soroban Merge] Create a "Learn" section of the docs #354

Merged
merged 67 commits into from
Mar 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
67 commits
Select commit Hold shift + click to select a range
f555c8b
initial commit
kalepail Jul 15, 2022
deecd4e
example including an image
kalepail Jul 15, 2022
193d77d
add doc on assets-and-authorization, with auth part filled in
graydon Jul 22, 2022
118c3e9
update wordmark
kalepail Jul 29, 2022
b8ff8d0
Add a homepage (#197)
kalepail Oct 11, 2022
e3b03f1
added a meta image
kalepail Oct 12, 2022
414fe68
Soroban landing (#396)
alejomendoza Apr 26, 2023
d9f1817
Evm to Soroban (#409)
Julian-dev28 May 30, 2023
c724746
Add dapps challenge (#487)
Julian-dev28 Jul 26, 2023
0780a36
seo-editorial-docs (#547)
briwylde08 Aug 16, 2023
226c0fd
SDC UI upgrades (#542)
Julian-dev28 Aug 16, 2023
742336d
Add lp dapp challenge (#543)
Julian-dev28 Sep 20, 2023
b04fc23
Sdc mental models: payment dapp upgrades (#641)
nmadadair Nov 14, 2023
e1260d5
undo some changes from the docs scavenger hunt (#656)
ElliotFriend Nov 27, 2023
5c9bcd5
clearer Soroban favicon (#662)
briwylde08 Nov 30, 2023
c08bd1f
Add oracle dapp challenge (#664)
Julian-dev28 Dec 1, 2023
4836581
add some items for the rollout (#684)
kalepail Dec 19, 2023
0a06a0c
Pre mainnet restructure (#644)
ElliotFriend Jan 9, 2024
e1629f8
Pre mainnet restructure (#644)
ElliotFriend Jan 9, 2024
05e60b0
docs: make the transaction lifecycle page a draft (#701)
ElliotFriend Jan 9, 2024
8a6d23c
Fix description of enums supported by contract types (#703)
leighmcculloch Jan 17, 2024
b58cf4e
Update resource limits and make a new reference page for them (#736)
ElliotFriend Feb 22, 2024
56626a5
[Stellar Merge] Tools Section (#739)
ElliotFriend Feb 23, 2024
662688d
[Stellar Merge] Tools Section (#739)
ElliotFriend Feb 23, 2024
1968178
Update fee page, close #710 (#745)
janewang Feb 23, 2024
77157a8
Update fee page, close #710 (#745)
janewang Feb 23, 2024
0a7a584
[Stellar Merge] Redirects for Soroban RPC pages (#757)
ElliotFriend Mar 5, 2024
2d2df8e
move some directories into a "learn" directory
ElliotFriend Mar 5, 2024
37668f4
more README.mdx files
ElliotFriend Mar 5, 2024
d691131
update sidebars
ElliotFriend Mar 5, 2024
5d33dc3
add a "Learn" item to the top navbar
ElliotFriend Mar 5, 2024
45d1700
fix a boat-load of broken links
ElliotFriend Mar 5, 2024
1337dfb
add whitespace back to list of operations
ElliotFriend Mar 6, 2024
fefb1c9
add more linebreak spaces
ElliotFriend Mar 6, 2024
9019695
initial nginx redirects
ElliotFriend Mar 6, 2024
aff593e
Add Java SDK Example. (#765)
overcat Mar 6, 2024
b8ae1c8
use a README file in the stellar data structures section
ElliotFriend Mar 6, 2024
46d2efe
Merge remote-tracking branch 'merge-subset/main' into soroban-merge/l…
ElliotFriend Mar 6, 2024
5c9125b
pull in changes for soroban-internals section
ElliotFriend Mar 6, 2024
d972b7d
use a README file in soroban-internals section
ElliotFriend Mar 6, 2024
0121e60
Merge remote-tracking branch 'merge-subset/main' into soroban-merge/l…
ElliotFriend Mar 6, 2024
32b3cc6
move the soroban env diagram file location
ElliotFriend Mar 6, 2024
12a28c2
Merge remote-tracking branch 'merge-subset/main' into soroban-merge/l…
ElliotFriend Mar 6, 2024
31284db
fix broken links in soroban internals pages
ElliotFriend Mar 6, 2024
4f85e41
run soroban internals pages through linter
ElliotFriend Mar 6, 2024
693f8d8
use a README file in soroban types category
ElliotFriend Mar 6, 2024
ccf62f6
use README for contract interactions section
ElliotFriend Mar 6, 2024
8e555cd
Merge remote-tracking branch 'merge-subset/main' into soroban-merge/l…
ElliotFriend Mar 6, 2024
fe4345c
move migrate docs into learn directory
ElliotFriend Mar 6, 2024
d5b4388
use a README document for the migration section
ElliotFriend Mar 6, 2024
3d5c75b
fixup some broken links in the migration section
ElliotFriend Mar 6, 2024
1b223cf
Merge branch 'main' into soroban-merge/learn
ElliotFriend Mar 6, 2024
c27d3f3
fix a couple more broken links
ElliotFriend Mar 6, 2024
4242ad8
quick placeholders for sq and fca00c, we'll want better copy probably
ElliotFriend Mar 7, 2024
20a4916
try to capture any anchor URLs used in the glossary
ElliotFriend Mar 12, 2024
8c565a7
update existing redirects for new learn section
ElliotFriend Mar 12, 2024
2cfeaac
fix muxed accounts redirect
ElliotFriend Mar 12, 2024
7e96a09
better README files in chain migration categories
ElliotFriend Mar 12, 2024
506a9ff
Merge branch 'main' into soroban-merge/learn
ElliotFriend Mar 13, 2024
c0d0887
rename "soroban-internals" to "smart contract internals"
ElliotFriend Mar 13, 2024
b37888c
fix broken links
ElliotFriend Mar 13, 2024
71e9be5
fix canonical links in smart-contract-internals directory
ElliotFriend Mar 13, 2024
4a31b42
change title of Smart Contracts Internals category page
ElliotFriend Mar 13, 2024
980775b
couple tweaks
briwylde08 Mar 13, 2024
b7d2bca
capitalization
briwylde08 Mar 13, 2024
cbe1d87
fix link
briwylde08 Mar 13, 2024
60d8bee
use `.mdx` links to markdown files in fees encyclopedia page
ElliotFriend Mar 13, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Welcome to the official home repository for [Documentation][docs] and
[API Reference][api] for the [Stellar Network][stellar].

# Table of Contents <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->

- [Contributing](#contributing)
- [Quick Start](#quick-start)
Expand All @@ -14,7 +14,7 @@ Welcome to the official home repository for [Documentation][docs] and
- [Alert](#alert)
- [Code Example](#code-example)

# Contributing
## Contributing

Contributions are more than welcome! Thank you! 🎉

Expand All @@ -29,8 +29,8 @@ helpful and meaningful way. Markdown is super easy to learn, and will come quite
naturally after only a bit of practice. You can always help fix typos, spelling,
and broken links, too.

# Quick Start
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)][codespaces]
## Quick Start
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)][codespaces]
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][gitpod]

To begin development on the documentation, you will first need [yarn][yarn]
Expand All @@ -55,7 +55,7 @@ npm run check:mdx # this will search for problems in the MDX files
npm run format:mdx # this will fix any problems that were found
```

# Repository Structure
## Repository Structure

- `/docs/` Contains all the documentation content. If you're contributing to the
actual documentation, rather than site functionality, this is likely where you
Expand Down Expand Up @@ -88,9 +88,9 @@ npm run format:mdx # this will fix any problems that were found
case-by-case basis, and it may be determined that a redirect isn't the right
approach in some instances.)

# Using Markdown
## Using Markdown

## Markdown Basics
### Markdown Basics

If you're unfamiliar with Markdown, there are **loads** of good tutorials and
cheat sheets out there. Check out some of these resources to get a handle on the
Expand All @@ -100,24 +100,24 @@ basics:
- [Interactive markdown tutorial][tutorial]
- [The markdown guide][guide]

## Custom Markdown
### Custom Markdown

Our repository uses some custom React components that can be used inside the
`MDX` documents. Use them as follows:

**Make sure that there is an empty line within the wrapper.** For example,

```
```text
<Alert>
<!-- EMPTY LINE AFTER THE COMPONENT'S OPENING TAG IS REQUIRED -->

Note: the testnet is reset every three months, so when building on it, make sure you have a plan to recreate necessary accounts and other data. For more info, check out the [best practices for using the testnet](../../fundamentals-and-concepts/testnet-and-pubnet).
Note: the testnet is reset every three months, so when building on it, make sure you have a plan to recreate necessary accounts and other data. For more info, check out the [best practices for using the testnet](../../learn/fundamentals/networks.mdx).

<!-- EMPTY LINE BEFORE THE COMPONENT'S CLOSING TAG IS REQUIRED -->
</Alert>
```

### Alert
#### Alert

![Testnet reset alert](./readme-imgs/alert.png)

Expand All @@ -134,7 +134,7 @@ Note: the testnet is reset every three months, so when building on it, make sure
</Alert>
```

### Code Example
#### Code Example

![Create account code example](./readme-imgs/code-example.png)

Expand Down
8 changes: 4 additions & 4 deletions docs/building-apps/application-design-considerations.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ There are four custody options to consider:

- Non-custodial service - the user of the application stores their own secret key
- Custodial service - the service provider (application) stores the users’ secret keys
- Mixture of both - with the use of [multisig](../encyclopedia/signatures-multisig.mdx), this option is useful for maintaining non-custodial status while still allowing for account recovery
- Mixture of both - with the use of [multisig](../learn/encyclopedia/signatures-multisig.mdx), this option is useful for maintaining non-custodial status while still allowing for account recovery
- Third-party key management services - integrate a third-party custodial service into your application that can store your users’ secret keys

### Non-custodial service
Expand All @@ -24,13 +24,13 @@ Typically, non-custodial applications create or import a pre-existing Stellar ac

With a custodial service, the service provider (an application such as a centralized exchange) stores the users’ secret keys and delegates usage rights to the user.

Many custodial services choose to use a single pooled Stellar account (called shared, omnibus, or [pooled accounts](https://developers.stellar.org/docs/encyclopedia/pooled-accounts-muxed-accounts-memos)) to handle transactions on behalf of their users instead of creating a new Stellar account for each user. To distinguish between individual users in a pooled account, we encourage the implementation of [muxed accounts](https://developers.stellar.org/docs/encyclopedia/pooled-accounts-muxed-accounts-memos#muxed-accounts).
Many custodial services choose to use a single pooled Stellar account (called shared, omnibus, or [pooled accounts](../learn/encyclopedia/pooled-accounts-muxed-accounts-memos.mdx)) to handle transactions on behalf of their users instead of creating a new Stellar account for each user. To distinguish between individual users in a pooled account, we encourage the implementation of [muxed accounts](../learn/encyclopedia/pooled-accounts-muxed-accounts-memos.mdx#muxed-accounts).

Learn how to set up an application as a custodial service in this [tutorial].

### A mixture of non-custodial and custodial

Building an application with [multi-signature](../encyclopedia/signatures-multisig.mdx) capabilities allows you to have a non-custodial service with account recovery. If the user loses their secret key, they can still sign transactions with other authorized signatures, granted the signature threshold is high enough.
Building an application with [multi-signature](../learn/encyclopedia/signatures-multisig.mdx) capabilities allows you to have a non-custodial service with account recovery. If the user loses their secret key, they can still sign transactions with other authorized signatures, granted the signature threshold is high enough.

### Third-party key management services​

Expand Down Expand Up @@ -95,7 +95,7 @@ The flow with Claimable Balances looks like this:

### Option 2: the wallet creates and funds the Stellar account upon user sign-up​

For this option, the wallet creates and funds the Stellar account upon every new user sign-up with the minimum requirement of 1XLM, plus the .5XLM reserve for establishing the first trustline, plus a bit more to cover transaction fees. For more information on minimum balances, check out the [Lumens section](https://developers.stellar.org/docs/fundamentals-and-concepts/lumens#minimum-balance).
For this option, the wallet creates and funds the Stellar account upon every new user sign-up with the minimum requirement of 1XLM, plus the .5XLM reserve for establishing the first trustline, plus a bit more to cover transaction fees. For more information on minimum balances, check out the [Lumens section](../learn/fundamentals/lumens.mdx#minimum-balance).

The flow looks like this:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -188,8 +188,8 @@ Source: https://github.com/stellar/basic-payment-app/blob/main/src/lib/stellar/h

Our `walletStore` is used in a ton of places in our application, especially in the confirmation modal when asking a user to input their pincode. Read on to see how we've done that.

[accounts section]: ../../fundamentals-and-concepts/stellar-data-structures/accounts
[accounts section]: ../../learn/fundamentals/stellar-data-structures/accounts.mdx
[non-custodial application]: ../application-design-considerations#non-custodial-service
[`js-stellar-wallets` sdk]: https://github.com/stellar/js-stellar-wallets
[sponsored reserves]: ../../encyclopedia/sponsored-reserves
[sponsored reserves]: ../../learn/encyclopedia/sponsored-reserves.mdx
[contacts list]: ./contacts-list
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ In this example, we’ll use an anchor on Stellar’s Testnet to simulate a bank

:::info

SEPs define community-decided standards for interoperability on Stellar. Read more in our [SEPs section](../../../fundamentals-and-concepts/stellar-ecosystem-proposals).
SEPs define community-decided standards for interoperability on Stellar. Read more in our [SEPs section](../../../learn/fundamentals/stellar-ecosystem-proposals.mdx).

:::

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ title: Manage Trust
sidebar_position: 30
---

For an account to hold and trade assets other than XLM, it must establish a [trustline](../../fundamentals-and-concepts/stellar-data-structures/accounts#trustlines) with the issuing account of that particular asset. Each trustline increases the account’s [base reserve](../../fundamentals-and-concepts/stellar-data-structures/accounts#base-reserves-and-subentries) by 0.5 XLM, which means the account will have to hold more XLM in its minimum balance.
For an account to hold and trade assets other than XLM, it must establish a [trustline](../../learn/fundamentals/stellar-data-structures/accounts.mdx#trustlines) with the issuing account of that particular asset. Each trustline increases the account’s [base reserve](../../learn/fundamentals/stellar-data-structures/accounts.mdx#base-reserves-and-subentries) by 0.5 XLM, which means the account will have to hold more XLM in its minimum balance.

## User experience

First, we’ll have the user create a trustline for an asset by navigating to the Assets page, selecting an asset, and clicking the “Add Asset” button.

:::info

An asset is displayed as an asset code and issuer address. Learn more in our [Assets section](https://developers.stellar.org/docs/fundamentals-and-concepts/stellar-data-structures/assets).
An asset is displayed as an asset code and issuer address. Learn more in our [Assets section](../../learn/fundamentals/stellar-data-structures/assets.mdx).

:::

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Path Payment
sidebar_position: 50
---

A path payment is where the asset sent can be different from the asset received. There are two possible path payment operations: 1) `path_payment_strict_send`, which allows the user to specify the amount of the asset to send, and 2) `path_payment_strict_receive`, which allows the user to specify the amount of the asset received. Read more in the [Path Payments Encyclopedia Entry](../../encyclopedia/path-payments).
A path payment is where the asset sent can be different from the asset received. There are two possible path payment operations: 1) `path_payment_strict_send`, which allows the user to specify the amount of the asset to send, and 2) `path_payment_strict_receive`, which allows the user to specify the amount of the asset received. Read more in the [Path Payments Encyclopedia Entry](../../learn/encyclopedia/path-payments.mdx).

## User experience

Expand All @@ -17,7 +17,7 @@ The user will then preview the transaction, input their pincode, and select the

### The `/dashboard/send` page

Most of this page has been discussed in the [Payment section](./payment#the-dashboardsend-page). Below, we're highlighting the unique pieces that are added to BasicPay to allow for the path payment feature.
Most of this page has been discussed in the [Payment section](./payment.mdx#the-dashboardsend-page). Below, we're highlighting the unique pieces that are added to BasicPay to allow for the path payment feature.

```html title="/src/routes/dashboard/send/+page.svelte"
<script>
Expand Down
4 changes: 2 additions & 2 deletions docs/building-apps/example-application-tutorial/payment.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ In our BasicPay application, the user will navigate to the Payments page where c

The user clicks the "Confirm Transaction" button. If the destination account exists and is properly funded with XLM, this will trigger a Transaction Preview where they can view the transaction details.

All Stellar transactions require a small fee to make it to the ledger. Read more in our [Fees, Surge Pricing, and Fee Strategies section](../../encyclopedia/fees-surge-pricing-fee-strategies).
All Stellar transactions require a small fee to make it to the ledger. Read more in our [Fees, Surge Pricing, and Fee Strategies section](../../learn/encyclopedia/fees-surge-pricing-fee-strategies.mdx).

In BasicPay, we’ve set it up so that the user always pays a static fee of 100,000 [stroops](../../fundamentals-and-concepts/stellar-data-structures/assets#amount-precision) (one stroop equals 0.0000001 XLM) per operation. Alternatively, you can add a feature to your application that allows the user to set their own fee.
In BasicPay, we’ve set it up so that the user always pays a static fee of 100,000 [stroops](../../learn/fundamentals/stellar-data-structures/assets.mdx#amount-precision) (one stroop equals 0.0000001 XLM) per operation. Alternatively, you can add a feature to your application that allows the user to set their own fee.

![payment](/assets/fees.png)

Expand Down
2 changes: 1 addition & 1 deletion docs/building-apps/wallet/sep30.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@ var recoverableWallet = await recovery.createRecoverableWallet(
With the given parameters, this function will create a transaction that will:

1. Set `deviceKp` as the primary account key. Please note that the master key belonging to `accountKp` will be locked. `deviceKp` should be used as a primary signer instead.
2. Set all operation thresholds to 10. You can read more about threshold in the [documentation](https://developers.stellar.org/docs/encyclopedia/signatures-multisig#thresholds)
2. Set all operation thresholds to 10. You can read more about threshold in the [documentation](../../learn/encyclopedia/signatures-multisig.mdx#thresholds)
3. Use identities that were defined earlier on both servers. (That means, both server will accept SEP-10 authentication via `recoveryKp` as an auth method)
4. Set device key weight to 10, and recovery server weight to 5. Given these account thresholds, both servers must be used to recover the account, as transaction signed by one will only have weight of 5, which is not sufficient to change account key.

Expand Down
2 changes: 1 addition & 1 deletion docs/building-apps/wallet/stellar.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -403,7 +403,7 @@ bool success = await stellar.submitTransaction(modifyAccountTransaction);

#### Sponsor Operations

Some operations, that modify account reserves can be [sponsored](https://developers.stellar.org/docs/encyclopedia/sponsored-reserves#sponsored-reserves-operations). For sponsored operations, the sponsoring account will be paying for the reserves instead of the account that being sponsored. This allows you to do some operations, even if account doesn't have enough funds to perform such operations. To sponsor a transaction, <LanguageSpecific kt={<span>simply start a <code>sponsoring</code> block:</span>} ts={<span>simply create a building function (describing which operations are to be sponsored) and pass it to the <code>sponsoring</code> method:</span>}/>
Some operations, that modify account reserves can be [sponsored](../../learn/encyclopedia/sponsored-reserves.mdx#sponsored-reserves-operations). For sponsored operations, the sponsoring account will be paying for the reserves instead of the account that being sponsored. This allows you to do some operations, even if account doesn't have enough funds to perform such operations. To sponsor a transaction, <LanguageSpecific kt={<span>simply start a <code>sponsoring</code> block:</span>} ts={<span>simply create a building function (describing which operations are to be sponsored) and pass it to the <code>sponsoring</code> method:</span>}/>

<CodeExample>

Expand Down
7 changes: 0 additions & 7 deletions docs/encyclopedia/_category_.json

This file was deleted.

4 changes: 0 additions & 4 deletions docs/fundamentals-and-concepts/_category_.json

This file was deleted.

This file was deleted.

Loading
Loading