diff --git a/docs/build/guides/basics/classic-transition.mdx b/docs/build/guides/basics/classic-transition.mdx new file mode 100644 index 000000000..33dc3374d --- /dev/null +++ b/docs/build/guides/basics/classic-transition.mdx @@ -0,0 +1,47 @@ +--- +title: Add support for smart contracts +sidebar_position: 40 +description: Considerations for integrating with Stellar’s smart contracts specifically for wallets and exchanges +--- + +Stellar recently [upgraded its protocol](https://stellar.org/blog/developers/protocol-20-preparing-smart-contracts-to-stellar) to support smart contracts, adding a new way to interact with the network. This one-pager highlights key considerations for integrating with Stellar’s smart contracts specifically for wallets and exchanges that already support Stellar’s “classic” operations. It quickly outlines what changes to expect, provides links to detailed documentation, and is a starting point for adapting existing Stellar Classic processes to the new smart contract environment. + +## 1. Infrastructure + +### Transitioning from Horizon to RPC + +To properly support Stellar's smart contracts, you must use [Stellar RPC](../../../data/rpc). More specifically, you need RPC to simulate transactions that execute smart contracts, as described in the "Simulating Transactions" section, and it provides a convenient [API](../../../data/rpc/api-reference) for consuming contract events. Both of these features are not available in Horizon. + +### Running Your Own RPC vs. Leveraging Third-Party Providers + +You can set up an RPC environment by hosting your own node or using a third-party provider. For guidance on hosting your own instance, including a Docker-based setup, refer to the [Admin Guide](../../../data/rpc/admin-guide). Alternatively, a list of trusted providers is available in the [ecosystem RPC providers documentation](../../../data/rpc/rpc-providers). + +## 2. Data Ingestion + +### Ingesting Smart Contract Events + +Horizon offers an effects endpoint that describes state changes executed by classic operations. Similarly, contracts emit [events](../../../learn/encyclopedia/contract-development/events.mdx) that describe changes to their state, which can be fetched via RPC's API. Off-chain solutions can [monitor and ingest these events](../../../build/guides/events/ingest.mdx) (for token transfers or protocol updates) and remain in sync with on-chain data. Each event is defined by the contract and is subject to standards applied to the implementation. Depending on the requirements for retention, a solution might have to handle ingestion directly or use a [third-party service](../../../data/data-indexers/indexer-providers) for a longer-term history. + +### Simulating Transaction + +While events should be used to monitor changes to a contract’s state, clients may also need to determine the current state of a contract. [Simulation](../../../build/guides/transactions/simulateTransaction-Deep-Dive.mdx) allows clients to execute contract invocations with incurring fees or finalizing changes, making it an ideal approach for fetching contracts’ current state. For example, clients can call the balance function on a [SEP-0041](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md)-compliant token contract to fetch a user’s current balance. + +## 3. Transaction Workflow Changes + +### Building Transactions + +Transaction construction involves specifying a call to a contract function rather than any of the built-in operations Stellar offers. When building these contract calls, it is necessary to specify the relevant contract ID and function arguments according to the contract interface. See more at [Documentation for Contract Interaction - Stellar Transaction](../../../learn/encyclopedia/contract-development/contract-interactions/stellar-transaction.mdx). + +You can still use the libraries or tools you’re already familiar with to assemble these transactions, [but keep in mind the extra steps required for contract invocation](../../../build/guides/transactions/invoke-contract-tx-sdk.mdx). + +### Simulating Transaction + +Transactions that execute smart contracts must be [simulated](../../../build/guides/transactions/simulateTransaction-Deep-Dive.mdx) before sending. That is because simulation doesn’t just provide the results of executing transactions; it also provides essential information such as the transaction’s read/write [footprint](../../../learn/encyclopedia/contract-development/contract-interactions/transaction-simulation.mdx#footprint) and [authorizations](../../../learn/encyclopedia/contract-development/contract-interactions/transaction-simulation.mdx#authorization) needed, and clients must add this information to the transaction before sending it to the network for execution. + +### Signing & Auth Entries + +Smart contracts can define their own [custom authorization logic](../../../learn/encyclopedia/security/authorization.mdx), meaning you might need [additional signatures for specific authorization data](../../../learn/encyclopedia/contract-development/contract-interactions/stellar-transaction.mdx#authorization-data) to prove permission for certain contract calls. Each contract can have its own requirements, so a good practice is to [leverage transaction simulations to identify specific authorization requirements for a transaction](../../../learn/encyclopedia/contract-development/contract-interactions/transaction-simulation.mdx#authorization). + +### Asynchronous Transaction Submission + +Unlike Horizon, [RPC only queues transactions for inclusion rather than waiting for final confirmation](../../../data/rpc/api-reference/methods/sendTransaction). Therefore, it is necessary to [poll the transaction’s status](../../../data/rpc/api-reference/methods/getTransaction) to determine if a transaction eventually succeeds or fails. This asynchronous model, as well as other common challenges, can be seen at the [Documentation for Dapp Development - Common Pitfalls](../../../build/guides/dapps/frontend-guide.mdx#7-common-pitfalls). diff --git a/docs/build/guides/basics/send-and-receive-payments.mdx b/docs/build/guides/basics/send-and-receive-payments.mdx index 42be6c52a..8e11beb79 100644 --- a/docs/build/guides/basics/send-and-receive-payments.mdx +++ b/docs/build/guides/basics/send-and-receive-payments.mdx @@ -25,7 +25,7 @@ In the following code samples, proper error checking is omitted for brevity. How ## Send a Payment -Stellar stores and communicates transaction data in a binary format called [XDR](../../../learn/encyclopedia/data-format/xdr.mdx), which is optimized for network performance but unreadable to the human eye. Luckily, [Horizon](../../../data/horizon/README.mdx), the Stellar API, and the [Stellar SDKs](../../../tools/sdks/library.mdx) convert XDRs into friendlier formats. Here’s how you might send 10 lumens to an account: +Stellar stores and communicates transaction data in a binary format called [XDR](../../../learn/encyclopedia/data-format/xdr.mdx), which is optimized for network performance but unreadable to the human eye. Luckily, [Horizon](../../../data/horizon/README.mdx), the Stellar API, and the [Stellar SDKs](../../../tools/sdks/README.mdx) convert XDRs into friendlier formats. Here’s how you might send 10 lumens to an account: diff --git a/docs/build/guides/conventions/deploy-sac-with-code.mdx b/docs/build/guides/conventions/deploy-sac-with-code.mdx index 0bdc3b913..a64b7434a 100644 --- a/docs/build/guides/conventions/deploy-sac-with-code.mdx +++ b/docs/build/guides/conventions/deploy-sac-with-code.mdx @@ -20,7 +20,7 @@ description: Deploy a SAC for a Stellar asset using Javascript SDK ## Overview -In this guide, you'll learn how to deploy a [Stellar Asset Contract (SAC)](../../../tokens/stellar-asset-contract.mdx) for a Stellar asset using the [Stellar SDK](../../../tools/sdks/library.mdx#javascript-sdk). The Stellar SDK is a set of tools and library designed to help developers build applications that interact with the Stellar blockchain network. +In this guide, you'll learn how to deploy a [Stellar Asset Contract (SAC)](../../../tokens/stellar-asset-contract.mdx) for a Stellar asset using the [Stellar SDK](../../../tools/sdks/client-sdks.mdx#javascript-sdk). The Stellar SDK is a set of tools and library designed to help developers build applications that interact with the Stellar blockchain network. ### Prerequisites: diff --git a/docs/build/guides/conventions/extending-wasm-ttl.mdx b/docs/build/guides/conventions/extending-wasm-ttl.mdx index 8ae2e149a..d950c6e3a 100644 --- a/docs/build/guides/conventions/extending-wasm-ttl.mdx +++ b/docs/build/guides/conventions/extending-wasm-ttl.mdx @@ -96,7 +96,7 @@ impl ExtendTTLContract { -The code below uses Nodejs environment but same concept can also be applied in the browser using Freighter wallet or using any other [Stellar SDK](../../../tools/sdks/library.mdx). +The code below uses Nodejs environment but same concept can also be applied in the browser using Freighter wallet or using any other [Stellar SDK](../../../tools/sdks/client-sdks.mdx). ```javascript import * as StellarSdk from "@stellar/stellar-sdk"; diff --git a/docs/build/guides/dapps/working-with-contract-specs.mdx b/docs/build/guides/dapps/working-with-contract-specs.mdx index c285613c1..fd5ce924f 100644 --- a/docs/build/guides/dapps/working-with-contract-specs.mdx +++ b/docs/build/guides/dapps/working-with-contract-specs.mdx @@ -22,10 +22,10 @@ These details guide how you interact with the contract, regardless of the progra Before diving into contract interactions, ensure you have the following: - Stellar CLI ([`stellar`](../../smart-contracts/getting-started/setup.mdx#install-the-stellar-cli)) installed -- A Soroban-compatible SDK for your programming language. View the [list of available SDKs](../../../tools/sdks/library.mdx) to find one that suits your needs +- A Soroban-compatible SDK for your programming language. View the [list of available SDKs](../../../tools/sdks/README.mdx) to find one that suits your needs - Access to a Stellar [RPC server](../../../learn/fundamentals/networks.mdx) (local or on a test network) -For this guide, we will focus on the [Java](/docs/tools/sdks/library#java-sdk), [Python](/docs/tools/sdks/library#python-sdk), and [PHP](/docs/tools/sdks/library#php-sdk) SDKs for reference, but the concepts can also be applied to other languages. +For this guide, we will focus on the [Java](../../../tools/sdks/client-sdks.mdx#java-sdk), [Python](../../../tools/sdks/client-sdks.mdx#python-sdk), and [PHP](../../../tools/sdks/client-sdks.mdx#php-sdk) SDKs for reference, but the concepts can also be applied to other languages. ## What are contract specs? diff --git a/docs/build/guides/testing/differential-tests.mdx b/docs/build/guides/testing/differential-tests.mdx index 9a5674f8f..7947f82a2 100644 --- a/docs/build/guides/testing/differential-tests.mdx +++ b/docs/build/guides/testing/differential-tests.mdx @@ -52,10 +52,10 @@ Assuming the contract has been deployed, and changes are being made to the local #[test] fn differential_test() { - let env = Env::default(); assert_eq!( // Baseline – the deployed contract { + let env = Env::default(); let contract_id = env.register(deployed::WASM, ()); let client = IncrementContractClient::new(&env, &contract_id); ( @@ -66,11 +66,12 @@ Assuming the contract has been deployed, and changes are being made to the local client.increment(), ), // Events - env.events.all(), + env.events().all(), ) }, // Local – the changed or refactored contract { + let env = Env::default(); let contract_id = env.register(IncrementContract, ()); let client = IncrementContractClient::new(&env, &contract_id); ( @@ -81,7 +82,7 @@ Assuming the contract has been deployed, and changes are being made to the local client.increment(), ), // Events - env.events.all(), + env.events().all(), ) }, ); @@ -104,12 +105,6 @@ Differential tests work best when less assumptions are made. Rather than asserti ::: -:::info - -Depending on the test complexity it can be desirable to use an independent `Env` for testing the deployed vs local. However at the moment it is only possible to compare host values, like `String`, `Bytes`, `Vec`, `Map`, if they've been created using the same `Env`. The tracking issue for supportin comparisons across environments is [stellar/rs-soroban-sdk#1360]. - -::: - [Getting Started]: ../../smart-contracts/getting-started [increment example]: https://github.com/stellar/soroban-examples/blob/main/increment/src/lib.rs [Differential Testing with Test Snapshots]: ./differential-tests-with-test-snapshots.mdx diff --git a/docs/build/guides/testing/integration-tests-with-mainnet-data.mdx b/docs/build/guides/testing/fork-testing.mdx similarity index 90% rename from docs/build/guides/testing/integration-tests-with-mainnet-data.mdx rename to docs/build/guides/testing/fork-testing.mdx index 04fb6f4e6..e86bce561 100644 --- a/docs/build/guides/testing/integration-tests-with-mainnet-data.mdx +++ b/docs/build/guides/testing/fork-testing.mdx @@ -1,11 +1,11 @@ --- -title: Integration Tests with Mainnet Data +title: Fork Testing hide_table_of_contents: true -description: Integration testing uses dependency contracts instead of mocks. +description: Integration testing using mainnet data. sidebar_position: 6 --- -Testing with mainnet data is another form of [integration test], where not only mainnet contracts can be used, but also their data on mainnet. +Fork testing is another form of [integration test], where not only mainnet contracts can be used, but also their data on mainnet. A snapshot of the ledger is taken and used to create an environment for testing. The test operates as a fork of that initial state. Our ability to test a contract that relies on another contract is limited to our own knowledge of this other contract and the different states it can get into. Integration testing, where real dependencies are used removes some assumptions, but if a dependency has complex state it may also be useful to test against mainnet data as it exists at different points in time. @@ -79,5 +79,5 @@ A snapshot can be created of any contract deployed to mainnet or testnet using t [pause contract]: https://github.com/stellar/soroban-examples/blob/main/pause/src/lib.rs [integration test]: ./integration-tests.mdx [Making Cross-Contract Calls]: ../conventions/cross-contract.mdx -[Soroban Rust SDK]: ../../../tools/sdks/library.mdx#soroban-rust-sdk +[Soroban Rust SDK]: ../../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk [Stellar CLI]: ../../../tools/developer-tools/cli/README.mdx diff --git a/docs/build/guides/testing/integration-tests.mdx b/docs/build/guides/testing/integration-tests.mdx index b11d5defa..cc38d8b0d 100644 --- a/docs/build/guides/testing/integration-tests.mdx +++ b/docs/build/guides/testing/integration-tests.mdx @@ -69,4 +69,4 @@ Most tests, whether they're unit, mocks, or integration tests, will look very si [pause contract]: https://github.com/stellar/soroban-examples/blob/main/pause/src/lib.rs [Integration Tests]: ./integration-tests.mdx [Making Cross-Contract Calls]: ../conventions/cross-contract.mdx -[Soroban Rust SDK]: ../../../tools/sdks/library.mdx#soroban-rust-sdk +[Soroban Rust SDK]: ../../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk diff --git a/docs/build/guides/testing/mocking.mdx b/docs/build/guides/testing/mocking.mdx index 523361b1c..e7af6efe3 100644 --- a/docs/build/guides/testing/mocking.mdx +++ b/docs/build/guides/testing/mocking.mdx @@ -123,4 +123,4 @@ The [Soroban Rust SDK] handles contract calls defensively so that any unexpected [increment-with-pause contract]: https://github.com/stellar/soroban-examples/blob/main/increment-with-pause/src/lib.rs [Integration Tests]: ./integration-tests.mdx [Making Cross-Contract Calls]: ../conventions/cross-contract.mdx -[Soroban Rust SDK]: ../../../tools/sdks/library.mdx#soroban-rust-sdk +[Soroban Rust SDK]: ../../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk diff --git a/docs/build/guides/tokens/deploying-a-sac.mdx b/docs/build/guides/tokens/deploying-a-sac.mdx index feb15e9e2..a48ec89bf 100644 --- a/docs/build/guides/tokens/deploying-a-sac.mdx +++ b/docs/build/guides/tokens/deploying-a-sac.mdx @@ -28,7 +28,7 @@ In this guide, you'll learn how to deploy a [Stellar Asset Contract (SAC)](../.. Before you begin, make sure you have the following: - Basic understanding of [Rust programming language](https://www.rust-lang.org/). To brush up on Rust, check out [Rustlings](https://github.com/rust-lang/rustlings) or [The Rust book](https://doc.rust-lang.org/book/). -- [Soroban Rust SDK](../../../tools/sdks/library.mdx#soroban-rust-sdk) installed and configured in your development environment. +- [Soroban Rust SDK](../../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk) installed and configured in your development environment. - Basic understanding of the Soroban Rust SDK and familiarity with Soroban's core concepts and Rust programming. ## 1. Define the SacDeployer contract diff --git a/docs/build/smart-contracts/overview.mdx b/docs/build/smart-contracts/overview.mdx index a7f81e667..0240f0ec3 100644 --- a/docs/build/smart-contracts/overview.mdx +++ b/docs/build/smart-contracts/overview.mdx @@ -21,7 +21,7 @@ Support for other languages may be supported in the future, but at this time, on ## Soroban Rust SDK -Contracts are developed using a software development kit (SDK). The [Soroban Rust SDK](../../tools/sdks/library.mdx#soroban-rust-sdk) consists of a Rust crate and a command-line tool. +Contracts are developed using a software development kit (SDK). The [Soroban Rust SDK](../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk) consists of a Rust crate and a command-line tool. The SDK crate acts as a substitute for the Rust standard library — providing data structures and utility functions for contracts — as well as providing access to smart-contract-specific functionality from the contract environment, like cryptographic hashing and signature verification, access to on-chain persistent storage, and location and invocation of secondary contracts via stable identifiers. diff --git a/docs/data/horizon/README.mdx b/docs/data/horizon/README.mdx index c3fb68967..08ade0213 100644 --- a/docs/data/horizon/README.mdx +++ b/docs/data/horizon/README.mdx @@ -15,7 +15,7 @@ On August 1, 2024, the SDF truncated historical data on its Horizon instances to Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by Stellar Core. This API serves the bridge between apps and [Stellar Core](../../validators/README.mdx). Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account. -Horizon can be accessed via cURL, a browser, or one of the [Stellar SDKs](../../tools/sdks/library.mdx). To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls. +Horizon can be accessed via cURL, a browser, or one of the [Stellar SDKs](../../tools/sdks/README.mdx). To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls. This guide describes how to administer a production Horizon instance (refer to the [Developers' Blog](https://www.stellar.org/developers-blog/a-new-sun-on-the-horizon) for some background on the performance and architectural improvements of this major version bump). For information about developing on the Horizon codebase, check out the [Development Guide](https://github.com/stellar/go/blob/master/services/horizon/internal/docs/GUIDE_FOR_DEVELOPERS.md). diff --git a/docs/data/migrate-from-horizon-to-rpc/README.mdx b/docs/data/migrate-from-horizon-to-rpc/README.mdx index 05b2f7120..7b8338a0f 100644 --- a/docs/data/migrate-from-horizon-to-rpc/README.mdx +++ b/docs/data/migrate-from-horizon-to-rpc/README.mdx @@ -82,7 +82,7 @@ In the interim the [`getTransactions`] method can be used to retrieve the meta X [RPC JSON-RPC API]: rpc/api-reference [JSON-RPC]: rpc/api-reference/json-rpc [Data]: ../data -[SDKs]: ../tools/sdks/library +[SDKs]: ../tools/sdks [`GET /`]: horizon/api-reference [`GET /ledgers`]: horizon/api-reference/list-all-ledgers [`GET /ledgers/{seq}`]: horizon/api-reference/retrieve-a-ledger diff --git a/docs/data/rpc/admin-guide.mdx b/docs/data/rpc/admin-guide.mdx index faf22a09b..77771afa9 100644 --- a/docs/data/rpc/admin-guide.mdx +++ b/docs/data/rpc/admin-guide.mdx @@ -11,7 +11,7 @@ The RPC service allows you to communicate directly with Soroban via a [JSON RPC For example, you can build an application and have it [send a transaction](./api-reference/methods/getTransaction.mdx), [get ledger](./api-reference/methods/getLedgerEntries.mdx) and [event data](./api-reference/methods/getEvents.mdx), or [simulate transactions](./api-reference/methods/simulateTransaction.mdx). -Alternatively, you can use one of Soroban's [client SDKs](/docs/tools/sdks/library), such as the [@stellar/stellar-sdk](/docs/tools/sdks/library#javascript-sdk), which will need to communicate with an RPC instance to access the network. +Alternatively, you can use one of Soroban's [client SDKs](/docs/tools/sdks/client-sdks), such as the [@stellar/stellar-sdk](/docs/tools/sdks/client-sdks#javascript-sdk), which will need to communicate with an RPC instance to access the network. ## Run Your Own Instance for Development diff --git a/docs/learn/encyclopedia/contract-development/contract-interactions/stellar-transaction.mdx b/docs/learn/encyclopedia/contract-development/contract-interactions/stellar-transaction.mdx index ba14280c2..f5079356c 100644 --- a/docs/learn/encyclopedia/contract-development/contract-interactions/stellar-transaction.mdx +++ b/docs/learn/encyclopedia/contract-development/contract-interactions/stellar-transaction.mdx @@ -458,7 +458,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](../../../../tools/sdks/library.mdx#javascript-sdk): +Each of these variations of host function invocation has convenience methods in the [JavaScript SDK](../../../../tools/sdks/client-sdks.mdx#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/learn/encyclopedia/contract-development/types/built-in-types.mdx b/docs/learn/encyclopedia/contract-development/types/built-in-types.mdx index cb53417fd..db5ee59b2 100644 --- a/docs/learn/encyclopedia/contract-development/types/built-in-types.mdx +++ b/docs/learn/encyclopedia/contract-development/types/built-in-types.mdx @@ -20,7 +20,7 @@ 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.mdx -[rust sdk]: ../../../../tools/sdks/library.mdx#soroban-rust-sdk +[rust sdk]: ../../../../tools/sdks/contract-sdks.mdx#soroban-rust-sdk :::tip diff --git a/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx b/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx index 5f4970036..6237713c5 100644 --- a/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx +++ b/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx @@ -21,9 +21,9 @@ sidebar_label: Fully-Typed Contracts /> -When you compile a contract created with [soroban-sdk](../../../../tools/sdks/library.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 comments from the contract's author. +When you compile a contract created with [soroban-sdk](../../../../tools/sdks/contract-sdks.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 comments from the contract's author. -These interface types are formatted using [XDR](../../data-format/xdr.mdx), a data format used widely throughout Stellar. It can be tricky to create or consume XDR manually, but tooling can fetch these interface types to make your life easier. [Stellar CLI](../../../../tools/developer-tools/cli/README.mdx#cli) and [Stellar SDK](../../../../tools/sdks/library.mdx#javascript-sdk) are two such tools to do so. Let's look at each. +These interface types are formatted using [XDR](../../data-format/xdr.mdx), a data format used widely throughout Stellar. It can be tricky to create or consume XDR manually, but tooling can fetch these interface types to make your life easier. [Stellar CLI](../../../../tools/developer-tools/cli/README.mdx#cli) and [Stellar SDK](../../../../tools/sdks/client-sdks.mdx#javascript-sdk) are two such tools to do so. Let's look at each. ## Stellar CLI: `stellar contract invoke` diff --git a/docs/learn/encyclopedia/data-format/xdr-json.mdx b/docs/learn/encyclopedia/data-format/xdr-json.mdx new file mode 100644 index 000000000..89623efeb --- /dev/null +++ b/docs/learn/encyclopedia/data-format/xdr-json.mdx @@ -0,0 +1,42 @@ +--- +title: XDR-JSON +sidebar_position: 2 +--- + +import { CodeExample } from "@site/src/components/CodeExample"; + +The XDR-JSON schema is defined by the [stellar-xdr crate](https://docs.rs/stellar-xdr) and provides a round-trippable means for converting Stellar [XDR] values to JSON and converting that JSON back to the identical XDR. + +Converting with the schema is also exposed by the following tools and libraries. + +The JSON-Schema for the XDR-JSON format can be found using the [`stellar xdr types schema`] command. + +## Tools + +- [Stellar CLI > `stellar xdr`](../../../tools/developer-tools/cli/stellar-cli.mdx#stellar-xdr) +- [Lab > View XDR](../../../tools/developer-tools/lab) + +## Libraries + +- [stellar-xdr](https://docs.rs/stellar-xdr) rust crate +- [@stellar/stellar-xdr-json](https://www.npmjs.com/package/@stellar/stellar-xdr-json) npm package +- [github.com/stellar/go-stellar-xdr-json](https://github.com/stellar/go-stellar-xdr-json) go package + +## Key Characteristics of the JSON and XDR Conversion Schema + +- **Round-Trippable:** The JSON format allows for converting from XDR to JSON and back to XDR without loss of information. + +- **Self-Describing:** The JSON format describes the internals of the type but does not identify the type that is encoded. This is similar to XDR, which also does not identify the encoded type. + +- **64-bit Integers:** The JSON format includes integers up to 64-bit in size. JavaScript runtimes do not support 64-bit integers, so a custom decoder must be used, such as [lossless-json](https://www.npmjs.com/package/lossless-json). + +- **Escaped ASCII Strings:** The JSON format includes strings that are UTF-8 safe, escaped ASCII strings. This is because XDR strings are not UTF-8 encoded, but are instead byte streams that can contain any values. Non-ASCII characters are escaped. + +:::info[backwards-incompatible] + +The defined schema (linked above) is **not** backwards compatible between a given protocol version and prior versions. The best practice is to store required ledger data in XDR format, not in JSON format. + +::: + +[XDR]: xdr +[`stellar xdr types schema`]: ../../../tools/developer-tools/cli/stellar-cli.mdx#stellar-xdr-types-schema diff --git a/docs/learn/encyclopedia/data-format/xdr.mdx b/docs/learn/encyclopedia/data-format/xdr.mdx index 1fcb0821b..f45ffed8f 100644 --- a/docs/learn/encyclopedia/data-format/xdr.mdx +++ b/docs/learn/encyclopedia/data-format/xdr.mdx @@ -1,5 +1,6 @@ --- title: XDR +sidebar_position: 1 --- import { CodeExample } from "@site/src/components/CodeExample"; @@ -10,25 +11,9 @@ Stellar stores and communicates ledger data, transactions, results, history, and Data structures in XDR are specified in `.x` files. These files _only_ contain data structure definitions, no operations or executable code. The `.x` files for the XDR structures used on the Stellar Network are available on [GitHub](https://github.com/stellar/stellar-xdr). -## JSON and XDR Conversion Schema +:::tip -The canonical JSON and XDR Schema is defined by the [stellar-xdr crate](https://docs.rs/stellar-xdr) and also exposed by the [@stellar/stellar-xdr-json npm package](https://www.npmjs.com/package/@stellar/stellar-xdr-json). The schema provides a round-trippable means for converting any Stellar XDR type to JSON and converting that JSON back to the identical XDR. - -This conversion is visible in the Stellar CLI, Lab View XDR, and Hubble events table. - -### Key Characteristics of the JSON and XDR Conversion Schema - -- **Round-Trippable:** The JSON format allows for converting from XDR to JSON and back to XDR without loss of information. - -- **Self-Describing:** The JSON format describes the internals of the type but does not identify the type that is encoded. This is similar to XDR, which also does not identify the encoded type. - -- **64-bit Integers:** The JSON format includes integers up to 64-bit in size. JavaScript runtimes do not support 64-bit integers, so a custom decoder must be used, such as [lossless-json](https://www.npmjs.com/package/lossless-json). - -- **Escaped ASCII Strings:** The JSON format includes strings that UTF-8 safe, escaped ASCII strings. This is because XDR strings are not UTF-8 encoded, but are instead byte streams that can contain any values. Non-ASCII characters are escaped. - -:::info[backwards-incompatible] - -The defined schema (linked above) is **not** backwards compatible between a given protocol version and prior versions. The best practice is to store required ledger data in XDR format, not in JSON format. +Stellar XDR is encodable into JSON using the [XDR-JSON] schema. ::: @@ -237,3 +222,4 @@ This overview should give you a strong baseline on understanding how to inspect {/* TODO: Room to expand much more: Tools -> CLI Visualization, JSON Visualization, Stellar Lab */} [RFC4506]: http://tools.ietf.org/html/rfc4506.html +[XDR-JSON]: ./xdr-json.mdx diff --git a/docs/learn/fundamentals/fees-resource-limits-metering.mdx b/docs/learn/fundamentals/fees-resource-limits-metering.mdx index 7fb7e9dbf..0449c0e0f 100644 --- a/docs/learn/fundamentals/fees-resource-limits-metering.mdx +++ b/docs/learn/fundamentals/fees-resource-limits-metering.mdx @@ -106,7 +106,7 @@ Fees are deducted from the source account unless there is a fee-bump transaction The network can enter surge pricing mode under two circumstances: 1. when the number of operations submitted to a ledger exceeds the network capacity (1,000 operations for transactions that do not execute smart contracts), or 2. if there is competition between smart contract transactions for a particular resource (instructions, ledger entry accesses (reads and writes), ledger IO (bytes read and bytes written), and the total size of transactions to be applied). During this time, the network uses market dynamics to decide which transactions to include in the ledger. Transactions that offer a higher maximum base fee bid make it to the ledger first. -During surge pricing mode, transactions are sorted based on their inclusion fee amount, and the user pays the minimum inclusion fee in their transaction set. For example, if there are five transactions with respective inclusion fees of 2, 3, 4, 4, and 5 XLM, and only four of them an make it to the ledger, then all included transactions pay the inclusion fee of 3 XLM. If all five transactions can make it to the ledger (which would mean the network is not in surge pricing mode), each would pay the minimum inclusion fee of 100 stroops (.0001 XLM). +During surge pricing mode, transactions are sorted based on their inclusion fee amount, and the user pays the minimum inclusion fee in their transaction set. For example, if there are five transactions with respective inclusion fees of 2, 3, 4, 4, and 5 XLM, and only four of them an make it to the ledger, then all included transactions pay the inclusion fee of 3 XLM. If all five transactions can make it to the ledger (which would mean the network is not in surge pricing mode), each would pay the minimum inclusion fee of 100 stroops (.00001 XLM). If there are multiple transactions offering the same inclusion fee, but they cannot all fit into the ledger, transactions are picked randomly so that the total operations for the entire set don’t exceed 1,000. The rest of the transactions are pushed to the next ledger or discarded if they’ve been waiting for too long. If your transaction is discarded, Horizon will return a timeout error. diff --git a/docs/learn/fundamentals/stellar-stack.mdx b/docs/learn/fundamentals/stellar-stack.mdx index c7cc1d2cc..9ada31bc5 100644 --- a/docs/learn/fundamentals/stellar-stack.mdx +++ b/docs/learn/fundamentals/stellar-stack.mdx @@ -45,4 +45,4 @@ SDF does not provide a publicly available RPC endpoint for Mainnet. Developers s SDKs simplify some of the work of accessing Horizon and the Stellar RPC by converting the data into friendlier formats and allowing you to program in the language of your choice. Stellar’s SDKs show you how to request data and create and submit transactions. Soroban's SDKs allow you to write smart contracts in Rust and interact with smart contracts in a myriad of other languages. -View Stellar's [SDK library](../../tools/sdks/library.mdx) to access our SDKs and their documentation. +View Stellar's [SDK library](../../tools/sdks/README.mdx) to access our SDKs and their documentation. diff --git a/docs/learn/migrate/evm/smart-contract-deployment.mdx b/docs/learn/migrate/evm/smart-contract-deployment.mdx index 9958e23c9..4c97926e9 100644 --- a/docs/learn/migrate/evm/smart-contract-deployment.mdx +++ b/docs/learn/migrate/evm/smart-contract-deployment.mdx @@ -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](../../../tools/sdks/library.mdx), 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](../../../tools/sdks/README.mdx), 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`](../../../tools/sdks/library.mdx#javascript-sdk), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for Stellar 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`](../../../tools/sdks/client-sdks.mdx#javascript-sdk), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for Stellar 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](../../../tools/sdks/library.mdx). +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](../../../tools/sdks/client-sdks.mdx). ```python # This example shows how to deploy a compiled contract to the Stellar network. diff --git a/docs/learn/migrate/evm/solidity-and-rust-basics.mdx b/docs/learn/migrate/evm/solidity-and-rust-basics.mdx index c780469f0..97904502c 100644 --- a/docs/learn/migrate/evm/solidity-and-rust-basics.mdx +++ b/docs/learn/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`](../../../tools/sdks/library.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`](../../../tools/sdks/contract-sdks.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/tokens/stellar-asset-contract.mdx b/docs/tokens/stellar-asset-contract.mdx index ba7099da0..f4cbdb6ec 100644 --- a/docs/tokens/stellar-asset-contract.mdx +++ b/docs/tokens/stellar-asset-contract.mdx @@ -53,7 +53,7 @@ Anyone can deploy the instances of Stellar Asset Contract. Note, that the initia [contract_id]: https://github.com/stellar/stellar-xdr/blob/dc23adf60e095a6ce626b2b09128e58a5eae0cd0/Stellar-transaction.x#L661 [stellar cli]: ../tools/developer-tools/cli/stellar-cli.mdx -[stellar sdk]: ../tools/sdks/library.mdx +[stellar sdk]: ../tools/sdks/README.mdx ## Interacting with classic Stellar assets diff --git a/docs/tokens/token-interface.mdx b/docs/tokens/token-interface.mdx index 3d05a5aa3..502620646 100644 --- a/docs/tokens/token-interface.mdx +++ b/docs/tokens/token-interface.mdx @@ -23,7 +23,7 @@ For any given contract function, there are 3 requirements that should be consist ### Code -The interface below uses the Rust [soroban-sdk](../tools/sdks/library.mdx#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. +The interface below uses the Rust [soroban-sdk](../tools/sdks/contract-sdks.mdx#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. ```rust pub trait TokenInterface { diff --git a/docs/tools/README.mdx b/docs/tools/README.mdx index d33cc3381..824335784 100644 --- a/docs/tools/README.mdx +++ b/docs/tools/README.mdx @@ -9,7 +9,7 @@ description: "Explore tools for building, testing, and deploying blockchain appl This section of the docs will provide links to the SDKs and developer tools for use when developing on Stellar as well as documentation for various SDF-maintained platforms such as the Anchor Platform and Stellar Disbursement Platform (SDP). -## [SDKs](./sdks/library.mdx) +## [SDKs](./sdks/README.mdx) Stellar’s Software Development Kits (SDKs) provide devs with the tools, libraries, and documentation to interact with and develop on the blockchain. They simplify tasks such as creating and deploying smart contracts and sending transactions while also offering APIs to access data and integrate functionalities into applications. diff --git a/docs/tools/developer-tools/cli/README.mdx b/docs/tools/developer-tools/cli/README.mdx index 25b7f9675..a0a238a53 100644 --- a/docs/tools/developer-tools/cli/README.mdx +++ b/docs/tools/developer-tools/cli/README.mdx @@ -1,12 +1,10 @@ --- -title: CLI -description: Explore a suite of developer tools for Stellar, including CLI. +title: Stellar CLI +description: The CLI for interacting with the Stellar network sidebar_position: 50 --- -# CLI - -### [Stellar CLI](https://github.com/stellar/stellar-cli) +# Stellar CLI The command line interface to Soroban smart contracts. It allows you to build, deploy, and interact with smart contracts; configure identities; generate key pairs; manage networks; and more. @@ -14,6 +12,10 @@ Install Stellar CLI as explained in [Setup](../../../build/smart-contracts/getti The auto-generated comprehensive reference documentation is available [here](stellar-cli.mdx). -### [Sora](https://github.com/tolgayayci/sora) +:::note + +[Sora] is a cross platform GUI maintained by a third party that is designed to provide a graphical interface to the Stellar CLI. It offers a user-friendly interface for managing projects, identities, networks, contract methods, events, logs and so more in a graphical user interface rather than command line interface. + +::: -Sora is a cross platform GUI designed to simplify use of Stellar CLI. It offers a user-friendly interface for managing projects, identities, networks, contract methods, events, logs and so more in ease. +[Sora]: https://github.com/tolgayayci/sora diff --git a/docs/tools/developer-tools/cli/install-cli.mdx b/docs/tools/developer-tools/cli/install-cli.mdx index 71b67f1a1..aa8fa29a6 100644 --- a/docs/tools/developer-tools/cli/install-cli.mdx +++ b/docs/tools/developer-tools/cli/install-cli.mdx @@ -6,19 +6,25 @@ sidebar_position: 50 # Install the Stellar CLI -### [Stellar CLI](https://github.com/stellar/stellar-cli) +### Stellar CLI There are a few ways to install the latest released version of Stellar CLI. Install with Homebrew (macOS, Linux): -```sh +```text brew install stellar-cli ``` -Install with cargo from source: +Install with winget (Windows): -```sh +```text +winget install --id Stellar.StellarCLI +``` + +Install with cargo from source ([github.com/stellar/stellar-cli](https://github.com/stellar/stellar-cli)): + +```text cargo install --locked stellar-cli --features opt ``` @@ -26,7 +32,7 @@ cargo install --locked stellar-cli --features opt The Stellar CLI supports some autocompletion. To set up, run the following commands: -```sh +```text stellar completion --shell ``` @@ -34,13 +40,13 @@ Possible SHELL values are `bash`, `elvish`, `fish`, `powershell`, `zsh`, etc. To enable autocomplete in the current bash shell, run: -```sh +```text source <(stellar completion --shell bash) ``` To enable autocomplete permanently, run: -```sh +```text echo "source <(stellar completion --shell bash)" >> ~/.bashrc ``` diff --git a/docs/tools/sdks/README.mdx b/docs/tools/sdks/README.mdx index 02005f9cc..998232e88 100644 --- a/docs/tools/sdks/README.mdx +++ b/docs/tools/sdks/README.mdx @@ -9,6 +9,10 @@ sidebar_position: 10 import DocCardList from "@theme/DocCardList"; -This section provides the [SDK Library](./library.mdx) that contains a complete collection of SDKs that can interact with the Stellar network. We also detail the minimum requirements if you'd like to [Build Your Own SDK](./build-your-own.mdx). +The SDK section is split into three categories: + +- [Contract SDKs](./contract-sdks.mdx) that are used to build smart contracts that will be deployed to the Stellar network; +- [Client & XDR SDKs](./client-sdks.mdx) that are used by applications to interact with the network; +- [Build your own SDK](./build-your-own.mdx) that details the minimum requirements for building your own SDK. diff --git a/docs/tools/sdks/build-your-own.mdx b/docs/tools/sdks/build-your-own.mdx index 5f6a64501..d3eba4851 100644 --- a/docs/tools/sdks/build-your-own.mdx +++ b/docs/tools/sdks/build-your-own.mdx @@ -1,6 +1,6 @@ --- -title: "Build Your Own SDK" -sidebar_position: 20 +title: "Build Your Own Contract SDK" +sidebar_position: 30 --- :::note diff --git a/docs/tools/sdks/library.mdx b/docs/tools/sdks/client-sdks.mdx similarity index 74% rename from docs/tools/sdks/library.mdx rename to docs/tools/sdks/client-sdks.mdx index a4be75560..bd5905604 100644 --- a/docs/tools/sdks/library.mdx +++ b/docs/tools/sdks/client-sdks.mdx @@ -1,54 +1,25 @@ --- -title: Simplify Blockchain Development with SDKs for Rust, Python, and More -sidebar_label: "SDK Library" +title: "Simplify Blockchain Development with SDKs for Java, Python, and More" +sidebar_label: "Client & XDR SDKs" +sidebar_position: 20 description: "Explore the Stellar SDK library to simplify blockchain development. Leverage Rust, JavaScript, Python, and more to build on and integrate with the network." -sidebar_position: 10 --- -# SDK Library +# Client & XDR SDKs -The list of SDKs is separated into two categories: +Client and XDR SDKs are used by applications to interact with the network. -- Contract SDKs (used to build and interact with smart contracts on the network), and -- Client & XDR SDKs (used by applications to interact with the network) +:::note -The JavaScript, Go, and Rust SDKs are maintained by SDF. The rest SDK are maintained by dedicated community developers. All SDKs are open-source; file a GitHub issue or pull request in the specific SDK repository if you have questions or suggestions. +For SDKs for building smart contracts, see [Contract SDKs](./contract-sdks.mdx). -Each SDK has its own source code and documentation. Learn how to use a specific SDK by referring to the documentation. - -## Contract SDKs - -### Soroban Rust SDK - -[Rust SDK](https://github.com/stellar/rs-soroban-sdk) | [Docs](https://docs.rs/soroban-sdk) - -Also known as the Smart Contract SDK. The `soroban-sdk` Rust crate contains the Soroban Rust SDK for building smart contracts on Stellar. - -Report issues and share feedback about the `soroban-sdk` [here](https://github.com/stellar/rs-soroban-sdk/issues/new/choose). - -**Add `soroban-sdk` as a dependency** by using [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. +The JavaScript and Go SDKs, and some Rust libraries, are maintained by SDF. The rest of the SDKs are maintained by dedicated community developers. All SDKs are open-source; file a GitHub issue or pull request in the specific SDK repository if you have questions or suggestions. -```toml -[dependencies] -soroban-sdk = $VERSION - -[dev_dependencies] -soroban-sdk = { version = $VERSION, features = ["testutils"] } -``` - -### AssemblyScript SDK - -[AssemblyScript SDK](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). - -## Client & XDR SDKs +Each SDK has its own source code and documentation. Learn how to use a specific SDK by referring to the documentation. -### JavaScript SDK +## 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) @@ -59,7 +30,7 @@ It provides: - A networking layer API for Stellar 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. -### Python 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) @@ -72,7 +43,7 @@ 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. -### Rust +## Rust Functionality for interacting with Stellar data can be found in the following Rust crates: @@ -85,10 +56,10 @@ Functionality for interacting with Stellar data can be found in the following Ru Provides Stellar Strkey (Address) [SEP-23] encoding/decoding. [XDR]: ../../learn/encyclopedia/data-format/xdr -[XDR-JSON]: ../../learn/encyclopedia/data-format/xdr#json-and-xdr-conversion-schema +[XDR-JSON]: ../../learn/encyclopedia/data-format/xdr-json.mdx [SEP-23]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0023.md -### iOS SDK +## 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) @@ -96,7 +67,7 @@ The `stellar-ios-mac-sdk` is an open source Stellar SDK for iOS & Mac. It provid The iOS SDK is maintained by dedicated community developer, Soneso. -### Flutter SDK +## Flutter SDK [Flutter SDK](https://github.com/Soneso/stellar_flutter_sdk) | [Docs](https://github.com/Soneso/stellar_flutter_sdk/blob/master/soroban.md) @@ -104,7 +75,7 @@ The `stellar-flutter-sdk` is an open source Stellar SDK for Flutter developers. The Flutter Stellar SDK is maintained by dedicated community developer, Soneso. -### PHP SDK +## PHP SDK [PHP SDK](https://github.com/Soneso/stellar-php-sdk) | [Docs](https://github.com/Soneso/stellar-php-sdk/blob/main/soroban.md) @@ -112,37 +83,37 @@ The `stellar-php-sdk` is an open source Stellar SDK for PHP developers. It provi The PHP Stellar SDK is maintained by dedicated community developer, Soneso. -### Elixir SDK +## 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 [Java SDK](https://github.com/lightsail-network/java-stellar-sdk) | [Docs](https://lightsail-network.github.io/java-stellar-sdk/) `java-stellar-sdk` provides APIs to build transactions and connect to Horizon and also provides functionality to deploy and invoke Soroban smart contracts and communicates with the Stellar RPC Server. -### Go +## 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: [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 [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 [C# .NET SDK](https://github.com/Beans-BV/dotnet-stellar-sdk) | [Docs](https://elucidsoft.github.io/dotnet-stellar-sdk/) -### Scala +## Scala [Scala SDK](https://github.com/Synesso/scala-stellar-sdk) | [Docs](https://synesso.github.io/scala-stellar-sdk/) -### Qt/C++ +## Qt/C++ [Qt/C++ SDK](https://github.com/bnogalm/StellarQtSDK) | [Docs](https://github.com/bnogalm/StellarQtSDK/wiki) diff --git a/docs/tools/sdks/contract-sdks.mdx b/docs/tools/sdks/contract-sdks.mdx new file mode 100644 index 000000000..159a9fb4b --- /dev/null +++ b/docs/tools/sdks/contract-sdks.mdx @@ -0,0 +1,47 @@ +--- +title: "Build smart contracts that will be deployed to the Stellar network" +sidebar_label: Contract SDKs +sidebar_position: 10 +--- + +# Contract SDKs + +Contract SDKs are used to build smart contracts that will be deployed to the Stellar network. + +:::note + +For Client and XDR SDKs, visit this [page](./client-sdks.mdx). + +::: + +The Rust SDK is maintained by SDF. The AssemblyScript SDK is maintained by dedicated community developers. All SDKs are open-source; file a GitHub issue or pull request in the specific SDK repository if you have questions or suggestions. + +Each SDK has its own source code and documentation. Learn how to use a specific SDK by referring to the documentation. + +## Soroban Rust SDK + +[Rust SDK](https://github.com/stellar/rs-soroban-sdk) | [Docs](https://docs.rs/soroban-sdk) + +The `soroban-sdk` Rust crate contains the Soroban Rust SDK for building smart contracts for Stellar. + +Report issues and share feedback about the `soroban-sdk` [here](https://github.com/stellar/rs-soroban-sdk/issues/new/choose). + +**Add `soroban-sdk` as a dependency** by using [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 + +[AssemblyScript SDK](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). diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 83a144cf0..3be251a68 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -205,7 +205,7 @@ const config: Config = { activeBaseRegex: `(docs/tools|platforms)`, items: [ { - to: '/docs/tools/sdks/library', + to: '/docs/tools/sdks', label: 'SDKs', activeBasePath: 'docs/tools/sdks' }, diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index d0587adbc..9a03223e2 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -162,3 +162,4 @@ rewrite ^/docs/smart-contracts(.*)$ "/docs/build/smart-contracts$1" permanent; # Moving testing docs around rewrite ^/docs/build/guides/testing/detecting-changes-with-test-snapshots(.*)$ "/docs/build/guides/testing/differential-tests-with-test-snapshots$1" permanent; +rewrite ^/docs/build/guides/testing/integration-tests-with-mainnet-data(.*)$ "/docs/build/guides/testing/fork-testing$1" permanent; diff --git a/package.json b/package.json index b981aa7b8..665651f48 100644 --- a/package.json +++ b/package.json @@ -47,9 +47,9 @@ "@docusaurus/remark-plugin-npm2yarn": "3.4.0", "@docusaurus/theme-mermaid": "3.4.0", "@mdx-js/react": "^3.0.0", - "@stellar/open-rpc-docs-react": "^0.2.1", "@open-rpc/meta-schema": "^1.14.9", "@open-rpc/schema-utils-js": "^1.16.2", + "@stellar/open-rpc-docs-react": "^0.2.1", "ajv": "^8.16.0", "axios": "^1.7.4", "canvas-embed": "^1.0.80", diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 1f860bc1e..5a7094226 100644 --- a/src/pages/index.mdx +++ b/src/pages/index.mdx @@ -142,7 +142,7 @@ Interact with other Stellar developers, keep up with ecosystem standards and pro | [Hardware requirements](/docs/data/requirements) | The recommended hardware requirements for users looking to set up a Horizon instance | Learn | | [Admin guide](/docs/data/requirements) | A comprehensive set of guides that will teach you how to administer a production Horizon instance | Tutorial | | [API reference](/docs/data/horizon/api-reference) | Detailed documentation that provides information about the API endpoints, methods, parameters, and responses | Guide | -| [SDK library](/docs/tools/sdks/library) | Use the various SDKs to simplify the Horizon setup process by using pre-built tools and libraries that make it easier to configure, manage, and connect to the network | Tool | +| [SDK library](/docs/tools/sdks) | Use the various SDKs to simplify the Horizon setup process by using pre-built tools and libraries that make it easier to configure, manage, and connect to the network | Tool | | [Ecosystem providers](/docs/data/horizon/horizon-providers) | Create a PR in the docs to list your available Horizon service on this page | Tool | | Stellar RPC | | | @@ -150,7 +150,7 @@ Interact with other Stellar developers, keep up with ecosystem standards and pro | [Hardware requirements](/docs/data/requirements) | The recommended hardware requirements for users looking to set up an RPC node | Learn | | [Admin guide](/docs/data/rpc/admin-guide) | A comprehensive guide that will teach you how to administer a production RPC node | Tutorial | | [API reference](/docs/data/rpc/api-reference) | Detailed documentation that provides information about the API endpoints, methods, parameters, and responses | Guide | -| [SDK library](/docs/tools/sdks/library) | Use the various SDKs to simplify the RPC setup process by using pre-built tools and libraries that make it easier to configure, manage, and connect to the network | Tool | +| [SDK library](/docs/tools/sdks) | Use the various SDKs to simplify the RPC setup process by using pre-built tools and libraries that make it easier to configure, manage, and connect to the network | Tool | | [Ecosystem providers](/docs/data/rpc/rpc-providers) | Create a PR in the docs to list your available RPC service on this page | Tool |