From 378f9da2fd0c322fd8b3accb06034eb309042d80 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Tue, 20 Feb 2024 12:49:22 -0600 Subject: [PATCH 01/14] create redirects for tools and SDKs pages --- nginx/includes/redirects.conf | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index b8914662..56cc5d15 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -17,7 +17,6 @@ rewrite "^/docs/getting-started/deploy-to-futurenet$" "/docs/getting-started/dep rewrite "^/api/incomplete-methods$" "/api/methods" permanent; rewrite "^/docs/tutorials/testing$" "/docs/soroban-internals/debugging" permanent; rewrite "^/docs/category/how-to-guides$" "/docs/guides" permanent; -rewrite "^/docs/SDKs/rust$" "/docs/reference/sdks/write-contracts" permanent; rewrite "^/docs/getting-started/connect-freighter-wallet$" "/docs/reference/freighter" permanent; rewrite "^/docs/common-interfaces/token$" "/docs/tokens/token-interface" permanent; rewrite "^/docs/how-to-guides/tokens$" "/docs/tutorials/tokens" permanent; @@ -34,8 +33,6 @@ rewrite "^/docs/fundamentals-and-concepts/migrating-from-evm(/.*)$" "/docs/migra rewrite "^/docs/reference/releases$" "/docs/releases" permanent; rewrite "^/docs/fundamentals-and-concepts/faq$" "/docs/faq" permanent; rewrite "^/docs/reference/testnet$" "/docs/reference/networks" permanent; -rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "/docs/reference/sdks/write-contracts" permanent; -rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "/docs/reference/sdks/interact-with-contracts" permanent; rewrite "^/docs/fundamentals-and-concepts/(built-in-types|custom-types|fully-typed-contracts)$" "/docs/soroban-internals/types/$1" permanent; rewrite "^/docs/fundamentals-and-concepts/invoking-contracts-with-transactions$" "/docs/soroban-internals/contract-interactions/stellar-transaction" permanent; rewrite "^/docs/soroban-internals/contract-interactions/stellar-transactions$" "/docs/soroban-internals/contract-interactions/stellar-transaction" permanent; @@ -43,3 +40,10 @@ rewrite "^/docs/fundamentals-and-concepts/interacting-with-contracts$" "/docs/so rewrite "^/docs/(basic|advanced)-tutorials(/.*)$" "/docs/tutorials$2" permanent; rewrite "^/docs/fundamentals-and-concepts(/.*)$" "/docs/soroban-internals$1" permanent; rewrite "^/docs/notes" "/meetings" permanent; +# BEGIN merge redirects +rewrite "^/docs/developer-tools" "https://developers.stellar.org/docs/tools" permanent; +rewrite "^/docs/SDKs/rust$" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/docs/reference/sdks/write-contracts" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/docs/reference/sdks/build-your-own" "https://developers.stellar.org/docs/tools/sdks" permanent From b01671718ea62a9df234b707f021ebdb38a56131 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 12:40:13 -0600 Subject: [PATCH 02/14] adjust some redirect URLs to better reflect new stellar-docs pages --- nginx/includes/redirects.conf | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 56cc5d15..4c4394c4 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -41,9 +41,9 @@ rewrite "^/docs/(basic|advanced)-tutorials(/.*)$" "/docs/tutorials$2" permanent; rewrite "^/docs/fundamentals-and-concepts(/.*)$" "/docs/soroban-internals$1" permanent; rewrite "^/docs/notes" "/meetings" permanent; # BEGIN merge redirects -rewrite "^/docs/developer-tools" "https://developers.stellar.org/docs/tools" permanent; -rewrite "^/docs/SDKs/rust$" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/docs/developer-tools" "https://developers.stellar.org/docs/tools/developer-tools" permanent; +rewrite "^/docs/SDKs/rust$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; rewrite "^/docs/reference/sdks/write-contracts" "https://developers.stellar.org/docs/tools/sdks" permanent; -rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "https://developers.stellar.org/docs/tools/sdks" permanent; -rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "https://developers.stellar.org/docs/tools/sdks" permanent; -rewrite "^/docs/reference/sdks/build-your-own" "https://developers.stellar.org/docs/tools/sdks" permanent +rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; +rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; +rewrite "^/docs/reference/sdks/build-your-own" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent From dc01951c856ccf59f9b71c11fb0199663bf05189 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 13:48:14 -0600 Subject: [PATCH 03/14] forgot a semicolon! --- nginx/includes/redirects.conf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 4c4394c4..48061d0a 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -46,4 +46,4 @@ rewrite "^/docs/SDKs/rust$" "https://developers.stellar.org/docs/tools/sdks/libr rewrite "^/docs/reference/sdks/write-contracts" "https://developers.stellar.org/docs/tools/sdks" permanent; rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; -rewrite "^/docs/reference/sdks/build-your-own" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent +rewrite "^/docs/reference/sdks/build-your-own" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent; From fc2340818a08c42fc1f13f6a49d97111610c9100 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 15:25:12 -0600 Subject: [PATCH 04/14] linking to migrated developer tools page --- docs/developer-tools.mdx | 38 -------------------------------------- sidebars.js | 18 ++++++++++++++++-- src/css/custom.scss | 7 +++++++ 3 files changed, 23 insertions(+), 40 deletions(-) delete mode 100644 docs/developer-tools.mdx diff --git a/docs/developer-tools.mdx b/docs/developer-tools.mdx deleted file mode 100644 index 1c0caeae..00000000 --- a/docs/developer-tools.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_position: 75 -title: Developer Tools ---- - -:::info - -All tools currently listed are built and maintained by dedicated community members. - -::: - -### [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. - -### [Use Soroban](https://usesoroban.app/) - -A web GUI for building, deploying, and testing contracts. - -### [Soroban Copilot](https://github.com/mootz12/soroban-copilot) - -A collection of no_std Rust packages focused on making Soroban development easier. - -### [Soroban React](https://github.com/esteblock/soroban-react) - -A simple, powerful framework for building modern Soroban dApps using React. - -### [Sorobix](https://sorobix.vercel.app/) - -An IDE where you can write, deploy, and invoke contracts on the Stellar network using Soroban. - -### [SubQuery](https://subquery.network/) - -An open-source and flexible data indexer that supports both Stellar and Soroban. SubQuery allows users to build a custom API for their dapp or smart contract in minutes and provides clean indexed data to any service. You can index ledgers, transactions, operations, and effects from Stellar, and transactions and events from Soroban, into your own Postgres database. Read the [quick start guide here](https://academy.subquery.network/quickstart/quickstart_chains/stellar.html). - -### [Keizai](https://keizai.dev/) - -Keizai is an open-source postman-inspired application, designed to simplify and elevate the testing process for developers working with Soroban smart contracts. diff --git a/sidebars.js b/sidebars.js index cec6e3d6..6ab58cf2 100644 --- a/sidebars.js +++ b/sidebars.js @@ -8,6 +8,20 @@ module.exports = { type: 'link', label: 'Meeting Notes', href: '/meetings', - } - ] + }, + { + type: 'html', + value: '
', + }, + { + type: 'html', + value: 'Migrated Content:', + className: 'sidebar-title', + }, + { + type: 'link', + href: 'https://developers.stellar.org/docs/tools/developer-tools', + label: 'Developer Tools', + }, + ], }; diff --git a/src/css/custom.scss b/src/css/custom.scss index c63fec03..e3adbc4d 100644 --- a/src/css/custom.scss +++ b/src/css/custom.scss @@ -177,3 +177,10 @@ select[data-testid="example-pairing-select"] { .sidebar-category-items-hidden ul { display: none !important; } + +/* Sidebar title items */ +.sidebar-title { + // margin-top: 0.25rem; + padding: var(--ifm-menu-link-padding-vertical) 0.4rem; + font-weight: bolder; +} From 75ec34b52b9a0b5e34a6677e8058d9087ef41b7d Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 15:25:34 -0600 Subject: [PATCH 05/14] fine-tuning some redirects --- nginx/includes/redirects.conf | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 48061d0a..6af82543 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -44,6 +44,6 @@ rewrite "^/docs/notes" "/meetings" permanent; rewrite "^/docs/developer-tools" "https://developers.stellar.org/docs/tools/developer-tools" permanent; rewrite "^/docs/SDKs/rust$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; rewrite "^/docs/reference/sdks/write-contracts" "https://developers.stellar.org/docs/tools/sdks" permanent; -rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; -rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; -rewrite "^/docs/reference/sdks/build-your-own" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent; +rewrite "^/docs/reference/sdks/build-your-own-sdk" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent; +rewrite "^/docs/reference/sdks.*$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; +rewrite "^/docs/category/sdks$" "https://developers.stellar.org/docs/tools/sdks" permanent; From 287dc87882aefaf965ac97be1a40f1cc7324511f Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 16:21:00 -0600 Subject: [PATCH 06/14] add a list of "already migrated" stuff to the sidebar --- docs/migrate/evm/solidity-and-rust-basics.mdx | 2 +- sidebars.js | 28 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index cdcd8f08..dc7be947 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](../../reference/soroban-cli.mdx), one of many robust [Developer Tools](../../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. +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.mdx), one of many robust [Developer Tools](https://developers.stellar.org/docs/tools/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/sidebars.js b/sidebars.js index 6ab58cf2..81f241dd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -23,5 +23,33 @@ module.exports = { href: 'https://developers.stellar.org/docs/tools/developer-tools', label: 'Developer Tools', }, + { + type: 'category', + label: 'Reference', + collapsed: false, + items: [ + { + type: 'category', + label: 'SDKs', + items: [ + { + type: 'link', + href: 'https://developers.stellar.org/docs/tools/sdks/library', + label: 'Write Contracts', + }, + { + type: 'link', + href: 'https://developers.stellar.org/docs/tools/sdks/library', + label: 'Interact with Contracts', + }, + { + type: 'link', + href: 'https://developers.stellar.org/docs/tools/sdks/build-your-own', + label: 'Build Your Own SDK', + }, + ], + }, + ], + }, ], }; From 6dd2a28a8f124e876607a9bf30894a420ea6eb08 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 16:31:17 -0600 Subject: [PATCH 07/14] remove SDKs content that's being migrated --- docs/reference/sdks/_category_.json | 7 -- docs/reference/sdks/build-your-own-sdk.mdx | 93 ------------------- .../sdks/interact-with-contracts.mdx | 75 --------------- docs/reference/sdks/write-contracts.mdx | 76 --------------- 4 files changed, 251 deletions(-) delete mode 100644 docs/reference/sdks/_category_.json delete mode 100644 docs/reference/sdks/build-your-own-sdk.mdx delete mode 100644 docs/reference/sdks/interact-with-contracts.mdx delete mode 100644 docs/reference/sdks/write-contracts.mdx diff --git a/docs/reference/sdks/_category_.json b/docs/reference/sdks/_category_.json deleted file mode 100644 index 224dc2ce..00000000 --- a/docs/reference/sdks/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "position": 20, - "label": "SDKs", - "link": { - "type": "generated-index" - } -} diff --git a/docs/reference/sdks/build-your-own-sdk.mdx b/docs/reference/sdks/build-your-own-sdk.mdx deleted file mode 100644 index 5ddf696a..00000000 --- a/docs/reference/sdks/build-your-own-sdk.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_position: 30 -title: Build Your Own SDK -description: A guide to developing Soroban SDKs for languages other than Rust. ---- - -Soroban currently has one SDK for writing contracts in Rust, which can be found [here][soroban-sdk]. - -To build SDKs for other languages a few things need to be included in the SDK to provide contracts with the foundation they need to accept inputs, decode them, store data, call other contracts, etc. - -Below is a list of functionality a Soroban SDK needs to support those things, as well as some details on what an SDK can provide in regards to testing capabilities. - -## Functionality - -### Value Conversions - -- [RawVal] encode/decode -- [Object] encode/decode -- [Symbol] encode/decode -- [Status] encode/decode - -### Host Functions - -The host functions defined in [env.json] are functions callable from within the Wasm Guest environment. These need to be available to contracts to call, in some form, ideally wrapped so that contracts have a nicer interface. - -Host functions have friendly names in the file above, such as `get_ledger_version`, however in the Wasm they are only importable via short names, such as `x.4`. The letter proceeding the dot is the module, and the value after the dot is the function name. The mappins are available in env.rs. - -### SDK Types - -All the types in [soroban-sdk](https://docs.rs/soroban-sdk) should be supported. Notably: - -- [Map] -- [Vec] -- [Bytes] - -### User Defined Types - -Contracts should be able to create user defined types, such as structs, unions, or enums, and have them be transmitted to the host for storing and transmitted back for loading. - -SDKs do this by converting objects to and from a `Val`. In the [soroban-sdk] this is referred to as a [RawVal]. - -#### Structs - -Structs with named fields should be translated into a `Map` with keys as `Symbol`s and the values as the field value, i.e. `Map`. - -Structs with unnamed fields should be translated into a `Vec` with the values as the elements. i.e. `Vec`. - -#### Unions - -Unions (or enums in some languages) with named variants and unit or tuple values should be translated into a `Vec` with the first element as a `Symbol` of the name of the variant, and zero or more additional elements representing a value stored with the variant. - -#### Enums - -Enums with integer values should be translated into a `u32`. - -### User Defined Errors - -Errors are `u32` values that are translated into a [Status]. - -### Environment Meta Generation - -Contracts must contain a Wasm custom section with name `contractenvmetav0` and containing a serialized [`SCEnvMetaEntry`]. The interface version stored within should match the version of the host functions supported. - -### Contract Spec Generation - -Contracts should contain a Wasm custom section with name `contractspecv0` and containing a serialized stream of [`SCSpecEntry`]. There should be a `SCSpecEntry` for every function, struct, and union exported by the contract. - -### Contract Meta Generation - -Contracts may optionally contain a Wasm custom section with name `contractmetav0` and containing a serialized [`SCMetaEntry`]. Contracts may store any metadata in the entries that can be used by applications and tooling off-network. - -## Testing - -Any Soroban SDK ideally provides a test environment for executing contract functions in the context of a Soroban runtime environment. The [soroban-sdk] does this by embedding the Soroban environment Rust library, [soroban-env-host]. - -The test environment should include: - -- Invoking contract functions. -- Integration testing across multiple contracts. - -[soroban-sdk]: https://docs.rs/soroban-sdk -[soroban-env-host]: https://github.com/stellar/rs-soroban-env -[RawVal]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/raw_val.rs -[Status]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/status.rs -[Object]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/object.rs -[Symbol]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/symbol.rs -[env.json]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/env.json -[Map]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/map.rs -[Vec]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/vec.rs -[Bytes]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/bytes.rs -[`SCEnvMetaEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-env-meta.x -[`SCSpecEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-spec.x -[`SCMetaEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-meta.x diff --git a/docs/reference/sdks/interact-with-contracts.mdx b/docs/reference/sdks/interact-with-contracts.mdx deleted file mode 100644 index 27e4cc19..00000000 --- a/docs/reference/sdks/interact-with-contracts.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -sidebar_position: 20 -title: Interact with Contracts -description: SDKs support writing Soroban applications in many languages. ---- - -## JavaScript SDK - -`stellar-sdk` is the JavaScript library for communicating with a Soroban RPC server, communicating with the Horizon API, and building transactions on the Stellar network. 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 and the Horizon API. -- facilities for building and signing transactions, for communicating with an RPC instance, for communicating with a Horizon instance, and for submitting transactions or querying network state. - -The SDK is available at: https://github.com/stellar/js-stellar-sdk and on NPM [here](https://www.npmjs.com/package/@stellar/stellar-sdk). - -## 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. - -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. - -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. - -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. - -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. - -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 is available at: https://github.com/stellar/java-stellar-sdk diff --git a/docs/reference/sdks/write-contracts.mdx b/docs/reference/sdks/write-contracts.mdx deleted file mode 100644 index 5f902a3f..00000000 --- a/docs/reference/sdks/write-contracts.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -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 -``` From 08e10d2b15c3493ae2a5239faf9434291b531fae Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 16:31:41 -0600 Subject: [PATCH 08/14] fix the resulting broken links --- docs/migrate/evm/smart-contract-deployment.mdx | 8 ++++---- docs/migrate/evm/solidity-and-rust-basics.mdx | 2 +- .../contract-interactions/stellar-transaction.mdx | 2 +- docs/soroban-internals/types/built-in-types.mdx | 2 +- docs/soroban-internals/types/fully-typed-contracts.mdx | 2 +- docs/tokens/token-interface.mdx | 4 ++-- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/migrate/evm/smart-contract-deployment.mdx b/docs/migrate/evm/smart-contract-deployment.mdx index a09ce525..f42b0623 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](../../reference/soroban-cli.mdx), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. ### Hardhat @@ -44,7 +44,7 @@ Soroban, with its lightweight design, offers developers an exceptional platform Hardhat offers a streamlined workflow for deploying smart contracts on the Ethereum Virtual Machine, with key components such as `ethers.js`, `scripts`, and `testing` playing crucial roles. -On the other hand, Soroban presents a compelling alternative, boasting powerful SDKs that facilitate smart contract development and deployment. In the upcoming section, we will delve into [Soroban's SDKs](../../category/sdks), drawing comparisons with Hardhat components, and highlighting the unique advantages each platform brings to the table. +On the other hand, Soroban presents a compelling alternative, boasting powerful SDKs that facilitate smart contract development and deployment. In the upcoming section, we will delve into [Soroban's SDKs](https://developers.stellar.org/docs/tools/sdks), drawing comparisons with Hardhat components, and highlighting the unique advantages each platform brings to the table. ### Ethers.js @@ -62,7 +62,7 @@ async function main() { ### Soroban Client -Soroban offers a comparable library, [`stellar-sdk`](../../reference/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 as well as the traditional Horizon API, simplifying the process of building and signing transactions. Additionally, `stellar-sdk` streamlines communication with RPC instances and supports submitting transactions or querying network state with ease. +Soroban offers a comparable library, [`stellar-sdk`](https://developers.stellar.org/docs/tools/sdks/library#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 as well as the traditional Horizon API, simplifying the process of building and signing transactions. Additionally, `stellar-sdk` streamlines communication with RPC instances and supports submitting transactions or querying network state with ease. ### Scripts @@ -89,7 +89,7 @@ main() ### Soroban Scripts -Soroban offers an extensive collection of SDKs that include scripting capabilities, ensuring a smooth workflow for deploying and managing smart contracts. Developers can automate tasks such as compiling, deploying, and interacting with smart contracts using a variety of SDKs that support scripting in languages like [`JavaScript`, `TypeScript`, `Python`, and others](../../category/sdks). +Soroban offers an extensive collection of SDKs that include scripting capabilities, ensuring a smooth workflow for deploying and managing smart contracts. Developers can automate tasks such as compiling, deploying, and interacting with smart contracts using a variety of SDKs that support scripting in languages like [`JavaScript`, `TypeScript`, `Python`, and others](https://developers.stellar.org/docs/tools/sdks). ```python # This example shows how to deploy a compiled contract to the Stellar network. diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index dc7be947..0debd5f1 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/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. +This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](https://developers.stellar.org/docs/tools/sdks/library#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/soroban-internals/contract-interactions/stellar-transaction.mdx b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx index 528de15e..284e5005 100644 --- a/docs/soroban-internals/contract-interactions/stellar-transaction.mdx +++ b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx @@ -402,7 +402,7 @@ The `hostFunction` in `InvokeHostFunctionOp` will be executed by the Soroban hos ##### JavaScript Usage -Each of these variations of host function invocation has convenience methods in the [JavaScript SDK](../../reference/sdks/interact-with-contracts.mdx#javascript-sdk): +Each of these variations of host function invocation has convenience methods in the [JavaScript SDK](https://developers.stellar.org/docs/tools/sdks/library#javascript-sdk): - [`Operation.invokeHostFunction`](https://stellar.github.io/js-stellar-sdk/Operation.html#.invokeHostFunction) is the lowest-level method that corresponds directly to the XDR. - [`Operation.invokeContractFunction`](https://stellar.github.io/js-stellar-sdk/Operation.html#.invokeContractFunction) is an abstraction to invoke the method of a particular contract, similar to [`Contract.call`](https://stellar.github.io/js-stellar-sdk/Contract.html#call). diff --git a/docs/soroban-internals/types/built-in-types.mdx b/docs/soroban-internals/types/built-in-types.mdx index 05129c1f..446539ce 100644 --- a/docs/soroban-internals/types/built-in-types.mdx +++ b/docs/soroban-internals/types/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.mdx -[Rust SDK]: ../../reference/sdks/write-contracts.mdx#soroban-rust-sdk +[Rust SDK]: https://developers.stellar.org/docs/tools/sdks/library#soroban-rust-sdk :::tip diff --git a/docs/soroban-internals/types/fully-typed-contracts.mdx b/docs/soroban-internals/types/fully-typed-contracts.mdx index 741ffe7b..f1d9274a 100644 --- a/docs/soroban-internals/types/fully-typed-contracts.mdx +++ b/docs/soroban-internals/types/fully-typed-contracts.mdx @@ -25,7 +25,7 @@ sidebar_label: Fully-Typed Contracts /> -When you compile a contract created with [soroban-sdk](../../reference/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](https://developers.stellar.org/docs/tools/sdks/library#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/tokens/token-interface.mdx b/docs/tokens/token-interface.mdx index 92666861..7d6ed066 100644 --- a/docs/tokens/token-interface.mdx +++ b/docs/tokens/token-interface.mdx @@ -35,8 +35,8 @@ consistent with the interface described here: ### Code The interface below uses the Rust -[soroban-sdk](../reference/sdks/write-contracts.mdx#soroban-rust-sdk) to declare -a trait that complies with the +[soroban-sdk](https://developers.stellar.org/docs/tools/sdks/library#soroban-rust-sdk) +to declare a trait that complies with the [SEP-41](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md) token interface. From 433ceceea6318cedf9e32a4034f8bc53d0b2200c Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 17:39:54 -0600 Subject: [PATCH 09/14] Revert "remove SDKs content that's being migrated" This reverts commit 6dd2a28a8f124e876607a9bf30894a420ea6eb08. --- docs/reference/sdks/_category_.json | 7 ++ docs/reference/sdks/build-your-own-sdk.mdx | 93 +++++++++++++++++++ .../sdks/interact-with-contracts.mdx | 75 +++++++++++++++ docs/reference/sdks/write-contracts.mdx | 76 +++++++++++++++ 4 files changed, 251 insertions(+) create mode 100644 docs/reference/sdks/_category_.json create mode 100644 docs/reference/sdks/build-your-own-sdk.mdx create mode 100644 docs/reference/sdks/interact-with-contracts.mdx create mode 100644 docs/reference/sdks/write-contracts.mdx diff --git a/docs/reference/sdks/_category_.json b/docs/reference/sdks/_category_.json new file mode 100644 index 00000000..224dc2ce --- /dev/null +++ b/docs/reference/sdks/_category_.json @@ -0,0 +1,7 @@ +{ + "position": 20, + "label": "SDKs", + "link": { + "type": "generated-index" + } +} diff --git a/docs/reference/sdks/build-your-own-sdk.mdx b/docs/reference/sdks/build-your-own-sdk.mdx new file mode 100644 index 00000000..5ddf696a --- /dev/null +++ b/docs/reference/sdks/build-your-own-sdk.mdx @@ -0,0 +1,93 @@ +--- +sidebar_position: 30 +title: Build Your Own SDK +description: A guide to developing Soroban SDKs for languages other than Rust. +--- + +Soroban currently has one SDK for writing contracts in Rust, which can be found [here][soroban-sdk]. + +To build SDKs for other languages a few things need to be included in the SDK to provide contracts with the foundation they need to accept inputs, decode them, store data, call other contracts, etc. + +Below is a list of functionality a Soroban SDK needs to support those things, as well as some details on what an SDK can provide in regards to testing capabilities. + +## Functionality + +### Value Conversions + +- [RawVal] encode/decode +- [Object] encode/decode +- [Symbol] encode/decode +- [Status] encode/decode + +### Host Functions + +The host functions defined in [env.json] are functions callable from within the Wasm Guest environment. These need to be available to contracts to call, in some form, ideally wrapped so that contracts have a nicer interface. + +Host functions have friendly names in the file above, such as `get_ledger_version`, however in the Wasm they are only importable via short names, such as `x.4`. The letter proceeding the dot is the module, and the value after the dot is the function name. The mappins are available in env.rs. + +### SDK Types + +All the types in [soroban-sdk](https://docs.rs/soroban-sdk) should be supported. Notably: + +- [Map] +- [Vec] +- [Bytes] + +### User Defined Types + +Contracts should be able to create user defined types, such as structs, unions, or enums, and have them be transmitted to the host for storing and transmitted back for loading. + +SDKs do this by converting objects to and from a `Val`. In the [soroban-sdk] this is referred to as a [RawVal]. + +#### Structs + +Structs with named fields should be translated into a `Map` with keys as `Symbol`s and the values as the field value, i.e. `Map`. + +Structs with unnamed fields should be translated into a `Vec` with the values as the elements. i.e. `Vec`. + +#### Unions + +Unions (or enums in some languages) with named variants and unit or tuple values should be translated into a `Vec` with the first element as a `Symbol` of the name of the variant, and zero or more additional elements representing a value stored with the variant. + +#### Enums + +Enums with integer values should be translated into a `u32`. + +### User Defined Errors + +Errors are `u32` values that are translated into a [Status]. + +### Environment Meta Generation + +Contracts must contain a Wasm custom section with name `contractenvmetav0` and containing a serialized [`SCEnvMetaEntry`]. The interface version stored within should match the version of the host functions supported. + +### Contract Spec Generation + +Contracts should contain a Wasm custom section with name `contractspecv0` and containing a serialized stream of [`SCSpecEntry`]. There should be a `SCSpecEntry` for every function, struct, and union exported by the contract. + +### Contract Meta Generation + +Contracts may optionally contain a Wasm custom section with name `contractmetav0` and containing a serialized [`SCMetaEntry`]. Contracts may store any metadata in the entries that can be used by applications and tooling off-network. + +## Testing + +Any Soroban SDK ideally provides a test environment for executing contract functions in the context of a Soroban runtime environment. The [soroban-sdk] does this by embedding the Soroban environment Rust library, [soroban-env-host]. + +The test environment should include: + +- Invoking contract functions. +- Integration testing across multiple contracts. + +[soroban-sdk]: https://docs.rs/soroban-sdk +[soroban-env-host]: https://github.com/stellar/rs-soroban-env +[RawVal]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/raw_val.rs +[Status]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/status.rs +[Object]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/object.rs +[Symbol]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/src/symbol.rs +[env.json]: https://github.com/stellar/rs-soroban-env/blob/main/soroban-env-common/env.json +[Map]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/map.rs +[Vec]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/vec.rs +[Bytes]: https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-sdk/src/bytes.rs +[`SCEnvMetaEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-env-meta.x +[`SCSpecEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-spec.x +[`SCMetaEntry`]: https://github.com/stellar/stellar-xdr/blob/next/Stellar-contract-meta.x diff --git a/docs/reference/sdks/interact-with-contracts.mdx b/docs/reference/sdks/interact-with-contracts.mdx new file mode 100644 index 00000000..27e4cc19 --- /dev/null +++ b/docs/reference/sdks/interact-with-contracts.mdx @@ -0,0 +1,75 @@ +--- +sidebar_position: 20 +title: Interact with Contracts +description: SDKs support writing Soroban applications in many languages. +--- + +## JavaScript SDK + +`stellar-sdk` is the JavaScript library for communicating with a Soroban RPC server, communicating with the Horizon API, and building transactions on the Stellar network. 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 and the Horizon API. +- facilities for building and signing transactions, for communicating with an RPC instance, for communicating with a Horizon instance, and for submitting transactions or querying network state. + +The SDK is available at: https://github.com/stellar/js-stellar-sdk and on NPM [here](https://www.npmjs.com/package/@stellar/stellar-sdk). + +## 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. + +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. + +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. + +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. + +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. + +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 is available at: https://github.com/stellar/java-stellar-sdk diff --git a/docs/reference/sdks/write-contracts.mdx b/docs/reference/sdks/write-contracts.mdx new file mode 100644 index 00000000..5f902a3f --- /dev/null +++ b/docs/reference/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 +``` From 1df0d4dd0146dbfb49f405ecc15130a07f4aa37b Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 17:42:52 -0600 Subject: [PATCH 10/14] Revert "linking to migrated developer tools page" This reverts commit fc2340818a08c42fc1f13f6a49d97111610c9100. --- docs/developer-tools.mdx | 38 +++++++++++++++++++++++++++++++++ sidebars.js | 46 ++-------------------------------------- src/css/custom.scss | 7 ------ 3 files changed, 40 insertions(+), 51 deletions(-) create mode 100644 docs/developer-tools.mdx diff --git a/docs/developer-tools.mdx b/docs/developer-tools.mdx new file mode 100644 index 00000000..1c0caeae --- /dev/null +++ b/docs/developer-tools.mdx @@ -0,0 +1,38 @@ +--- +sidebar_position: 75 +title: Developer Tools +--- + +:::info + +All tools currently listed are built and maintained by dedicated community members. + +::: + +### [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. + +### [Use Soroban](https://usesoroban.app/) + +A web GUI for building, deploying, and testing contracts. + +### [Soroban Copilot](https://github.com/mootz12/soroban-copilot) + +A collection of no_std Rust packages focused on making Soroban development easier. + +### [Soroban React](https://github.com/esteblock/soroban-react) + +A simple, powerful framework for building modern Soroban dApps using React. + +### [Sorobix](https://sorobix.vercel.app/) + +An IDE where you can write, deploy, and invoke contracts on the Stellar network using Soroban. + +### [SubQuery](https://subquery.network/) + +An open-source and flexible data indexer that supports both Stellar and Soroban. SubQuery allows users to build a custom API for their dapp or smart contract in minutes and provides clean indexed data to any service. You can index ledgers, transactions, operations, and effects from Stellar, and transactions and events from Soroban, into your own Postgres database. Read the [quick start guide here](https://academy.subquery.network/quickstart/quickstart_chains/stellar.html). + +### [Keizai](https://keizai.dev/) + +Keizai is an open-source postman-inspired application, designed to simplify and elevate the testing process for developers working with Soroban smart contracts. diff --git a/sidebars.js b/sidebars.js index 81f241dd..cec6e3d6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -8,48 +8,6 @@ module.exports = { type: 'link', label: 'Meeting Notes', href: '/meetings', - }, - { - type: 'html', - value: '
', - }, - { - type: 'html', - value: 'Migrated Content:', - className: 'sidebar-title', - }, - { - type: 'link', - href: 'https://developers.stellar.org/docs/tools/developer-tools', - label: 'Developer Tools', - }, - { - type: 'category', - label: 'Reference', - collapsed: false, - items: [ - { - type: 'category', - label: 'SDKs', - items: [ - { - type: 'link', - href: 'https://developers.stellar.org/docs/tools/sdks/library', - label: 'Write Contracts', - }, - { - type: 'link', - href: 'https://developers.stellar.org/docs/tools/sdks/library', - label: 'Interact with Contracts', - }, - { - type: 'link', - href: 'https://developers.stellar.org/docs/tools/sdks/build-your-own', - label: 'Build Your Own SDK', - }, - ], - }, - ], - }, - ], + } + ] }; diff --git a/src/css/custom.scss b/src/css/custom.scss index e3adbc4d..c63fec03 100644 --- a/src/css/custom.scss +++ b/src/css/custom.scss @@ -177,10 +177,3 @@ select[data-testid="example-pairing-select"] { .sidebar-category-items-hidden ul { display: none !important; } - -/* Sidebar title items */ -.sidebar-title { - // margin-top: 0.25rem; - padding: var(--ifm-menu-link-padding-vertical) 0.4rem; - font-weight: bolder; -} From 3666430c46b2c2f410e298aa4aab2a1fd6f0b1b7 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Wed, 21 Feb 2024 17:49:58 -0600 Subject: [PATCH 11/14] try this method of turning docs into external links --- docs/developer-tools.mdx | 4 ++++ docs/reference/sdks/build-your-own-sdk.mdx | 4 ++++ .../sdks/interact-with-contracts.mdx | 4 ++++ docs/reference/sdks/write-contracts.mdx | 4 ++++ src/sidebar-generator.js | 20 ++++++++++++++++++- 5 files changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/developer-tools.mdx b/docs/developer-tools.mdx index 1c0caeae..170934f6 100644 --- a/docs/developer-tools.mdx +++ b/docs/developer-tools.mdx @@ -1,6 +1,10 @@ --- sidebar_position: 75 title: Developer Tools +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/developer-tools + label: Developer Tools --- :::info diff --git a/docs/reference/sdks/build-your-own-sdk.mdx b/docs/reference/sdks/build-your-own-sdk.mdx index 5ddf696a..70e1db7e 100644 --- a/docs/reference/sdks/build-your-own-sdk.mdx +++ b/docs/reference/sdks/build-your-own-sdk.mdx @@ -2,6 +2,10 @@ sidebar_position: 30 title: Build Your Own SDK description: A guide to developing Soroban SDKs for languages other than Rust. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/sdks/build-your-own + label: Build Your Own SDK --- Soroban currently has one SDK for writing contracts in Rust, which can be found [here][soroban-sdk]. diff --git a/docs/reference/sdks/interact-with-contracts.mdx b/docs/reference/sdks/interact-with-contracts.mdx index 27e4cc19..8e74f1ab 100644 --- a/docs/reference/sdks/interact-with-contracts.mdx +++ b/docs/reference/sdks/interact-with-contracts.mdx @@ -2,6 +2,10 @@ sidebar_position: 20 title: Interact with Contracts description: SDKs support writing Soroban applications in many languages. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/sdks/library + label: Interact with Contracts --- ## JavaScript SDK diff --git a/docs/reference/sdks/write-contracts.mdx b/docs/reference/sdks/write-contracts.mdx index 5f902a3f..1ac4299a 100644 --- a/docs/reference/sdks/write-contracts.mdx +++ b/docs/reference/sdks/write-contracts.mdx @@ -2,6 +2,10 @@ sidebar_position: 10 title: Write Contracts description: SDKs support writing Soroban contracts in Rust and AssemblyScript. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/sdks/library + label: Write Contracts --- ## Soroban Rust SDK diff --git a/src/sidebar-generator.js b/src/sidebar-generator.js index 338353d5..0fe8a08d 100644 --- a/src/sidebar-generator.js +++ b/src/sidebar-generator.js @@ -1,6 +1,24 @@ const fs = require('fs') const path = require('path') +const migrationLinksRecursive = (sidebarItems) => { + const result = sidebarItems.map((sidebarItem) => { + if (sidebarItem.type === 'category') { + return {...sidebarItem, items: migrationLinksRecursive(sidebarItem.items)} + } + + if (sidebarItem.customProps?.migration?.href && sidebarItem.customProps?.migration?.label) { + sidebarItem = { + type: 'link', + href: sidebarItem.customProps.migration.href, + label: sidebarItem.customProps.migration.label, + } + } + return sidebarItem + }) + return result +} + module.exports = async ({ defaultSidebarItemsGenerator, ...args }) => { if (args.version.contentPath.endsWith('docs')) { @@ -31,5 +49,5 @@ module.exports = async ({ defaultSidebarItemsGenerator, ...args }) => { } const sidebarItems = await defaultSidebarItemsGenerator({ ...args }) - return sidebarItems + return migrationLinksRecursive(sidebarItems) } From 60b235fa224280922b446f5cb97c9199dc9befd6 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 22 Feb 2024 12:52:04 -0600 Subject: [PATCH 12/14] include soroban-cli page in the tools migration --- docs/reference/soroban-cli.mdx | 10 ++++++++++ nginx/includes/redirects.conf | 5 +++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/reference/soroban-cli.mdx b/docs/reference/soroban-cli.mdx index bd3dafc1..9f6b9b50 100644 --- a/docs/reference/soroban-cli.mdx +++ b/docs/reference/soroban-cli.mdx @@ -2,8 +2,18 @@ sidebar_position: 80 title: Soroban CLI description: The tool for interacting with deployed contracts. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli + label: Soroban CLI --- +:::danger These are not the droids you're looking for + +This page has been migrated to the Stellar Developers documentation. Please [click here](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli) for the most up-to-date information + +::: + Soroban CLI is the command line interface to Soroban. It allows you to build, deploy, and interact with smart contracts; configure identities; generate key pairs; manage networks; and more. Install Soroban CLI as explained in [Setup](../getting-started/setup.mdx). diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index 6af82543..01678fde 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -6,9 +6,7 @@ rewrite "^/docs/tutorials/deploy-to-futurenet$" "/docs/getting-started/deploy-to rewrite "^/fundamentals-and-concepts/faq$" "/docs/faq" permanent; rewrite "^/docs/examples/events$" "/docs/tutorials/events" permanent; rewrite "^/docs/learn/rust-dialect$" "/docs/soroban-internals/rust-dialect" permanent; -rewrite "^/docs/reference/command-line$" "/docs/reference/soroban-cli" permanent; rewrite "^/docs/advanced-tutorials/liquidity-pool-b6f$" "/docs/tutorials/liquidity-pool" permanent; -rewrite "^/reference/soroban-cli$" "/docs/reference/soroban-cli" permanent; rewrite "^/docs(/category)?/learn$" "/docs/category/soroban-internals" permanent; rewrite "^/docs/category/fundamentals-and-concepts$" "/docs/category/soroban-internals" permanent; rewrite "^/docs/built-in-contracts/token$" "/docs/tokens/stellar-asset-contract" permanent; @@ -47,3 +45,6 @@ rewrite "^/docs/reference/sdks/write-contracts" "https://developers.stellar.org/ rewrite "^/docs/reference/sdks/build-your-own-sdk" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent; rewrite "^/docs/reference/sdks.*$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; rewrite "^/docs/category/sdks$" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/reference/soroban-cli$" "https://developers.stellar.org/docs/tools/developer-tools#soroban-cli" permanent; +rewrite "^/docs/reference/command-line$" "https://developers.stellar.org/docs/tools/developer-tools#soroban-cli" permanent; +rewrite "^/docs/reference/soroban-cli$" "https://developers.stellar.org/docs/tools/developer-tools#soroban-cli" permanent; From 46bd7b492196caa868dc969f0cd6c0505b11bbea Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 22 Feb 2024 12:54:16 -0600 Subject: [PATCH 13/14] change cli links to developer docs --- docs/guides/cli/README.mdx | 2 +- docs/migrate/evm/smart-contract-deployment.mdx | 2 +- docs/migrate/evm/solidity-and-rust-basics.mdx | 2 +- docs/soroban-internals/types/fully-typed-contracts.mdx | 2 +- docs/tokens/stellar-asset-contract.mdx | 2 +- docs/tutorials/liquidity-pool.mdx | 2 +- docs/tutorials/tokens.mdx | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/guides/cli/README.mdx b/docs/guides/cli/README.mdx index e87ce3df..d85e7aa7 100644 --- a/docs/guides/cli/README.mdx +++ b/docs/guides/cli/README.mdx @@ -5,4 +5,4 @@ hide_table_of_contents: true The [Soroban CLI] is a crucial tool for developers to use while creating and interacting with Soroban smart contracts. -[Soroban CLI]: ../../reference/soroban-cli.mdx +[Soroban CLI]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli diff --git a/docs/migrate/evm/smart-contract-deployment.mdx b/docs/migrate/evm/smart-contract-deployment.mdx index f42b0623..e4ad03d5 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.mdx), 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](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. ### Hardhat diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index 0debd5f1..224e3067 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](../../reference/soroban-cli.mdx), one of many robust [Developer Tools](https://developers.stellar.org/docs/tools/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](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli), one of many robust [Developer Tools](https://developers.stellar.org/docs/tools/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/soroban-internals/types/fully-typed-contracts.mdx b/docs/soroban-internals/types/fully-typed-contracts.mdx index f1d9274a..05a34608 100644 --- a/docs/soroban-internals/types/fully-typed-contracts.mdx +++ b/docs/soroban-internals/types/fully-typed-contracts.mdx @@ -29,7 +29,7 @@ When you compile a contract created with [soroban-sdk](https://developers.stella 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](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli) is the first tool to do so. Specifically, one subcommand: ## `soroban contract invoke` diff --git a/docs/tokens/stellar-asset-contract.mdx b/docs/tokens/stellar-asset-contract.mdx index 7ac0e2ae..956e8759 100644 --- a/docs/tokens/stellar-asset-contract.mdx +++ b/docs/tokens/stellar-asset-contract.mdx @@ -52,7 +52,7 @@ deployment. Asset Issuer will have the administrative permissions after the contract has been deployed. [contract_id]: https://github.com/stellar/stellar-xdr/blob/dc23adf60e095a6ce626b2b09128e58a5eae0cd0/Stellar-transaction.x#L661 -[Soroban-CLI]: ../reference/soroban-cli.mdx +[Soroban-CLI]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli ## Interacting with classic Stellar assets diff --git a/docs/tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx index 25fd46d6..9cc7e1c4 100644 --- a/docs/tutorials/liquidity-pool.mdx +++ b/docs/tutorials/liquidity-pool.mdx @@ -1014,4 +1014,4 @@ soroban contract invoke \ --min_b 196 \ ``` -[`soroban-cli`]: ../reference/soroban-cli.mdx +[`soroban-cli`]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli diff --git a/docs/tutorials/tokens.mdx b/docs/tutorials/tokens.mdx index ec961950..38e004dc 100644 --- a/docs/tutorials/tokens.mdx +++ b/docs/tutorials/tokens.mdx @@ -1071,4 +1071,4 @@ soroban contract invoke \ --id GBZV3NONYSUDVTEHATQO4BCJVFXJO3XQU5K32X3XREVZKSMMOZFO4ZXR ``` -[`soroban-cli`]: ../reference/soroban-cli.mdx +[`soroban-cli`]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli From 454b7a9795fdbc16bf7118332c327475043518d5 Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Thu, 22 Feb 2024 15:02:07 -0600 Subject: [PATCH 14/14] use by-name params in pagination example (#743) Refs: #728 --- api/pagination.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/pagination.mdx b/api/pagination.mdx index 3ac52f5a..3da84ce1 100644 --- a/api/pagination.mdx +++ b/api/pagination.mdx @@ -18,6 +18,12 @@ For example, calling a method with pagination parameter set: "jsonrpc": "2.0", "id": "1", "method": "exampleMethod", - "params": ["other", "arguments", { "cursor": "1234-1", "limit": 100 }] + "params": { + "some": "argument", + "pagination": { + "cursor": "1234-1", + "limit": 100 + } + } } ```