From 3949c1f1bdd5c5dd423880bb0fe66d2738752a86 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:31:47 -0600 Subject: [PATCH 01/95] docs: rename "fundamentals and concepts" to "soroban internals" --- .../_category_.json | 0 .../authorization.mdx | 0 .../built-in-types.mdx | 0 .../contract-lifecycle.mdx | 0 .../custom-types.mdx | 0 .../debugging.mdx | 0 .../environment-concepts.mdx | 0 .../{fundamentals-and-concepts => soroban-internals}/errors.mdx | 0 .../{fundamentals-and-concepts => soroban-internals}/events.mdx | 0 docs/{fundamentals-and-concepts => soroban-internals}/faq.mdx | 0 .../fees-and-metering.mdx | 0 .../fully-typed-contracts.mdx | 0 .../high-level-overview.mdx | 0 .../interacting-with-contracts.mdx | 0 .../invoking-contracts-with-transactions.mdx | 0 .../migrating-from-evm/_category_.json | 0 .../migrating-from-evm/introduction-to-solidity-and-rust.mdx | 0 .../migrating-from-evm/smart-contract-deployment.mdx | 0 .../migrating-from-evm/solidity-and-rust-advanced-concepts.mdx | 0 .../migrating-from-evm/solidity-and-rust-basics.mdx | 0 .../persisting-data.mdx | 0 .../rust-dialect.mdx | 0 .../state-expiration.mdx | 0 nginx/includes/redirects.conf | 2 ++ 24 files changed, 2 insertions(+) rename docs/{fundamentals-and-concepts => soroban-internals}/_category_.json (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/authorization.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/built-in-types.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/contract-lifecycle.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/custom-types.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/debugging.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/environment-concepts.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/errors.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/events.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/faq.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/fees-and-metering.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/fully-typed-contracts.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/high-level-overview.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/interacting-with-contracts.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/invoking-contracts-with-transactions.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/migrating-from-evm/_category_.json (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/migrating-from-evm/introduction-to-solidity-and-rust.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/migrating-from-evm/smart-contract-deployment.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/migrating-from-evm/solidity-and-rust-basics.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/persisting-data.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/rust-dialect.mdx (100%) rename docs/{fundamentals-and-concepts => soroban-internals}/state-expiration.mdx (100%) diff --git a/docs/fundamentals-and-concepts/_category_.json b/docs/soroban-internals/_category_.json similarity index 100% rename from docs/fundamentals-and-concepts/_category_.json rename to docs/soroban-internals/_category_.json diff --git a/docs/fundamentals-and-concepts/authorization.mdx b/docs/soroban-internals/authorization.mdx similarity index 100% rename from docs/fundamentals-and-concepts/authorization.mdx rename to docs/soroban-internals/authorization.mdx diff --git a/docs/fundamentals-and-concepts/built-in-types.mdx b/docs/soroban-internals/built-in-types.mdx similarity index 100% rename from docs/fundamentals-and-concepts/built-in-types.mdx rename to docs/soroban-internals/built-in-types.mdx diff --git a/docs/fundamentals-and-concepts/contract-lifecycle.mdx b/docs/soroban-internals/contract-lifecycle.mdx similarity index 100% rename from docs/fundamentals-and-concepts/contract-lifecycle.mdx rename to docs/soroban-internals/contract-lifecycle.mdx diff --git a/docs/fundamentals-and-concepts/custom-types.mdx b/docs/soroban-internals/custom-types.mdx similarity index 100% rename from docs/fundamentals-and-concepts/custom-types.mdx rename to docs/soroban-internals/custom-types.mdx diff --git a/docs/fundamentals-and-concepts/debugging.mdx b/docs/soroban-internals/debugging.mdx similarity index 100% rename from docs/fundamentals-and-concepts/debugging.mdx rename to docs/soroban-internals/debugging.mdx diff --git a/docs/fundamentals-and-concepts/environment-concepts.mdx b/docs/soroban-internals/environment-concepts.mdx similarity index 100% rename from docs/fundamentals-and-concepts/environment-concepts.mdx rename to docs/soroban-internals/environment-concepts.mdx diff --git a/docs/fundamentals-and-concepts/errors.mdx b/docs/soroban-internals/errors.mdx similarity index 100% rename from docs/fundamentals-and-concepts/errors.mdx rename to docs/soroban-internals/errors.mdx diff --git a/docs/fundamentals-and-concepts/events.mdx b/docs/soroban-internals/events.mdx similarity index 100% rename from docs/fundamentals-and-concepts/events.mdx rename to docs/soroban-internals/events.mdx diff --git a/docs/fundamentals-and-concepts/faq.mdx b/docs/soroban-internals/faq.mdx similarity index 100% rename from docs/fundamentals-and-concepts/faq.mdx rename to docs/soroban-internals/faq.mdx diff --git a/docs/fundamentals-and-concepts/fees-and-metering.mdx b/docs/soroban-internals/fees-and-metering.mdx similarity index 100% rename from docs/fundamentals-and-concepts/fees-and-metering.mdx rename to docs/soroban-internals/fees-and-metering.mdx diff --git a/docs/fundamentals-and-concepts/fully-typed-contracts.mdx b/docs/soroban-internals/fully-typed-contracts.mdx similarity index 100% rename from docs/fundamentals-and-concepts/fully-typed-contracts.mdx rename to docs/soroban-internals/fully-typed-contracts.mdx diff --git a/docs/fundamentals-and-concepts/high-level-overview.mdx b/docs/soroban-internals/high-level-overview.mdx similarity index 100% rename from docs/fundamentals-and-concepts/high-level-overview.mdx rename to docs/soroban-internals/high-level-overview.mdx diff --git a/docs/fundamentals-and-concepts/interacting-with-contracts.mdx b/docs/soroban-internals/interacting-with-contracts.mdx similarity index 100% rename from docs/fundamentals-and-concepts/interacting-with-contracts.mdx rename to docs/soroban-internals/interacting-with-contracts.mdx diff --git a/docs/fundamentals-and-concepts/invoking-contracts-with-transactions.mdx b/docs/soroban-internals/invoking-contracts-with-transactions.mdx similarity index 100% rename from docs/fundamentals-and-concepts/invoking-contracts-with-transactions.mdx rename to docs/soroban-internals/invoking-contracts-with-transactions.mdx diff --git a/docs/fundamentals-and-concepts/migrating-from-evm/_category_.json b/docs/soroban-internals/migrating-from-evm/_category_.json similarity index 100% rename from docs/fundamentals-and-concepts/migrating-from-evm/_category_.json rename to docs/soroban-internals/migrating-from-evm/_category_.json diff --git a/docs/fundamentals-and-concepts/migrating-from-evm/introduction-to-solidity-and-rust.mdx b/docs/soroban-internals/migrating-from-evm/introduction-to-solidity-and-rust.mdx similarity index 100% rename from docs/fundamentals-and-concepts/migrating-from-evm/introduction-to-solidity-and-rust.mdx rename to docs/soroban-internals/migrating-from-evm/introduction-to-solidity-and-rust.mdx diff --git a/docs/fundamentals-and-concepts/migrating-from-evm/smart-contract-deployment.mdx b/docs/soroban-internals/migrating-from-evm/smart-contract-deployment.mdx similarity index 100% rename from docs/fundamentals-and-concepts/migrating-from-evm/smart-contract-deployment.mdx rename to docs/soroban-internals/migrating-from-evm/smart-contract-deployment.mdx diff --git a/docs/fundamentals-and-concepts/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx b/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx similarity index 100% rename from docs/fundamentals-and-concepts/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx rename to docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx diff --git a/docs/fundamentals-and-concepts/migrating-from-evm/solidity-and-rust-basics.mdx b/docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx similarity index 100% rename from docs/fundamentals-and-concepts/migrating-from-evm/solidity-and-rust-basics.mdx rename to docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx diff --git a/docs/fundamentals-and-concepts/persisting-data.mdx b/docs/soroban-internals/persisting-data.mdx similarity index 100% rename from docs/fundamentals-and-concepts/persisting-data.mdx rename to docs/soroban-internals/persisting-data.mdx diff --git a/docs/fundamentals-and-concepts/rust-dialect.mdx b/docs/soroban-internals/rust-dialect.mdx similarity index 100% rename from docs/fundamentals-and-concepts/rust-dialect.mdx rename to docs/soroban-internals/rust-dialect.mdx diff --git a/docs/fundamentals-and-concepts/state-expiration.mdx b/docs/soroban-internals/state-expiration.mdx similarity index 100% rename from docs/fundamentals-and-concepts/state-expiration.mdx rename to docs/soroban-internals/state-expiration.mdx diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 4a49926e..3662cc2b 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -20,3 +20,5 @@ rewrite "^/docs/SDKs/rust$" "/docs/reference/sdks/rust" permanent; rewrite "^/docs/getting-started/connect-freighter-wallet$" "/docs/reference/freighter" permanent; rewrite "^/docs/common-interfaces/token$" "/docs/reference/interfaces/token-interface" permanent; rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permanent; +# BEGIN re-structure redirects +# "fundamentals-and-concepts" is now "soroban-internals" From d9e76f50ffa56728bc5c7ff87b5e1e470693cf15 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:34:17 -0600 Subject: [PATCH 02/95] docs: remove old "under the hood" section --- docs/under-the-hood/_category_.json | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/under-the-hood/_category_.json diff --git a/docs/under-the-hood/_category_.json b/docs/under-the-hood/_category_.json deleted file mode 100644 index 320a4f38..00000000 --- a/docs/under-the-hood/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 60, - "label": "Under the Hood", - "link": { - "type": "generated-index" - } -} From 7bf4bb5934998a86bb09eb79a5072831dc96858f Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:38:19 -0600 Subject: [PATCH 03/95] docs: add tags to the various tutorials --- docs/advanced-tutorials/atomic-multi-swap.mdx | 3 +++ docs/advanced-tutorials/atomic-swap.mdx | 3 +++ docs/advanced-tutorials/custom-account.mdx | 3 +++ docs/advanced-tutorials/fuzzing.mdx | 3 +++ docs/advanced-tutorials/liquidity-pool.mdx | 3 +++ docs/advanced-tutorials/single-offer-sale.mdx | 3 +++ docs/advanced-tutorials/stellar-asset-contract.mdx | 3 +++ docs/advanced-tutorials/timelock.mdx | 3 +++ docs/advanced-tutorials/tokens.mdx | 3 +++ docs/basic-tutorials/alloc.mdx | 3 +++ docs/basic-tutorials/auth.mdx | 3 +++ docs/basic-tutorials/cross-contract-call.mdx | 3 +++ docs/basic-tutorials/custom-types.mdx | 3 +++ docs/basic-tutorials/deployer.mdx | 3 +++ docs/basic-tutorials/errors.mdx | 3 +++ docs/basic-tutorials/events.mdx | 3 +++ docs/basic-tutorials/logging.mdx | 3 +++ docs/basic-tutorials/upgrading-contracts.mdx | 3 +++ docs/basic-tutorials/wasm-metadata.mdx | 3 +++ 19 files changed, 57 insertions(+) diff --git a/docs/advanced-tutorials/atomic-multi-swap.mdx b/docs/advanced-tutorials/atomic-multi-swap.mdx index a2f1aa4c..2db61dee 100644 --- a/docs/advanced-tutorials/atomic-multi-swap.mdx +++ b/docs/advanced-tutorials/atomic-multi-swap.mdx @@ -2,6 +2,9 @@ sidebar_position: 4 title: Batched Atomic Swaps description: Swap tokens between two groups. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/atomic-swap.mdx b/docs/advanced-tutorials/atomic-swap.mdx index ad65594f..b4c9f670 100644 --- a/docs/advanced-tutorials/atomic-swap.mdx +++ b/docs/advanced-tutorials/atomic-swap.mdx @@ -2,6 +2,9 @@ sidebar_position: 3 title: Atomic Swap description: Swap tokens atomically between two parties. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/custom-account.mdx b/docs/advanced-tutorials/custom-account.mdx index 8e3c21ae..07856313 100644 --- a/docs/advanced-tutorials/custom-account.mdx +++ b/docs/advanced-tutorials/custom-account.mdx @@ -2,6 +2,9 @@ sidebar_position: 8 title: Custom Account description: Implement a contract that supports multisig and custom auth policies. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/fuzzing.mdx b/docs/advanced-tutorials/fuzzing.mdx index 026ab8db..2c87b365 100644 --- a/docs/advanced-tutorials/fuzzing.mdx +++ b/docs/advanced-tutorials/fuzzing.mdx @@ -2,6 +2,9 @@ sidebar_position: 9 title: Fuzz Testing description: Fuzz test contracts with cargo-fuzz. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/liquidity-pool.mdx b/docs/advanced-tutorials/liquidity-pool.mdx index 0a80e3ed..ff34353f 100644 --- a/docs/advanced-tutorials/liquidity-pool.mdx +++ b/docs/advanced-tutorials/liquidity-pool.mdx @@ -2,6 +2,9 @@ sidebar_position: 7 title: Liquidity Pool description: Write a constant-product liquidity pool contract. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/single-offer-sale.mdx b/docs/advanced-tutorials/single-offer-sale.mdx index 0eb47a17..1d2eb393 100644 --- a/docs/advanced-tutorials/single-offer-sale.mdx +++ b/docs/advanced-tutorials/single-offer-sale.mdx @@ -2,6 +2,9 @@ sidebar_position: 6 title: Single Offer Sale description: Allow a seller to sell one token for another token to multiple buyers. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/stellar-asset-contract.mdx b/docs/advanced-tutorials/stellar-asset-contract.mdx index ae898fc0..9a224905 100644 --- a/docs/advanced-tutorials/stellar-asset-contract.mdx +++ b/docs/advanced-tutorials/stellar-asset-contract.mdx @@ -2,6 +2,9 @@ sidebar_position: 2 title: Stellar Asset Contract description: Use Stellar assets on Soroban. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/timelock.mdx b/docs/advanced-tutorials/timelock.mdx index baa4e97c..d05f870a 100644 --- a/docs/advanced-tutorials/timelock.mdx +++ b/docs/advanced-tutorials/timelock.mdx @@ -2,6 +2,9 @@ sidebar_position: 5 title: Timelock description: Write a timelock implementing a claimable balance. +tags: + - tutorial + - advanced --- diff --git a/docs/advanced-tutorials/tokens.mdx b/docs/advanced-tutorials/tokens.mdx index 9b1de054..cff5d1c3 100644 --- a/docs/advanced-tutorials/tokens.mdx +++ b/docs/advanced-tutorials/tokens.mdx @@ -2,6 +2,9 @@ sidebar_position: 1 title: Tokens description: Construct a smart contract token. +tags: + - tutorial + - advanced --- diff --git a/docs/basic-tutorials/alloc.mdx b/docs/basic-tutorials/alloc.mdx index 5ad661a4..2d90fdf7 100644 --- a/docs/basic-tutorials/alloc.mdx +++ b/docs/basic-tutorials/alloc.mdx @@ -2,6 +2,9 @@ sidebar_position: 7 title: Allocator description: Use the allocator feature in a smart contract. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/auth.mdx b/docs/basic-tutorials/auth.mdx index 7fce14c1..ee27835d 100644 --- a/docs/basic-tutorials/auth.mdx +++ b/docs/basic-tutorials/auth.mdx @@ -2,6 +2,9 @@ sidebar_position: 4 title: Auth description: Implement authentication and authorization. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/cross-contract-call.mdx b/docs/basic-tutorials/cross-contract-call.mdx index d49423bf..055a8fd0 100644 --- a/docs/basic-tutorials/cross-contract-call.mdx +++ b/docs/basic-tutorials/cross-contract-call.mdx @@ -2,6 +2,9 @@ sidebar_position: 5 title: Cross Contract Calls description: Call a smart contract from another smart contract. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/custom-types.mdx b/docs/basic-tutorials/custom-types.mdx index 7855b56f..4ceaf954 100644 --- a/docs/basic-tutorials/custom-types.mdx +++ b/docs/basic-tutorials/custom-types.mdx @@ -2,6 +2,9 @@ sidebar_position: 4 title: Custom Types description: Define your data structures. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/deployer.mdx b/docs/basic-tutorials/deployer.mdx index c2ec9e7b..921c77f4 100644 --- a/docs/basic-tutorials/deployer.mdx +++ b/docs/basic-tutorials/deployer.mdx @@ -2,6 +2,9 @@ sidebar_position: 6 title: Deployer description: Deploy a smart contract using another smart contract. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/errors.mdx b/docs/basic-tutorials/errors.mdx index 2bb2c2c5..03c03e0d 100644 --- a/docs/basic-tutorials/errors.mdx +++ b/docs/basic-tutorials/errors.mdx @@ -2,6 +2,9 @@ sidebar_position: 2 title: Errors description: Define and generate errors in a smart contract. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/events.mdx b/docs/basic-tutorials/events.mdx index 2072c3cf..82d9c169 100644 --- a/docs/basic-tutorials/events.mdx +++ b/docs/basic-tutorials/events.mdx @@ -2,6 +2,9 @@ sidebar_position: 1 title: Events description: Publish events from a contract. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/logging.mdx b/docs/basic-tutorials/logging.mdx index 37a845f4..cf9d9869 100644 --- a/docs/basic-tutorials/logging.mdx +++ b/docs/basic-tutorials/logging.mdx @@ -2,6 +2,9 @@ sidebar_position: 3 title: Logging description: Use logs to debug smart contracts. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/upgrading-contracts.mdx b/docs/basic-tutorials/upgrading-contracts.mdx index 30b32c24..af204dc9 100644 --- a/docs/basic-tutorials/upgrading-contracts.mdx +++ b/docs/basic-tutorials/upgrading-contracts.mdx @@ -2,6 +2,9 @@ sidebar_position: 9 title: Upgrading Contracts description: Upgrade a WASM smart contract. +tags: + - tutorial + - beginner --- diff --git a/docs/basic-tutorials/wasm-metadata.mdx b/docs/basic-tutorials/wasm-metadata.mdx index d27613f9..c80bb412 100644 --- a/docs/basic-tutorials/wasm-metadata.mdx +++ b/docs/basic-tutorials/wasm-metadata.mdx @@ -2,6 +2,9 @@ sidebar_position: 8 title: Metadata description: Write structured metadata. +tags: + - tutorial + - beginner --- From 09519bc9b160e5f01220b257b57e0920cb270a56 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:41:35 -0600 Subject: [PATCH 04/95] docs: move tutorials into one main directory --- docs/tutorials/_category_.json | 7 +++++++ docs/{basic-tutorials => tutorials}/alloc.mdx | 0 .../atomic-multi-swap.mdx | 0 docs/{advanced-tutorials => tutorials}/atomic-swap.mdx | 0 docs/{basic-tutorials => tutorials}/auth.mdx | 0 .../{basic-tutorials => tutorials}/cross-contract-call.mdx | 0 docs/{advanced-tutorials => tutorials}/custom-account.mdx | 0 docs/{basic-tutorials => tutorials}/custom-types.mdx | 0 docs/{basic-tutorials => tutorials}/deployer.mdx | 0 docs/{basic-tutorials => tutorials}/errors.mdx | 0 docs/{basic-tutorials => tutorials}/events.mdx | 0 docs/{advanced-tutorials => tutorials}/fuzzing.mdx | 0 docs/{advanced-tutorials => tutorials}/liquidity-pool.mdx | 0 docs/{basic-tutorials => tutorials}/logging.mdx | 0 .../single-offer-sale.mdx | 0 .../stellar-asset-contract.mdx | 0 docs/{advanced-tutorials => tutorials}/timelock.mdx | 0 docs/{advanced-tutorials => tutorials}/tokens.mdx | 0 .../{basic-tutorials => tutorials}/upgrading-contracts.mdx | 0 docs/{basic-tutorials => tutorials}/wasm-metadata.mdx | 0 nginx/includes/redirects.conf | 2 ++ 21 files changed, 9 insertions(+) create mode 100644 docs/tutorials/_category_.json rename docs/{basic-tutorials => tutorials}/alloc.mdx (100%) rename docs/{advanced-tutorials => tutorials}/atomic-multi-swap.mdx (100%) rename docs/{advanced-tutorials => tutorials}/atomic-swap.mdx (100%) rename docs/{basic-tutorials => tutorials}/auth.mdx (100%) rename docs/{basic-tutorials => tutorials}/cross-contract-call.mdx (100%) rename docs/{advanced-tutorials => tutorials}/custom-account.mdx (100%) rename docs/{basic-tutorials => tutorials}/custom-types.mdx (100%) rename docs/{basic-tutorials => tutorials}/deployer.mdx (100%) rename docs/{basic-tutorials => tutorials}/errors.mdx (100%) rename docs/{basic-tutorials => tutorials}/events.mdx (100%) rename docs/{advanced-tutorials => tutorials}/fuzzing.mdx (100%) rename docs/{advanced-tutorials => tutorials}/liquidity-pool.mdx (100%) rename docs/{basic-tutorials => tutorials}/logging.mdx (100%) rename docs/{advanced-tutorials => tutorials}/single-offer-sale.mdx (100%) rename docs/{advanced-tutorials => tutorials}/stellar-asset-contract.mdx (100%) rename docs/{advanced-tutorials => tutorials}/timelock.mdx (100%) rename docs/{advanced-tutorials => tutorials}/tokens.mdx (100%) rename docs/{basic-tutorials => tutorials}/upgrading-contracts.mdx (100%) rename docs/{basic-tutorials => tutorials}/wasm-metadata.mdx (100%) diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json new file mode 100644 index 00000000..8c3f9dc6 --- /dev/null +++ b/docs/tutorials/_category_.json @@ -0,0 +1,7 @@ +{ + "position": 40, + "label": "Tutorials", + "link": { + "type": "generated-index" + } +} diff --git a/docs/basic-tutorials/alloc.mdx b/docs/tutorials/alloc.mdx similarity index 100% rename from docs/basic-tutorials/alloc.mdx rename to docs/tutorials/alloc.mdx diff --git a/docs/advanced-tutorials/atomic-multi-swap.mdx b/docs/tutorials/atomic-multi-swap.mdx similarity index 100% rename from docs/advanced-tutorials/atomic-multi-swap.mdx rename to docs/tutorials/atomic-multi-swap.mdx diff --git a/docs/advanced-tutorials/atomic-swap.mdx b/docs/tutorials/atomic-swap.mdx similarity index 100% rename from docs/advanced-tutorials/atomic-swap.mdx rename to docs/tutorials/atomic-swap.mdx diff --git a/docs/basic-tutorials/auth.mdx b/docs/tutorials/auth.mdx similarity index 100% rename from docs/basic-tutorials/auth.mdx rename to docs/tutorials/auth.mdx diff --git a/docs/basic-tutorials/cross-contract-call.mdx b/docs/tutorials/cross-contract-call.mdx similarity index 100% rename from docs/basic-tutorials/cross-contract-call.mdx rename to docs/tutorials/cross-contract-call.mdx diff --git a/docs/advanced-tutorials/custom-account.mdx b/docs/tutorials/custom-account.mdx similarity index 100% rename from docs/advanced-tutorials/custom-account.mdx rename to docs/tutorials/custom-account.mdx diff --git a/docs/basic-tutorials/custom-types.mdx b/docs/tutorials/custom-types.mdx similarity index 100% rename from docs/basic-tutorials/custom-types.mdx rename to docs/tutorials/custom-types.mdx diff --git a/docs/basic-tutorials/deployer.mdx b/docs/tutorials/deployer.mdx similarity index 100% rename from docs/basic-tutorials/deployer.mdx rename to docs/tutorials/deployer.mdx diff --git a/docs/basic-tutorials/errors.mdx b/docs/tutorials/errors.mdx similarity index 100% rename from docs/basic-tutorials/errors.mdx rename to docs/tutorials/errors.mdx diff --git a/docs/basic-tutorials/events.mdx b/docs/tutorials/events.mdx similarity index 100% rename from docs/basic-tutorials/events.mdx rename to docs/tutorials/events.mdx diff --git a/docs/advanced-tutorials/fuzzing.mdx b/docs/tutorials/fuzzing.mdx similarity index 100% rename from docs/advanced-tutorials/fuzzing.mdx rename to docs/tutorials/fuzzing.mdx diff --git a/docs/advanced-tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx similarity index 100% rename from docs/advanced-tutorials/liquidity-pool.mdx rename to docs/tutorials/liquidity-pool.mdx diff --git a/docs/basic-tutorials/logging.mdx b/docs/tutorials/logging.mdx similarity index 100% rename from docs/basic-tutorials/logging.mdx rename to docs/tutorials/logging.mdx diff --git a/docs/advanced-tutorials/single-offer-sale.mdx b/docs/tutorials/single-offer-sale.mdx similarity index 100% rename from docs/advanced-tutorials/single-offer-sale.mdx rename to docs/tutorials/single-offer-sale.mdx diff --git a/docs/advanced-tutorials/stellar-asset-contract.mdx b/docs/tutorials/stellar-asset-contract.mdx similarity index 100% rename from docs/advanced-tutorials/stellar-asset-contract.mdx rename to docs/tutorials/stellar-asset-contract.mdx diff --git a/docs/advanced-tutorials/timelock.mdx b/docs/tutorials/timelock.mdx similarity index 100% rename from docs/advanced-tutorials/timelock.mdx rename to docs/tutorials/timelock.mdx diff --git a/docs/advanced-tutorials/tokens.mdx b/docs/tutorials/tokens.mdx similarity index 100% rename from docs/advanced-tutorials/tokens.mdx rename to docs/tutorials/tokens.mdx diff --git a/docs/basic-tutorials/upgrading-contracts.mdx b/docs/tutorials/upgrading-contracts.mdx similarity index 100% rename from docs/basic-tutorials/upgrading-contracts.mdx rename to docs/tutorials/upgrading-contracts.mdx diff --git a/docs/basic-tutorials/wasm-metadata.mdx b/docs/tutorials/wasm-metadata.mdx similarity index 100% rename from docs/basic-tutorials/wasm-metadata.mdx rename to docs/tutorials/wasm-metadata.mdx diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 3662cc2b..32c2c16e 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -22,3 +22,5 @@ rewrite "^/docs/common-interfaces/token$" "/docs/reference/interfaces/token-inte rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permanent; # BEGIN re-structure redirects # "fundamentals-and-concepts" is now "soroban-internals" +# all of the "basic-tutorials" are now in "tutorials" +# all of the "advanced-tutorials" are now in "tutorials" From 912f524eca6d1a9df4fdff052982219afcfece33 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:47:55 -0600 Subject: [PATCH 05/95] fix broken links to old pages --- docs/getting-started/create-an-app.mdx | 8 ++++---- docs/getting-started/hello-world.mdx | 4 ++-- docs/getting-started/storing-data.mdx | 4 ++-- docs/reference/freighter.mdx | 2 +- docs/reference/interfaces/token-interface.mdx | 2 +- docs/reference/releases.mdx | 2 +- docs/soroban-internals/authorization.mdx | 10 +++++----- docs/soroban-internals/built-in-types.mdx | 2 +- docs/soroban-internals/contract-lifecycle.mdx | 4 ++-- docs/soroban-internals/custom-types.mdx | 4 ++-- docs/soroban-internals/debugging.mdx | 2 +- docs/soroban-internals/environment-concepts.mdx | 2 +- docs/soroban-internals/errors.mdx | 4 ++-- docs/soroban-internals/events.mdx | 4 ++-- docs/soroban-internals/faq.mdx | 4 ++-- docs/soroban-internals/fees-and-metering.mdx | 2 +- docs/soroban-internals/fully-typed-contracts.mdx | 2 +- docs/soroban-internals/high-level-overview.mdx | 2 +- .../interacting-with-contracts.mdx | 4 ++-- .../invoking-contracts-with-transactions.mdx | 14 +++++++------- .../solidity-and-rust-advanced-concepts.mdx | 4 ++-- .../solidity-and-rust-basics.mdx | 4 ++-- docs/soroban-internals/persisting-data.mdx | 2 +- docs/soroban-internals/rust-dialect.mdx | 2 +- docs/soroban-internals/state-expiration.mdx | 8 ++++---- docs/tutorials/alloc.mdx | 4 ++-- docs/tutorials/atomic-multi-swap.mdx | 2 +- docs/tutorials/atomic-swap.mdx | 4 ++-- docs/tutorials/auth.mdx | 10 +++++----- docs/tutorials/cross-contract-call.mdx | 2 +- docs/tutorials/custom-account.mdx | 2 +- docs/tutorials/custom-types.mdx | 2 +- docs/tutorials/deployer.mdx | 4 ++-- docs/tutorials/errors.mdx | 2 +- docs/tutorials/events.mdx | 2 +- docs/tutorials/fuzzing.mdx | 2 +- docs/tutorials/liquidity-pool.mdx | 2 +- docs/tutorials/logging.mdx | 2 +- docs/tutorials/single-offer-sale.mdx | 2 +- docs/tutorials/stellar-asset-contract.mdx | 8 ++++---- docs/tutorials/timelock.mdx | 2 +- docs/tutorials/tokens.mdx | 2 +- docs/tutorials/upgrading-contracts.mdx | 4 ++-- docs/tutorials/wasm-metadata.mdx | 2 +- 44 files changed, 81 insertions(+), 81 deletions(-) diff --git a/docs/getting-started/create-an-app.mdx b/docs/getting-started/create-an-app.mdx index a20c5aeb..96dd2ac3 100644 --- a/docs/getting-started/create-an-app.mdx +++ b/docs/getting-started/create-an-app.mdx @@ -41,7 +41,7 @@ git commit -m "Initialize Astro project" ## Generate an NPM package for the Hello World contract -Before we even open the new frontend files, let's generate an NPM package for the Hello World contract. This is our suggested way to interact with contracts from frontends. These generated libraries work with any JavaScript project (not a specific UI like React), and make it easy to work with some of the trickiest bits of Soroban, like encoding [XDR](https://soroban.stellar.org/docs/fundamentals-and-concepts/fully-typed-contracts). +Before we even open the new frontend files, let's generate an NPM package for the Hello World contract. This is our suggested way to interact with contracts from frontends. These generated libraries work with any JavaScript project (not a specific UI like React), and make it easy to work with some of the trickiest bits of Soroban, like encoding [XDR](https://soroban.stellar.org/docs/soroban-internals/fully-typed-contracts). This is going to use the CLI command `soroban contract bindings typescript`: @@ -464,7 +464,7 @@ Here are some common issues and how to fix them. Sometimes the call to `hello` can start failing. You can obviously stub out the call and define `greeting` some other way to troubleshoot. -One of the common problems here is that the contract [expires](../fundamentals-and-concepts/state-expiration.mdx). To check if this is the problem, you can re-run `npm run reset`. +One of the common problems here is that the contract [expires](../soroban-internals/state-expiration.mdx). To check if this is the problem, you can re-run `npm run reset`. If you're still having problems, join our Discord (link above) or [open an issue in GitHub](https://github.com/stellar/soroban-docs/issues/new/choose). @@ -483,6 +483,6 @@ Looking at `git diff` will be a great way to remember all the interesting things At this point, you've seen a full end-to-end example of building on Soroban! What's next? You choose! You can: -- See more complex example contracts in the [Basic Tutorials](/docs/category/basic-tutorials) and [Advanced Tutorials](/docs/category/advanced-tutorials) sections. -- Learn more about the [fundamentals and concepts](/docs/category/fundamentals-and-concepts) of Soroban. +- See more complex example contracts in the [Basic Tutorials](/docs/category/tutorials) and [Advanced Tutorials](/docs/category/tutorials) sections. +- Learn more about the [fundamentals and concepts](/docs/category/soroban-internals) of Soroban. - Check out a more full-featured [example app](https://github.com/stellar/soroban-example-dapp), which uses React rather than vanilla JavaScript and Next.js rather than Astro. This app also has a more complex setup & initialization process, with the option of using a [locally-hosted RPC node](../reference/rpc.mdx). diff --git a/docs/getting-started/hello-world.mdx b/docs/getting-started/hello-world.mdx index 2d5d02aa..c2144703 100644 --- a/docs/getting-started/hello-world.mdx +++ b/docs/getting-started/hello-world.mdx @@ -113,7 +113,7 @@ debug-assertions = true See the [logging example] for more information about how to log. -[logging example]: ../basic-tutorials/logging.mdx +[logging example]: ../tutorials/logging.mdx ### Wrapping it Up @@ -338,7 +338,7 @@ A `.wasm` file will be outputted in the `target` directory. The `.wasm` file is target/wasm32-unknown-unknown/release/hello_soroban.wasm ``` -The `.wasm` file contains the logic of the contract, as well as the contract's [specification / interface types](../fundamentals-and-concepts/fully-typed-contracts.mdx), which can be imported into other contracts who wish to call it. This is the only artifact needed to deploy the contract, share the interface with others, or integration test against the contract. +The `.wasm` file contains the logic of the contract, as well as the contract's [specification / interface types](../soroban-internals/fully-typed-contracts.mdx), which can be imported into other contracts who wish to call it. This is the only artifact needed to deploy the contract, share the interface with others, or integration test against the contract. ## Optimizing Builds diff --git a/docs/getting-started/storing-data.mdx b/docs/getting-started/storing-data.mdx index c3001d2a..6d3df6e6 100644 --- a/docs/getting-started/storing-data.mdx +++ b/docs/getting-started/storing-data.mdx @@ -234,7 +234,7 @@ let mut count: u32 = env If no value is currently stored, the value given to `unwrap_or(...)` is returned instead. -Values stored as contract data and retrieved are transmitted from [the environment](../fundamentals-and-concepts/environment-concepts.mdx) and expanded into the type specified. In this case a `u32`. If the value can be expanded, the type returned will be a `u32`. Otherwise, if a developer caused it to be some other type, a panic would occur at the unwrap. +Values stored as contract data and retrieved are transmitted from [the environment](../soroban-internals/environment-concepts.mdx) and expanded into the type specified. In this case a `u32`. If the value can be expanded, the type returned will be a `u32`. Otherwise, if a developer caused it to be some other type, a panic would occur at the unwrap. The `set()` function stores the new count value against the key, replacing the existing value. @@ -247,7 +247,7 @@ env.storage() ### Managing Contract Data Lifetimes with `bump()` All contract data has a "lifetime" that must be periodically bumped. If an -entry's lifetime is not periodically bumped, the entry will eventually reach the end of its lifetime and "expire". You can learn more about this in the [State Expiration](../fundamentals-and-concepts/state-expiration.mdx) document. +entry's lifetime is not periodically bumped, the entry will eventually reach the end of its lifetime and "expire". You can learn more about this in the [State Expiration](../soroban-internals/state-expiration.mdx) document. For now, it's worth knowing that there are three kinds of storage: `Persistent`, `Temporary`, and `Instance`. This contract only uses `Instance` storage: `env.storage().instance()`. Every time the counter is incremented, this storage gets bumped by 100 [ledgers](https://developers.stellar.org/docs/fundamentals-and-concepts/stellar-data-structures/ledgers), or about 500 seconds. diff --git a/docs/reference/freighter.mdx b/docs/reference/freighter.mdx index 63428573..0b0b2a8c 100644 --- a/docs/reference/freighter.mdx +++ b/docs/reference/freighter.mdx @@ -71,7 +71,7 @@ If you're building a JS dapp, easily sign Soroban transactions using the [Freigh ## Sign Authorization Entries -In order to take advantage of [contract authorization](../fundamentals-and-concepts/authorization), you can use Freighter's API to sign an authorization entry. +In order to take advantage of [contract authorization](../soroban-internals/authorization), you can use Freighter's API to sign an authorization entry. A good example of how signing an authorization entry works can be found in the [`authorizeEntry` helper of soroban-client](https://github.com/stellar/js-stellar-base/blob/e3d6fc3351e7d242b374c7c6057668366364a279/src/auth.js#L97). diff --git a/docs/reference/interfaces/token-interface.mdx b/docs/reference/interfaces/token-interface.mdx index 4f122c07..0d1b18d0 100644 --- a/docs/reference/interfaces/token-interface.mdx +++ b/docs/reference/interfaces/token-interface.mdx @@ -209,7 +209,7 @@ Its important to note the that the token interface not only incorporates the aut To provide more context, when you use the token interface, there is a function called `authorized` that returns "true" if an address has token authorization. -More details on Authorization can be found [here](../../fundamentals-and-concepts/authorization). +More details on Authorization can be found [here](../../soroban-internals/authorization). For the functions in the token interface, [trapping](https://doc.rust-lang.org/book/ch09-00-error-handling.html) should be used as the standard way to handle failure conditions since the interface is not designed to return error codes. This means that when a function encounters an error, it will halt execution and revert any state changes that occurred during the function call. diff --git a/docs/reference/releases.mdx b/docs/reference/releases.mdx index dabcde32..8df464c2 100644 --- a/docs/reference/releases.mdx +++ b/docs/reference/releases.mdx @@ -565,7 +565,7 @@ See https://github.com/stellar/soroban-tools/releases v0.7.0 for more details. This release comes with a revamp of authorization approach that is breaking for most of the contracts that did any sort of auth logic or used tokens. -[example](../basic-tutorials/auth.mdx) and [authorization overview](../fundamentals-and-concepts/authorization.mdx) +[example](../tutorials/auth.mdx) and [authorization overview](../soroban-internals/authorization.mdx) for more details. ### Changelog diff --git a/docs/soroban-internals/authorization.mdx b/docs/soroban-internals/authorization.mdx index a5cf097d..0210d7ea 100644 --- a/docs/soroban-internals/authorization.mdx +++ b/docs/soroban-internals/authorization.mdx @@ -14,7 +14,7 @@ description: Smart contract authorization. /> @@ -105,7 +105,7 @@ for this authorization are defined by the `Address` and are enforced by the Soroban host. Replay protection is also implemented in the host, i.e., there is normally no need for a contract to manage its own nonces. -[auth example]: ../basic-tutorials/auth.mdx +[auth example]: ../tutorials/auth.mdx #### Authorizing Sub-contract Calls @@ -119,7 +119,7 @@ Contracts don't need to do anything special to benefit from this feature. Just calling a sub-contract that calls `require_auth` will ensure that the sub-contract call has been properly authorized. -[timelock example]: ../advanced-tutorials/timelock.mdx +[timelock example]: ../tutorials/timelock.mdx #### When to `require_auth` @@ -149,7 +149,7 @@ even have different authorization contexts (customized via arguments in `require_auth_for_args`). [Atomic swap] is an example that deals with authorization of two `Address`es. -[Atomic swap]: ../advanced-tutorials/atomic-swap.mdx +[Atomic swap]: ../tutorials/atomic-swap.mdx Note though, that contracts that deal with multiple authorized `Address`es need a bit more complex support on the client side (to collect and attach the proper @@ -251,7 +251,7 @@ called). For the exact interface and more details, see the [custom account example]. -[custom account example]: ../advanced-tutorials/custom-account.mdx +[custom account example]: ../tutorials/custom-account.mdx ### Advanced Concepts diff --git a/docs/soroban-internals/built-in-types.mdx b/docs/soroban-internals/built-in-types.mdx index 9859d6ef..8a08c4a6 100644 --- a/docs/soroban-internals/built-in-types.mdx +++ b/docs/soroban-internals/built-in-types.mdx @@ -17,7 +17,7 @@ description: Built-in types used as smart contract inputs and outputs. /> diff --git a/docs/soroban-internals/contract-lifecycle.mdx b/docs/soroban-internals/contract-lifecycle.mdx index cfb770c3..acfb0998 100644 --- a/docs/soroban-internals/contract-lifecycle.mdx +++ b/docs/soroban-internals/contract-lifecycle.mdx @@ -19,7 +19,7 @@ description: The process of developing, deploying, and maintaining smart contrac /> @@ -63,4 +63,4 @@ TBD: expand this section. ## Upgrading contracts -See the [Upgrading Contracts](../basic-tutorials/upgrading-contracts.mdx) page for details on this. +See the [Upgrading Contracts](../tutorials/upgrading-contracts.mdx) page for details on this. diff --git a/docs/soroban-internals/custom-types.mdx b/docs/soroban-internals/custom-types.mdx index a447ceb9..30c8ab16 100644 --- a/docs/soroban-internals/custom-types.mdx +++ b/docs/soroban-internals/custom-types.mdx @@ -17,7 +17,7 @@ description: Struct, union, and enum types defined by contracts. /> @@ -30,7 +30,7 @@ for storage. :::info The [custom types example] demonstrates how to define your own types. -[custom types example]: ../basic-tutorials/custom-types.mdx +[custom types example]: ../tutorials/custom-types.mdx ::: diff --git a/docs/soroban-internals/debugging.mdx b/docs/soroban-internals/debugging.mdx index 0e718075..087e0db6 100644 --- a/docs/soroban-internals/debugging.mdx +++ b/docs/soroban-internals/debugging.mdx @@ -17,7 +17,7 @@ description: Debug smart contracts natively and as WASM. /> diff --git a/docs/soroban-internals/environment-concepts.mdx b/docs/soroban-internals/environment-concepts.mdx index 903eef61..e543bbee 100644 --- a/docs/soroban-internals/environment-concepts.mdx +++ b/docs/soroban-internals/environment-concepts.mdx @@ -20,7 +20,7 @@ description: The interface that defines objects, functions, and data available t /> diff --git a/docs/soroban-internals/errors.mdx b/docs/soroban-internals/errors.mdx index 9d136603..bea89154 100644 --- a/docs/soroban-internals/errors.mdx +++ b/docs/soroban-internals/errors.mdx @@ -14,7 +14,7 @@ description: Generating errors from smart contracts. /> @@ -27,7 +27,7 @@ types of contract functions. :::info The [errors example] demonstrates how to define your own error types. -[errors example]: ../basic-tutorials/errors.mdx +[errors example]: ../tutorials/errors.mdx ::: diff --git a/docs/soroban-internals/events.mdx b/docs/soroban-internals/events.mdx index 02227bcb..f8a038a1 100644 --- a/docs/soroban-internals/events.mdx +++ b/docs/soroban-internals/events.mdx @@ -17,7 +17,7 @@ description: Monitor off-chain smart contract changes. /> @@ -30,7 +30,7 @@ the [TransactionMetaV3] XDR below that there is a list of `OperationEvents` called `events`. Each `OperationEvent` corresponds to an operation in a transaction, and itself contains a list of `ContractEvents`. Note that `events` will only be populated if the transaction succeeds. Take a look at [this -example](../basic-tutorials/events.mdx) to learn more about how to emit an event +example](../tutorials/events.mdx) to learn more about how to emit an event in your contract. [TransactionMetaV3]: #transactionmetav3 diff --git a/docs/soroban-internals/faq.mdx b/docs/soroban-internals/faq.mdx index 3a5f959f..7d5919e9 100644 --- a/docs/soroban-internals/faq.mdx +++ b/docs/soroban-internals/faq.mdx @@ -17,7 +17,7 @@ description: Frequently asked questions about Soroban on Stellar. /> @@ -41,7 +41,7 @@ Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Ste ### Can Soroban contracts interact with Stellar assets? -Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](../advanced-tutorials/stellar-asset-contract.mdx). +Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](../tutorials/stellar-asset-contract.mdx). ### Do issuers of Stellar assets maintain their authorization over an asset that has been sent to a non-account identifier in Soroban? (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK) diff --git a/docs/soroban-internals/fees-and-metering.mdx b/docs/soroban-internals/fees-and-metering.mdx index dec10f72..eb1caa66 100644 --- a/docs/soroban-internals/fees-and-metering.mdx +++ b/docs/soroban-internals/fees-and-metering.mdx @@ -17,7 +17,7 @@ description: Smart contract fees and metering on Soroban. /> diff --git a/docs/soroban-internals/fully-typed-contracts.mdx b/docs/soroban-internals/fully-typed-contracts.mdx index 4c55a45c..476feb27 100644 --- a/docs/soroban-internals/fully-typed-contracts.mdx +++ b/docs/soroban-internals/fully-typed-contracts.mdx @@ -21,7 +21,7 @@ sidebar_label: Fully-Typed Contracts /> diff --git a/docs/soroban-internals/high-level-overview.mdx b/docs/soroban-internals/high-level-overview.mdx index 671e952c..cc42a0d8 100644 --- a/docs/soroban-internals/high-level-overview.mdx +++ b/docs/soroban-internals/high-level-overview.mdx @@ -17,7 +17,7 @@ description: An overview of Rust, SDKs, and the Soroban host environment. /> diff --git a/docs/soroban-internals/interacting-with-contracts.mdx b/docs/soroban-internals/interacting-with-contracts.mdx index 459835b6..f8f52ea1 100644 --- a/docs/soroban-internals/interacting-with-contracts.mdx +++ b/docs/soroban-internals/interacting-with-contracts.mdx @@ -14,7 +14,7 @@ description: Interact with smart contracts. /> @@ -105,7 +105,7 @@ Since host objects are immutable, there is limited risk to passing a shared refe ### Footprint -As mentioned in the [persisting data](../fundamentals-and-concepts/persisting-data.mdx) section, a contract can only load or store `CONTRACT_DATA` entries that are declared in a _footprint_ associated with its invocation. +As mentioned in the [persisting data](../soroban-internals/persisting-data.mdx) section, a contract can only load or store `CONTRACT_DATA` entries that are declared in a _footprint_ associated with its invocation. A footprint is a set of ledger keys, each marked as either read-only or read-write. Read-only keys are available to the transaction for reading; read-write keys are available for reading, writing, or both. diff --git a/docs/soroban-internals/invoking-contracts-with-transactions.mdx b/docs/soroban-internals/invoking-contracts-with-transactions.mdx index e79c6428..9b8eb9fa 100644 --- a/docs/soroban-internals/invoking-contracts-with-transactions.mdx +++ b/docs/soroban-internals/invoking-contracts-with-transactions.mdx @@ -20,7 +20,7 @@ toc_max_heading_level: 4 /> @@ -265,7 +265,7 @@ The `InvokeHostFunctionOp` can be used to perform the following Soroban operatio - Invoke contract functions. - Upload Wasm of the new contracts. -- Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../advanced-tutorials/stellar-asset-contract.mdx)). +- Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../tutorials/stellar-asset-contract.mdx)). [`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli @@ -401,7 +401,7 @@ The `hostFunction` in `InvokeHostFunctionOp` will be executed by the Soroban hos #### Authorization Data -Soroban's [authorization framework](../fundamentals-and-concepts/authorization.mdx) +Soroban's [authorization framework](../soroban-internals/authorization.mdx) provides a standardized way for passing authorization data to the contract invocations via `SorobanAuthorizationEntry` structures. @@ -502,7 +502,7 @@ recording auth mode in Soroban's `simulateTransaction` mechanism (see the [docs] details). [envelope-xdr]: https://github.com/stellar/stellar-xdr/blob/e372df9f677961aac04c5a4cc80a3667f310b29f/Stellar-transaction.x#L703 -[simulate-transaction-doc]: ../fundamentals-and-concepts/interacting-with-contracts.mdx#authorization +[simulate-transaction-doc]: ../soroban-internals/interacting-with-contracts.mdx#authorization ##### Stellar Account Signatures @@ -521,13 +521,13 @@ pub struct AccountEd25519Signature { ``` [structures]: https://github.com/stellar/rs-soroban-env/blob/99d8c92cdc7e5cd0f5311df8f88d04658ecde7d2/soroban-env-host/src/native_contract/account_contract.rs#L51 -[custom accounts]: ../fundamentals-and-concepts/authorization.mdx#account-abstraction +[custom accounts]: ../soroban-internals/authorization.mdx#account-abstraction ### Transaction resources Every Soroban transaction has to have a `SorobanTransactionData` transaction [extension] populated. This is needed to compute the -[Soroban resource fee](../fundamentals-and-concepts/fees-and-metering.mdx). +[Soroban resource fee](../soroban-internals/fees-and-metering.mdx). [extension]: https://github.com/stellar/stellar-xdr/blob/c2e702c70951ff59a1eff257f08cf38d47210e5f/Stellar-transaction.x#L874 @@ -567,4 +567,4 @@ resource fee. The footprint must contain the `LedgerKey`s that will be read and/or written. The simplest method to determine the values in `SorobanResources` and -`refundableFee` is to use the [`simulateTransaction` mechanism](../fundamentals-and-concepts/interacting-with-contracts.mdx#transaction-simulation). +`refundableFee` is to use the [`simulateTransaction` mechanism](../soroban-internals/interacting-with-contracts.mdx#transaction-simulation). diff --git a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx b/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx index 0ff1e0b1..b6cc44cc 100644 --- a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx +++ b/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx @@ -170,7 +170,7 @@ impl AllocContract { In this example, the `alloc` crate is imported into the smart contract using the `extern crate alloc;` statement. The `alloc` crate is then used to create a temporary vector that holds values from 0 to `count`. The values in the vector are then summed and returned. -For more details on how to use the `alloc` crate, including a hands-on practical exercise, visit the [alloc section](../../basic-tutorials/alloc#how-it-works) of the documentation. +For more details on how to use the `alloc` crate, including a hands-on practical exercise, visit the [alloc section](../../tutorials/alloc#how-it-works) of the documentation. #### Inheriting Functionality from Other Crates @@ -898,7 +898,7 @@ By utilizing these authorization methods provided by the `Address` object from t Soroban's approach to authorization in this example offers several advantages over Solidity's model of ERC20 by eliminating the need for separate approval management. Instead, authorization checks can be directly incorporated into any Soroban function. This simplifies the contract codebase and reduces the complexity associated with managing separate approval states. -Soroban authorization provides Contract-level Authorization, Account Abstraction Functionality, and more advanced Authorization checks. To learn more about these advantages, visit the [Authorization section](../../fundamentals-and-concepts/authorization) of the documentation. +Soroban authorization provides Contract-level Authorization, Account Abstraction Functionality, and more advanced Authorization checks. To learn more about these advantages, visit the [Authorization section](../../soroban-internals/authorization) of the documentation. ## Summary diff --git a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx b/docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx index 4f3d5be5..1b0af1e3 100644 --- a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx +++ b/docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx @@ -121,7 +121,7 @@ fn main() { ### Data Types -The [Soroban Rust SDK](https://docs.rs/soroban-sdk/latest/soroban_sdk/index.html) supports a variety of [Built-In Types](../../fundamentals-and-concepts/built-in-types) which consist of both Primitive and [Custom Types](../../fundamentals-and-concepts/custom-types), such as: +The [Soroban Rust SDK](https://docs.rs/soroban-sdk/latest/soroban_sdk/index.html) supports a variety of [Built-In Types](../../soroban-internals/built-in-types) which consist of both Primitive and [Custom Types](../../soroban-internals/custom-types), such as: #### Primitive Data Types @@ -322,7 +322,7 @@ Rust enforces [**strict ownership rules**](https://doc.rust-lang.org/book/ch04-0 Contract development in Rust involves certain restrictions due to either unavailable features in the deployment environment or high runtime costs. Thus, the code written for contracts can be seen as a distinct _dialect_ of Rust, focusing on deterministic behavior and minimized code size. -To learn more about Rust's Contract Dialect, check out the [Contract Rust Dialect Page](../../fundamentals-and-concepts/rust-dialect). +To learn more about Rust's Contract Dialect, check out the [Contract Rust Dialect Page](../../soroban-internals/rust-dialect). ## Writing and Interacting with Simple Smart Contracts diff --git a/docs/soroban-internals/persisting-data.mdx b/docs/soroban-internals/persisting-data.mdx index 779597c3..e0354888 100644 --- a/docs/soroban-internals/persisting-data.mdx +++ b/docs/soroban-internals/persisting-data.mdx @@ -14,7 +14,7 @@ description: Store and access smart contract data. /> diff --git a/docs/soroban-internals/rust-dialect.mdx b/docs/soroban-internals/rust-dialect.mdx index dedfe90f..dcd07c3c 100644 --- a/docs/soroban-internals/rust-dialect.mdx +++ b/docs/soroban-internals/rust-dialect.mdx @@ -17,7 +17,7 @@ description: Differences between Soroban Rust and typical Rust programming. /> diff --git a/docs/soroban-internals/state-expiration.mdx b/docs/soroban-internals/state-expiration.mdx index e1de02a0..17c73bd9 100644 --- a/docs/soroban-internals/state-expiration.mdx +++ b/docs/soroban-internals/state-expiration.mdx @@ -14,7 +14,7 @@ description: Smart contract state expiration. /> @@ -151,7 +151,7 @@ expirationLedger that is large enough. `BumpFootprintExpirationOp` is a Soroban operation, and therefore must be the only operation in a transaction. The transaction also needs to populate `SorobanTransactionData` transaction extension explained -[here](../fundamentals-and-concepts/invoking-contracts-with-transactions.mdx#transaction-resources). To fill +[here](../soroban-internals/invoking-contracts-with-transactions.mdx#transaction-resources). To fill out `SorobanResources`, use the transaction simulation mentioned in the provided link, or make sure `readBytes` includes the key and entry size of every entry in the `readOnly` set. @@ -188,7 +188,7 @@ parameter and is subject to be updated (likely increased) via network upgrades. `RestoreFootprintOp` is a Soroban operation, and therefore must be the only operation in a transaction. The transaction also needs to populate `SorobanTransactionData` transaction extension explained -[here](../fundamentals-and-concepts/invoking-contracts-with-transactions.mdx#transaction-resources). To fill +[here](../soroban-internals/invoking-contracts-with-transactions.mdx#transaction-resources). To fill out `SorobanResources`, use the transaction simulation mentioned in the provided link, or make sure `writeBytes` includes the key and entry size of every entry in the `readWrite` set and make sure `extendedMetaDataSizeBytes` is at least double of @@ -204,7 +204,7 @@ We've done our best to build tooling around state expiration in both the Soroban Both restoring and bumping the expiration of ledger entries follows a three-step process regardless of their nature (contract data, instances, etc.): -1. **Identify the ledger entries**. This usually means acquiring them from a Soroban RPC server as part of your initial transaction simulation (see the [transaction simulation docs](https://soroban.stellar.org/docs/fundamentals-and-concepts/interacting-with-contracts#transaction-simulation) and the [`simulateTransaction`](https://soroban.stellar.org/api/methods/simulateTransaction) RPC method). +1. **Identify the ledger entries**. This usually means acquiring them from a Soroban RPC server as part of your initial transaction simulation (see the [transaction simulation docs](https://soroban.stellar.org/docs/soroban-internals/interacting-with-contracts#transaction-simulation) and the [`simulateTransaction`](https://soroban.stellar.org/api/methods/simulateTransaction) RPC method). 2. **Prepare your operation**. This means describing the ledger entries within the corresponding operation (i.e. `bumpFootprintOp` or `restoreFootprintOp`) and its ledger footprint (the `SorobanTransactionData` field), then simulating it to fill out fee and resource usage information (when restoring, you usually have simulation results already). diff --git a/docs/tutorials/alloc.mdx b/docs/tutorials/alloc.mdx index 2d90fdf7..07c88c08 100644 --- a/docs/tutorials/alloc.mdx +++ b/docs/tutorials/alloc.mdx @@ -20,7 +20,7 @@ tags: /> @@ -109,7 +109,7 @@ extern crate alloc; Imports the `alloc` crate, which is required in order to support allocation under `no_std`. See [Contract Rust dialect] for more info about `no_std`. -[contract rust dialect]: ../fundamentals-and-concepts/rust-dialect.mdx +[contract rust dialect]: ../soroban-internals/rust-dialect.mdx ```rust let mut v1 = alloc::vec![]; diff --git a/docs/tutorials/atomic-multi-swap.mdx b/docs/tutorials/atomic-multi-swap.mdx index 2db61dee..75b6cccf 100644 --- a/docs/tutorials/atomic-multi-swap.mdx +++ b/docs/tutorials/atomic-multi-swap.mdx @@ -17,7 +17,7 @@ tags: /> diff --git a/docs/tutorials/atomic-swap.mdx b/docs/tutorials/atomic-swap.mdx index b4c9f670..78bf49fa 100644 --- a/docs/tutorials/atomic-swap.mdx +++ b/docs/tutorials/atomic-swap.mdx @@ -20,7 +20,7 @@ tags: /> @@ -28,7 +28,7 @@ The [atomic swap example] swaps two tokens between two authorized parties atomically while following the limits they set. This is example demonstrates advanced usage of Soroban auth framework and -assumes the reader is familiar with the [auth example](../basic-tutorials/auth.mdx) and with +assumes the reader is familiar with the [auth example](../tutorials/auth.mdx) and with Soroban token usage. [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp] diff --git a/docs/tutorials/auth.mdx b/docs/tutorials/auth.mdx index ee27835d..2092e383 100644 --- a/docs/tutorials/auth.mdx +++ b/docs/tutorials/auth.mdx @@ -20,7 +20,7 @@ tags: /> @@ -425,16 +425,16 @@ Contract auth: [{"address_with_nonce":null,"root_invocation":{"contract_id":"000 ## Further reading -[Authorization documentation](../fundamentals-and-concepts/authorization.mdx) provides more details +[Authorization documentation](../soroban-internals/authorization.mdx) provides more details on how Soroban auth framework works. -[Timelock](../advanced-tutorials/timelock.mdx) and [Single Offer](../advanced-tutorials/single-offer-sale.mdx) examples +[Timelock](../tutorials/timelock.mdx) and [Single Offer](../tutorials/single-offer-sale.mdx) examples demonstrate authorizing token operations on behalf of the user, which can be extended to any nested contract invocations. -[Atomic Swap](../advanced-tutorials/atomic-swap.mdx) example demonstrates multi-party authorization +[Atomic Swap](../tutorials/atomic-swap.mdx) example demonstrates multi-party authorization where multiple users sign their parts of the contract invocation. -[Custom Account](../advanced-tutorials/custom-account.mdx) example for demonstrates an account +[Custom Account](../tutorials/custom-account.mdx) example for demonstrates an account contract that defines a custom authentication scheme and user-defined authorization policies. diff --git a/docs/tutorials/cross-contract-call.mdx b/docs/tutorials/cross-contract-call.mdx index 055a8fd0..5c21d1d2 100644 --- a/docs/tutorials/cross-contract-call.mdx +++ b/docs/tutorials/cross-contract-call.mdx @@ -20,7 +20,7 @@ tags: /> diff --git a/docs/tutorials/custom-account.mdx b/docs/tutorials/custom-account.mdx index 07856313..db0bf818 100644 --- a/docs/tutorials/custom-account.mdx +++ b/docs/tutorials/custom-account.mdx @@ -22,7 +22,7 @@ tags: /> diff --git a/docs/tutorials/custom-types.mdx b/docs/tutorials/custom-types.mdx index 4ceaf954..3a4a153a 100644 --- a/docs/tutorials/custom-types.mdx +++ b/docs/tutorials/custom-types.mdx @@ -17,7 +17,7 @@ tags: /> diff --git a/docs/tutorials/deployer.mdx b/docs/tutorials/deployer.mdx index 921c77f4..181069cb 100644 --- a/docs/tutorials/deployer.mdx +++ b/docs/tutorials/deployer.mdx @@ -20,7 +20,7 @@ tags: /> @@ -149,7 +149,7 @@ from their own address (`deployer == env.current_contract_address()``). :::info -For introduction to Soroban authorization see the [auth tutorial](https://soroban.stellar.org/docs/basic-tutorials/auth) +For introduction to Soroban authorization see the [auth tutorial](https://soroban.stellar.org/docs/tutorials/auth) ::: diff --git a/docs/tutorials/errors.mdx b/docs/tutorials/errors.mdx index 03c03e0d..a76b62ed 100644 --- a/docs/tutorials/errors.mdx +++ b/docs/tutorials/errors.mdx @@ -20,7 +20,7 @@ tags: /> diff --git a/docs/tutorials/events.mdx b/docs/tutorials/events.mdx index 82d9c169..f79900af 100644 --- a/docs/tutorials/events.mdx +++ b/docs/tutorials/events.mdx @@ -17,7 +17,7 @@ tags: /> diff --git a/docs/tutorials/fuzzing.mdx b/docs/tutorials/fuzzing.mdx index 2c87b365..21dd210c 100644 --- a/docs/tutorials/fuzzing.mdx +++ b/docs/tutorials/fuzzing.mdx @@ -17,7 +17,7 @@ tags: /> diff --git a/docs/tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx index ff34353f..a8106f11 100644 --- a/docs/tutorials/liquidity-pool.mdx +++ b/docs/tutorials/liquidity-pool.mdx @@ -20,7 +20,7 @@ tags: /> diff --git a/docs/tutorials/logging.mdx b/docs/tutorials/logging.mdx index cf9d9869..372766a1 100644 --- a/docs/tutorials/logging.mdx +++ b/docs/tutorials/logging.mdx @@ -17,7 +17,7 @@ tags: /> diff --git a/docs/tutorials/single-offer-sale.mdx b/docs/tutorials/single-offer-sale.mdx index 1d2eb393..ba22bbaa 100644 --- a/docs/tutorials/single-offer-sale.mdx +++ b/docs/tutorials/single-offer-sale.mdx @@ -22,7 +22,7 @@ tags: /> diff --git a/docs/tutorials/stellar-asset-contract.mdx b/docs/tutorials/stellar-asset-contract.mdx index 9a224905..ea5e1a43 100644 --- a/docs/tutorials/stellar-asset-contract.mdx +++ b/docs/tutorials/stellar-asset-contract.mdx @@ -17,7 +17,7 @@ tags: /> @@ -53,7 +53,7 @@ smart contract developers to get started on Stellar. For every 'classic' asset exactly one respective Stellar Asset Contract can be deployed. It can be deployed using the `InvokeHostFunctionOp` with `HOST_FUNCTION_TYPE_CREATE_CONTRACT` and `CONTRACT_ID_FROM_ASSET` specified -[here](../fundamentals-and-concepts/invoking-contracts-with-transactions). The resulting token will have a +[here](../soroban-internals/invoking-contracts-with-transactions). The resulting token will have a deterministic identifier, which will be the sha256 hash of `HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET` xdr specified [here][contract_id]. @@ -126,8 +126,8 @@ about `AUTH_REQUIRED_FLAG` [here](https://developers.stellar.org/docs/issuing-as ## Authorization semantics -See the [authorization overview](../fundamentals-and-concepts/authorization.mdx) and -[auth example](../basic-tutorials/auth.mdx) for general information about authorization in +See the [authorization overview](../soroban-internals/authorization.mdx) and +[auth example](../tutorials/auth.mdx) for general information about authorization in Soroban. The token contract contains three kinds of operations that follow the token diff --git a/docs/tutorials/timelock.mdx b/docs/tutorials/timelock.mdx index d05f870a..540c6f11 100644 --- a/docs/tutorials/timelock.mdx +++ b/docs/tutorials/timelock.mdx @@ -20,7 +20,7 @@ tags: /> diff --git a/docs/tutorials/tokens.mdx b/docs/tutorials/tokens.mdx index cff5d1c3..f891b6dd 100644 --- a/docs/tutorials/tokens.mdx +++ b/docs/tutorials/tokens.mdx @@ -17,7 +17,7 @@ tags: /> diff --git a/docs/tutorials/upgrading-contracts.mdx b/docs/tutorials/upgrading-contracts.mdx index af204dc9..46ea0b2e 100644 --- a/docs/tutorials/upgrading-contracts.mdx +++ b/docs/tutorials/upgrading-contracts.mdx @@ -17,7 +17,7 @@ tags: /> @@ -82,7 +82,7 @@ pub fn upgrade(e: Env, new_wasm_hash: BytesN<32>) { The `update_current_contract_wasm` host function will also emit a `SYSTEM` contract [event] that contains the old and new wasm reference, allowing downstream users to be notified when a contract they use is updated. The event structure will have `topics = ["executable_update", old_executable: ContractExecutable, old_executable: ContractExecutable]` and `data = []`. [here]: https://docs.rs/soroban-sdk/20.0.0-rc2/soroban_sdk/struct.Env.html#method.update_current_contract_wasm -[event]: ../fundamentals-and-concepts/events.mdx#event-types +[event]: ../soroban-internals/events.mdx#event-types ## Tests diff --git a/docs/tutorials/wasm-metadata.mdx b/docs/tutorials/wasm-metadata.mdx index c80bb412..5f6c8507 100644 --- a/docs/tutorials/wasm-metadata.mdx +++ b/docs/tutorials/wasm-metadata.mdx @@ -17,7 +17,7 @@ tags: /> From 7e32c195dea556069fc73386aa3fd1385fe0afbe Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:49:01 -0600 Subject: [PATCH 06/95] docs: renaming soroban internals in category file --- docs/soroban-internals/_category_.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/soroban-internals/_category_.json b/docs/soroban-internals/_category_.json index 8b075cc5..0a02b8ff 100644 --- a/docs/soroban-internals/_category_.json +++ b/docs/soroban-internals/_category_.json @@ -1,6 +1,6 @@ { "position": 50, - "label": "Fundamentals and Concepts", + "label": "Soroban Internals", "link": { "type": "generated-index" } From 084f3ca51f226086965af07b8ddb30113229b6bb Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 10:52:28 -0600 Subject: [PATCH 07/95] docs: remove old "command line reference" category --- docs/command-line-reference/_category_.json | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/command-line-reference/_category_.json diff --git a/docs/command-line-reference/_category_.json b/docs/command-line-reference/_category_.json deleted file mode 100644 index f133e26a..00000000 --- a/docs/command-line-reference/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 0, - "label": "Command-line Reference", - "link": { - "type": "generated-index" - } -} From 6877e3bcdaa9b97e892030783fe76f0af61ad5eb Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:06:16 -0600 Subject: [PATCH 08/95] docs: add tokens directory, rearrange sidebars --- docs/getting-started/_category_.json | 4 ++-- docs/index.mdx | 2 +- docs/soroban-internals/_category_.json | 2 +- docs/soroban-internals/faq.mdx | 2 +- .../invoking-contracts-with-transactions.mdx | 2 +- docs/tokens/_category_.json | 7 +++++++ .../stellar-asset-contract.mdx | 17 +++++++---------- .../interfaces => tokens}/token-interface.mdx | 2 +- docs/tutorials/_category_.json | 2 +- docs/tutorials/tokens.mdx | 4 ++-- 10 files changed, 24 insertions(+), 20 deletions(-) create mode 100644 docs/tokens/_category_.json rename docs/{tutorials => tokens}/stellar-asset-contract.mdx (94%) rename docs/{reference/interfaces => tokens}/token-interface.mdx (99%) diff --git a/docs/getting-started/_category_.json b/docs/getting-started/_category_.json index 6871e3ab..f1fc5af6 100644 --- a/docs/getting-started/_category_.json +++ b/docs/getting-started/_category_.json @@ -1,7 +1,7 @@ { - "position": 10, + "position": 20, "label": "Getting Started", "link": { "type": "generated-index" } -} \ No newline at end of file +} diff --git a/docs/index.mdx b/docs/index.mdx index a5e6734f..5ad3941b 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 0 +sidebar_position: 10 title: Welcome --- diff --git a/docs/soroban-internals/_category_.json b/docs/soroban-internals/_category_.json index 0a02b8ff..ea4caea7 100644 --- a/docs/soroban-internals/_category_.json +++ b/docs/soroban-internals/_category_.json @@ -1,5 +1,5 @@ { - "position": 50, + "position": 40, "label": "Soroban Internals", "link": { "type": "generated-index" diff --git a/docs/soroban-internals/faq.mdx b/docs/soroban-internals/faq.mdx index 7d5919e9..6da413f4 100644 --- a/docs/soroban-internals/faq.mdx +++ b/docs/soroban-internals/faq.mdx @@ -41,7 +41,7 @@ Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Ste ### Can Soroban contracts interact with Stellar assets? -Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](../tutorials/stellar-asset-contract.mdx). +Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](../tokens/stellar-asset-contract.mdx). ### Do issuers of Stellar assets maintain their authorization over an asset that has been sent to a non-account identifier in Soroban? (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK) diff --git a/docs/soroban-internals/invoking-contracts-with-transactions.mdx b/docs/soroban-internals/invoking-contracts-with-transactions.mdx index 9b8eb9fa..5a44343a 100644 --- a/docs/soroban-internals/invoking-contracts-with-transactions.mdx +++ b/docs/soroban-internals/invoking-contracts-with-transactions.mdx @@ -265,7 +265,7 @@ The `InvokeHostFunctionOp` can be used to perform the following Soroban operatio - Invoke contract functions. - Upload Wasm of the new contracts. -- Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../tutorials/stellar-asset-contract.mdx)). +- Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../tokens/stellar-asset-contract.mdx)). [`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli diff --git a/docs/tokens/_category_.json b/docs/tokens/_category_.json new file mode 100644 index 00000000..cde3c06a --- /dev/null +++ b/docs/tokens/_category_.json @@ -0,0 +1,7 @@ +{ + "position": 50, + "label": "Tokens", + "link": { + "type": "generated-index" + } +} diff --git a/docs/tutorials/stellar-asset-contract.mdx b/docs/tokens/stellar-asset-contract.mdx similarity index 94% rename from docs/tutorials/stellar-asset-contract.mdx rename to docs/tokens/stellar-asset-contract.mdx index ea5e1a43..4607cda3 100644 --- a/docs/tutorials/stellar-asset-contract.mdx +++ b/docs/tokens/stellar-asset-contract.mdx @@ -1,10 +1,7 @@ --- -sidebar_position: 2 +sidebar_position: 20 title: Stellar Asset Contract description: Use Stellar assets on Soroban. -tags: - - tutorial - - advanced --- @@ -17,7 +14,7 @@ tags: /> @@ -44,7 +41,7 @@ assets. For this reason, we introduced the Stellar Asset Contract, or SAC for short, which allows users to use their Stellar account and trustline balances in Soroban. -The SAC implements the [token interface](../reference/interfaces/token-interface), which is similar to the +The SAC implements the [token interface](token-interface.mdx), which is similar to the widely used ERC-20 token standard. This should make it easier for existing smart contract developers to get started on Stellar. @@ -131,7 +128,7 @@ See the [authorization overview](../soroban-internals/authorization.mdx) and Soroban. The token contract contains three kinds of operations that follow the token -[interface](../reference/interfaces/token-interface#code): +[interface](token-interface.mdx#code): - getters, such as `balance`, which do not change the state of the contract - unprivileged mutators, such as `incr_allow` and `xfer`, which change the state @@ -182,9 +179,9 @@ impl MyContract { See the full examples that utilize the token contract in various ways for more details: -- [Timelock](timelock.mdx) and [single offer](single-offer-sale.mdx) move token +- [Timelock](../tutorials/timelock.mdx) and [single offer](../tutorials/single-offer-sale.mdx) move token via `xfer` to and from the contract -- [Atomic swap](atomic-swap.mdx) uses `incr_allow` to transfer token on behalf +- [Atomic swap](../tutorials/atomic-swap.mdx) uses `incr_allow` to transfer token on behalf of the user Notice, that these examples don't do anything to support SAC specifically. @@ -207,6 +204,6 @@ implementation. ## Contract Interface This interface can be found in the [SDK]. It extends the common -[token interface](tokens.mdx). +[token interface](token-interface.mdx). [SDK]: https://github.com/stellar/rs-soroban-sdk/blob/v20.0.0-rc2/soroban-sdk/src/token.rs diff --git a/docs/reference/interfaces/token-interface.mdx b/docs/tokens/token-interface.mdx similarity index 99% rename from docs/reference/interfaces/token-interface.mdx rename to docs/tokens/token-interface.mdx index 0d1b18d0..45e5031e 100644 --- a/docs/reference/interfaces/token-interface.mdx +++ b/docs/tokens/token-interface.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 10 title: Token Interface description: The common interface implemented by tokens that are compatible with Soroban's built-in tokens. --- diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json index 8c3f9dc6..74f2f140 100644 --- a/docs/tutorials/_category_.json +++ b/docs/tutorials/_category_.json @@ -1,5 +1,5 @@ { - "position": 40, + "position": 30, "label": "Tutorials", "link": { "type": "generated-index" diff --git a/docs/tutorials/tokens.mdx b/docs/tutorials/tokens.mdx index f891b6dd..e67f6dd0 100644 --- a/docs/tutorials/tokens.mdx +++ b/docs/tutorials/tokens.mdx @@ -31,7 +31,7 @@ the [Token Interface]. [oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v20.0.0-rc2 [token example]: https://github.com/stellar/soroban-examples/tree/v20.0.0-rc2/token -[Token Interface]: ../reference/interfaces/token-interface.mdx +[Token Interface]: ../tokens/token-interface.mdx ## Run the Example @@ -551,7 +551,7 @@ This example contract, **global** however, demonstrates how a smart contract tok constructed that doesn't take advantage of the Stellar Asset Contract, but does still satisfy the commonly used Token Interface to maximize interoperability. -[Stellar Asset Contract]: stellar-asset-contract.mdx +[Stellar Asset Contract]: ../tokens/stellar-asset-contract.mdx [later]: #compatibility-with-stellar-assets ### Separation of Functionality From 6c77040887999c2d0507446c7692ff4e60151226 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:21:51 -0600 Subject: [PATCH 09/95] docs: rearrange migration from evm guide --- docs/migrate/_category_.json | 7 +++++++ docs/migrate/cosmos.mdx | 7 +++++++ docs/migrate/evm/_category_.json | 7 +++++++ .../evm}/introduction-to-solidity-and-rust.mdx | 0 .../evm}/smart-contract-deployment.mdx | 0 .../evm}/solidity-and-rust-advanced-concepts.mdx | 2 +- .../evm}/solidity-and-rust-basics.mdx | 0 docs/migrate/near.mdx | 7 +++++++ docs/migrate/solana.mdx | 7 +++++++ docs/soroban-internals/migrating-from-evm/_category_.json | 7 ------- nginx/includes/redirects.conf | 3 +++ 11 files changed, 39 insertions(+), 8 deletions(-) create mode 100644 docs/migrate/_category_.json create mode 100644 docs/migrate/cosmos.mdx create mode 100644 docs/migrate/evm/_category_.json rename docs/{soroban-internals/migrating-from-evm => migrate/evm}/introduction-to-solidity-and-rust.mdx (100%) rename docs/{soroban-internals/migrating-from-evm => migrate/evm}/smart-contract-deployment.mdx (100%) rename docs/{soroban-internals/migrating-from-evm => migrate/evm}/solidity-and-rust-advanced-concepts.mdx (99%) rename docs/{soroban-internals/migrating-from-evm => migrate/evm}/solidity-and-rust-basics.mdx (100%) create mode 100644 docs/migrate/near.mdx create mode 100644 docs/migrate/solana.mdx delete mode 100644 docs/soroban-internals/migrating-from-evm/_category_.json diff --git a/docs/migrate/_category_.json b/docs/migrate/_category_.json new file mode 100644 index 00000000..650b54d1 --- /dev/null +++ b/docs/migrate/_category_.json @@ -0,0 +1,7 @@ +{ + "position": 60, + "label": "Migrate from Another Chain", + "link": { + "type": "generated-index" + } +} diff --git a/docs/migrate/cosmos.mdx b/docs/migrate/cosmos.mdx new file mode 100644 index 00000000..372e592b --- /dev/null +++ b/docs/migrate/cosmos.mdx @@ -0,0 +1,7 @@ +--- +sidebar_position: 30 +title: Cosmos +description: Migrate your smart contract code from Cosmos to Soroban +--- + +I dunno, like copy/paste it? diff --git a/docs/migrate/evm/_category_.json b/docs/migrate/evm/_category_.json new file mode 100644 index 00000000..ada35ff5 --- /dev/null +++ b/docs/migrate/evm/_category_.json @@ -0,0 +1,7 @@ +{ + "position": 10, + "label": "EVM Networks", + "link": { + "type": "generated-index" + } +} diff --git a/docs/soroban-internals/migrating-from-evm/introduction-to-solidity-and-rust.mdx b/docs/migrate/evm/introduction-to-solidity-and-rust.mdx similarity index 100% rename from docs/soroban-internals/migrating-from-evm/introduction-to-solidity-and-rust.mdx rename to docs/migrate/evm/introduction-to-solidity-and-rust.mdx diff --git a/docs/soroban-internals/migrating-from-evm/smart-contract-deployment.mdx b/docs/migrate/evm/smart-contract-deployment.mdx similarity index 100% rename from docs/soroban-internals/migrating-from-evm/smart-contract-deployment.mdx rename to docs/migrate/evm/smart-contract-deployment.mdx diff --git a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx b/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx similarity index 99% rename from docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx rename to docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx index b6cc44cc..d1510079 100644 --- a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-advanced-concepts.mdx +++ b/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx @@ -542,7 +542,7 @@ In contrast to Solidity's global variables, Soroban relies on passing an [`Env`] The `Env` provides access to information about the currently executing contract, who invoked it, contract data, functions for signing, hashing, etc. -For instance, you would use `env.storage().persistent().get(key)` to access a `persistent` target value from the contract's [storage](https://docs.rs/soroban-sdk/latest/soroban_sdk/struct.Env.html). Read more about the different storage types [here](../persisting-data.mdx). +For instance, you would use `env.storage().persistent().get(key)` to access a `persistent` target value from the contract's [storage](https://docs.rs/soroban-sdk/latest/soroban_sdk/struct.Env.html). Read more about the different storage types [here](../../soroban-internals/persisting-data.mdx). - `env.storage()` is used to get a struct for accessing and updating contract data that has been stored. - Used as `env.storage().persistent().get()` or `env.persistent().storage().set()`. diff --git a/docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx similarity index 100% rename from docs/soroban-internals/migrating-from-evm/solidity-and-rust-basics.mdx rename to docs/migrate/evm/solidity-and-rust-basics.mdx diff --git a/docs/migrate/near.mdx b/docs/migrate/near.mdx new file mode 100644 index 00000000..78ca55a7 --- /dev/null +++ b/docs/migrate/near.mdx @@ -0,0 +1,7 @@ +--- +sidebar_position: 40 +title: Near +description: Migrate your smart contract code from Near to Soroban +--- + +I dunno, like copy/paste it? diff --git a/docs/migrate/solana.mdx b/docs/migrate/solana.mdx new file mode 100644 index 00000000..1a982326 --- /dev/null +++ b/docs/migrate/solana.mdx @@ -0,0 +1,7 @@ +--- +sidebar_position: 20 +title: Solana +description: Migrate your smart contract code from Solana to Soroban +--- + +I dunno, like copy/paste it? diff --git a/docs/soroban-internals/migrating-from-evm/_category_.json b/docs/soroban-internals/migrating-from-evm/_category_.json deleted file mode 100644 index ee88e50f..00000000 --- a/docs/soroban-internals/migrating-from-evm/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 16, - "label": "Migrating from EVM", - "link": { - "type": "generated-index" - } -} diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 32c2c16e..69b3d7a3 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -24,3 +24,6 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # "fundamentals-and-concepts" is now "soroban-internals" # all of the "basic-tutorials" are now in "tutorials" # all of the "advanced-tutorials" are now in "tutorials" +# "reference/interfaces/token-interface" has moved to "tokens/token-interface" +# "tutorials/stellar-asset-contract" has moved to "tokens/stellar-asset-contract" +# "soroban-internals/migrate-from-evm" has moved to "migrate/evm" From f929a95047c4e49e23035ff1baa7c38f4b06c5b1 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:22:50 -0600 Subject: [PATCH 10/95] docs: remove unused reference/interfaces category --- docs/reference/interfaces/_category_.json | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/reference/interfaces/_category_.json diff --git a/docs/reference/interfaces/_category_.json b/docs/reference/interfaces/_category_.json deleted file mode 100644 index 430dd772..00000000 --- a/docs/reference/interfaces/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 2, - "label": "Interfaces", - "link": { - "type": "generated-index" - } -} From d44e9981a6ebadd759cca635a04309a41d39935e Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:27:41 -0600 Subject: [PATCH 11/95] docs: move "reference" section to "resources" --- docs/getting-started/create-an-app.mdx | 4 ++-- docs/getting-started/deploy-incrementor.mdx | 4 ++-- docs/getting-started/deploy-to-testnet.mdx | 2 +- docs/migrate/evm/smart-contract-deployment.mdx | 4 ++-- docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx | 2 +- docs/migrate/evm/solidity-and-rust-basics.mdx | 4 ++-- docs/{reference => resources}/_category_.json | 4 ++-- docs/{reference => resources}/freighter.mdx | 0 docs/{reference => resources}/releases.mdx | 0 docs/{reference => resources}/rpc-list.mdx | 0 docs/{reference => resources}/rpc.mdx | 0 docs/{reference => resources}/sdks/_category_.json | 0 docs/{reference => resources}/sdks/assemblyscript-sdk.mdx | 0 docs/{reference => resources}/sdks/build-your-own-sdk.mdx | 0 docs/{reference => resources}/sdks/data-providers.mdx | 0 docs/{reference => resources}/sdks/elixir.mdx | 0 docs/{reference => resources}/sdks/flutter-sdk.mdx | 0 docs/{reference => resources}/sdks/ios-sdk.mdx | 0 docs/{reference => resources}/sdks/java.mdx | 0 docs/{reference => resources}/sdks/js.mdx | 0 docs/{reference => resources}/sdks/php-sdk.mdx | 0 docs/{reference => resources}/sdks/python.mdx | 0 docs/{reference => resources}/sdks/rust.mdx | 0 docs/{reference => resources}/soroban-cli.mdx | 0 docs/{reference => resources}/testnet.mdx | 0 docs/soroban-internals/built-in-types.mdx | 2 +- docs/soroban-internals/fully-typed-contracts.mdx | 4 ++-- docs/tutorials/liquidity-pool.mdx | 4 ++-- docs/tutorials/tokens.mdx | 4 ++-- nginx/includes/redirects.conf | 3 ++- 30 files changed, 21 insertions(+), 20 deletions(-) rename docs/{reference => resources}/_category_.json (54%) rename docs/{reference => resources}/freighter.mdx (100%) rename docs/{reference => resources}/releases.mdx (100%) rename docs/{reference => resources}/rpc-list.mdx (100%) rename docs/{reference => resources}/rpc.mdx (100%) rename docs/{reference => resources}/sdks/_category_.json (100%) rename docs/{reference => resources}/sdks/assemblyscript-sdk.mdx (100%) rename docs/{reference => resources}/sdks/build-your-own-sdk.mdx (100%) rename docs/{reference => resources}/sdks/data-providers.mdx (100%) rename docs/{reference => resources}/sdks/elixir.mdx (100%) rename docs/{reference => resources}/sdks/flutter-sdk.mdx (100%) rename docs/{reference => resources}/sdks/ios-sdk.mdx (100%) rename docs/{reference => resources}/sdks/java.mdx (100%) rename docs/{reference => resources}/sdks/js.mdx (100%) rename docs/{reference => resources}/sdks/php-sdk.mdx (100%) rename docs/{reference => resources}/sdks/python.mdx (100%) rename docs/{reference => resources}/sdks/rust.mdx (100%) rename docs/{reference => resources}/soroban-cli.mdx (100%) rename docs/{reference => resources}/testnet.mdx (100%) diff --git a/docs/getting-started/create-an-app.mdx b/docs/getting-started/create-an-app.mdx index 96dd2ac3..71b24d68 100644 --- a/docs/getting-started/create-an-app.mdx +++ b/docs/getting-started/create-an-app.mdx @@ -130,7 +130,7 @@ While `hello` is a simple view-only/read method, `increment` changes on-chain st The way signing works in a browser is with a _wallet_. Wallets can be web apps, browser extensions, standalone apps, or even separate hardware devices. -Right now, the wallet that best supports Soroban is [Freighter](../reference/freighter.mdx). It is available as a Firefox Add-on, as well as extensions for Chrome and Brave. Go ahead and [install it now](https://freighter.app). +Right now, the wallet that best supports Soroban is [Freighter](../resources/freighter.mdx). It is available as a Firefox Add-on, as well as extensions for Chrome and Brave. Go ahead and [install it now](https://freighter.app). Once it's installed, open it up by clicking the extension icon. If this is your first time using Freighter, you will need to create a new wallet. Go through the prompts to create a password and save your recovery passphrase. @@ -485,4 +485,4 @@ At this point, you've seen a full end-to-end example of building on Soroban! Wha - See more complex example contracts in the [Basic Tutorials](/docs/category/tutorials) and [Advanced Tutorials](/docs/category/tutorials) sections. - Learn more about the [fundamentals and concepts](/docs/category/soroban-internals) of Soroban. -- Check out a more full-featured [example app](https://github.com/stellar/soroban-example-dapp), which uses React rather than vanilla JavaScript and Next.js rather than Astro. This app also has a more complex setup & initialization process, with the option of using a [locally-hosted RPC node](../reference/rpc.mdx). +- Check out a more full-featured [example app](https://github.com/stellar/soroban-example-dapp), which uses React rather than vanilla JavaScript and Next.js rather than Astro. This app also has a more complex setup & initialization process, with the option of using a [locally-hosted RPC node](../resources/rpc.mdx). diff --git a/docs/getting-started/deploy-incrementor.mdx b/docs/getting-started/deploy-incrementor.mdx index 4d4da538..4d9679e4 100644 --- a/docs/getting-started/deploy-incrementor.mdx +++ b/docs/getting-started/deploy-incrementor.mdx @@ -77,9 +77,9 @@ Run it a few more times to watch the count change. Sometimes you'll need to run your own node: -- Production apps! Stellar maintains public test RPC nodes for Testnet and Futurenet, but not for Mainnet. Instead, you will need to run your own node, and point your app at that. If you want to use a software-as-a-service platform for this, [various providers](../reference/rpc-list.mdx) are available. +- Production apps! Stellar maintains public test RPC nodes for Testnet and Futurenet, but not for Mainnet. Instead, you will need to run your own node, and point your app at that. If you want to use a software-as-a-service platform for this, [various providers](../resources/rpc-list.mdx) are available. - When you need a network that differs from the version deployed to Testnet. -The Soroban team maintains Docker containers that makes this as straightforward as possible. See the [RPC](../reference/rpc.mdx) reference for details. +The Soroban team maintains Docker containers that makes this as straightforward as possible. See the [RPC](../resources/rpc.mdx) reference for details. Up next, we'll use the deployed contracts to build a simple web app. diff --git a/docs/getting-started/deploy-to-testnet.mdx b/docs/getting-started/deploy-to-testnet.mdx index 7d0a395b..6656aba4 100644 --- a/docs/getting-started/deploy-to-testnet.mdx +++ b/docs/getting-started/deploy-to-testnet.mdx @@ -53,7 +53,7 @@ Using the code we wrote in [Write a Contract](hello-world.mdx#write-a-contract) :::info -In the background, the CLI is making RPC calls. For information on that checkout out the [RPC](../reference/rpc.mdx) reference page. +In the background, the CLI is making RPC calls. For information on that checkout out the [RPC](../resources/rpc.mdx) reference page. ::: diff --git a/docs/migrate/evm/smart-contract-deployment.mdx b/docs/migrate/evm/smart-contract-deployment.mdx index 6a0a98eb..adb279ad 100644 --- a/docs/migrate/evm/smart-contract-deployment.mdx +++ b/docs/migrate/evm/smart-contract-deployment.mdx @@ -26,7 +26,7 @@ Soroban and Hardhat are both frameworks that enable developers to build, test, a ### Soroban Framework -Soroban is a Rust-based framework tailored for developing smart contracts on the Stellar network. Designed as a lightweight framework, with [tools to support developers](../../reference/soroban-cli), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. +Soroban is a Rust-based framework tailored for developing smart contracts on the Stellar network. Designed as a lightweight framework, with [tools to support developers](../../resources/soroban-cli), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. ### Hardhat @@ -62,7 +62,7 @@ async function main() { ### Soroban Client -Soroban offers a comparable library, [`js-soroban-client`](../../reference/sdks/js), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for `soroban-rpc` methods, simplifying the process of building and signing transactions. Additionally, `js-soroban-client` streamlines communication with `soroban-rpc` instances and supports submitting transactions or querying network state with ease. +Soroban offers a comparable library, [`js-soroban-client`](../../resources/sdks/js), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for `soroban-rpc` methods, simplifying the process of building and signing transactions. Additionally, `js-soroban-client` streamlines communication with `soroban-rpc` instances and supports submitting transactions or querying network state with ease. ### Scripts diff --git a/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx b/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx index d1510079..641a5414 100644 --- a/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx +++ b/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx @@ -409,7 +409,7 @@ It's worth mentioning that the Soroban Rust SDK comes with several built-in requ Interfaces are an essential part of building smart contracts with Soroban. -There are many types of smart contract interfaces, and each has a specific purpose. One example of an interface built with Soroban is the [Token Interface](../../reference/interfaces/token-interface). This interface ensures that tokens deployed on Soroban are interoperable with Soroban's built-in tokens (such as the Stellar Asset Contract). The Token Interface consists of three compatibility requirements: +There are many types of smart contract interfaces, and each has a specific purpose. One example of an interface built with Soroban is the [Token Interface](../../resources/interfaces/token-interface). This interface ensures that tokens deployed on Soroban are interoperable with Soroban's built-in tokens (such as the Stellar Asset Contract). The Token Interface consists of three compatibility requirements: - `function interface` - `authorization` diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index 1b0af1e3..ed69cc0f 100644 --- a/docs/migrate/evm/solidity-and-rust-basics.mdx +++ b/docs/migrate/evm/solidity-and-rust-basics.mdx @@ -455,7 +455,7 @@ impl IncrementContract { } ``` -This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](../../reference/sdks/rust), a Rust-based smart contract development toolkit developed by the [Stellar Development Foundation (SDF)](https://stellar.org/foundation). The Soroban Rust SDK provides a powerful set of tools for writing smart contracts that run on the Soroban Virtual Machine. +This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](../../resources/sdks/rust), a Rust-based smart contract development toolkit developed by the [Stellar Development Foundation (SDF)](https://stellar.org/foundation). The Soroban Rust SDK provides a powerful set of tools for writing smart contracts that run on the Soroban Virtual Machine. Here's a line-by-line explanation of what the code is doing: @@ -541,7 +541,7 @@ env.storage().instance().get(&COUNTER).unwrap_or(0) This is a repeat of the code we saw earlier, which retrieves the value associated with the key `COUNTER` from the contract storage. If there is no value set for the key `COUNTER`, a default value of 0 is used. Finally, the `unwrap()` method is called to extract the actual value from the `Ok` wrapper, which is then returned to the caller of the function. -Now that we have written our smart contract, it's time to explore how we can interact with it using the [Soroban-CLI](../../reference/soroban-cli), one of many robust [Developer Tools](http://localhost:3000/docs/developer-tools) available. This powerful command-line tool allows us to interact with the Soroban Virtual Machine from a local machine, providing us with an efficient and flexible way to manage our smart contract. +Now that we have written our smart contract, it's time to explore how we can interact with it using the [Soroban-CLI](../../resources/soroban-cli), one of many robust [Developer Tools](http://localhost:3000/docs/developer-tools) available. This powerful command-line tool allows us to interact with the Soroban Virtual Machine from a local machine, providing us with an efficient and flexible way to manage our smart contract. ### Interacting with the Rust Smart Counter diff --git a/docs/reference/_category_.json b/docs/resources/_category_.json similarity index 54% rename from docs/reference/_category_.json rename to docs/resources/_category_.json index f6d95cfe..37edb4d5 100644 --- a/docs/reference/_category_.json +++ b/docs/resources/_category_.json @@ -1,6 +1,6 @@ { - "position": 50, - "label": "Reference", + "position": 70, + "label": "Resources", "link": { "type": "generated-index" } diff --git a/docs/reference/freighter.mdx b/docs/resources/freighter.mdx similarity index 100% rename from docs/reference/freighter.mdx rename to docs/resources/freighter.mdx diff --git a/docs/reference/releases.mdx b/docs/resources/releases.mdx similarity index 100% rename from docs/reference/releases.mdx rename to docs/resources/releases.mdx diff --git a/docs/reference/rpc-list.mdx b/docs/resources/rpc-list.mdx similarity index 100% rename from docs/reference/rpc-list.mdx rename to docs/resources/rpc-list.mdx diff --git a/docs/reference/rpc.mdx b/docs/resources/rpc.mdx similarity index 100% rename from docs/reference/rpc.mdx rename to docs/resources/rpc.mdx diff --git a/docs/reference/sdks/_category_.json b/docs/resources/sdks/_category_.json similarity index 100% rename from docs/reference/sdks/_category_.json rename to docs/resources/sdks/_category_.json diff --git a/docs/reference/sdks/assemblyscript-sdk.mdx b/docs/resources/sdks/assemblyscript-sdk.mdx similarity index 100% rename from docs/reference/sdks/assemblyscript-sdk.mdx rename to docs/resources/sdks/assemblyscript-sdk.mdx diff --git a/docs/reference/sdks/build-your-own-sdk.mdx b/docs/resources/sdks/build-your-own-sdk.mdx similarity index 100% rename from docs/reference/sdks/build-your-own-sdk.mdx rename to docs/resources/sdks/build-your-own-sdk.mdx diff --git a/docs/reference/sdks/data-providers.mdx b/docs/resources/sdks/data-providers.mdx similarity index 100% rename from docs/reference/sdks/data-providers.mdx rename to docs/resources/sdks/data-providers.mdx diff --git a/docs/reference/sdks/elixir.mdx b/docs/resources/sdks/elixir.mdx similarity index 100% rename from docs/reference/sdks/elixir.mdx rename to docs/resources/sdks/elixir.mdx diff --git a/docs/reference/sdks/flutter-sdk.mdx b/docs/resources/sdks/flutter-sdk.mdx similarity index 100% rename from docs/reference/sdks/flutter-sdk.mdx rename to docs/resources/sdks/flutter-sdk.mdx diff --git a/docs/reference/sdks/ios-sdk.mdx b/docs/resources/sdks/ios-sdk.mdx similarity index 100% rename from docs/reference/sdks/ios-sdk.mdx rename to docs/resources/sdks/ios-sdk.mdx diff --git a/docs/reference/sdks/java.mdx b/docs/resources/sdks/java.mdx similarity index 100% rename from docs/reference/sdks/java.mdx rename to docs/resources/sdks/java.mdx diff --git a/docs/reference/sdks/js.mdx b/docs/resources/sdks/js.mdx similarity index 100% rename from docs/reference/sdks/js.mdx rename to docs/resources/sdks/js.mdx diff --git a/docs/reference/sdks/php-sdk.mdx b/docs/resources/sdks/php-sdk.mdx similarity index 100% rename from docs/reference/sdks/php-sdk.mdx rename to docs/resources/sdks/php-sdk.mdx diff --git a/docs/reference/sdks/python.mdx b/docs/resources/sdks/python.mdx similarity index 100% rename from docs/reference/sdks/python.mdx rename to docs/resources/sdks/python.mdx diff --git a/docs/reference/sdks/rust.mdx b/docs/resources/sdks/rust.mdx similarity index 100% rename from docs/reference/sdks/rust.mdx rename to docs/resources/sdks/rust.mdx diff --git a/docs/reference/soroban-cli.mdx b/docs/resources/soroban-cli.mdx similarity index 100% rename from docs/reference/soroban-cli.mdx rename to docs/resources/soroban-cli.mdx diff --git a/docs/reference/testnet.mdx b/docs/resources/testnet.mdx similarity index 100% rename from docs/reference/testnet.mdx rename to docs/resources/testnet.mdx diff --git a/docs/soroban-internals/built-in-types.mdx b/docs/soroban-internals/built-in-types.mdx index 8a08c4a6..64ef8528 100644 --- a/docs/soroban-internals/built-in-types.mdx +++ b/docs/soroban-internals/built-in-types.mdx @@ -25,7 +25,7 @@ Built-in types are available to all contracts for use as contract function inputs and outputs, and are defined by the [environment] and the [Rust SDK]. [environment]: environment-concepts -[Rust SDK]: ../reference/sdks/rust +[Rust SDK]: ../resources/sdks/rust :::tip diff --git a/docs/soroban-internals/fully-typed-contracts.mdx b/docs/soroban-internals/fully-typed-contracts.mdx index 476feb27..45895a52 100644 --- a/docs/soroban-internals/fully-typed-contracts.mdx +++ b/docs/soroban-internals/fully-typed-contracts.mdx @@ -25,11 +25,11 @@ sidebar_label: Fully-Typed Contracts /> -When you compile a contract created with [soroban-sdk](../reference/sdks/rust.mdx), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. +When you compile a contract created with [soroban-sdk](../resources/sdks/rust.mdx), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. Today, these interface types are formatted using [XDR](https://developers.stellar.org/docs/encyclopedia/xdr), but this [may change](https://github.com/stellar/rs-soroban-sdk/issues/683) down the road. -The important part is that tooling can fetch these interface types to make your life easier. [Soroban CLI](../reference/soroban-cli.mdx) is the first tool to do so. Specifically, one subcommand: +The important part is that tooling can fetch these interface types to make your life easier. [Soroban CLI](../resources/soroban-cli.mdx) is the first tool to do so. Specifically, one subcommand: ## `soroban contract invoke` diff --git a/docs/tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx index a8106f11..21200bb6 100644 --- a/docs/tutorials/liquidity-pool.mdx +++ b/docs/tutorials/liquidity-pool.mdx @@ -594,7 +594,7 @@ Soroban tokens: really care, as long as the functions it needs from the common [Token Interface] are available in the token contract. -[Token Interface]: ../reference/interfaces/token-interface +[Token Interface]: ../resources/interfaces/token-interface #### Creating a Custom `POOL` Token for LP Shares @@ -1015,4 +1015,4 @@ soroban contract invoke \ --min_b 196 \ ``` -[`soroban-cli`]: ../reference/soroban-cli +[`soroban-cli`]: ../resources/soroban-cli diff --git a/docs/tutorials/tokens.mdx b/docs/tutorials/tokens.mdx index e67f6dd0..fc8ae924 100644 --- a/docs/tutorials/tokens.mdx +++ b/docs/tutorials/tokens.mdx @@ -676,7 +676,7 @@ authorization, etc. ::: -[Soroban-CLI]: ../reference/soroban-cli +[Soroban-CLI]: ../resources/soroban-cli ## Tests @@ -1101,4 +1101,4 @@ soroban contract invoke \ --id GBZV3NONYSUDVTEHATQO4BCJVFXJO3XQU5K32X3XREVZKSMMOZFO4ZXR ``` -[`soroban-cli`]: ../reference/soroban-cli +[`soroban-cli`]: ../resources/soroban-cli diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 69b3d7a3..d0989d97 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -24,6 +24,7 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # "fundamentals-and-concepts" is now "soroban-internals" # all of the "basic-tutorials" are now in "tutorials" # all of the "advanced-tutorials" are now in "tutorials" -# "reference/interfaces/token-interface" has moved to "tokens/token-interface" +# "reference/interfaces/token-interface" has moved to "tokens/token-interface" (this'll be a big one!) # "tutorials/stellar-asset-contract" has moved to "tokens/stellar-asset-contract" # "soroban-internals/migrate-from-evm" has moved to "migrate/evm" +# "reference" has moved to "resources" From eb1b93497d27794520afd40c2c33f3981901263a Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:32:37 -0600 Subject: [PATCH 12/95] docs: move "releases" page up a level --- docs/{resources => }/releases.mdx | 4 ++-- docs/resources/rpc.mdx | 2 +- nginx/includes/redirects.conf | 1 + 3 files changed, 4 insertions(+), 3 deletions(-) rename docs/{resources => }/releases.mdx (99%) diff --git a/docs/resources/releases.mdx b/docs/releases.mdx similarity index 99% rename from docs/resources/releases.mdx rename to docs/releases.mdx index 8df464c2..d49a669b 100644 --- a/docs/resources/releases.mdx +++ b/docs/releases.mdx @@ -12,7 +12,7 @@ Release candidates are software releases that are also released to the [Testnet] ::: -[Testnet]: testnet.mdx +[Testnet]: resources/testnet.mdx ## Preview 11 (September 11, 2023): Testnet and Futurenet Edition @@ -565,7 +565,7 @@ See https://github.com/stellar/soroban-tools/releases v0.7.0 for more details. This release comes with a revamp of authorization approach that is breaking for most of the contracts that did any sort of auth logic or used tokens. -[example](../tutorials/auth.mdx) and [authorization overview](../soroban-internals/authorization.mdx) +[example](tutorials/auth.mdx) and [authorization overview](soroban-internals/authorization.mdx) for more details. ### Changelog diff --git a/docs/resources/rpc.mdx b/docs/resources/rpc.mdx index cce5cbb3..8e563282 100644 --- a/docs/resources/rpc.mdx +++ b/docs/resources/rpc.mdx @@ -215,7 +215,7 @@ helm install my-rpc stellar/soroban-rpc \ This example of Helm chart usage highlights some key aspects: -- Set the `global.image.sorobanRpc.tag` to a tag from the [soroban-rpc dockerhub repo](https://hub.docker.com/r/stellar/soroban-rpc) for the image version you want to run. Refer to [the releases page](./releases) to find the correct tag for the Soroban release you are running. +- Set the `global.image.sorobanRpc.tag` to a tag from the [soroban-rpc dockerhub repo](https://hub.docker.com/r/stellar/soroban-rpc) for the image version you want to run. Refer to [the releases page](../releases.mdx) to find the correct tag for the Soroban release you are running. - The RPC server stores a revolving window of recent data from network ledgers to disk. The size of that data varies depending on the network and its transaction volumes, but it has an estimated range between 10 to 100 MB. To ensure the RPC pod has consistent access to disk storage space and read/write throughput, this example demonstrates how to optionally enable the Helm chart deployment to use a `PersistentVolumeClaim` (PVC) of 100MB from `default` storage class on Kubernetes by enabling these persistence parameters: diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index d0989d97..f1c995db 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -28,3 +28,4 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # "tutorials/stellar-asset-contract" has moved to "tokens/stellar-asset-contract" # "soroban-internals/migrate-from-evm" has moved to "migrate/evm" # "reference" has moved to "resources" +# "releases" has moved up one level ("/docs/{reference,resources}/releases" -> "/docs/releases") From 6dd5345610b2af55f6f5cbdd8e0281800beb5969 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:38:33 -0600 Subject: [PATCH 13/95] docs: move FAQ page up one level --- docs/{soroban-internals => }/faq.mdx | 8 ++++---- docs/releases.mdx | 2 +- nginx/includes/redirects.conf | 18 ++++++++++-------- 3 files changed, 15 insertions(+), 13 deletions(-) rename docs/{soroban-internals => }/faq.mdx (94%) diff --git a/docs/soroban-internals/faq.mdx b/docs/faq.mdx similarity index 94% rename from docs/soroban-internals/faq.mdx rename to docs/faq.mdx index 6da413f4..f9db2fb5 100644 --- a/docs/soroban-internals/faq.mdx +++ b/docs/faq.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 2 -title: Soroban on Stellar FAQs +sidebar_position: 80 +title: FAQs description: Frequently asked questions about Soroban on Stellar. --- @@ -17,7 +17,7 @@ description: Frequently asked questions about Soroban on Stellar. /> @@ -41,7 +41,7 @@ Yes. Stellar accounts are shared with Soroban. Smart contacts have access to Ste ### Can Soroban contracts interact with Stellar assets? -Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](../tokens/stellar-asset-contract.mdx). +Yes. Soroban contains a built-in Stellar Asset Contract that is able to interact with classic trustlines. Read more about this [here](tokens/stellar-asset-contract.mdx). ### Do issuers of Stellar assets maintain their authorization over an asset that has been sent to a non-account identifier in Soroban? (AUTH_REQUIRED, AUTH_REVOCABLE, AUTH_CLAWBACK) diff --git a/docs/releases.mdx b/docs/releases.mdx index d49a669b..5a457826 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 90 title: Releases description: Soroban software releases and changelogs. --- diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index f1c995db..74a5f842 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -21,11 +21,13 @@ rewrite "^/docs/getting-started/connect-freighter-wallet$" "/docs/reference/frei rewrite "^/docs/common-interfaces/token$" "/docs/reference/interfaces/token-interface" permanent; rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permanent; # BEGIN re-structure redirects -# "fundamentals-and-concepts" is now "soroban-internals" -# all of the "basic-tutorials" are now in "tutorials" -# all of the "advanced-tutorials" are now in "tutorials" -# "reference/interfaces/token-interface" has moved to "tokens/token-interface" (this'll be a big one!) -# "tutorials/stellar-asset-contract" has moved to "tokens/stellar-asset-contract" -# "soroban-internals/migrate-from-evm" has moved to "migrate/evm" -# "reference" has moved to "resources" -# "releases" has moved up one level ("/docs/{reference,resources}/releases" -> "/docs/releases") +# Nothing has been done here yet, but I'm noting what changes will need to be addressed +# - "fundamentals-and-concepts" is now "soroban-internals" +# - all of the "basic-tutorials" are now in "tutorials" +# - all of the "advanced-tutorials" are now in "tutorials" +# - "reference/interfaces/token-interface" has moved to "tokens/token-interface" (this'll be a big one!) +# - "tutorials/stellar-asset-contract" has moved to "tokens/stellar-asset-contract" +# - "soroban-internals/migrate-from-evm" has moved to "migrate/evm" +# - "reference" has moved to "resources" +# - "releases" has moved up one level ("/docs/{reference,resources}/releases" -> "/docs/releases") +# - "faq" has moved up one level ("/docs/{reference,resources}/faq" -> "/docs/faq") From b2b3def9a4cf61f38596fe121c73e26d564f55fa Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:43:10 -0600 Subject: [PATCH 14/95] docs: move dev tools into resources directory --- docs/migrate/evm/solidity-and-rust-basics.mdx | 2 +- docs/{ => resources}/developer-tools.mdx | 0 nginx/includes/redirects.conf | 1 + 3 files changed, 2 insertions(+), 1 deletion(-) rename docs/{ => resources}/developer-tools.mdx (100%) diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index ed69cc0f..27fa68f3 100644 --- a/docs/migrate/evm/solidity-and-rust-basics.mdx +++ b/docs/migrate/evm/solidity-and-rust-basics.mdx @@ -541,7 +541,7 @@ env.storage().instance().get(&COUNTER).unwrap_or(0) This is a repeat of the code we saw earlier, which retrieves the value associated with the key `COUNTER` from the contract storage. If there is no value set for the key `COUNTER`, a default value of 0 is used. Finally, the `unwrap()` method is called to extract the actual value from the `Ok` wrapper, which is then returned to the caller of the function. -Now that we have written our smart contract, it's time to explore how we can interact with it using the [Soroban-CLI](../../resources/soroban-cli), one of many robust [Developer Tools](http://localhost:3000/docs/developer-tools) available. This powerful command-line tool allows us to interact with the Soroban Virtual Machine from a local machine, providing us with an efficient and flexible way to manage our smart contract. +Now that we have written our smart contract, it's time to explore how we can interact with it using the [Soroban-CLI](../../resources/soroban-cli), one of many robust [Developer Tools](../../resources/developer-tools.mdx) available. This powerful command-line tool allows us to interact with the Soroban Virtual Machine from a local machine, providing us with an efficient and flexible way to manage our smart contract. ### Interacting with the Rust Smart Counter diff --git a/docs/developer-tools.mdx b/docs/resources/developer-tools.mdx similarity index 100% rename from docs/developer-tools.mdx rename to docs/resources/developer-tools.mdx diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 74a5f842..c03a147e 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -31,3 +31,4 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # - "reference" has moved to "resources" # - "releases" has moved up one level ("/docs/{reference,resources}/releases" -> "/docs/releases") # - "faq" has moved up one level ("/docs/{reference,resources}/faq" -> "/docs/faq") +# - "developer-tools" has moved into the "resources" directory From b024b7a1ece790dd634b0bcdfca3b80d528c939a Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:51:22 -0600 Subject: [PATCH 15/95] docs: move testnet.mdx to networks.mdx --- docs/releases.mdx | 2 +- docs/resources/developer-tools.mdx | 4 ++-- docs/resources/networks.mdx | 29 ++++++++++++++++++++++ docs/resources/sdks/_category_.json | 2 +- docs/resources/testnet.mdx | 37 ----------------------------- nginx/includes/redirects.conf | 1 + 6 files changed, 34 insertions(+), 41 deletions(-) create mode 100644 docs/resources/networks.mdx delete mode 100644 docs/resources/testnet.mdx diff --git a/docs/releases.mdx b/docs/releases.mdx index 5a457826..d9fe42b0 100644 --- a/docs/releases.mdx +++ b/docs/releases.mdx @@ -12,7 +12,7 @@ Release candidates are software releases that are also released to the [Testnet] ::: -[Testnet]: resources/testnet.mdx +[Testnet]: resources/networks.mdx ## Preview 11 (September 11, 2023): Testnet and Futurenet Edition diff --git a/docs/resources/developer-tools.mdx b/docs/resources/developer-tools.mdx index f76485a1..886e54d6 100644 --- a/docs/resources/developer-tools.mdx +++ b/docs/resources/developer-tools.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 60 +sidebar_position: 10 title: Developer Tools --- @@ -11,7 +11,7 @@ All tools currently listed are built and maintained by dedicated community membe ### [Soroban Dev](https://sorobandev.com/) -A web developer’s guide to Soroban. Contains guides for learning Soroban and Rust, developer tools, example applications, and more. +A web developer's guide to Soroban. Contains guides for learning Soroban and Rust, developer tools, example applications, and more. ### [Use Soroban](https://usesoroban.app/) diff --git a/docs/resources/networks.mdx b/docs/resources/networks.mdx new file mode 100644 index 00000000..c324fc58 --- /dev/null +++ b/docs/resources/networks.mdx @@ -0,0 +1,29 @@ +--- +sidebar_position: 3 +title: Networks +description: The shared Soroban test networks. +--- + +Testnet and Futurenet have been made available as the first shared test networks to enable developers to learn, tinker, and build applications on Soroban while being able to interact with other participants. + +| Testnet | Testnet | Futurenet | +| :----------------- | ----------------------------------- | ---------------------------------------- | +| Network Passphrase | `Test SDF Network ; September 2015` | `Test SDF Future Network ; October 2022` | +| Horizon API | https://horizon-testnet.stellar.org | https://horizon-futurenet.stellar.org | +| Friendbot API | https://friendbot.stellar.org | https://friendbot-futurenet.stellar.org | +| Validator | `core-live-testnet.stellar.org` | `core-live-futurenet.stellar.org` | +| History Archive | https://history-testnet.stellar.org | https://history-futurenet.stellar.org | + +:::caution + +Testnet can be reset at any time. A reset erases all accounts, contract data, and contract deployments from the network. + +::: + +:::caution + +All components deployed to Testnet and releases supporting Testnet, such as the [Soroban RPC Server], are in active development and will be unstable at times. They should be treated as development releases with no production capabilities, API or backward compatibility guarantees. + +::: + +[Soroban RPC Server]: https://github.com/stellar/quickstart#soroban-rpc-server diff --git a/docs/resources/sdks/_category_.json b/docs/resources/sdks/_category_.json index 7e1e701e..88f45998 100644 --- a/docs/resources/sdks/_category_.json +++ b/docs/resources/sdks/_category_.json @@ -1,5 +1,5 @@ { - "position": 1, + "position": 20, "label": "SDKs", "link": { "type": "generated-index" diff --git a/docs/resources/testnet.mdx b/docs/resources/testnet.mdx deleted file mode 100644 index 47dcd96e..00000000 --- a/docs/resources/testnet.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -sidebar_position: 3 -title: Testnet -description: The shared Soroban test network. ---- - -Testnet is available as the first shared test network to enable developers to learn, tinker and build applications on Soroban while being able to interact with other participants. - -| Testnet | | -| :----------------- | ----------------------------------- | -| Network Passphrase | `Test SDF Network ; September 2015` | -| Horizon API | https://horizon-testnet.stellar.org | -| Friendbot API | https://friendbot.stellar.org | -| Validator | `core-live-testnet.stellar.org` | -| History Archive | https://history-testnet.stellar.org | - -| Futurenet | | -| :----------------- | ---------------------------------------- | -| Network Passphrase | `Test SDF Future Network ; October 2022` | -| Horizon API | https://horizon-futurenet.stellar.org | -| Friendbot API | https://friendbot-futurenet.stellar.org | -| Validator | `core-live-futurenet.stellar.org` | -| History Archive | https://history-futurenet.stellar.org | - -:::caution - -Testnet can be reset at any time. A reset erases all accounts, contract data, and contract deployments from the network. - -::: - -:::caution - -All components deployed to Testnet and releases supporting Testnet, such as the [Soroban RPC Server], are in active development and will be unstable at times. They should be treated as development releases with no production capabilities, API or backward compatibility guarantees. - -::: - -[Soroban RPC Server]: https://github.com/stellar/quickstart#soroban-rpc-server diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index c03a147e..1bd5d210 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -32,3 +32,4 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # - "releases" has moved up one level ("/docs/{reference,resources}/releases" -> "/docs/releases") # - "faq" has moved up one level ("/docs/{reference,resources}/faq" -> "/docs/faq") # - "developer-tools" has moved into the "resources" directory +# - "resources/testnet" has been moved to "resources/networks" From 7c4f8ac9353d6f240002ec2908c202732b51a5dc Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 11:54:50 -0600 Subject: [PATCH 16/95] docs: rearrange items in resources directory --- docs/resources/freighter.mdx | 2 +- docs/resources/networks.mdx | 2 +- docs/resources/rpc-list.mdx | 2 +- docs/resources/rpc.mdx | 2 +- docs/resources/soroban-cli.mdx | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/resources/freighter.mdx b/docs/resources/freighter.mdx index 0b0b2a8c..7bbdf63a 100644 --- a/docs/resources/freighter.mdx +++ b/docs/resources/freighter.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 60 title: Freighter Wallet description: Freighter is a browser extension that can sign Soroban transactions. --- diff --git a/docs/resources/networks.mdx b/docs/resources/networks.mdx index c324fc58..2a34d52b 100644 --- a/docs/resources/networks.mdx +++ b/docs/resources/networks.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 30 title: Networks description: The shared Soroban test networks. --- diff --git a/docs/resources/rpc-list.mdx b/docs/resources/rpc-list.mdx index 4bf267ce..20946de4 100644 --- a/docs/resources/rpc-list.mdx +++ b/docs/resources/rpc-list.mdx @@ -1,6 +1,6 @@ --- +sidebar_position: 50 title: RPC Providers -sidebar_position: 7 --- ## Ecosystem Providers diff --git a/docs/resources/rpc.mdx b/docs/resources/rpc.mdx index 8e563282..b59877cd 100644 --- a/docs/resources/rpc.mdx +++ b/docs/resources/rpc.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 40 title: RPC Usage --- diff --git a/docs/resources/soroban-cli.mdx b/docs/resources/soroban-cli.mdx index f7f2a2d8..a25dbb29 100644 --- a/docs/resources/soroban-cli.mdx +++ b/docs/resources/soroban-cli.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 70 title: Soroban CLI description: The tool for interacting with deployed contracts. --- @@ -9,7 +9,7 @@ Soroban CLI is the command line interface to Soroban. It allows you to build, de Install Soroban CLI as explained in [Setup](../getting-started/setup). Auto-generated comprehensive reference documentation is available at: -https://github.com/stellar/soroban-tools/blob/v20.0.0-rc2/docs/soroban-cli-full-docs.md +https://github.com/stellar/soroban-tools/blob/v20.0.0-rc.4.1/docs/soroban-cli-full-docs.md Subscribe to releases on the GitHub repository: https://github.com/stellar/soroban-tools From ec542cb73d30e6e8001fc50ebb592670b048c79a Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 12:14:31 -0600 Subject: [PATCH 17/95] docs: collapse various SDK pages into two pages --- docs/resources/sdks/assemblyscript-sdk.mdx | 35 -------- docs/resources/sdks/build-your-own-sdk.mdx | 2 +- docs/resources/sdks/elixir.mdx | 15 ---- docs/resources/sdks/flutter-sdk.mdx | 15 ---- .../sdks/interact-with-contracts.mdx | 89 +++++++++++++++++++ docs/resources/sdks/ios-sdk.mdx | 15 ---- docs/resources/sdks/java.mdx | 11 --- docs/resources/sdks/js.mdx | 16 ---- docs/resources/sdks/php-sdk.mdx | 15 ---- docs/resources/sdks/python.mdx | 18 ---- docs/resources/sdks/rust.mdx | 40 --------- docs/resources/sdks/write-contracts.mdx | 76 ++++++++++++++++ nginx/includes/redirects.conf | 1 + 13 files changed, 167 insertions(+), 181 deletions(-) delete mode 100644 docs/resources/sdks/assemblyscript-sdk.mdx delete mode 100644 docs/resources/sdks/elixir.mdx delete mode 100644 docs/resources/sdks/flutter-sdk.mdx create mode 100644 docs/resources/sdks/interact-with-contracts.mdx delete mode 100644 docs/resources/sdks/ios-sdk.mdx delete mode 100644 docs/resources/sdks/java.mdx delete mode 100644 docs/resources/sdks/js.mdx delete mode 100644 docs/resources/sdks/php-sdk.mdx delete mode 100644 docs/resources/sdks/python.mdx delete mode 100644 docs/resources/sdks/rust.mdx create mode 100644 docs/resources/sdks/write-contracts.mdx diff --git a/docs/resources/sdks/assemblyscript-sdk.mdx b/docs/resources/sdks/assemblyscript-sdk.mdx deleted file mode 100644 index 75d8c308..00000000 --- a/docs/resources/sdks/assemblyscript-sdk.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_position: 5 -title: AssemblyScript SDK -description: as-soroban-sdk supports writing Soroban contracts in AssemblyScript. ---- - -The `as-soroban-sdk` is an open source SDK that supports writing programs for the Soroban smart contract platform by using the AssemblyScript programming language. - -The AssemblyScript Soroban SDK is maintained by dedicated community developer, Soneso. - -:::info - -Report issues and share feedback about the `AssemblyScript Soroban SDK` -[here](https://github.com/Soneso/as-soroban-sdk/issues/new). - -::: - -## SDK Documentation - -SDK documentation is available at: -https://github.com/Soneso/as-soroban-sdk - -## Examples - -Many examples are available at: -https://github.com/Soneso/as-soroban-examples - -## Subscribe to Releases - -Subscribe to releases on the GitHub repository: -https://github.com/Soneso/as-soroban-sdk - -## Add `as-soroban-sdk` as a Dependency - -`npm install as-soroban-sdk` diff --git a/docs/resources/sdks/build-your-own-sdk.mdx b/docs/resources/sdks/build-your-own-sdk.mdx index be78da46..af3d1ade 100644 --- a/docs/resources/sdks/build-your-own-sdk.mdx +++ b/docs/resources/sdks/build-your-own-sdk.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 30 title: Build Your Own SDK description: A guide to developing Soroban SDKs for languages other than Rust. --- diff --git a/docs/resources/sdks/elixir.mdx b/docs/resources/sdks/elixir.mdx deleted file mode 100644 index c8fa23dc..00000000 --- a/docs/resources/sdks/elixir.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 9 -title: Elixir SDK -description: Soroban.ex supports writing Soroban applications in Elixir. ---- - -**Soroban.ex** is an open source library for Elixir to interact with the Soroban-RPC server, and facilitate the deployment and invocation of Soroban smart contracts. - -The Elixir SDK (**Soroban.ex**) can be found on GitHub at https://github.com/kommitters/soroban.ex. - -This SDK is maintained by dedicated community developers, kommitters Open Source. - -## Documentation - -Documentation is available at https://github.com/kommitters/soroban.ex#documentation. diff --git a/docs/resources/sdks/flutter-sdk.mdx b/docs/resources/sdks/flutter-sdk.mdx deleted file mode 100644 index aa5fa273..00000000 --- a/docs/resources/sdks/flutter-sdk.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 7 -title: Flutter SDK -description: stellar-flutter-sdk supports writing Soroban applications in Flutter. ---- - -The `stellar-flutter-sdk` is an open source Stellar SDK for Flutter developers. It provides APIs to build transactions and connect to Horizon. - -It also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. - -The [Flutter Stellar SDK](https://github.com/Soneso/stellar_flutter_sdk) is maintained by dedicated community developer, Soneso. - -## SDK Documentation for Soroban - -The SDK documentation for Soroban features is available [here](https://github.com/Soneso/stellar_flutter_sdk/blob/master/soroban.md). diff --git a/docs/resources/sdks/interact-with-contracts.mdx b/docs/resources/sdks/interact-with-contracts.mdx new file mode 100644 index 00000000..27addcc2 --- /dev/null +++ b/docs/resources/sdks/interact-with-contracts.mdx @@ -0,0 +1,89 @@ +--- +sidebar_position: 20 +title: Interact with Contracts +description: SDKs support writing Soroban applications in many languages. +--- + +## JavaScript SDK + +`js-soroban-client` is a Javascript library for communicating with a Soroban RPC server. It is used for building Stellar apps either on Node.js or in the browser. + +It provides: + +- a networking layer API for soroban-rpc methods. +- facilities for building and signing transactions, for communicating with a soroban-rpc instance, and for submitting transactions or querying network state. + +### SDK Documentation + +SDK documentation is available at: https://github.com/stellar/js-soroban-client + +## Python SDK + +`py-stellar-base` is a Python library for communicating with a Stellar Horizon server. It is used for building Stellar apps on Python. It supports Python 3.7+ as well as PyPy 3.7+. + +This SDK is maintained by a dedicated community developer. + +It provides: + +- a networking layer API for Horizon endpoints. +- facilities for building and signing transactions, for communicating with a Stellar Horizon instance, and for submitting transactions or querying network history. + +### SDK Documentation + +The Python SDK is available at: https://github.com/StellarCN/py-stellar-base + +## iOS SDK + +The `stellar-ios-mac-sdk` is an open source Stellar SDK for iOS & Mac. It provides APIs to build transactions and connect to Horizon. + +It also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. + +The [iOS Stellar SDK](https://github.com/Soneso/stellar-ios-mac-sdk) is maintained by dedicated community developer, Soneso. + +### SDK Documentation for Soroban + +The SDK documentation for Soroban features is available [here](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/soroban.md). + +## Flutter SDK + +The `stellar-flutter-sdk` is an open source Stellar SDK for Flutter developers. It provides APIs to build transactions and connect to Horizon. + +It also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. + +The [Flutter Stellar SDK](https://github.com/Soneso/stellar_flutter_sdk) is maintained by dedicated community developer, Soneso. + +### SDK Documentation for Soroban + +The SDK documentation for Soroban features is available [here](https://github.com/Soneso/stellar_flutter_sdk/blob/master/soroban.md). + +## PHP SDK + +The `stellar-php-sdk` is an open source Stellar SDK for PHP developers. It provides APIs to build transactions and connect to Horizon. + +It also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. + +The [PHP Stellar SDK](https://github.com/Soneso/stellar-php-sdk) is maintained by dedicated community developer, Soneso. + +### SDK Documentation for Soroban + +The SDK documentation for Soroban features is available [here](https://github.com/Soneso/stellar-php-sdk/blob/main/soroban.md). + +## Elixir SDK + +`Soroban.ex` is an open source library for Elixir to interact with the Soroban-RPC server, and facilitate the deployment and invocation of Soroban smart contracts. + +The Elixir SDK (`Soroban.ex`) can be found on GitHub at https://github.com/kommitters/soroban.ex. + +This SDK is maintained by dedicated community developers, kommitters Open Source. + +### SDK Documentation + +Documentation is available at https://github.com/kommitters/soroban.ex#documentation. + +## Java SDK + +`java-stellar-sdk` provides APIs to build transactions and connect to Horizon, it also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. + +### SDK Documentation + +SDK is available at: https://github.com/stellar/java-stellar-sdk diff --git a/docs/resources/sdks/ios-sdk.mdx b/docs/resources/sdks/ios-sdk.mdx deleted file mode 100644 index ecf741a9..00000000 --- a/docs/resources/sdks/ios-sdk.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 6 -title: iOS SDK -description: stellar-ios-mac-sdk supports writing Soroban applications for iOS and Mac. ---- - -The `stellar-ios-mac-sdk` is an open source Stellar SDK for iOS & Mac. It provides APIs to build transactions and connect to Horizon. - -It also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. - -The [iOS Stellar SDK](https://github.com/Soneso/stellar-ios-mac-sdk) is maintained by dedicated community developer, Soneso. - -## SDK Documentation for Soroban - -The SDK documentation for Soroban features is available [here](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/soroban.md). diff --git a/docs/resources/sdks/java.mdx b/docs/resources/sdks/java.mdx deleted file mode 100644 index 2c27ea50..00000000 --- a/docs/resources/sdks/java.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 10 -title: Java SDK -description: java-stellar-sdk supports writing Soroban applications in Java. ---- - -java-stellar-sdk provides APIs to build transactions and connect to Horizon, it also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. - -## Java SDK - -SDK is available at: https://github.com/stellar/java-stellar-sdk diff --git a/docs/resources/sdks/js.mdx b/docs/resources/sdks/js.mdx deleted file mode 100644 index d250b0e6..00000000 --- a/docs/resources/sdks/js.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_position: 3 -title: JavaScript SDK -description: js-soroban-client supports writing Soroban applications in JavaScript. ---- - -js-soroban-client is a Javascript library for communicating with a Soroban RPC server. It is used for building Stellar apps either on Node.js or in the browser. - -It provides: - -- a networking layer API for soroban-rpc methods. -- facilities for building and signing transactions, for communicating with a soroban-rpc instance, and for submitting transactions or querying network state. - -## JavaScript SDK - -SDK is available at: https://github.com/stellar/js-soroban-client diff --git a/docs/resources/sdks/php-sdk.mdx b/docs/resources/sdks/php-sdk.mdx deleted file mode 100644 index 66f1e2ff..00000000 --- a/docs/resources/sdks/php-sdk.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_position: 8 -title: PHP SDK -description: stellar-php-sdk supports writing Soroban applications in PHP. ---- - -The `stellar-php-sdk` is an open source Stellar SDK for PHP developers. It provides APIs to build transactions and connect to Horizon. - -It also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Soroban RPC Server. - -The [PHP Stellar SDK](https://github.com/Soneso/stellar-php-sdk) is maintained by dedicated community developer, Soneso. - -## SDK Documentation for Soroban - -The SDK documentation for Soroban features is available [here](https://github.com/Soneso/stellar-php-sdk/blob/main/soroban.md). diff --git a/docs/resources/sdks/python.mdx b/docs/resources/sdks/python.mdx deleted file mode 100644 index 72158ec3..00000000 --- a/docs/resources/sdks/python.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_position: 4 -title: Python SDK -description: py-stellar-base supports writing Soroban applications in Python. ---- - -py-stellar-base is a Python library for communicating with a Stellar Horizon server. It is used for building Stellar apps on Python. It supports Python 3.7+ as well as PyPy 3.7+. - -This SDK is maintained by a dedicated community developer. - -It provides: - -- a networking layer API for Horizon endpoints. -- facilities for building and signing transactions, for communicating with a Stellar Horizon instance, and for submitting transactions or querying network history. - -## Python SDK - -The Python SDK is available at: https://github.com/StellarCN/py-stellar-base/tree/soroban diff --git a/docs/resources/sdks/rust.mdx b/docs/resources/sdks/rust.mdx deleted file mode 100644 index 4dbef863..00000000 --- a/docs/resources/sdks/rust.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 1 -title: Soroban Rust SDK -description: soroban-sdk supports writing Soroban contracts in Rust. ---- - -The `soroban-sdk` Rust crate contains the Soroban Rust SDK. - -:::info - -Report issues and share feedback about the `soroban-sdk` -[here](https://github.com/stellar/rs-soroban-sdk/issues/new/choose). - -::: - -## SDK Documentation - -SDK documentation is available at: -https://docs.rs/soroban-sdk - -## Subscribe to Releases - -Subscribe to releases on the GitHub repository: -https://github.com/stellar/rs-soroban-sdk - -## Add `soroban-sdk` as a Dependency - -Use [crates.io](https://crates.io/crates/soroban-sdk) to find the version of the -most recent SDK release. - -Add the following sections to the `Cargo.toml` to import the `soroban-sdk` and -replace `$VERSION` with the released version. - -```toml -[dependencies] -soroban-sdk = $VERSION - -[dev_dependencies] -soroban-sdk = { version = $VERSION, features = ["testutils"] } -``` diff --git a/docs/resources/sdks/write-contracts.mdx b/docs/resources/sdks/write-contracts.mdx new file mode 100644 index 00000000..5f902a3f --- /dev/null +++ b/docs/resources/sdks/write-contracts.mdx @@ -0,0 +1,76 @@ +--- +sidebar_position: 10 +title: Write Contracts +description: SDKs support writing Soroban contracts in Rust and AssemblyScript. +--- + +## Soroban Rust SDK + +The `soroban-sdk` Rust crate contains the Soroban Rust SDK. + +:::info + +Report issues and share feedback about the `soroban-sdk` +[here](https://github.com/stellar/rs-soroban-sdk/issues/new/choose). + +::: + +### SDK Documentation + +SDK documentation is available at: +https://docs.rs/soroban-sdk + +### Subscribe to Releases + +Subscribe to releases on the GitHub repository: +https://github.com/stellar/rs-soroban-sdk + +### Add `soroban-sdk` as a Dependency + +Use [crates.io](https://crates.io/crates/soroban-sdk) to find the version of the +most recent SDK release. + +Add the following sections to the `Cargo.toml` to import the `soroban-sdk` and +replace `$VERSION` with the released version. + +```toml +[dependencies] +soroban-sdk = $VERSION + +[dev_dependencies] +soroban-sdk = { version = $VERSION, features = ["testutils"] } +``` + +## AssemblyScript SDK + +The `as-soroban-sdk` is an open source SDK that supports writing programs for the Soroban smart contract platform by using the AssemblyScript programming language. + +The AssemblyScript Soroban SDK is maintained by dedicated community developer, Soneso. + +:::info + +Report issues and share feedback about the `AssemblyScript Soroban SDK` +[here](https://github.com/Soneso/as-soroban-sdk/issues/new). + +::: + +### SDK Documentation + +SDK documentation is available at: +https://github.com/Soneso/as-soroban-sdk + +### Examples + +Many examples are available at: +https://github.com/Soneso/as-soroban-examples + +### Subscribe to Releases + +Subscribe to releases on the GitHub repository: +https://github.com/Soneso/as-soroban-sdk + +### Add `as-soroban-sdk` as a Dependency + +```bash +npm install as-soroban-sdk +``` diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 1bd5d210..07ad9048 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -33,3 +33,4 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # - "faq" has moved up one level ("/docs/{reference,resources}/faq" -> "/docs/faq") # - "developer-tools" has moved into the "resources" directory # - "resources/testnet" has been moved to "resources/networks" +# - various SDK pages have been collapsed into "resources/sdks/{write-contracts,interact-with-contracts}" From 8585b4c0764b002414658c047687183981c3cc90 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 12:17:16 -0600 Subject: [PATCH 18/95] docs: move data-providers up one level --- docs/resources/{sdks => }/data-providers.mdx | 2 +- docs/resources/freighter.mdx | 2 +- docs/resources/soroban-cli.mdx | 2 +- nginx/includes/redirects.conf | 1 + 4 files changed, 4 insertions(+), 3 deletions(-) rename docs/resources/{sdks => }/data-providers.mdx (99%) diff --git a/docs/resources/sdks/data-providers.mdx b/docs/resources/data-providers.mdx similarity index 99% rename from docs/resources/sdks/data-providers.mdx rename to docs/resources/data-providers.mdx index 33fb2a21..7fe65faf 100644 --- a/docs/resources/sdks/data-providers.mdx +++ b/docs/resources/data-providers.mdx @@ -1,6 +1,6 @@ --- title: Data Providers -sidebar_position: 8 +sidebar_position: 60 --- In order for the Stellar network to remain as open and accessible as it has always been, Soroban-related data is available through a number of channels. diff --git a/docs/resources/freighter.mdx b/docs/resources/freighter.mdx index 7bbdf63a..0b2b7923 100644 --- a/docs/resources/freighter.mdx +++ b/docs/resources/freighter.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 60 +sidebar_position: 70 title: Freighter Wallet description: Freighter is a browser extension that can sign Soroban transactions. --- diff --git a/docs/resources/soroban-cli.mdx b/docs/resources/soroban-cli.mdx index a25dbb29..8065cdda 100644 --- a/docs/resources/soroban-cli.mdx +++ b/docs/resources/soroban-cli.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 70 +sidebar_position: 80 title: Soroban CLI description: The tool for interacting with deployed contracts. --- diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 07ad9048..e18e55c1 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -34,3 +34,4 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # - "developer-tools" has moved into the "resources" directory # - "resources/testnet" has been moved to "resources/networks" # - various SDK pages have been collapsed into "resources/sdks/{write-contracts,interact-with-contracts}" +# - "data providers" has moved from "resources/sdks" into just "resources" From 39f322204c39ba8f92cac6f1961fe6cc8501df6c Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 12:26:54 -0600 Subject: [PATCH 19/95] docs: remove some empty categories, move the tutorial template --- docs/advanced-tutorials/_category_.json | 7 ------- docs/basic-tutorials/_category_.json | 7 ------- docs/host-functions-reference/_category_.json | 7 ------- docs/intro/_category_.json | 7 ------- docs/{ => tutorials}/TUTORIAL-TEMPLATE.mdx | 8 ++++---- 5 files changed, 4 insertions(+), 32 deletions(-) delete mode 100644 docs/advanced-tutorials/_category_.json delete mode 100644 docs/basic-tutorials/_category_.json delete mode 100644 docs/host-functions-reference/_category_.json delete mode 100644 docs/intro/_category_.json rename docs/{ => tutorials}/TUTORIAL-TEMPLATE.mdx (96%) diff --git a/docs/advanced-tutorials/_category_.json b/docs/advanced-tutorials/_category_.json deleted file mode 100644 index 44b2f6a5..00000000 --- a/docs/advanced-tutorials/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 45, - "label": "Advanced Tutorials", - "link": { - "type": "generated-index" - } - } \ No newline at end of file diff --git a/docs/basic-tutorials/_category_.json b/docs/basic-tutorials/_category_.json deleted file mode 100644 index d48e388f..00000000 --- a/docs/basic-tutorials/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 40, - "label": "Basic Tutorials", - "link": { - "type": "generated-index" - } -} diff --git a/docs/host-functions-reference/_category_.json b/docs/host-functions-reference/_category_.json deleted file mode 100644 index dcd21d4f..00000000 --- a/docs/host-functions-reference/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 0, - "label": "Host Functions Reference", - "link": { - "type": "generated-index" - } -} diff --git a/docs/intro/_category_.json b/docs/intro/_category_.json deleted file mode 100644 index 88e3c9ae..00000000 --- a/docs/intro/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 0, - "label": "Intro", - "link": { - "type": "generated-index" - } -} diff --git a/docs/TUTORIAL-TEMPLATE.mdx b/docs/tutorials/TUTORIAL-TEMPLATE.mdx similarity index 96% rename from docs/TUTORIAL-TEMPLATE.mdx rename to docs/tutorials/TUTORIAL-TEMPLATE.mdx index 5c4315a2..ce5625c2 100644 --- a/docs/TUTORIAL-TEMPLATE.mdx +++ b/docs/tutorials/TUTORIAL-TEMPLATE.mdx @@ -1,7 +1,7 @@ --- sidebar_position: 1000 -title: How-To Guides Template -description: A description of the how-to guide that is being written +title: Tutorial Template +description: A description of the tutorial that is being written draft: true --- @@ -18,7 +18,7 @@ Place each link definition at the bottom of the section it (first) is used In [oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v20.0.0-rc2 [example demonstrates]: https://github.com/stellar/soroban-examples/tree/v20.0.0-rc2/hello_world -[other example]: getting-started/ +[other example]: ../getting-started/ ## Run the Example @@ -47,7 +47,7 @@ running 1 test test test::test ... ok ``` -[Setup]: ./getting-started/setup.mdx +[Setup]: ../getting-started/setup.mdx ## Code From e14b1aeac283a9cbb7cb4e0a8c338a0d52c5b5e3 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 12:41:39 -0600 Subject: [PATCH 20/95] docs: add a new getting-started page, reorganize that section --- docs/getting-started/create-an-app.mdx | 4 +- docs/getting-started/deploy-incrementor.mdx | 5 +- docs/getting-started/deploy-to-testnet.mdx | 3 +- docs/getting-started/hello-world.mdx | 3 +- .../multi-contract-projects.mdx | 123 ++++++++++++++++++ docs/getting-started/setup.mdx | 2 +- docs/getting-started/storing-data.mdx | 117 +---------------- 7 files changed, 133 insertions(+), 124 deletions(-) create mode 100644 docs/getting-started/multi-contract-projects.mdx diff --git a/docs/getting-started/create-an-app.mdx b/docs/getting-started/create-an-app.mdx index 71b24d68..359862dc 100644 --- a/docs/getting-started/create-an-app.mdx +++ b/docs/getting-started/create-an-app.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 6 -title: 5. Create an App +sidebar_position: 60 +title: 6. Create an App description: Make a frontend web app that interacts with your smart contracts. --- diff --git a/docs/getting-started/deploy-incrementor.mdx b/docs/getting-started/deploy-incrementor.mdx index 4d9679e4..506cec7e 100644 --- a/docs/getting-started/deploy-incrementor.mdx +++ b/docs/getting-started/deploy-incrementor.mdx @@ -1,11 +1,10 @@ --- -sidebar_position: 5 -title: 4. Deploy Incrementor +sidebar_position: 50 +title: 5. Deploy Incrementor description: Deploy the Incrementor contract to Testnet. --- - 4. Deploy Incrementor to Testnet. - Deploy a smart contract to a live test network. - Create your first smart contract in Rust. + + +```toml +[workspace] +resolver = "2" +members = [ + "contracts/*", +] + +[workspace.dependencies] +soroban-sdk = "20.0.0-rc2" + +[profile.release] +opt-level = "z" +overflow-checks = true +debug = 0 +strip = "symbols" +debug-assertions = false +panic = "abort" +codegen-units = 1 +lto = true + +[profile.release-with-logs] +inherits = "release" +debug-assertions = true +``` + + + + +```toml +[package] +name = "hello-soroban" +version = "0.1.0" +edition = "2021" + +[lib] +crate-type = ["cdylib"] + +[dependencies] +soroban-sdk = { workspace = true } + +[dev_dependencies] +soroban-sdk = { workspace = true, features = ["testutils"] } + +[features] +testutils = ["soroban-sdk/testutils"] +``` + + + + +Now make sure everything works: + +```bash +soroban contract build +``` + +Everything should build. + +```bash +cargo test +``` + +All tests should pass. diff --git a/docs/getting-started/setup.mdx b/docs/getting-started/setup.mdx index 1aac5a37..f43ee98a 100644 --- a/docs/getting-started/setup.mdx +++ b/docs/getting-started/setup.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 0 title: Setup description: Install and configure Rust to deploy smart contracts. --- diff --git a/docs/getting-started/storing-data.mdx b/docs/getting-started/storing-data.mdx index 6d3df6e6..33ea0868 100644 --- a/docs/getting-started/storing-data.mdx +++ b/docs/getting-started/storing-data.mdx @@ -1,11 +1,10 @@ --- -sidebar_position: 4 -title: 3. Storing Data +sidebar_position: 40 +title: 4. Storing Data description: Write a smart contract that stores and retrieves data. --- - Write a smart contract that stores and retrieves data. -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - Now that we've built a basic Hello World example to see the rough structure of Soroban contracts, we'll write a simple contract that stores and retrieves data. This will help you see the basics of Soroban's storage system. We'll also organize the two contracts as one combined project using a Cargo Workspace, which is a common pattern for Soroban projects. This is going to follow along with the [increment example](https://github.com/stellar/soroban-examples/tree/v20.0.0-rc2/increment), which has a single function that increments an internal counter and returns the value. If you want to see a working example, [try it in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v20.0.0-rc2). -This tutorial assumes that you've already completed the previous steps in Getting Started: [Setup](./setup.mdx), [Hello World](./hello-world.mdx), and [Deploy to Testnet](./deploy-to-testnet.mdx). - -## Setting up a multi-contract project - -Many Soroban projects need more than one contract. Cargo makes this easy with workspaces, though it doesn't yet give a way to initialize a new project as a workspace (see [#8365](https://github.com/rust-lang/cargo/issues/8365)). Let's set it up manually. - -Rather than just a `hello-soroban` folder, we want a new `soroban-tutorial` folder with a `contracts` folder inside, into which we'll move the existing `hello-soroban` project. As a diff, we want this: - -```diff --hello-soroban -+soroban-tutorial/contracts/hello-soroban -``` - -So change into the parent directory of `hello-soroban` and: - -```bash -mkdir -p soroban-tutorial/contracts -mv hello-soroban soroban-tutorial/contracts -cd soroban-tutorial -``` - -You're going to want some Rust and Cargo stuff in different spots. From the new project root, run: - -```bash -rm contracts/hello-soroban/Cargo.lock -mv contracts/hello-soroban/target . -mv contracts/hello-soroban/.soroban . -cp contracts/hello-soroban/Cargo.toml . -``` - -Note that we copied the Cargo.toml file. That's because we're going to need some of it in the root and some of it in the subdirectory. - -In the root `Cargo.toml`: - -- remove the `[package]`, `[lib]`, `[features]`, and `[dev_dependencies]` sections -- keep the `[profile.release*]` stuff -- replace the line `[dependencies]` with `[workspace.dependencies]` -- add a `[workspace]` section (see below for specific values) - -In the contract-specific `Cargo.toml`: - -- remove the `[profile.release*]` stuff -- set the dependency versions to use the workspace versions (see example below) - -It all ends up looking like this: - - - - -```toml -[workspace] -resolver = "2" -members = [ - "contracts/*", -] - -[workspace.dependencies] -soroban-sdk = "20.0.0-rc2" - -[profile.release] -opt-level = "z" -overflow-checks = true -debug = 0 -strip = "symbols" -debug-assertions = false -panic = "abort" -codegen-units = 1 -lto = true - -[profile.release-with-logs] -inherits = "release" -debug-assertions = true -``` - - - - -```toml -[package] -name = "hello-soroban" -version = "0.1.0" -edition = "2021" - -[lib] -crate-type = ["cdylib"] - -[dependencies] -soroban-sdk = { workspace = true } - -[dev_dependencies] -soroban-sdk = { workspace = true, features = ["testutils"] } - -[features] -testutils = ["soroban-sdk/testutils"] -``` - - - - -Now make sure everything works: - - soroban contract build - -Everything should build. - - cargo test - -All tests should pass. +This tutorial assumes that you've already completed the previous steps in Getting Started: [Setup](setup.mdx), [Hello World](hello-world.mdx), [Deploy to Testnet](deploy-to-testnet.mdx), and [Multi-Contract Projects](multi-contract-projects.mdx). ## Code From ddafbb90a3cbc96e6b6d1d65361752b82bec1179 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 12:48:39 -0600 Subject: [PATCH 21/95] docs: change sidebar position integers in soroban-internals --- docs/soroban-internals/authorization.mdx | 2 +- docs/soroban-internals/built-in-types.mdx | 2 +- docs/soroban-internals/contract-lifecycle.mdx | 2 +- docs/soroban-internals/custom-types.mdx | 2 +- docs/soroban-internals/debugging.mdx | 2 +- docs/soroban-internals/environment-concepts.mdx | 2 +- docs/soroban-internals/errors.mdx | 2 +- docs/soroban-internals/events.mdx | 2 +- docs/soroban-internals/fees-and-metering.mdx | 2 +- docs/soroban-internals/fully-typed-contracts.mdx | 4 ++-- docs/soroban-internals/high-level-overview.mdx | 2 +- docs/soroban-internals/interacting-with-contracts.mdx | 2 +- .../invoking-contracts-with-transactions.mdx | 2 +- docs/soroban-internals/persisting-data.mdx | 2 +- docs/soroban-internals/rust-dialect.mdx | 2 +- docs/soroban-internals/state-expiration.mdx | 2 +- 16 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/soroban-internals/authorization.mdx b/docs/soroban-internals/authorization.mdx index 0210d7ea..fca0f97f 100644 --- a/docs/soroban-internals/authorization.mdx +++ b/docs/soroban-internals/authorization.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 20 title: Authorization description: Smart contract authorization. --- diff --git a/docs/soroban-internals/built-in-types.mdx b/docs/soroban-internals/built-in-types.mdx index 64ef8528..86793bbd 100644 --- a/docs/soroban-internals/built-in-types.mdx +++ b/docs/soroban-internals/built-in-types.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 30 title: Built-In Types description: Built-in types used as smart contract inputs and outputs. --- diff --git a/docs/soroban-internals/contract-lifecycle.mdx b/docs/soroban-internals/contract-lifecycle.mdx index acfb0998..d68a6fe0 100644 --- a/docs/soroban-internals/contract-lifecycle.mdx +++ b/docs/soroban-internals/contract-lifecycle.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 40 title: Contract Lifecycle description: The process of developing, deploying, and maintaining smart contracts. --- diff --git a/docs/soroban-internals/custom-types.mdx b/docs/soroban-internals/custom-types.mdx index 30c8ab16..f2b3fd40 100644 --- a/docs/soroban-internals/custom-types.mdx +++ b/docs/soroban-internals/custom-types.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 50 title: Custom Types description: Struct, union, and enum types defined by contracts. --- diff --git a/docs/soroban-internals/debugging.mdx b/docs/soroban-internals/debugging.mdx index 087e0db6..f66b4676 100644 --- a/docs/soroban-internals/debugging.mdx +++ b/docs/soroban-internals/debugging.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 70 title: Debugging description: Debug smart contracts natively and as WASM. --- diff --git a/docs/soroban-internals/environment-concepts.mdx b/docs/soroban-internals/environment-concepts.mdx index e543bbee..af640d99 100644 --- a/docs/soroban-internals/environment-concepts.mdx +++ b/docs/soroban-internals/environment-concepts.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 10 +sidebar_position: 80 title: Environment Concepts description: The interface that defines objects, functions, and data available to smart contracts. --- diff --git a/docs/soroban-internals/errors.mdx b/docs/soroban-internals/errors.mdx index bea89154..63183455 100644 --- a/docs/soroban-internals/errors.mdx +++ b/docs/soroban-internals/errors.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 11 +sidebar_position: 90 title: Errors description: Generating errors from smart contracts. --- diff --git a/docs/soroban-internals/events.mdx b/docs/soroban-internals/events.mdx index f8a038a1..cc2e1599 100644 --- a/docs/soroban-internals/events.mdx +++ b/docs/soroban-internals/events.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 12 +sidebar_position: 100 title: Events description: Monitor off-chain smart contract changes. --- diff --git a/docs/soroban-internals/fees-and-metering.mdx b/docs/soroban-internals/fees-and-metering.mdx index eb1caa66..72782dc6 100644 --- a/docs/soroban-internals/fees-and-metering.mdx +++ b/docs/soroban-internals/fees-and-metering.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 13 +sidebar_position: 110 title: Fees and Metering description: Smart contract fees and metering on Soroban. --- diff --git a/docs/soroban-internals/fully-typed-contracts.mdx b/docs/soroban-internals/fully-typed-contracts.mdx index 45895a52..06c37053 100644 --- a/docs/soroban-internals/fully-typed-contracts.mdx +++ b/docs/soroban-internals/fully-typed-contracts.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 14 +sidebar_position: 120 title: "Fully-Typed Contracts" desctiption: Smart contract WASM files contain a machine-readable description of the interface type. sidebar_label: Fully-Typed Contracts @@ -25,7 +25,7 @@ sidebar_label: Fully-Typed Contracts /> -When you compile a contract created with [soroban-sdk](../resources/sdks/rust.mdx), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. +When you compile a contract created with [soroban-sdk](../resources/sdks/write-contracts.mdx#soroban-rust-sdk), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. Today, these interface types are formatted using [XDR](https://developers.stellar.org/docs/encyclopedia/xdr), but this [may change](https://github.com/stellar/rs-soroban-sdk/issues/683) down the road. diff --git a/docs/soroban-internals/high-level-overview.mdx b/docs/soroban-internals/high-level-overview.mdx index cc42a0d8..77171c84 100644 --- a/docs/soroban-internals/high-level-overview.mdx +++ b/docs/soroban-internals/high-level-overview.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 10 title: High-Level Overview description: An overview of Rust, SDKs, and the Soroban host environment. --- diff --git a/docs/soroban-internals/interacting-with-contracts.mdx b/docs/soroban-internals/interacting-with-contracts.mdx index f8f52ea1..522bf6ec 100644 --- a/docs/soroban-internals/interacting-with-contracts.mdx +++ b/docs/soroban-internals/interacting-with-contracts.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 15 +sidebar_position: 130 title: Interacting with Contracts description: Interact with smart contracts. --- diff --git a/docs/soroban-internals/invoking-contracts-with-transactions.mdx b/docs/soroban-internals/invoking-contracts-with-transactions.mdx index 5a44343a..e7419a82 100644 --- a/docs/soroban-internals/invoking-contracts-with-transactions.mdx +++ b/docs/soroban-internals/invoking-contracts-with-transactions.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 16 +sidebar_position: 140 title: Interacting with Soroban via Stellar description: Invoke and deploy smart contracts with the InvokeHostFunctionOp operation. toc_max_heading_level: 4 diff --git a/docs/soroban-internals/persisting-data.mdx b/docs/soroban-internals/persisting-data.mdx index e0354888..5d380aec 100644 --- a/docs/soroban-internals/persisting-data.mdx +++ b/docs/soroban-internals/persisting-data.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 150 title: Persisting Data description: Store and access smart contract data. --- diff --git a/docs/soroban-internals/rust-dialect.mdx b/docs/soroban-internals/rust-dialect.mdx index dcd07c3c..d3ffab72 100644 --- a/docs/soroban-internals/rust-dialect.mdx +++ b/docs/soroban-internals/rust-dialect.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 60 title: Contract Rust Dialect description: Differences between Soroban Rust and typical Rust programming. --- diff --git a/docs/soroban-internals/state-expiration.mdx b/docs/soroban-internals/state-expiration.mdx index 17c73bd9..10edab16 100644 --- a/docs/soroban-internals/state-expiration.mdx +++ b/docs/soroban-internals/state-expiration.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 160 title: State Expiration description: Smart contract state expiration. --- From 5d3c76d51b273954ee9e98d3de76e1013678b5f9 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 13:47:56 -0600 Subject: [PATCH 22/95] docs: shuffling contract interaction around in soroban-internals --- docs/soroban-internals/authorization.mdx | 2 +- .../contract-interactions/_category_.json | 4 + .../contract-interactions/cross-contract.mdx | 25 +++ .../contract-interactions/index.mdx | 42 +++++ .../stellar-transaction.mdx} | 20 +-- .../contract-interactions/tests.mdx | 24 +++ .../transaction-simulation.mdx | 57 +++++++ docs/soroban-internals/fees-and-metering.mdx | 2 +- .../interacting-with-contracts.mdx | 156 ------------------ docs/soroban-internals/state-expiration.mdx | 6 +- .../transaction-lifecycle.mdx | 14 ++ docs/soroban-internals/types/_category_.json | 7 + .../{ => types}/built-in-types.mdx | 10 +- .../{ => types}/custom-types.mdx | 8 +- .../{ => types}/fully-typed-contracts.mdx | 14 +- docs/tokens/stellar-asset-contract.mdx | 2 +- nginx/includes/redirects.conf | 4 + 17 files changed, 210 insertions(+), 187 deletions(-) create mode 100644 docs/soroban-internals/contract-interactions/_category_.json create mode 100644 docs/soroban-internals/contract-interactions/cross-contract.mdx create mode 100644 docs/soroban-internals/contract-interactions/index.mdx rename docs/soroban-internals/{invoking-contracts-with-transactions.mdx => contract-interactions/stellar-transaction.mdx} (97%) create mode 100644 docs/soroban-internals/contract-interactions/tests.mdx create mode 100644 docs/soroban-internals/contract-interactions/transaction-simulation.mdx delete mode 100644 docs/soroban-internals/interacting-with-contracts.mdx create mode 100644 docs/soroban-internals/transaction-lifecycle.mdx create mode 100644 docs/soroban-internals/types/_category_.json rename docs/soroban-internals/{ => types}/built-in-types.mdx (93%) rename docs/soroban-internals/{ => types}/custom-types.mdx (96%) rename docs/soroban-internals/{ => types}/fully-typed-contracts.mdx (84%) diff --git a/docs/soroban-internals/authorization.mdx b/docs/soroban-internals/authorization.mdx index fca0f97f..8766e0e0 100644 --- a/docs/soroban-internals/authorization.mdx +++ b/docs/soroban-internals/authorization.mdx @@ -187,7 +187,7 @@ with the existing Stellar accounts, Soroban supports 4 different kinds of the account implementations. Below are the general descriptions of these implementations. See the transaction -[guide](./invoking-contracts-with-transactions.mdx) for the +[guide](contract-interactions/stellar-transaction.mdx) for the concrete information of how different accounts are represented. ##### Stellar Account diff --git a/docs/soroban-internals/contract-interactions/_category_.json b/docs/soroban-internals/contract-interactions/_category_.json new file mode 100644 index 00000000..6f4df844 --- /dev/null +++ b/docs/soroban-internals/contract-interactions/_category_.json @@ -0,0 +1,4 @@ +{ + "position": 120, + "label": "Contract Interactions" +} diff --git a/docs/soroban-internals/contract-interactions/cross-contract.mdx b/docs/soroban-internals/contract-interactions/cross-contract.mdx new file mode 100644 index 00000000..2a13a8c7 --- /dev/null +++ b/docs/soroban-internals/contract-interactions/cross-contract.mdx @@ -0,0 +1,25 @@ +--- +sidebar_position: 10 +title: Cross-Contract +description: Interact with a Soroban contract from within another Soroban contract. +--- + +A cross-contract invocation is a powerful (yet expensive) kind of contract interaction. A contract invocation is similar to starting a new process because the code that runs will be in a separate address space, meaning that they do not share any data other than what was passed in the invocation. While a contract invocation typically transfers control to a _different_ contract, it is possible to transfer control to the currently running contract. Regardless of whether the contract that receives control is a different contract or the currently running contract, the value returned by `get_invoking_contract` will be the previous value of `get_current_contract`. A contract invocation can only access the public methods of a contract. + +If a contract contains a public function `f`, then invoking `f` can be done by making a Rust function call to `f::invoke`. + +Some contracts, such as the token contract, only export the contract invocation functions. In doing so, they are able to assign those functions friendly names. For example, [initialize](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/contract.rs#L55-L57) + +```rust +#[contractimpl(export_if = "export")] +impl TokenTrait for Token { + fn initialize(e: Env, admin: Identifier, decimal: u32, name: Binary, symbol: Binary) { +``` + +is [exported](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/lib.rs#L26) as + +```rust +pub use crate::contract::initialize::invoke as initialize; +``` + +This function is then easily [called by the liquidity pool contract](https://github.com/stellar/soroban-examples/blob/4060d3bd5ee7846020b68ee583665a4d4cf4b315/liquidity_pool/src/lib.rs#L164-L171). diff --git a/docs/soroban-internals/contract-interactions/index.mdx b/docs/soroban-internals/contract-interactions/index.mdx new file mode 100644 index 00000000..433f3d7b --- /dev/null +++ b/docs/soroban-internals/contract-interactions/index.mdx @@ -0,0 +1,42 @@ +--- +title: Calling Contracts +description: Interact with smart contracts. +--- + + + Interact with smart contracts. + + + + + + +Contracts are invoked through a pair of host functions `call` and `try_call`: + +- `try_call(contract, function, args)` calls `function` exported from `contract`, passing `args` and returning a `Status` on any error. +- `call(contract, function, args)` just calls `try_call` with its arguments and traps on `Status`, essentially propagating the error. + +In both cases `contract` is a `Binary` host object containing the contract ID, `function` is a `Symbol` holding the name of an exported function to call, and `args` is a `Vector` of values to pass as arguments. + +These host functions can be invoked in two separate ways: + +- From outside the host, such as when a user submits a transaction that calls a contract. +- From within the host, when one contract calls another. + +Both cases follow the same logic: + +- The contract's Wasm bytecode is retrieved from a `CONTRACT_DATA` ledger entry in the host's storage system. +- A Wasm VM is instantiated for the duration of the invocation. +- The function is looked up and invoked, with arguments passed from caller to callee. + +When a call occurs from outside the host, any arguments will typically be provided in serialized XDR form accompanying the transaction, and will be deserialized and converted to host objects automatically before invoking the contract. + +When a call occurs from inside the host, the caller and callee contracts _share the same host_ and the caller can pass references to host objects directly to the callee without any need to serialize or deserialize them. + +Since host objects are immutable, there is limited risk to passing a shared reference from one contract to another: the callee cannot modify the object in a way that would surprise the caller, only create new objects. diff --git a/docs/soroban-internals/invoking-contracts-with-transactions.mdx b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx similarity index 97% rename from docs/soroban-internals/invoking-contracts-with-transactions.mdx rename to docs/soroban-internals/contract-interactions/stellar-transaction.mdx index e7419a82..08a04615 100644 --- a/docs/soroban-internals/invoking-contracts-with-transactions.mdx +++ b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 140 -title: Interacting with Soroban via Stellar +sidebar_position: 30 +title: Stellar Transaction description: Invoke and deploy smart contracts with the InvokeHostFunctionOp operation. toc_max_heading_level: 4 --- @@ -20,7 +20,7 @@ toc_max_heading_level: 4 /> @@ -265,7 +265,7 @@ The `InvokeHostFunctionOp` can be used to perform the following Soroban operatio - Invoke contract functions. - Upload Wasm of the new contracts. -- Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../tokens/stellar-asset-contract.mdx)). +- Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../../tokens/stellar-asset-contract.mdx)). [`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli @@ -401,7 +401,7 @@ The `hostFunction` in `InvokeHostFunctionOp` will be executed by the Soroban hos #### Authorization Data -Soroban's [authorization framework](../soroban-internals/authorization.mdx) +Soroban's [authorization framework](../authorization.mdx) provides a standardized way for passing authorization data to the contract invocations via `SorobanAuthorizationEntry` structures. @@ -502,7 +502,7 @@ recording auth mode in Soroban's `simulateTransaction` mechanism (see the [docs] details). [envelope-xdr]: https://github.com/stellar/stellar-xdr/blob/e372df9f677961aac04c5a4cc80a3667f310b29f/Stellar-transaction.x#L703 -[simulate-transaction-doc]: ../soroban-internals/interacting-with-contracts.mdx#authorization +[simulate-transaction-doc]: transaction-simulation.mdx#authorization ##### Stellar Account Signatures @@ -521,13 +521,13 @@ pub struct AccountEd25519Signature { ``` [structures]: https://github.com/stellar/rs-soroban-env/blob/99d8c92cdc7e5cd0f5311df8f88d04658ecde7d2/soroban-env-host/src/native_contract/account_contract.rs#L51 -[custom accounts]: ../soroban-internals/authorization.mdx#account-abstraction +[custom accounts]: ../authorization.mdx#account-abstraction ### Transaction resources Every Soroban transaction has to have a `SorobanTransactionData` transaction [extension] populated. This is needed to compute the -[Soroban resource fee](../soroban-internals/fees-and-metering.mdx). +[Soroban resource fee](../fees-and-metering.mdx). [extension]: https://github.com/stellar/stellar-xdr/blob/c2e702c70951ff59a1eff257f08cf38d47210e5f/Stellar-transaction.x#L874 @@ -559,7 +559,7 @@ struct SorobanTransactionData This data comprises two parts: Soroban resources and the `refundableFee`. The `refundableFee` is the portion of the transaction fee eligible for refund. It includes the fees for the contract events emitted by the transaction, the return -value of the host function invocation, and fees for the [ledger space rent](./state-expiration.mdx). +value of the host function invocation, and fees for the [ledger space rent](../state-expiration.mdx). The `SorobanResources` structure includes the ledger footprint and the resource values, which together determine the resource consumption limit and the @@ -567,4 +567,4 @@ resource fee. The footprint must contain the `LedgerKey`s that will be read and/or written. The simplest method to determine the values in `SorobanResources` and -`refundableFee` is to use the [`simulateTransaction` mechanism](../soroban-internals/interacting-with-contracts.mdx#transaction-simulation). +`refundableFee` is to use the [`simulateTransaction` mechanism](transaction-simulation.mdx). diff --git a/docs/soroban-internals/contract-interactions/tests.mdx b/docs/soroban-internals/contract-interactions/tests.mdx new file mode 100644 index 00000000..88e23026 --- /dev/null +++ b/docs/soroban-internals/contract-interactions/tests.mdx @@ -0,0 +1,24 @@ +--- +sidebar_position: 20 +title: Tests +description: Interacting with contracts in tests +--- + +[Debugging contracts](../debugging.mdx) explains that it is much more convenient to debug using native code than Wasm. Given that you are testing native code, it is tempting to interact with your contract directly using function calls. If you attempt this approach, you will find that it doesn't always work. Function call interactions do not set the environment into the correct state for contract execution, so functions involving contract data and determining the current or invoking contract will not work. + +When writing tests, it is important to always interact with contracts through contract invocation. In a production setting, contract invocation will execute Wasm bytecode loaded from the ledger. So how does this work if you are testing native code? You must register your contract with the environment, so it knows what functions are available and how to call them. While this sounds complex, the `contractimpl` procedural macro automatically generates almost all the code to do this. All you have to do is write a small [stub](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/testutils.rs#L12-L15) to actually call the generated code, such as + +```rust title="test.rs" +pub fn register_test_contract(e: &Env, contract_id: &[u8; 32]) { + let contract_id = FixedBinary::from_array(e, *contract_id); + e.register_contract(&contract_id, crate::contract::Token {}); +} +``` + +Some contracts, such as the token contract, also provide a [friendlier interface](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/testutils.rs#L26-L191) to facilitate testing. There are many ways these interfaces might make testing easier, but one common one is to allow automatic message signing by passing a [ed25519_dalek::Keypair](https://docs.rs/ed25519-dalek/latest/ed25519_dalek/struct.Keypair.html). + +Note that everything described in this section is only available if the `testutils` feature is enabled. + +### Example + +This machinery can also be used to test multiple contracts together. For example, the single offer contract test case [creates a token](https://github.com/stellar/soroban-examples/blob/56fef787395b5aed7cd7b19772cca28e21b3feb5/single_offer/src/test.rs#L22). diff --git a/docs/soroban-internals/contract-interactions/transaction-simulation.mdx b/docs/soroban-internals/contract-interactions/transaction-simulation.mdx new file mode 100644 index 00000000..ae44ac4b --- /dev/null +++ b/docs/soroban-internals/contract-interactions/transaction-simulation.mdx @@ -0,0 +1,57 @@ +--- +sidebar_position: 40 +title: Transaction Simulation +description: Simulate a contract interaction contained in a Stellar transaction. +--- + +## Footprint + +As mentioned in the [persisting data](../persisting-data.mdx) section, a contract can only load or store `CONTRACT_DATA` entries that are declared in a _footprint_ associated with its invocation. + +A footprint is a set of ledger keys, each marked as either read-only or read-write. Read-only keys are available to the transaction for reading; read-write keys are available for reading, writing, or both. + +Any Soroban transaction submitted by a user has to be accompanied by this footprint. A single footprint encompasses _all_ the data read and written by _all_ contracts transitively invoked by the transaction: not just the initial contract that the transaction calls, but also all contracts it calls, and so on. + +Since it can be difficult for a user to know which ledger entries a given contract call will attempt to read or write (especially entries that are caused by other contracts deep within a transaction), the host provides an auxiliary `simulateTransaction` mechanism that executes a transaction against a temporary, possibly out-of-date _snapshot_ of the ledger. The `simulateTransaction` mechanism is _not_ constrained to only read or write the contents of a footprint; rather it _records_ a footprint describing the transaction's execution, discards the execution's effects, and then returns the recorded footprint to its caller. + +This simulation-provided footprint can then be used to accompany a "real" submission of the same transaction to the network for real execution. If the state of the ledger has changed too much between the time of the simulated and the real submission, the footprint may be too stale and no longer accurately identify the _keys_ the transaction needs to read and/or write, at which point the simulation must be retried to refresh the footprint. + +In any event (whether successful or failing), the real transaction will execute atomically, deterministically, and with serializable consistency semantics. An inaccurate footprint simply causes deterministic transaction failure, not a stale-read anomaly. All effects of such a failed transaction are discarded, as they would be in the presence of any other error. + +## Authorization + +See the [authorization overview](../authorization.mdx) docs and authorization in +transactions [section][auth-data] for general information on Soroban +authorization. + +[auth-data]: stellar-transaction.mdx#authorization-data + +Soroban's `simulateTransaction` mechanism can also be used to compute the `SorobanAuthorizedInvocation` trees +that must be authorized by the `Address`es for all the +`require_auth` checks to pass. + +Soroban host provides a special 'recording' mode for auth. Whenever +`require_auth` is called, the host records its context (address, contract id, +function, arguments), attributes it to a `SorobanAuthorizedInvocation` tree, and marks +it as successful. Then, after the invocation has finished, `simulateTransaction` can return +all the recorded trees, as well as the generated random nonce values. + +Given this information from the simulation, the client only needs to provide these +trees and nonces to the respective `Address`es for signing and then build the +final transaction using the simulation output and the corresponding signatures. + +The recording auth mode is optional for `simulateTransaction`. For example, when dealing +with the custom account contracts, it may be necessary to simulate the custom +account's `__check_auth` code (that is simply omitted in the recording auth mode), +for example, to get its ledger footprint. The non-recording mode is referred to +as 'enforcing'. Enforcing mode is basically equivalent to running the +transaction on-chain (with possibly a slightly stale ledger state); hence, it +requires all the signatures to be valid. + +Note that the recording auth mode never emulates authorization failures. The +reason for that is that failing authorization is always an exceptional +situation (i.e., the `Address`es for which you don't anticipate successful +authorization shouldn't be used in the first place). It is similar to how, for +example, the `simulateTransaction` mechanism doesn't emulate failures caused by the incorrect +footprint. `simulateTransaction` with enforcing auth mode may still be used to verify the +signatures before executing the transaction on-chain. diff --git a/docs/soroban-internals/fees-and-metering.mdx b/docs/soroban-internals/fees-and-metering.mdx index 72782dc6..042850d8 100644 --- a/docs/soroban-internals/fees-and-metering.mdx +++ b/docs/soroban-internals/fees-and-metering.mdx @@ -58,7 +58,7 @@ Some parameters may contribute to multiple fee components. For example, the tran The implementation details for fee computation are provided by the following [library](https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-host/src/fees.rs). This library is used by the protocol to compute the fees and thus can be considered canonical. The resource fee rates may be updated based on network validator consensus. -The best way to find the required fees for any Soroban transaction is to use the [`simulateTransaction` mechanism](./interacting-with-contracts.mdx#transaction-simulation). +The best way to find the required fees for any Soroban transaction is to use the [`simulateTransaction` mechanism](contract-interactions/transaction-simulation.mdx). The fee rates are currently defined for the Testnet as follows: diff --git a/docs/soroban-internals/interacting-with-contracts.mdx b/docs/soroban-internals/interacting-with-contracts.mdx deleted file mode 100644 index 522bf6ec..00000000 --- a/docs/soroban-internals/interacting-with-contracts.mdx +++ /dev/null @@ -1,156 +0,0 @@ ---- -sidebar_position: 130 -title: Interacting with Contracts -description: Interact with smart contracts. ---- - - - Interact with smart contracts. - - - - - - -## Three types of interactions - -### Function call - -A function call is the simplest and least expensive kind of contract interaction. A function call does exactly what you would expect a contract call to do in any other software development context: the contract transfers control and data to another part of the _same_ contract. Because a function call always transfers control to the same contract, they do not change the values returned by `get_current_contract` and `get_invoking_contract`. A function call is the only way to access the private methods of a contract, although it can also be used to access the public methods of a contract. - -To perform a function call, simply make a Rust function call. - -### Contract invocation - -A contract invocation is a more powerful and more expensive kind of contract interaction. A contract invocation is similar to starting a new process because the code that runs will be in a separate address space, meaning that they do not share any data other than what was passed in the invocation. While a contract invocation typically transfers control to a _different_ contract, it is possible to transfer control to the currently running contract. Regardless of whether the contract that receives control is a different contract or the currently running contract, the value returned by `get_invoking_contract` will be the previous value of `get_current_contract`. A contract invocation can only access the public methods of a contract. - -If a contract contains a public function `f`, then invoking `f` can be done by making a Rust function call to `f::invoke`. - -Some contracts, such as the token contract, only export the contract invocation functions. In doing so, they are able to assign those functions friendly names. For example, [initialize](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/contract.rs#L55-L57) - -```rust -#[contractimpl(export_if = "export")] -impl TokenTrait for Token { - fn initialize(e: Env, admin: Identifier, decimal: u32, name: Binary, symbol: Binary) { -``` - -is [exported](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/lib.rs#L26) as - -```rust -pub use crate::contract::initialize::invoke as initialize; -``` - -This function is then easily [called by the liquidity pool contract](https://github.com/stellar/soroban-examples/blob/4060d3bd5ee7846020b68ee583665a4d4cf4b315/liquidity_pool/src/lib.rs#L164-L171). - -### Stellar Operation - -A Stellar operation is the ultimate entry point of every contract interaction. An operation transfers control and external data to a contract, allowing execution to begin. - -This kind of interaction is currently supported in experimental versions of stellar-core only. - -## Interacting with contracts in tests - -[Debugging contracts](debugging) explains that it is much more convenient to debug using native code than Wasm. Given that you are testing native code, it is tempting to interact with your contract directly using function calls. If you attempt this approach, you will find that it doesn't always work. Function call interactions do not set the environment into the correct state for contract execution, so functions involving contract data and determining the current or invoking contract will not work. - -When writing tests, it is important to always interact with contracts through contract invocation. In a production setting, contract invocation will execute Wasm bytecode loaded from the ledger. So how does this work if you are testing native code? You must register your contract with the environment, so it knows what functions are available and how to call them. While this sounds complex, the `contractimpl` procedural macro automatically generates almost all the code to do this. All you have to do is write a small [stub](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/testutils.rs#L12-L15) to actually call the generated code, such as - -```rust -pub fn register_test_contract(e: &Env, contract_id: &[u8; 32]) { - let contract_id = FixedBinary::from_array(e, *contract_id); - e.register_contract(&contract_id, crate::contract::Token {}); -} -``` - -Some contracts, such as the token contract, also provide a [friendlier interface](https://github.com/stellar/soroban-token-contract/blob/42380647bb817bf01c739c19286f18be881e0e41/src/testutils.rs#L26-L191) to facilitate testing. There are many ways these interfaces might make testing easier, but one common one is to allow automatic message signing by passing a [ed25519_dalek::Keypair](https://docs.rs/ed25519-dalek/latest/ed25519_dalek/struct.Keypair.html). - -Note that everything described in this section is only available if the `testutils` feature is enabled. - -### Example - -This machinery can also be used to test multiple contracts together. For example, the single offer contract test case [creates a token](https://github.com/stellar/soroban-examples/blob/56fef787395b5aed7cd7b19772cca28e21b3feb5/single_offer/src/test.rs#L22). - -## Calling contracts - -Contracts are invoked through a pair of host functions `call` and `try_call`: - -- `try_call(contract, function, args)` calls `function` exported from `contract`, passing `args` and returning a `Status` on any error. -- `call(contract, function, args)` just calls `try_call` with its arguments and traps on `Status`, essentially propagating the error. - -In both cases `contract` is a `Binary` host object containing the contract ID, `function` is a `Symbol` holding the name of an exported function to call, and `args` is a `Vector` of values to pass as arguments. - -These host functions can be invoked in two separate ways: - -- From outside the host, such as when a user submits a transaction that calls a contract. -- From within the host, when one contract calls another. - -Both cases follow the same logic: - -- The contract's Wasm bytecode is retrieved from a `CONTRACT_DATA` ledger entry in the host's storage system. -- A Wasm VM is instantiated for the duration of the invocation. -- The function is looked up and invoked, with arguments passed from caller to callee. - -When a call occurs from outside the host, any arguments will typically be provided in serialized XDR form accompanying the transaction, and will be deserialized and converted to host objects automatically before invoking the contract. - -When a call occurs from inside the host, the caller and callee contracts _share the same host_ and the caller can pass references to host objects directly to the callee without any need to serialize or deserialize them. - -Since host objects are immutable, there is limited risk to passing a shared reference from one contract to another: the callee cannot modify the object in a way that would surprise the caller, only create new objects. - -## Transaction Simulation - -### Footprint - -As mentioned in the [persisting data](../soroban-internals/persisting-data.mdx) section, a contract can only load or store `CONTRACT_DATA` entries that are declared in a _footprint_ associated with its invocation. - -A footprint is a set of ledger keys, each marked as either read-only or read-write. Read-only keys are available to the transaction for reading; read-write keys are available for reading, writing, or both. - -Any Soroban transaction submitted by a user has to be accompanied by this footprint. A single footprint encompasses _all_ the data read and written by _all_ contracts transitively invoked by the transaction: not just the initial contract that the transaction calls, but also all contracts it calls, and so on. - -Since it can be difficult for a user to know which ledger entries a given contract call will attempt to read or write (especially entries that are caused by other contracts deep within a transaction), the host provides an auxiliary `simulateTransaction` mechanism that executes a transaction against a temporary, possibly out-of-date _snapshot_ of the ledger. The `simulateTransaction` mechanism is _not_ constrained to only read or write the contents of a footprint; rather it _records_ a footprint describing the transaction's execution, discards the execution's effects, and then returns the recorded footprint to its caller. - -This simulation-provided footprint can then be used to accompany a "real" submission of the same transaction to the network for real execution. If the state of the ledger has changed too much between the time of the simulated and the real submission, the footprint may be too stale and no longer accurately identify the _keys_ the transaction needs to read and/or write, at which point the simulation must be retried to refresh the footprint. - -In any event (whether successful or failing), the real transaction will execute atomically, deterministically, and with serializable consistency semantics. An inaccurate footprint simply causes deterministic transaction failure, not a stale-read anomaly. All effects of such a failed transaction are discarded, as they would be in the presence of any other error. - -### Authorization - -See the [authorization overview](authorization.mdx) docs and authorization in -transactions [section][auth-data] for general information on Soroban -authorization. - -[auth-data]: ./invoking-contracts-with-transactions.mdx#authorization-data - -Soroban's `simulateTransaction` mechanism can also be used to compute the `SorobanAuthorizedInvocation` trees -that must be authorized by the `Address`es for all the -`require_auth` checks to pass. - -Soroban host provides a special 'recording' mode for auth. Whenever -`require_auth` is called, the host records its context (address, contract id, -function, arguments), attributes it to a `SorobanAuthorizedInvocation` tree, and marks -it as successful. Then, after the invocation has finished, `simulateTransaction` can return -all the recorded trees, as well as the generated random nonce values. - -Given this information from the simulation, the client only needs to provide these -trees and nonces to the respective `Address`es for signing and then build the -final transaction using the simulation output and the corresponding signatures. - -The recording auth mode is optional for `simulateTransaction`. For example, when dealing -with the custom account contracts, it may be necessary to simulate the custom -account's `__check_auth` code (that is simply omitted in the recording auth mode), -for example, to get its ledger footprint. The non-recording mode is referred to -as 'enforcing'. Enforcing mode is basically equivalent to running the -transaction on-chain (with possibly a slightly stale ledger state); hence, it -requires all the signatures to be valid. - -Note that the recording auth mode never emulates authorization failures. The -reason for that is that failing authorization is always an exceptional -situation (i.e., the `Address`es for which you don't anticipate successful -authorization shouldn't be used in the first place). It is similar to how, for -example, the `simulateTransaction` mechanism doesn't emulate failures caused by the incorrect -footprint. `simulateTransaction` with enforcing auth mode may still be used to verify the -signatures before executing the transaction on-chain. diff --git a/docs/soroban-internals/state-expiration.mdx b/docs/soroban-internals/state-expiration.mdx index 10edab16..29be9f29 100644 --- a/docs/soroban-internals/state-expiration.mdx +++ b/docs/soroban-internals/state-expiration.mdx @@ -151,7 +151,7 @@ expirationLedger that is large enough. `BumpFootprintExpirationOp` is a Soroban operation, and therefore must be the only operation in a transaction. The transaction also needs to populate `SorobanTransactionData` transaction extension explained -[here](../soroban-internals/invoking-contracts-with-transactions.mdx#transaction-resources). To fill +[here](contract-interactions/stellar-transaction.mdx#transaction-resources). To fill out `SorobanResources`, use the transaction simulation mentioned in the provided link, or make sure `readBytes` includes the key and entry size of every entry in the `readOnly` set. @@ -188,7 +188,7 @@ parameter and is subject to be updated (likely increased) via network upgrades. `RestoreFootprintOp` is a Soroban operation, and therefore must be the only operation in a transaction. The transaction also needs to populate `SorobanTransactionData` transaction extension explained -[here](../soroban-internals/invoking-contracts-with-transactions.mdx#transaction-resources). To fill +[here](contract-interactions/stellar-transaction.mdx#transaction-resources). To fill out `SorobanResources`, use the transaction simulation mentioned in the provided link, or make sure `writeBytes` includes the key and entry size of every entry in the `readWrite` set and make sure `extendedMetaDataSizeBytes` is at least double of @@ -204,7 +204,7 @@ We've done our best to build tooling around state expiration in both the Soroban Both restoring and bumping the expiration of ledger entries follows a three-step process regardless of their nature (contract data, instances, etc.): -1. **Identify the ledger entries**. This usually means acquiring them from a Soroban RPC server as part of your initial transaction simulation (see the [transaction simulation docs](https://soroban.stellar.org/docs/soroban-internals/interacting-with-contracts#transaction-simulation) and the [`simulateTransaction`](https://soroban.stellar.org/api/methods/simulateTransaction) RPC method). +1. **Identify the ledger entries**. This usually means acquiring them from a Soroban RPC server as part of your initial transaction simulation (see the [transaction simulation docs](contract-interactions/transaction-simulation.mdx) and the [`simulateTransaction`](/api/methods/simulateTransaction) RPC method). 2. **Prepare your operation**. This means describing the ledger entries within the corresponding operation (i.e. `bumpFootprintOp` or `restoreFootprintOp`) and its ledger footprint (the `SorobanTransactionData` field), then simulating it to fill out fee and resource usage information (when restoring, you usually have simulation results already). diff --git a/docs/soroban-internals/transaction-lifecycle.mdx b/docs/soroban-internals/transaction-lifecycle.mdx new file mode 100644 index 00000000..31135af6 --- /dev/null +++ b/docs/soroban-internals/transaction-lifecycle.mdx @@ -0,0 +1,14 @@ +--- +sidebar_position: 50 +title: Transaction Lifecycle +description: here's how a transaction works, and stuff. +--- + +See [GH issue #532](https://github.com/stellar/soroban-docs/issues/532) for details. + +We're getting a lot of questions that relate to the transaction lifecycle and don't have a great resource to send people to. + +The regular Stellar resources are confusing because: + +1. they don't have any information on preflight and +2. soroban-rpc's tx submission is async diff --git a/docs/soroban-internals/types/_category_.json b/docs/soroban-internals/types/_category_.json new file mode 100644 index 00000000..244c32ca --- /dev/null +++ b/docs/soroban-internals/types/_category_.json @@ -0,0 +1,7 @@ +{ + "position": 30, + "label": "Types", + "link": { + "type": "generated-index" + } +} diff --git a/docs/soroban-internals/built-in-types.mdx b/docs/soroban-internals/types/built-in-types.mdx similarity index 93% rename from docs/soroban-internals/built-in-types.mdx rename to docs/soroban-internals/types/built-in-types.mdx index 86793bbd..ff0bf8d6 100644 --- a/docs/soroban-internals/built-in-types.mdx +++ b/docs/soroban-internals/types/built-in-types.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 30 +sidebar_position: 10 title: Built-In Types description: Built-in types used as smart contract inputs and outputs. --- @@ -24,14 +24,14 @@ description: Built-in types used as smart contract inputs and outputs. Built-in types are available to all contracts for use as contract function inputs and outputs, and are defined by the [environment] and the [Rust SDK]. -[environment]: environment-concepts -[Rust SDK]: ../resources/sdks/rust +[environment]: ../environment-concepts.mdx +[Rust SDK]: ../../resources/sdks/write-contracts.mdx#soroban-rust-sdk :::tip Custom types like structs, enums, and unions are also supported. See [Custom Types]. -[Custom Types]: custom-types +[Custom Types]: custom-types.mdx ::: @@ -112,5 +112,5 @@ identify the payment recipient), as a data key (for example, to store the balance), as the authentication & authorization source (for example, to authorize a token transfer) etc. -See [authorization documentation](authorization.mdx) for more details on how to +See [authorization documentation](../authorization.mdx) for more details on how to use the `Address` type. diff --git a/docs/soroban-internals/custom-types.mdx b/docs/soroban-internals/types/custom-types.mdx similarity index 96% rename from docs/soroban-internals/custom-types.mdx rename to docs/soroban-internals/types/custom-types.mdx index f2b3fd40..ff428d91 100644 --- a/docs/soroban-internals/custom-types.mdx +++ b/docs/soroban-internals/types/custom-types.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 50 +sidebar_position: 20 title: Custom Types description: Struct, union, and enum types defined by contracts. --- @@ -21,7 +21,7 @@ description: Struct, union, and enum types defined by contracts. /> -import stack from "../../static/img/stack.png"; +import stack from "@site/static/img/stack.png"; Custom types are struct, union, and enum types defined by contracts. They are usable everywhere primitives types can be used: as contract inputs, outputs, or @@ -30,7 +30,7 @@ for storage. :::info The [custom types example] demonstrates how to define your own types. -[custom types example]: ../tutorials/custom-types.mdx +[custom types example]: ../../tutorials/custom-types.mdx ::: @@ -38,7 +38,7 @@ The [custom types example] demonstrates how to define your own types. Error enum types are another type contracts can define that have some unique behaviors. See [Errors] for more information. -[Errors]: ./errors +[Errors]: ../errors.mdx ::: diff --git a/docs/soroban-internals/fully-typed-contracts.mdx b/docs/soroban-internals/types/fully-typed-contracts.mdx similarity index 84% rename from docs/soroban-internals/fully-typed-contracts.mdx rename to docs/soroban-internals/types/fully-typed-contracts.mdx index 06c37053..08f05778 100644 --- a/docs/soroban-internals/fully-typed-contracts.mdx +++ b/docs/soroban-internals/types/fully-typed-contracts.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 120 +sidebar_position: 30 title: "Fully-Typed Contracts" desctiption: Smart contract WASM files contain a machine-readable description of the interface type. sidebar_label: Fully-Typed Contracts @@ -25,11 +25,11 @@ sidebar_label: Fully-Typed Contracts /> -When you compile a contract created with [soroban-sdk](../resources/sdks/write-contracts.mdx#soroban-rust-sdk), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. +When you compile a contract created with [soroban-sdk](../../resources/sdks/write-contracts.mdx#soroban-rust-sdk), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. Today, these interface types are formatted using [XDR](https://developers.stellar.org/docs/encyclopedia/xdr), but this [may change](https://github.com/stellar/rs-soroban-sdk/issues/683) down the road. -The important part is that tooling can fetch these interface types to make your life easier. [Soroban CLI](../resources/soroban-cli.mdx) is the first tool to do so. Specifically, one subcommand: +The important part is that tooling can fetch these interface types to make your life easier. [Soroban CLI](../../resources/soroban-cli.mdx) is the first tool to do so. Specifically, one subcommand: ## `soroban contract invoke` @@ -41,7 +41,7 @@ A unique CLI for each smart contract. Constructed on-the-fly, right from the on- With aliases in your shell, you can also easily make explicit CLIs out of your most-used contracts. For example, if you use the [Smart Deploy](https://communityfund.stellar.org/projects/smart-deploy-scf-13) contract: -```text +```bash $ alias smartdeploy="soroban contract invoke --id 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee --" $ smartdeploy --help Usage: 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee [COMMAND] @@ -65,11 +65,13 @@ Options: Like any other CLI, you can also get help for any of these subcommands using something like `smartdeploy deploy --help`. Soroban CLI again fetches the on-chain interface types, this time using it to generate a full list of all arguments to the function, and even generates examples. And just to be totally clear, you don't need to alias these commands. This would work, too: - soroban contract invoke --id 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee -- deploy --help +```bash +soroban contract invoke --id 6808e8e2cce73cfca472a8197080938b320d72e7b696e34eb52ebf17070f4ee -- deploy --help +``` Or, if you clone [soroban-examples](https://github.com/stellar/soroban-examples) and `make build` them all, you can get CLI help for any individual contract or a specific function within a contract: -```text +```bash $ soroban contract invoke --id 1 --wasm target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm -- hello --help Usage: hello [OPTIONS] diff --git a/docs/tokens/stellar-asset-contract.mdx b/docs/tokens/stellar-asset-contract.mdx index 4607cda3..b05e1c20 100644 --- a/docs/tokens/stellar-asset-contract.mdx +++ b/docs/tokens/stellar-asset-contract.mdx @@ -50,7 +50,7 @@ smart contract developers to get started on Stellar. For every 'classic' asset exactly one respective Stellar Asset Contract can be deployed. It can be deployed using the `InvokeHostFunctionOp` with `HOST_FUNCTION_TYPE_CREATE_CONTRACT` and `CONTRACT_ID_FROM_ASSET` specified -[here](../soroban-internals/invoking-contracts-with-transactions). The resulting token will have a +[here](../soroban-internals/contract-interactions/stellar-transaction.mdx). The resulting token will have a deterministic identifier, which will be the sha256 hash of `HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET` xdr specified [here][contract_id]. diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index e18e55c1..30a46f7b 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -35,3 +35,7 @@ rewrite "^/docs/how-to-guides/tokens$" "/docs/advanced-tutorials/tokens" permane # - "resources/testnet" has been moved to "resources/networks" # - various SDK pages have been collapsed into "resources/sdks/{write-contracts,interact-with-contracts}" # - "data providers" has moved from "resources/sdks" into just "resources" +# - "soroban-internals/{built-in-types,custom-types,fully-typed-contracts}" have been moved into an umbrella "soroban-internals/types" directory +# - "soroban-internals/invoking-contracts-with-transactions.mdx" has moved to "soroban-internals/contract-interactions/stellar-transactions.mdx" +# - other misc shuffling of content and pages into "soroban-internals/contract-interactions/" +# - "soroban-internals/interacting-with-contracts.mdx" moved to "soroban-internals/contract-interactions/index.mdx" From 463ac2029cdcf330322ea82e9834cd164abc6148 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 13:53:25 -0600 Subject: [PATCH 23/95] style: fixing a couple small markdown nits in dapps directory --- dapps/index.mdx | 4 ++-- dapps/scaffold-soroban.mdx | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/dapps/index.mdx b/dapps/index.mdx index 0339c631..5b1caf1d 100644 --- a/dapps/index.mdx +++ b/dapps/index.mdx @@ -15,7 +15,7 @@ While the course specifically focuses on the Soroban platform, the knowledge you Through The Soroban Dapps Challenge, you'll have hands-on experience using Soroban's initial versions of the smart contracts environment, a Rust SDK, a CLI, and an RPC server. You'll learn how to write, test, and deploy smart contracts, and you'll get to see your code in action on Futurenet. -# What This Course Entails +## What This Course Entails We've designed this course as a learning adventure. It's a way for developers from the Stellar ecosystem and other blockchain communities to experiment, provide feedback, and contribute to the Soroban development process. @@ -26,7 +26,7 @@ As you progress through The Soroban Dapps Challenge, anticipate your code to bre To get started, simply head over to the [Dashboard](/dashboard), connect your wallet, and see what challenges await you! -# Giving Your Feedback +## Giving Your Feedback We value your input. Feel free to file issues in the Soroban repos or raise them in the soroban channel in the Stellar Developer [Discord](https://discord.gg/3qrBhbwE). diff --git a/dapps/scaffold-soroban.mdx b/dapps/scaffold-soroban.mdx index daf47bfb..6a64c382 100644 --- a/dapps/scaffold-soroban.mdx +++ b/dapps/scaffold-soroban.mdx @@ -4,9 +4,9 @@ title: Scaffold Soroban description: Dive into the simple implementations of Soroban dapps to understand and learn the Soroban ecosystem. --- -import ReactPlayer from 'react-player' +## Demonstrative Soroban Dapps -# Scaffold Soroban: Demonstrative Soroban Dapps +import ReactPlayer from 'react-player' The **Soroban** team has invested considerable effort into contract implementation. They’ve built CLI’s and libraries, enabling contract builders to create and invoke using Rust, which forms the “backend” of Soroban. However, the “frontend”, which involves JS client libraries, required attention. @@ -42,7 +42,7 @@ This dapp demonstrates a simplified swap between two tokens by using the wallet See the [demo](https://github.com/stellar/soroban-react-atomic-swap/releases/tag/v1.0.0) -### How To Explore the Dapps on Scaffold-Soroban +## How To Explore the Dapps on Scaffold-Soroban To begin using these examples, navigate to [Scaffold-Soroban](https://scaffold-soroban.stellar.org/) and choose the name of the dapp you're interested in from the "select demo" dropdown: @@ -58,7 +58,7 @@ With the introduction of these dapps, let's delve deeper into some of their [sta Functionality behind the dapps is extensive and diverse, leveraging the `soroban-client` library to integrate with the Soroban RPC and facilitating direct communication with Soroban using a JSON RPC interface on the Stellar network. They are equipped to communicate across different network setups, as they incorporate the `RPC_URLS` and `getServer` functionalities, providing adaptability that is crucial for various development and deployment scenarios. Users can retrieve user-friendly token information without engaging with complex blockchain operations, by utilizing functions like `getTokenSymbol`, `getTokenName`, and `getTokenDecimals`. -A significant feature is the `simulateTx` function, which allows users to preview the outcome of a transaction before actually executing it. `simulateTx` allows users to submit a trial contract invocation by first running a simulation of the contract invocation as defined on the incoming transaction. The results are then applied to a new copy of the transaction, which is returned with the ledger footprint and authorization set, making it ready for signing and sending. The returned transaction will also have an updated fee, the sum of the fee set on the incoming transaction with the contract resource fees estimated from the simulation. It is advisable to check the fee on the returned transaction and validate or take appropriate measures for interaction with the user to confirm it is acceptable. +A significant feature is the `simulateTx` function, which allows users to preview the outcome of a transaction before actually executing it. `simulateTx` allows users to submit a trial contract invocation by first running a simulation of the contract invocation as defined on the incoming transaction. The results are then applied to a new copy of the transaction, which is returned with the ledger footprint and authorization set, making it ready for signing and sending. The returned transaction will also have an updated fee, the sum of the fee set on the incoming transaction with the contract resource fees estimated from the simulation. It is advisable to check the fee on the returned transaction and validate or take appropriate measures for interaction with the user to confirm it is acceptable. Other utilities such as `accountToScVal` and `numberToI128` are also provided to simplify transaction creation by converting user-friendly inputs into the formats expected by the Soroban RPC on the Stellar network. Furthermore, the dapps are built with premade helper functions such as the `makePayment` function which facilitates streamlined "transfer" operations and also includes memos for supplementary transaction-related information. @@ -68,4 +68,4 @@ The code referenced showcases various functionalities including sending transact We hope these dapps will help you understand the Soroban ecosystem better and inspire you to build your own dapps using tools like [soroban-client](https://github.com/stellar/js-soroban-client) and [freighter-api](https://www.npmjs.com/package/@stellar/freighter-api). We look forward to seeing what you create! -For any queries or discussions, don't hesitate to join us on [Discord!](https://discord.com/channels/897514728459468821/1037073682599780494). \ No newline at end of file +For any queries or discussions, don't hesitate to join us on [Discord!](https://discord.com/channels/897514728459468821/1037073682599780494). From 4483a79234e295d2713856590d0b668bd3bb02c2 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 14:04:21 -0600 Subject: [PATCH 24/95] docs: fix a broken link --- docs/getting-started/hello-world.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/hello-world.mdx b/docs/getting-started/hello-world.mdx index 3d205ae7..b18be791 100644 --- a/docs/getting-started/hello-world.mdx +++ b/docs/getting-started/hello-world.mdx @@ -337,7 +337,7 @@ A `.wasm` file will be outputted in the `target` directory. The `.wasm` file is target/wasm32-unknown-unknown/release/hello_soroban.wasm ``` -The `.wasm` file contains the logic of the contract, as well as the contract's [specification / interface types](../soroban-internals/fully-typed-contracts.mdx), which can be imported into other contracts who wish to call it. This is the only artifact needed to deploy the contract, share the interface with others, or integration test against the contract. +The `.wasm` file contains the logic of the contract, as well as the contract's [specification / interface types](../soroban-internals/types/fully-typed-contracts.mdx), which can be imported into other contracts who wish to call it. This is the only artifact needed to deploy the contract, share the interface with others, or integration test against the contract. ## Optimizing Builds From 347a1597d7fd252d392f50207155507e60bc1c25 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 14:41:48 -0600 Subject: [PATCH 25/95] feat: start to the "guides" page(s) --- docusaurus.config.js | 34 ++++++++++++++----- guides/bump-a-deployed-contract-instance.mdx | 5 +++ ...bump-a-deployed-contract-storage-entry.mdx | 5 +++ guides/bump-a-deployed-contract-wasm-code.mdx | 5 +++ ...rt-a-contract-id-to-a-contract-address.mdx | 5 +++ .../convert-types-using-the-soroban-sdk.mdx | 5 +++ guides/index.mdx | 5 +++ sidebarsGuides.js | 8 +++++ 8 files changed, 63 insertions(+), 9 deletions(-) create mode 100644 guides/bump-a-deployed-contract-instance.mdx create mode 100644 guides/bump-a-deployed-contract-storage-entry.mdx create mode 100644 guides/bump-a-deployed-contract-wasm-code.mdx create mode 100644 guides/convert-a-contract-id-to-a-contract-address.mdx create mode 100644 guides/convert-types-using-the-soroban-sdk.mdx create mode 100644 guides/index.mdx create mode 100644 sidebarsGuides.js diff --git a/docusaurus.config.js b/docusaurus.config.js index 9432516a..798b4e5b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -35,15 +35,26 @@ const config = { ], [ '@docusaurus/plugin-content-docs', - { - id: 'dapps', - path: 'dapps', - routeBasePath: 'dapps', - sidebarPath: require.resolve('./sidebarsDapps.js'), - editUrl: "https://github.com/stellar/soroban-docs/tree/main/", - showLastUpdateTime: true, - }, - ], + { + id: 'dapps', + path: 'dapps', + routeBasePath: 'dapps', + sidebarPath: require.resolve('./sidebarsDapps.js'), + editUrl: "https://github.com/stellar/soroban-docs/tree/main/", + showLastUpdateTime: true, + }, + ], + [ + '@docusaurus/plugin-content-docs', + { + id: 'guides', + path: 'guides', + routeBasePath: 'guides', + sidebarPath: require.resolve('./sidebarsGuides.js'), + editUrl: "https://github.com/stellar/soroban-docs/tree/main/", + showLastUpdateTime: true, + }, + ], require('./src/dev-server-plugin'), require('./src/analytics-module') ], @@ -107,6 +118,11 @@ const config = { label: 'Dapps', position: 'left' }, + { + to: '/guides', + label: 'Guides', + position: 'left' + }, { href: 'https://github.com/stellar/rs-soroban-sdk', label: 'GitHub', diff --git a/guides/bump-a-deployed-contract-instance.mdx b/guides/bump-a-deployed-contract-instance.mdx new file mode 100644 index 00000000..08682524 --- /dev/null +++ b/guides/bump-a-deployed-contract-instance.mdx @@ -0,0 +1,5 @@ +--- +title: Bump a deployed contract instance +--- + +Explain how to do the thing. diff --git a/guides/bump-a-deployed-contract-storage-entry.mdx b/guides/bump-a-deployed-contract-storage-entry.mdx new file mode 100644 index 00000000..87834699 --- /dev/null +++ b/guides/bump-a-deployed-contract-storage-entry.mdx @@ -0,0 +1,5 @@ +--- +title: Bump a deployed contract storage entry +--- + +Explain how to do the thing. diff --git a/guides/bump-a-deployed-contract-wasm-code.mdx b/guides/bump-a-deployed-contract-wasm-code.mdx new file mode 100644 index 00000000..33867a91 --- /dev/null +++ b/guides/bump-a-deployed-contract-wasm-code.mdx @@ -0,0 +1,5 @@ +--- +title: Bump a deployed contract Wasm code +--- + +Explain how to do the thing. diff --git a/guides/convert-a-contract-id-to-a-contract-address.mdx b/guides/convert-a-contract-id-to-a-contract-address.mdx new file mode 100644 index 00000000..34e80db8 --- /dev/null +++ b/guides/convert-a-contract-id-to-a-contract-address.mdx @@ -0,0 +1,5 @@ +--- +title: Convert a contract ID to a contract address +--- + +Explain how to do the thing. diff --git a/guides/convert-types-using-the-soroban-sdk.mdx b/guides/convert-types-using-the-soroban-sdk.mdx new file mode 100644 index 00000000..9504c447 --- /dev/null +++ b/guides/convert-types-using-the-soroban-sdk.mdx @@ -0,0 +1,5 @@ +--- +title: Convert types using the soroban-sdk +--- + +Explain how to do the thing. diff --git a/guides/index.mdx b/guides/index.mdx new file mode 100644 index 00000000..df21a533 --- /dev/null +++ b/guides/index.mdx @@ -0,0 +1,5 @@ +--- +title: Soroban Guides +--- + +these are the descriptive, bite-sized "chunks" that explain how to do something. diff --git a/sidebarsGuides.js b/sidebarsGuides.js new file mode 100644 index 00000000..9b41a1be --- /dev/null +++ b/sidebarsGuides.js @@ -0,0 +1,8 @@ +module.exports = { + guidesSidebar: [ + { + type: 'autogenerated', + dirName: '.', + }, + ], + }; From 10748f27164f43c449993f59f5dba34627575236 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 14:46:44 -0600 Subject: [PATCH 26/95] style(lint): fixing a small linting error --- docs/faq.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/faq.mdx b/docs/faq.mdx index f9db2fb5..8932e007 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -15,10 +15,7 @@ description: Frequently asked questions about Soroban on Stellar. property="og:description" content="Frequently asked questions about Soroban on Stellar." /> - + :::caution From a362d3bfe4cecd9f71bad460a3dfb6c9773a8a6e Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 15:22:11 -0600 Subject: [PATCH 27/95] remove guides placeholder --- guides/bump-a-deployed-contract-instance.mdx | 5 ----- guides/bump-a-deployed-contract-storage-entry.mdx | 5 ----- guides/bump-a-deployed-contract-wasm-code.mdx | 5 ----- guides/convert-a-contract-id-to-a-contract-address.mdx | 5 ----- guides/convert-types-using-the-soroban-sdk.mdx | 5 ----- guides/index.mdx | 5 ----- 6 files changed, 30 deletions(-) delete mode 100644 guides/bump-a-deployed-contract-instance.mdx delete mode 100644 guides/bump-a-deployed-contract-storage-entry.mdx delete mode 100644 guides/bump-a-deployed-contract-wasm-code.mdx delete mode 100644 guides/convert-a-contract-id-to-a-contract-address.mdx delete mode 100644 guides/convert-types-using-the-soroban-sdk.mdx delete mode 100644 guides/index.mdx diff --git a/guides/bump-a-deployed-contract-instance.mdx b/guides/bump-a-deployed-contract-instance.mdx deleted file mode 100644 index 08682524..00000000 --- a/guides/bump-a-deployed-contract-instance.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Bump a deployed contract instance ---- - -Explain how to do the thing. diff --git a/guides/bump-a-deployed-contract-storage-entry.mdx b/guides/bump-a-deployed-contract-storage-entry.mdx deleted file mode 100644 index 87834699..00000000 --- a/guides/bump-a-deployed-contract-storage-entry.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Bump a deployed contract storage entry ---- - -Explain how to do the thing. diff --git a/guides/bump-a-deployed-contract-wasm-code.mdx b/guides/bump-a-deployed-contract-wasm-code.mdx deleted file mode 100644 index 33867a91..00000000 --- a/guides/bump-a-deployed-contract-wasm-code.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Bump a deployed contract Wasm code ---- - -Explain how to do the thing. diff --git a/guides/convert-a-contract-id-to-a-contract-address.mdx b/guides/convert-a-contract-id-to-a-contract-address.mdx deleted file mode 100644 index 34e80db8..00000000 --- a/guides/convert-a-contract-id-to-a-contract-address.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Convert a contract ID to a contract address ---- - -Explain how to do the thing. diff --git a/guides/convert-types-using-the-soroban-sdk.mdx b/guides/convert-types-using-the-soroban-sdk.mdx deleted file mode 100644 index 9504c447..00000000 --- a/guides/convert-types-using-the-soroban-sdk.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Convert types using the soroban-sdk ---- - -Explain how to do the thing. diff --git a/guides/index.mdx b/guides/index.mdx deleted file mode 100644 index df21a533..00000000 --- a/guides/index.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Soroban Guides ---- - -these are the descriptive, bite-sized "chunks" that explain how to do something. From 2b562ce17a2ad0f7a2e5a2016d1b8ac5eecaf1fb Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 8 Nov 2023 15:53:32 -0600 Subject: [PATCH 28/95] fixing broken links --- docs/migrate/evm/smart-contract-deployment.mdx | 2 +- .../evm/solidity-and-rust-advanced-concepts.mdx | 4 ++-- docs/migrate/evm/solidity-and-rust-basics.mdx | 4 ++-- docs/resources/rpc.mdx | 2 +- .../stellar-transaction.mdx | 4 ++-- docs/tokens/token-interface.mdx | 4 ++-- docs/tutorials/liquidity-pool.mdx | 2 +- docusaurus.config.js | 16 ---------------- 8 files changed, 11 insertions(+), 27 deletions(-) diff --git a/docs/migrate/evm/smart-contract-deployment.mdx b/docs/migrate/evm/smart-contract-deployment.mdx index adb279ad..d1504d7e 100644 --- a/docs/migrate/evm/smart-contract-deployment.mdx +++ b/docs/migrate/evm/smart-contract-deployment.mdx @@ -62,7 +62,7 @@ async function main() { ### Soroban Client -Soroban offers a comparable library, [`js-soroban-client`](../../resources/sdks/js), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for `soroban-rpc` methods, simplifying the process of building and signing transactions. Additionally, `js-soroban-client` streamlines communication with `soroban-rpc` instances and supports submitting transactions or querying network state with ease. +Soroban offers a comparable library, [`js-soroban-client`](../../resources/sdks/interact-with-contracts.mdx#javascript-sdk), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for `soroban-rpc` methods, simplifying the process of building and signing transactions. Additionally, `js-soroban-client` streamlines communication with `soroban-rpc` instances and supports submitting transactions or querying network state with ease. ### Scripts diff --git a/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx b/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx index 641a5414..12eeac6a 100644 --- a/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx +++ b/docs/migrate/evm/solidity-and-rust-advanced-concepts.mdx @@ -409,13 +409,13 @@ It's worth mentioning that the Soroban Rust SDK comes with several built-in requ Interfaces are an essential part of building smart contracts with Soroban. -There are many types of smart contract interfaces, and each has a specific purpose. One example of an interface built with Soroban is the [Token Interface](../../resources/interfaces/token-interface). This interface ensures that tokens deployed on Soroban are interoperable with Soroban's built-in tokens (such as the Stellar Asset Contract). The Token Interface consists of three compatibility requirements: +There are many types of smart contract interfaces, and each has a specific purpose. One example of an interface built with Soroban is the [Token Interface](../../tokens/token-interface.mdx). This interface ensures that tokens deployed on Soroban are interoperable with Soroban's built-in tokens (such as the Stellar Asset Contract). The Token Interface consists of three compatibility requirements: - `function interface` - `authorization` - `events` -For more information on smart contract interfaces built with Soroban, including the Token Interface, visit the [interfaces section](../../category/interfaces) of the documentation. +For more information on smart contract interfaces built with Soroban, including the Token Interface, visit the [tokens section](../../category/tokens) of the documentation. ## Writing Safe and Efficient Rust Code for Smart Contracts diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index 27fa68f3..c7f1f67c 100644 --- a/docs/migrate/evm/solidity-and-rust-basics.mdx +++ b/docs/migrate/evm/solidity-and-rust-basics.mdx @@ -121,7 +121,7 @@ fn main() { ### Data Types -The [Soroban Rust SDK](https://docs.rs/soroban-sdk/latest/soroban_sdk/index.html) supports a variety of [Built-In Types](../../soroban-internals/built-in-types) which consist of both Primitive and [Custom Types](../../soroban-internals/custom-types), such as: +The [Soroban Rust SDK](https://docs.rs/soroban-sdk/latest/soroban_sdk/index.html) supports a variety of [Built-In Types](../../soroban-internals/types/built-in-types) which consist of both Primitive and [Custom Types](../../soroban-internals/types/custom-types), such as: #### Primitive Data Types @@ -455,7 +455,7 @@ impl IncrementContract { } ``` -This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](../../resources/sdks/rust), a Rust-based smart contract development toolkit developed by the [Stellar Development Foundation (SDF)](https://stellar.org/foundation). The Soroban Rust SDK provides a powerful set of tools for writing smart contracts that run on the Soroban Virtual Machine. +This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](../../resources/sdks/write-contracts.mdx#soroban-rust-sdk), a Rust-based smart contract development toolkit developed by the [Stellar Development Foundation (SDF)](https://stellar.org/foundation). The Soroban Rust SDK provides a powerful set of tools for writing smart contracts that run on the Soroban Virtual Machine. Here's a line-by-line explanation of what the code is doing: diff --git a/docs/resources/rpc.mdx b/docs/resources/rpc.mdx index b59877cd..a9ffb830 100644 --- a/docs/resources/rpc.mdx +++ b/docs/resources/rpc.mdx @@ -111,7 +111,7 @@ soroban contract invoke \ When you're done with your Standalone node, you can close it with ctrlc (not cmd). This will fully remove the container (that's what the `--rm` option to the `docker` command does), which means you will need to re-deploy your contract and re-fund your identity the next time you start it. If you work with local nodes often, you may want to create scripts to make these initialization steps easier. For example, see the [example dapp's `initialize.sh`](https://github.com/stellar/soroban-example-dapp/blob/abdac3afdb6c410cc426831ece93371c1a27347d/initialize.sh). -[Testnet]: testnet +[Testnet]: networks.mdx [Run on Sandbox]: ../getting-started/hello-world#run-on-sandbox ### Testnet diff --git a/docs/soroban-internals/contract-interactions/stellar-transaction.mdx b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx index 08a04615..db3dc93d 100644 --- a/docs/soroban-internals/contract-interactions/stellar-transaction.mdx +++ b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx @@ -29,7 +29,7 @@ import TabItem from "@theme/TabItem"; ## Example SDK Usage -Some (but not all yet) of the Stellar SDKs have functions built-in to handle most of the process of building a Stellar transaction to interact with a Soroban smart contract. Below, we demonstrate in JavaScript and Python how to build and submit a Stellar transaction that will invoke an instance of the [increment example](../getting-started/storing-data) smart contract. +Some (but not all yet) of the Stellar SDKs have functions built-in to handle most of the process of building a Stellar transaction to interact with a Soroban smart contract. Below, we demonstrate in JavaScript and Python how to build and submit a Stellar transaction that will invoke an instance of the [increment example](../../getting-started/storing-data) smart contract. @@ -267,7 +267,7 @@ The `InvokeHostFunctionOp` can be used to perform the following Soroban operatio - Upload Wasm of the new contracts. - Deploy new contracts using the uploaded Wasm or built-in implementations (this currently includes only the [token contract](../../tokens/stellar-asset-contract.mdx)). -[`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli +[`soroban-cli`]: ../../getting-started/setup#install-the-soroban-cli There is only a single `InvokeHostFunctionOp` allowed per transaction. Contracts should be used to perform multiple actions atomically, for example, to deploy diff --git a/docs/tokens/token-interface.mdx b/docs/tokens/token-interface.mdx index 45e5031e..c04bb9ac 100644 --- a/docs/tokens/token-interface.mdx +++ b/docs/tokens/token-interface.mdx @@ -34,7 +34,7 @@ consistent with the interface described here: ### Code -The interface below uses the Rust [soroban-sdk](https://soroban.stellar.org/docs/reference/sdks/rust). +The interface below uses the Rust [soroban-sdk](../resources/sdks/write-contracts.mdx#soroban-rust-sdk). ```rust pub trait Contract { @@ -209,7 +209,7 @@ Its important to note the that the token interface not only incorporates the aut To provide more context, when you use the token interface, there is a function called `authorized` that returns "true" if an address has token authorization. -More details on Authorization can be found [here](../../soroban-internals/authorization). +More details on Authorization can be found [here](../soroban-internals/authorization). For the functions in the token interface, [trapping](https://doc.rust-lang.org/book/ch09-00-error-handling.html) should be used as the standard way to handle failure conditions since the interface is not designed to return error codes. This means that when a function encounters an error, it will halt execution and revert any state changes that occurred during the function call. diff --git a/docs/tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx index 21200bb6..53f14103 100644 --- a/docs/tutorials/liquidity-pool.mdx +++ b/docs/tutorials/liquidity-pool.mdx @@ -594,7 +594,7 @@ Soroban tokens: really care, as long as the functions it needs from the common [Token Interface] are available in the token contract. -[Token Interface]: ../resources/interfaces/token-interface +[Token Interface]: ../tokens/token-interface.mdx #### Creating a Custom `POOL` Token for LP Shares diff --git a/docusaurus.config.js b/docusaurus.config.js index 798b4e5b..9da585d0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -44,17 +44,6 @@ const config = { showLastUpdateTime: true, }, ], - [ - '@docusaurus/plugin-content-docs', - { - id: 'guides', - path: 'guides', - routeBasePath: 'guides', - sidebarPath: require.resolve('./sidebarsGuides.js'), - editUrl: "https://github.com/stellar/soroban-docs/tree/main/", - showLastUpdateTime: true, - }, - ], require('./src/dev-server-plugin'), require('./src/analytics-module') ], @@ -118,11 +107,6 @@ const config = { label: 'Dapps', position: 'left' }, - { - to: '/guides', - label: 'Guides', - position: 'left' - }, { href: 'https://github.com/stellar/rs-soroban-sdk', label: 'GitHub', From 7fd260dc3804ae1d960218c4624858c001542760 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 9 Nov 2023 15:37:23 -0600 Subject: [PATCH 29/95] work on guides listing. might revert this --- docs/tutorials/_category_.json | 3 ++- docs/tutorials/index.mdx | 10 ++++++++++ docusaurus.config.js | 18 ++++++++++++++++++ guides/guide1.mdx | 11 +++++++++++ guides/guide2.mdx | 11 +++++++++++ guides/guide3.mdx | 8 ++++++++ guides/guide4.mdx | 8 ++++++++ guides/guide5.mdx | 8 ++++++++ guides/index.mdx | 17 +++++++++++++++++ sidebars.js | 2 +- 10 files changed, 94 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/index.mdx create mode 100644 guides/guide1.mdx create mode 100644 guides/guide2.mdx create mode 100644 guides/guide3.mdx create mode 100644 guides/guide4.mdx create mode 100644 guides/guide5.mdx create mode 100644 guides/index.mdx diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json index 74f2f140..f82ea08d 100644 --- a/docs/tutorials/_category_.json +++ b/docs/tutorials/_category_.json @@ -2,6 +2,7 @@ "position": 30, "label": "Tutorials", "link": { - "type": "generated-index" + "type": "doc", + "id": "tutorials/index" } } diff --git a/docs/tutorials/index.mdx b/docs/tutorials/index.mdx new file mode 100644 index 00000000..5961c718 --- /dev/null +++ b/docs/tutorials/index.mdx @@ -0,0 +1,10 @@ +--- +title: Tutorials +slug: /tutorials +--- + +import DocCardList from '@theme/DocCardList' + +The page with the things! + + diff --git a/docusaurus.config.js b/docusaurus.config.js index 9da585d0..a3270cca 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -22,6 +22,17 @@ const config = { }, plugins: [ "docusaurus-plugin-sass", + [ + '@docusaurus/plugin-content-docs', + { + id: 'guides', + path: 'guides', + routeBasePath: 'guides', + sidebarPath: require.resolve('./sidebarsGuides.js'), + editUrl: "https://github.com/stellar/soroban-docs/tree/main/", + showLastUpdateTime: true, + }, + ], [ '@docusaurus/plugin-content-docs', { @@ -58,6 +69,8 @@ const config = { breadcrumbs: true, sidebarPath: require.resolve("./sidebars.js"), editUrl: "https://github.com/stellar/soroban-docs/tree/main/", + // sidebarItemsGenerator: require('./src/sidebar-docs-generator'), + // exclude: ['**/guides/*.mdx'], }, theme: { customCss: [require.resolve("./src/css/custom.scss")], @@ -107,6 +120,11 @@ const config = { label: 'Dapps', position: 'left' }, + { + to: '/guides', + label: 'Guides', + position: 'left' + }, { href: 'https://github.com/stellar/rs-soroban-sdk', label: 'GitHub', diff --git a/guides/guide1.mdx b/guides/guide1.mdx new file mode 100644 index 00000000..e7023c99 --- /dev/null +++ b/guides/guide1.mdx @@ -0,0 +1,11 @@ +--- +title: guide 1 +description: really useful guide number one +tags: +- your +- mom +--- + +# Guided Guide 1 + +This is a guide to do something. diff --git a/guides/guide2.mdx b/guides/guide2.mdx new file mode 100644 index 00000000..f3603b86 --- /dev/null +++ b/guides/guide2.mdx @@ -0,0 +1,11 @@ +--- +title: guide 2 +description: really useful guide number two +tags: +- your +- dad +--- + +# Guided Guide 2 + +This is a guide to do something. diff --git a/guides/guide3.mdx b/guides/guide3.mdx new file mode 100644 index 00000000..4cfee00b --- /dev/null +++ b/guides/guide3.mdx @@ -0,0 +1,8 @@ +--- +title: guide 3 +description: really useful guide number three +--- + +# Guided Guide 3 + +This is a guide to do something. diff --git a/guides/guide4.mdx b/guides/guide4.mdx new file mode 100644 index 00000000..6bd6dd04 --- /dev/null +++ b/guides/guide4.mdx @@ -0,0 +1,8 @@ +--- +title: guide 4 +description: really useful guide number four +--- + +# Guided Guide 4 + +This is a guide to do something. diff --git a/guides/guide5.mdx b/guides/guide5.mdx new file mode 100644 index 00000000..80f51697 --- /dev/null +++ b/guides/guide5.mdx @@ -0,0 +1,8 @@ +--- +title: guide 5 +description: really useful guide number five +--- + +# Guided Guide 5 + +This is a guide to do something. diff --git a/guides/index.mdx b/guides/index.mdx new file mode 100644 index 00000000..fcee9812 --- /dev/null +++ b/guides/index.mdx @@ -0,0 +1,17 @@ +--- +title: Guided Guides +description: here you will find really useful guides +hide_table_of_contents: true +--- + +# Gateway to Guides + +We'll list a bunch of stuff. + +## Like this + +or that + +## Or even those + +Nah, nevermind. diff --git a/sidebars.js b/sidebars.js index 825262a8..801bdbf8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -5,4 +5,4 @@ module.exports = { dirName: '.', }, ], -}; \ No newline at end of file +}; From 69fd7dc0f1f2438fda87a47c0732575b78e029c5 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Fri, 17 Nov 2023 12:46:07 -0600 Subject: [PATCH 30/95] formatting mdx --- docs/tutorials/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/index.mdx b/docs/tutorials/index.mdx index 5961c718..08a59326 100644 --- a/docs/tutorials/index.mdx +++ b/docs/tutorials/index.mdx @@ -3,7 +3,7 @@ title: Tutorials slug: /tutorials --- -import DocCardList from '@theme/DocCardList' +import DocCardList from "@theme/DocCardList"; The page with the things! From 0f7fbc2aabce093c2a93a67f6f9d71652dd15eb5 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Mon, 20 Nov 2023 14:57:04 -0600 Subject: [PATCH 31/95] docs: fixing a broken link to tutorials --- docs/getting-started/create-an-app.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/create-an-app.mdx b/docs/getting-started/create-an-app.mdx index 359862dc..d1967fda 100644 --- a/docs/getting-started/create-an-app.mdx +++ b/docs/getting-started/create-an-app.mdx @@ -483,6 +483,6 @@ Looking at `git diff` will be a great way to remember all the interesting things At this point, you've seen a full end-to-end example of building on Soroban! What's next? You choose! You can: -- See more complex example contracts in the [Basic Tutorials](/docs/category/tutorials) and [Advanced Tutorials](/docs/category/tutorials) sections. +- See more complex example contracts in the [Tutorials](/docs/tutorials) section. - Learn more about the [fundamentals and concepts](/docs/category/soroban-internals) of Soroban. - Check out a more full-featured [example app](https://github.com/stellar/soroban-example-dapp), which uses React rather than vanilla JavaScript and Next.js rather than Astro. This app also has a more complex setup & initialization process, with the option of using a [locally-hosted RPC node](../resources/rpc.mdx). From 8ac467dbac4ec5f1aceb75531b69db7e3df3e3c1 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Tue, 21 Nov 2023 14:27:57 -0600 Subject: [PATCH 32/95] style: crack at making the tutorials filterable and hidden in the sidebar --- docs/tutorials/TUTORIAL-TEMPLATE.mdx | 3 + docs/tutorials/_category_.json | 3 +- docs/tutorials/alloc.mdx | 6 +- docs/tutorials/atomic-multi-swap.mdx | 6 +- docs/tutorials/atomic-swap.mdx | 6 +- docs/tutorials/auth.mdx | 6 +- docs/tutorials/cross-contract-call.mdx | 6 +- docs/tutorials/custom-account.mdx | 6 +- docs/tutorials/custom-types.mdx | 6 +- docs/tutorials/deployer.mdx | 6 +- docs/tutorials/errors.mdx | 6 +- docs/tutorials/events.mdx | 6 +- docs/tutorials/fuzzing.mdx | 6 +- docs/tutorials/index.mdx | 2 +- docs/tutorials/liquidity-pool.mdx | 6 +- docs/tutorials/logging.mdx | 6 +- docs/tutorials/single-offer-sale.mdx | 6 +- docs/tutorials/timelock.mdx | 6 +- docs/tutorials/tokens.mdx | 6 +- docs/tutorials/upgrading-contracts.mdx | 6 +- docs/tutorials/wasm-metadata.mdx | 6 +- docusaurus.config.js | 2 +- sidebars.js | 5 ++ src/components/atoms/SortableRow/index.js | 14 +++++ .../molecules/SortableTable/index.js | 34 ++++++++++ .../molecules/SortableTable/style.module.css | 4 ++ src/css/custom.scss | 6 ++ src/sidebar-docs-generator.js | 26 ++++++++ src/theme/DocCardList/index.js | 62 +++++++++++++++++++ src/theme/DocCardList/style.module.css | 7 +++ 30 files changed, 219 insertions(+), 57 deletions(-) create mode 100644 src/components/atoms/SortableRow/index.js create mode 100644 src/components/molecules/SortableTable/index.js create mode 100644 src/components/molecules/SortableTable/style.module.css create mode 100644 src/sidebar-docs-generator.js create mode 100644 src/theme/DocCardList/index.js create mode 100644 src/theme/DocCardList/style.module.css diff --git a/docs/tutorials/TUTORIAL-TEMPLATE.mdx b/docs/tutorials/TUTORIAL-TEMPLATE.mdx index ce5625c2..7726c94f 100644 --- a/docs/tutorials/TUTORIAL-TEMPLATE.mdx +++ b/docs/tutorials/TUTORIAL-TEMPLATE.mdx @@ -3,6 +3,9 @@ sidebar_position: 1000 title: Tutorial Template description: A description of the tutorial that is being written draft: true +sidebar_custom_props: + tutorial: + level: intermediate --- Quick note about what this [example demonstrates]. Maybe it's also based on some diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json index f82ea08d..0a547f6c 100644 --- a/docs/tutorials/_category_.json +++ b/docs/tutorials/_category_.json @@ -4,5 +4,6 @@ "link": { "type": "doc", "id": "tutorials/index" - } + }, + "collapsible": false } diff --git a/docs/tutorials/alloc.mdx b/docs/tutorials/alloc.mdx index 07c88c08..77ccf1e4 100644 --- a/docs/tutorials/alloc.mdx +++ b/docs/tutorials/alloc.mdx @@ -2,9 +2,9 @@ sidebar_position: 7 title: Allocator description: Use the allocator feature in a smart contract. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: intermediate --- diff --git a/docs/tutorials/atomic-multi-swap.mdx b/docs/tutorials/atomic-multi-swap.mdx index 75b6cccf..344cad99 100644 --- a/docs/tutorials/atomic-multi-swap.mdx +++ b/docs/tutorials/atomic-multi-swap.mdx @@ -2,9 +2,9 @@ sidebar_position: 4 title: Batched Atomic Swaps description: Swap tokens between two groups. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/atomic-swap.mdx b/docs/tutorials/atomic-swap.mdx index 78bf49fa..ee1d11cc 100644 --- a/docs/tutorials/atomic-swap.mdx +++ b/docs/tutorials/atomic-swap.mdx @@ -2,9 +2,9 @@ sidebar_position: 3 title: Atomic Swap description: Swap tokens atomically between two parties. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/auth.mdx b/docs/tutorials/auth.mdx index 2092e383..e866e9cb 100644 --- a/docs/tutorials/auth.mdx +++ b/docs/tutorials/auth.mdx @@ -2,9 +2,9 @@ sidebar_position: 4 title: Auth description: Implement authentication and authorization. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/cross-contract-call.mdx b/docs/tutorials/cross-contract-call.mdx index 5c21d1d2..457576db 100644 --- a/docs/tutorials/cross-contract-call.mdx +++ b/docs/tutorials/cross-contract-call.mdx @@ -2,9 +2,9 @@ sidebar_position: 5 title: Cross Contract Calls description: Call a smart contract from another smart contract. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/custom-account.mdx b/docs/tutorials/custom-account.mdx index db0bf818..a636f436 100644 --- a/docs/tutorials/custom-account.mdx +++ b/docs/tutorials/custom-account.mdx @@ -2,9 +2,9 @@ sidebar_position: 8 title: Custom Account description: Implement a contract that supports multisig and custom auth policies. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/custom-types.mdx b/docs/tutorials/custom-types.mdx index 3a4a153a..af8c3341 100644 --- a/docs/tutorials/custom-types.mdx +++ b/docs/tutorials/custom-types.mdx @@ -2,9 +2,9 @@ sidebar_position: 4 title: Custom Types description: Define your data structures. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/deployer.mdx b/docs/tutorials/deployer.mdx index 181069cb..91c73367 100644 --- a/docs/tutorials/deployer.mdx +++ b/docs/tutorials/deployer.mdx @@ -2,9 +2,9 @@ sidebar_position: 6 title: Deployer description: Deploy a smart contract using another smart contract. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/errors.mdx b/docs/tutorials/errors.mdx index a76b62ed..e9b4b5e8 100644 --- a/docs/tutorials/errors.mdx +++ b/docs/tutorials/errors.mdx @@ -2,9 +2,9 @@ sidebar_position: 2 title: Errors description: Define and generate errors in a smart contract. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/events.mdx b/docs/tutorials/events.mdx index f79900af..0075c129 100644 --- a/docs/tutorials/events.mdx +++ b/docs/tutorials/events.mdx @@ -2,9 +2,9 @@ sidebar_position: 1 title: Events description: Publish events from a contract. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/fuzzing.mdx b/docs/tutorials/fuzzing.mdx index 21dd210c..ea21dc8c 100644 --- a/docs/tutorials/fuzzing.mdx +++ b/docs/tutorials/fuzzing.mdx @@ -2,9 +2,9 @@ sidebar_position: 9 title: Fuzz Testing description: Fuzz test contracts with cargo-fuzz. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/index.mdx b/docs/tutorials/index.mdx index 08a59326..dc80386d 100644 --- a/docs/tutorials/index.mdx +++ b/docs/tutorials/index.mdx @@ -5,6 +5,6 @@ slug: /tutorials import DocCardList from "@theme/DocCardList"; -The page with the things! +The page lists all tutorials we have available for Soroban. Simply put, a "tutorial" is a guide or example that ends with a deployable smart contract. You can use the provided filters to find a relevant tutorial for your experience level. diff --git a/docs/tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx index 53f14103..ef8ef2f0 100644 --- a/docs/tutorials/liquidity-pool.mdx +++ b/docs/tutorials/liquidity-pool.mdx @@ -2,9 +2,9 @@ sidebar_position: 7 title: Liquidity Pool description: Write a constant-product liquidity pool contract. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/logging.mdx b/docs/tutorials/logging.mdx index 372766a1..81615ea8 100644 --- a/docs/tutorials/logging.mdx +++ b/docs/tutorials/logging.mdx @@ -2,9 +2,9 @@ sidebar_position: 3 title: Logging description: Use logs to debug smart contracts. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/single-offer-sale.mdx b/docs/tutorials/single-offer-sale.mdx index ba22bbaa..df06fa23 100644 --- a/docs/tutorials/single-offer-sale.mdx +++ b/docs/tutorials/single-offer-sale.mdx @@ -2,9 +2,9 @@ sidebar_position: 6 title: Single Offer Sale description: Allow a seller to sell one token for another token to multiple buyers. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/timelock.mdx b/docs/tutorials/timelock.mdx index 540c6f11..925b0739 100644 --- a/docs/tutorials/timelock.mdx +++ b/docs/tutorials/timelock.mdx @@ -2,9 +2,9 @@ sidebar_position: 5 title: Timelock description: Write a timelock implementing a claimable balance. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: advanced --- diff --git a/docs/tutorials/tokens.mdx b/docs/tutorials/tokens.mdx index fc8ae924..da4bd231 100644 --- a/docs/tutorials/tokens.mdx +++ b/docs/tutorials/tokens.mdx @@ -2,9 +2,9 @@ sidebar_position: 1 title: Tokens description: Construct a smart contract token. -tags: - - tutorial - - advanced +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/upgrading-contracts.mdx b/docs/tutorials/upgrading-contracts.mdx index 46ea0b2e..bf95b18c 100644 --- a/docs/tutorials/upgrading-contracts.mdx +++ b/docs/tutorials/upgrading-contracts.mdx @@ -2,9 +2,9 @@ sidebar_position: 9 title: Upgrading Contracts description: Upgrade a WASM smart contract. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docs/tutorials/wasm-metadata.mdx b/docs/tutorials/wasm-metadata.mdx index 5f6c8507..e8c2fd78 100644 --- a/docs/tutorials/wasm-metadata.mdx +++ b/docs/tutorials/wasm-metadata.mdx @@ -2,9 +2,9 @@ sidebar_position: 8 title: Metadata description: Write structured metadata. -tags: - - tutorial - - beginner +sidebar_custom_props: + tutorial: + level: beginner --- diff --git a/docusaurus.config.js b/docusaurus.config.js index a3270cca..161a2058 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -69,7 +69,7 @@ const config = { breadcrumbs: true, sidebarPath: require.resolve("./sidebars.js"), editUrl: "https://github.com/stellar/soroban-docs/tree/main/", - // sidebarItemsGenerator: require('./src/sidebar-docs-generator'), + sidebarItemsGenerator: require('./src/sidebar-docs-generator'), // exclude: ['**/guides/*.mdx'], }, theme: { diff --git a/sidebars.js b/sidebars.js index 801bdbf8..773a38fe 100644 --- a/sidebars.js +++ b/sidebars.js @@ -4,5 +4,10 @@ module.exports = { type: 'autogenerated', dirName: '.', }, + // { + // type: 'doc', + // id: 'tutorials/index', + // label: 'Tutorials Too', + // }, ], }; diff --git a/src/components/atoms/SortableRow/index.js b/src/components/atoms/SortableRow/index.js new file mode 100644 index 00000000..beaa46b5 --- /dev/null +++ b/src/components/atoms/SortableRow/index.js @@ -0,0 +1,14 @@ +import React from "react" + +const SortableRow = (props) => { + console.log('SortableRow props', props) + return ( + + {props.title} + click here + {props.difficulty} + + ) +} + +export default SortableRow diff --git a/src/components/molecules/SortableTable/index.js b/src/components/molecules/SortableTable/index.js new file mode 100644 index 00000000..662634cb --- /dev/null +++ b/src/components/molecules/SortableTable/index.js @@ -0,0 +1,34 @@ +import React, { useState } from "react" +import styles from "./style.module.css"; + +const arrowDown = ▼; +const arrowUp = ▲; + +const SortableTable = (props) => { + console.log('SortableTable props', props) + const [isAscending, setIsAscending] = useState(false); + const [sortColumn, setSortColumn] = useState(null) + + const sortTable = (val) => { + const sortDirection = col === val ? !isAscending : false + setIsAscending(sortDirection) + setSortColumn(val) + } + + return ( + + + + + + + + + + {props.children} + +
TitleLinkTags
+ ) +} + +export default SortableTable diff --git a/src/components/molecules/SortableTable/style.module.css b/src/components/molecules/SortableTable/style.module.css new file mode 100644 index 00000000..3a41004c --- /dev/null +++ b/src/components/molecules/SortableTable/style.module.css @@ -0,0 +1,4 @@ +.sortable { + width: 100%; + display: table; +} diff --git a/src/css/custom.scss b/src/css/custom.scss index 2a7fb3e9..c63fec03 100644 --- a/src/css/custom.scss +++ b/src/css/custom.scss @@ -171,3 +171,9 @@ select[data-testid="example-pairing-select"] { font-size: var(--ifm-font-size-base); border-radius: 5px; } + +/* Hidden sidebar items */ + +.sidebar-category-items-hidden ul { + display: none !important; +} diff --git a/src/sidebar-docs-generator.js b/src/sidebar-docs-generator.js new file mode 100644 index 00000000..55a38872 --- /dev/null +++ b/src/sidebar-docs-generator.js @@ -0,0 +1,26 @@ +const fs = require('fs') +const path = require('path') + +module.exports = async ({ defaultSidebarItemsGenerator, ...args }) => { + args.docs.map((doc) => { + if (doc.id === 'tutorials/index') { + doc.frontMatter.sidebar_class_name = "sidebar-category-items-hidden" + } + // if (doc.id.startsWith('tutorials')) { + // if (doc.id === 'tutorials/alloc') { + // console.log(doc) + // } + // } + }) + + // const docs = args.docs.filter((doc) => !doc.id.startsWith('tutorials')) + // const docs = args.docs + const sidebarItems = await defaultSidebarItemsGenerator({ ...args }) + // console.log('sidebarItems', sidebarItems) + // sidebarItems.map((item) => { + // if (item.id && item.id.startsWith('tutorials')) { + // item.className = 'sidebar-item-hidden' + // } + // }) + return sidebarItems +} diff --git a/src/theme/DocCardList/index.js b/src/theme/DocCardList/index.js new file mode 100644 index 00000000..10827e99 --- /dev/null +++ b/src/theme/DocCardList/index.js @@ -0,0 +1,62 @@ +import React, {useState} from 'react'; +import clsx from 'clsx'; +import { + useCurrentSidebarCategory, + filterDocCardListItems, +} from '@docusaurus/theme-common'; +import DocCard from '@theme/DocCard'; +import styles from './style.module.css' + +function DocCardListForCurrentSidebarCategory({className}) { + const category = useCurrentSidebarCategory(); + return category.label === 'Tutorials' + ? + : ; +} + +function FilterableDocCardList(props) { + const [tutorialLevel, setTutorialLevel] = useState('All') + + const {items, className} = props; + const filteredItems = filterDocCardListItems(items); + const filterDocCardsByTutorialLevel = (level) => { + return filteredItems.filter(item => level.toLowerCase() === 'all' ? true : item.customProps?.tutorial?.level === level.toLowerCase()) + } + let filteredDocCards = filterDocCardsByTutorialLevel(tutorialLevel) + + return ( + <> + + +
+ {filteredDocCards.map((item, index) => +
+ +
+ )} +
+ + ) +} + +export default function DocCardList(props) { + const {items, className} = props; + if (!items) { + return ; + } + const filteredItems = filterDocCardListItems(items); + return ( +
+ {filteredItems.map((item, index) => +
+ +
+ )} +
+ ); +} diff --git a/src/theme/DocCardList/style.module.css b/src/theme/DocCardList/style.module.css new file mode 100644 index 00000000..3751b7fd --- /dev/null +++ b/src/theme/DocCardList/style.module.css @@ -0,0 +1,7 @@ +.docCardFilterSelect { + padding: 0.75rem; + width: 100%; + margin-bottom: 1rem; + font-size: var(--ifm-font-size-base); + border-radius: 5px; +} From ac4f176f0efe2d4b30953ddc9006c6912f460a06 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 22 Nov 2023 14:45:13 -0600 Subject: [PATCH 33/95] customizing some components for the `/guides` pages and layouts --- docusaurus.config.js | 4 +- guides/cli/README.mdx | 6 ++ guides/cli/deploy-contract.mdx | 6 ++ guides/cli/install-wasm.mdx | 6 ++ guides/conversions/README.mdx | 6 ++ guides/conversions/address-to-bytesn.mdx | 6 ++ guides/index.mdx | 15 +--- guides/random/README.mdx | 6 ++ guides/{ => random}/guide1.mdx | 3 +- guides/{ => random}/guide2.mdx | 3 +- guides/{ => random}/guide3.mdx | 3 +- guides/{ => random}/guide4.mdx | 3 +- guides/{ => random}/guide5.mdx | 3 +- sidebars.js | 6 ++ sidebarsGuides.js | 14 +++- src/sidebar-docs-generator.js | 32 ++++++--- src/theme/DocCardList/index.js | 36 ++++++++++ src/theme/DocItem/Footer/index.js | 4 ++ src/theme/DocPage/Layout/Main/index.js | 23 ++++++ .../DocPage/Layout/Main/styles.module.css | 21 ++++++ .../Layout/Sidebar/ExpandButton/index.js | 28 ++++++++ .../Sidebar/ExpandButton/styles.module.css | 27 +++++++ src/theme/DocPage/Layout/Sidebar/index.js | 70 +++++++++++++++++++ .../DocPage/Layout/Sidebar/styles.module.css | 32 +++++++++ src/theme/DocPage/Layout/index.js | 31 ++++++++ src/theme/DocPage/Layout/styles.module.css | 18 +++++ src/theme/DocSidebar/index.js | 23 ++++++ 27 files changed, 400 insertions(+), 35 deletions(-) create mode 100644 guides/cli/README.mdx create mode 100644 guides/cli/deploy-contract.mdx create mode 100644 guides/cli/install-wasm.mdx create mode 100644 guides/conversions/README.mdx create mode 100644 guides/conversions/address-to-bytesn.mdx create mode 100644 guides/random/README.mdx rename guides/{ => random}/guide1.mdx (80%) rename guides/{ => random}/guide2.mdx (80%) rename guides/{ => random}/guide3.mdx (78%) rename guides/{ => random}/guide4.mdx (77%) rename guides/{ => random}/guide5.mdx (77%) create mode 100644 src/theme/DocPage/Layout/Main/index.js create mode 100644 src/theme/DocPage/Layout/Main/styles.module.css create mode 100644 src/theme/DocPage/Layout/Sidebar/ExpandButton/index.js create mode 100644 src/theme/DocPage/Layout/Sidebar/ExpandButton/styles.module.css create mode 100644 src/theme/DocPage/Layout/Sidebar/index.js create mode 100644 src/theme/DocPage/Layout/Sidebar/styles.module.css create mode 100644 src/theme/DocPage/Layout/index.js create mode 100644 src/theme/DocPage/Layout/styles.module.css create mode 100644 src/theme/DocSidebar/index.js diff --git a/docusaurus.config.js b/docusaurus.config.js index 161a2058..6e8b6629 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -29,6 +29,7 @@ const config = { path: 'guides', routeBasePath: 'guides', sidebarPath: require.resolve('./sidebarsGuides.js'), + sidebarItemsGenerator: require('./src/sidebar-docs-generator'), editUrl: "https://github.com/stellar/soroban-docs/tree/main/", showLastUpdateTime: true, }, @@ -88,7 +89,8 @@ const config = { image: 'img/meta.png', docs: { sidebar: { - autoCollapseCategories: false + autoCollapseCategories: false, + // hideable: true, } }, navbar: { diff --git a/guides/cli/README.mdx b/guides/cli/README.mdx new file mode 100644 index 00000000..4cee4b15 --- /dev/null +++ b/guides/cli/README.mdx @@ -0,0 +1,6 @@ +--- +title: Soroban-CLI +hide_table_of_contents: true +--- + +A collection of CLI guides. diff --git a/guides/cli/deploy-contract.mdx b/guides/cli/deploy-contract.mdx new file mode 100644 index 00000000..fb7531ba --- /dev/null +++ b/guides/cli/deploy-contract.mdx @@ -0,0 +1,6 @@ +--- +title: Deploy a Contract from Installed Wasm Bytecode +hide_table_of_contents: true +--- + +Deploy it after install. diff --git a/guides/cli/install-wasm.mdx b/guides/cli/install-wasm.mdx new file mode 100644 index 00000000..21afed0c --- /dev/null +++ b/guides/cli/install-wasm.mdx @@ -0,0 +1,6 @@ +--- +title: Install Wasm Bytecode +hide_table_of_contents: true +--- + +Install it onto the ledger diff --git a/guides/conversions/README.mdx b/guides/conversions/README.mdx new file mode 100644 index 00000000..36fad6cd --- /dev/null +++ b/guides/conversions/README.mdx @@ -0,0 +1,6 @@ +--- +title: Type Conversions +hide_table_of_contents: true +--- + +A collection of guides for converting from one data format to another diff --git a/guides/conversions/address-to-bytesn.mdx b/guides/conversions/address-to-bytesn.mdx new file mode 100644 index 00000000..e7a97c66 --- /dev/null +++ b/guides/conversions/address-to-bytesn.mdx @@ -0,0 +1,6 @@ +--- +title: Convert an Address to BytesN in Rust +hide_table_of_contents: true +--- + +The `Address` is an opaque type. diff --git a/guides/index.mdx b/guides/index.mdx index fcee9812..5d3026dd 100644 --- a/guides/index.mdx +++ b/guides/index.mdx @@ -1,17 +1,8 @@ --- -title: Guided Guides +title: Guides description: here you will find really useful guides hide_table_of_contents: true +sidebar_position: 0 --- -# Gateway to Guides - -We'll list a bunch of stuff. - -## Like this - -or that - -## Or even those - -Nah, nevermind. +The page lists all guides we have available for Soroban. Simply put, a "guide" is a short, bite-sized example that details how to accomplish a specific task. These guides are focused on a single topic, and are limited in scope. diff --git a/guides/random/README.mdx b/guides/random/README.mdx new file mode 100644 index 00000000..12055ee4 --- /dev/null +++ b/guides/random/README.mdx @@ -0,0 +1,6 @@ +--- +title: Random +hide_table_of_contents: true +--- + +A collection of random guides. diff --git a/guides/guide1.mdx b/guides/random/guide1.mdx similarity index 80% rename from guides/guide1.mdx rename to guides/random/guide1.mdx index e7023c99..a6e062e3 100644 --- a/guides/guide1.mdx +++ b/guides/random/guide1.mdx @@ -1,11 +1,10 @@ --- title: guide 1 description: really useful guide number one +hide_table_of_contents: true tags: - your - mom --- -# Guided Guide 1 - This is a guide to do something. diff --git a/guides/guide2.mdx b/guides/random/guide2.mdx similarity index 80% rename from guides/guide2.mdx rename to guides/random/guide2.mdx index f3603b86..9497b98d 100644 --- a/guides/guide2.mdx +++ b/guides/random/guide2.mdx @@ -1,11 +1,10 @@ --- title: guide 2 description: really useful guide number two +hide_table_of_contents: true tags: - your - dad --- -# Guided Guide 2 - This is a guide to do something. diff --git a/guides/guide3.mdx b/guides/random/guide3.mdx similarity index 78% rename from guides/guide3.mdx rename to guides/random/guide3.mdx index 4cfee00b..fe18d61a 100644 --- a/guides/guide3.mdx +++ b/guides/random/guide3.mdx @@ -1,8 +1,7 @@ --- title: guide 3 description: really useful guide number three +hide_table_of_contents: true --- -# Guided Guide 3 - This is a guide to do something. diff --git a/guides/guide4.mdx b/guides/random/guide4.mdx similarity index 77% rename from guides/guide4.mdx rename to guides/random/guide4.mdx index 6bd6dd04..7db27c65 100644 --- a/guides/guide4.mdx +++ b/guides/random/guide4.mdx @@ -1,8 +1,7 @@ --- title: guide 4 description: really useful guide number four +hide_table_of_contents: true --- -# Guided Guide 4 - This is a guide to do something. diff --git a/guides/guide5.mdx b/guides/random/guide5.mdx similarity index 77% rename from guides/guide5.mdx rename to guides/random/guide5.mdx index 80f51697..599f86e9 100644 --- a/guides/guide5.mdx +++ b/guides/random/guide5.mdx @@ -1,8 +1,7 @@ --- title: guide 5 description: really useful guide number five +hide_table_of_contents: true --- -# Guided Guide 5 - This is a guide to do something. diff --git a/sidebars.js b/sidebars.js index 773a38fe..f8d82d64 100644 --- a/sidebars.js +++ b/sidebars.js @@ -10,4 +10,10 @@ module.exports = { // label: 'Tutorials Too', // }, ], + // guidesSidebar: [ + // { + // type: 'autogenerated', + // dirName: '' + // } + // ], }; diff --git a/sidebarsGuides.js b/sidebarsGuides.js index 9b41a1be..d7a89f54 100644 --- a/sidebarsGuides.js +++ b/sidebarsGuides.js @@ -1,8 +1,18 @@ module.exports = { guidesSidebar: [ { - type: 'autogenerated', - dirName: '.', + type: 'category', + label: 'Guides', + link: { + type: 'doc', + id: 'index', + }, + items: [ + { + type: 'autogenerated', + dirName: '.' + } + ] }, ], }; diff --git a/src/sidebar-docs-generator.js b/src/sidebar-docs-generator.js index 55a38872..d6de09d8 100644 --- a/src/sidebar-docs-generator.js +++ b/src/sidebar-docs-generator.js @@ -2,19 +2,31 @@ const fs = require('fs') const path = require('path') module.exports = async ({ defaultSidebarItemsGenerator, ...args }) => { - args.docs.map((doc) => { - if (doc.id === 'tutorials/index') { - doc.frontMatter.sidebar_class_name = "sidebar-category-items-hidden" - } - // if (doc.id.startsWith('tutorials')) { - // if (doc.id === 'tutorials/alloc') { - // console.log(doc) - // } - // } - }) + + if (args.version.contentPath.endsWith('docs')) { + /** + * Adds a custom class name to the "Tutorials" index page, which we then + * use in the `/src/css/custom.scss` file to hide the `
    ` element + * that is contained within the item. The result is a single "Tutorials" + * page that contains the list of all the docs underneath it, while + * those items are not displayed in the sidebar. + */ + args.docs.map((doc) => { + if (doc.id === 'tutorials/index') { + doc.frontMatter.sidebar_class_name = "sidebar-category-items-hidden" + } + }) + } else if (args.version.contentPath.endsWith('guides')) { + args.docs.map((doc) => + doc.frontMatter.hide_table_of_contents = true + ) + } // const docs = args.docs.filter((doc) => !doc.id.startsWith('tutorials')) // const docs = args.docs + // if (args.version.contentPath.endsWith('guides')) { + // args.docs.map((doc) => console.log(doc.frontMatter)) + // } const sidebarItems = await defaultSidebarItemsGenerator({ ...args }) // console.log('sidebarItems', sidebarItems) // sidebarItems.map((item) => { diff --git a/src/theme/DocCardList/index.js b/src/theme/DocCardList/index.js index 10827e99..aa903da1 100644 --- a/src/theme/DocCardList/index.js +++ b/src/theme/DocCardList/index.js @@ -9,11 +9,46 @@ import styles from './style.module.css' function DocCardListForCurrentSidebarCategory({className}) { const category = useCurrentSidebarCategory(); + console.log(category) return category.label === 'Tutorials' ? + : category.label === 'Guides' + ? : ; } +function GuidesDocList(props) { + const {items, className} = props; + + // return ( + //
    + // {items.map((item, index) => { + // if (item.type === 'category') { + // return ( + //

    {item.label}

    + // ) + // }} + // )} + //
    + // ); + return ( +
    + {items.map((item, index) => { + if (item.type === 'category') { + return ( +
    +

    {item.label}

    + {item.items.map((item, index) => +

    {item.label}

    + )} +
    + ) + } + })} +
    + ) +} + function FilterableDocCardList(props) { const [tutorialLevel, setTutorialLevel] = useState('All') @@ -45,6 +80,7 @@ function FilterableDocCardList(props) { } export default function DocCardList(props) { + console.log('nonFilterableDocCardList props', props) const {items, className} = props; if (!items) { return ; diff --git a/src/theme/DocItem/Footer/index.js b/src/theme/DocItem/Footer/index.js index 80f671ff..ca0f67c2 100644 --- a/src/theme/DocItem/Footer/index.js +++ b/src/theme/DocItem/Footer/index.js @@ -5,6 +5,7 @@ import {useDoc} from '@docusaurus/theme-common/internal'; import LastUpdated from '@theme/LastUpdated'; import EditThisPage from '@theme/EditThisPage'; import TagsListInline from '@theme/TagsListInline'; +import DocCardList from '@theme/DocCardList'; import ReaderFeedback from '@site/src/components/ReaderFeedback'; import styles from './styles.module.css'; @@ -46,16 +47,19 @@ function EditMetaRow({ } export default function DocItemFooter() { const {metadata} = useDoc(); + console.log('metadata', metadata) const {editUrl, lastUpdatedAt, formattedLastUpdatedAt, lastUpdatedBy, tags} = metadata; const canDisplayTagsRow = tags.length > 0; const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy); const canDisplayFooter = canDisplayTagsRow || canDisplayEditMetaRow; + const canDisplayDocCardsOnGuide = metadata.permalink.startsWith('/guides') if (!canDisplayFooter) { return null; } return ( <> + {canDisplayDocCardsOnGuide &&
    }