diff --git a/docs/tools/interactive-learning.mdx b/docs/tools/interactive-learning.mdx deleted file mode 100644 index bc09fdb87..000000000 --- a/docs/tools/interactive-learning.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Interactive Learning ---- - -Here you can learn by doing. - -- Stellar Quest -- Soroban Quest -- Dapps Challenge -- RPCiege -- FCA00C - -Give it a whirl! diff --git a/docs/tools/sdks/README.mdx b/docs/tools/sdks/README.mdx index 0854dde6b..a99887f78 100644 --- a/docs/tools/sdks/README.mdx +++ b/docs/tools/sdks/README.mdx @@ -9,9 +9,9 @@ Each SDK has its own source code and documentation. Learn how to use a specific ### Soroban Rust SDK -The `soroban-sdk` Rust crate contains the Soroban Rust SDK. +[Rust SDK](https://github.com/stellar/rs-soroban-sdk) | [Docs](https://docs.rs/soroban-sdk) -[Source](https://github.com/stellar/rs-soroban-sdk) | [Docs](https://docs.rs/soroban-sdk) +The `soroban-sdk` Rust crate contains the Soroban Rust SDK. Report issues and share feedback about the `soroban-sdk` [here](https://github.com/stellar/rs-soroban-sdk/issues/new/choose). @@ -29,14 +29,16 @@ 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. +[AssemblyScript SDK](https://github.com/Soneso/as-soroban-sdk) -[Source](https://github.com/Soneso/as-soroban-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. Report issues and share feedback [here](https://github.com/Soneso/as-soroban-sdk/issues/new). ### JavaScript SDK +[JavaScript SDK](https://github.com/stellar/js-stellar-sdk) | [Docs](https://stellar.github.io/js-stellar-sdk/) | [NPM](https://www.npmjs.com/package/@stellar/stellar-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: @@ -44,10 +46,10 @@ 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. -[Source](https://github.com/stellar/js-stellar-sdk) | [Docs](https://stellar.github.io/js-stellar-sdk/) | [NPM](https://www.npmjs.com/package/@stellar/stellar-sdk) - ### Python SDK +[Python SDK](https://github.com/StellarCN/py-stellar-base) | [Docs](https://stellar-sdk.readthedocs.io/en/latest/) | [Examples](https://github.com/StellarCN/py-stellar-base/tree/master/examples) + `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. @@ -57,37 +59,61 @@ 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. -[Source](https://github.com/StellarCN/py-stellar-base) | [Docs](https://stellar-sdk.readthedocs.io/en/latest/) | [Examples](https://github.com/StellarCN/py-stellar-base/tree/master/examples) - ### iOS SDK +[iOS SDK](https://github.com/Soneso/stellar-ios-mac-sdk) | [Docs](https://github.com/Soneso/stellar-ios-mac-sdk/tree/master/docs) | [Smart Contract Docs](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/soroban.md) + 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 SDK is maintained by dedicated community developer, Soneso. -[Source](https://github.com/Soneso/stellar-ios-mac-sdk) | [Docs](https://github.com/Soneso/stellar-ios-mac-sdk/tree/master/docs) | [Smart Contract Docs](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/soroban.md) +### Flutter SDK + +[Flutter SDK](https://github.com/Soneso/stellar_flutter_sdk) | [Docs](https://github.com/Soneso/stellar_flutter_sdk/blob/master/soroban.md) + +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. -### Flutter SDK (same in both docs) +The Flutter Stellar SDK is maintained by dedicated community developer, Soneso. -### PHP SDK (same in both docs) +### PHP SDK -### Elixir SDK (separate for Soroban and Stellar) +[PHP SDK](https://github.com/Soneso/stellar-php-sdk) | [Docs](https://github.com/Soneso/stellar-php-sdk/blob/main/soroban.md) -### Java SDK (same in both docs) +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. -[Source](https://github.com/stellar/java-stellar-sdk) | [Docs](https://stellar.github.io/java-stellar-sdk/) +The PHP Stellar SDK is maintained by dedicated community developer, Soneso. -### Go (does this have Soroban?) +### Elixir SDK + +[Soroban Elixir SDK](https://github.com/kommitters/soroban.ex) & [Docs](https://github.com/kommitters/soroban.ex#documentation)| [Stellar Elixir SDK](https://github.com/kommitters/stellar_sdk) & [Docs](https://hexdocs.pm/stellar_sdk/readme.html#documentation) | [Examples](https://github.com/kommitters/stellar_sdk/tree/main/docs) + +This SDK is maintained by dedicated community developers, kommitters Open Source. + +### Java SDK + +[Java SDK](https://github.com/stellar/java-stellar-sdk) | [Docs](https://stellar.github.io/java-stellar-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. + +### Go This SDK is split up into separate packages, all of which you can find in the [Go monorepo README](https://github.com/stellar/go/blob/master/docs/reference/readme.md). The two key libraries for interacting with Horizon are `txnbuild`, which enables the construction, signing, and encoding of Stellar transactions, and `horizonclient`, which provides a web client for interfacing with Horizon server REST endpoints to retrieve ledger information and submit transactions built with `txnbuild`. -- txnbuild: [Source](https://github.com/stellar/go/tree/master/txnbuild) | [Docs](https://godoc.org/github.com/stellar/go/txnbuild) -- Horizonclient: [Source](https://github.com/stellar/go/tree/master/clients/horizonclient) | [Docs](https://godoc.org/github.com/stellar/go/clients/horizonclient) +- txnbuild: [SDK](https://github.com/stellar/go/tree/master/txnbuild) | [Docs](https://godoc.org/github.com/stellar/go/txnbuild) +- Horizonclient: [SDK](https://github.com/stellar/go/tree/master/clients/horizonclient) | [Docs](https://godoc.org/github.com/stellar/go/clients/horizonclient) + +### Ruby + +[Ruby SDK](https://github.com/astroband/ruby-stellar-sdk) | [Base Source](https://github.com/astroband/ruby-stellar-sdk/blob/master/base/README.md) | [SDK Source](https://github.com/astroband/ruby-stellar-sdk/blob/master/sdk/README.md) | [Docs](https://www.rubydoc.info/gems/stellar-sdk) | [Base Examples](https://github.com/astroband/ruby-stellar-sdk/tree/master/base/examples) | [SDK Examples](https://github.com/astroband/ruby-stellar-sdk/tree/master/sdk/examples) + +### C# .NET + +[C# .NET SDK](https://github.com/elucidsoft/dotnet-stellar-sdk) | [Docs](https://elucidsoft.github.io/dotnet-stellar-sdk/api/index.html) | [Tutorials](https://elucidsoft.github.io/dotnet-stellar-sdk/tutorials/index.html) -### Ruby (does this have Soroban?) +### Scala -### C# .NET (does this have Soroban?) +[Scala SDK](https://github.com/Synesso/scala-stellar-sdk) | [Docs](https://synesso.github.io/scala-stellar-sdk/) -### Scala (does this have Soroban?) +### Qt/C++ -### Qt/C++ (does this have Soroban?) +[Qt/C++ SDK](https://github.com/bnogalm/StellarQtSDK) | [Docs](https://github.com/bnogalm/StellarQtSDK/wiki) diff --git a/docs/tools/sdks/build-your-own-sdk.mdx b/docs/tools/sdks/build-your-own-sdk.mdx index a8db3e3f0..ed6962d5b 100644 --- a/docs/tools/sdks/build-your-own-sdk.mdx +++ b/docs/tools/sdks/build-your-own-sdk.mdx @@ -3,4 +3,96 @@ title: "Build Your Own SDK" sidebar_position: 20 --- -Build 'em! +:::note + +This is for building an SDK for writing smart contracts. + +::: + +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