From 3fdb809e9b2f0294b24f307addea9a535294fccb Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Fri, 29 Jul 2022 10:58:43 -0700 Subject: [PATCH] Changes from meeting today --- docs/examples/_category_.json | 2 +- docs/examples/liquidity-pool.mdx | 2 +- docs/examples/single-offer-sale.mdx | 2 +- docs/getting-started/build-a-wasm-file.mdx | 16 ---- .../{first-project.mdx => quick-start.mdx} | 2 +- docs/{guides => learn}/_category_.json | 2 +- docs/{guides => learn}/contract-lifecycle.mdx | 0 docs/{guides => learn}/debugging.mdx | 0 .../environment-concepts.mdx | 0 docs/{guides => learn}/events.mdx | 0 docs/{guides => learn}/gas-and-metering.mdx | 0 .../{guides => learn}/high-level-overview.mdx | 0 .../interacting-with-contracts-2.mdx | 0 .../interacting-with-contracts.mdx | 0 docs/{guides => learn}/persisting-data.mdx | 0 docs/{guides => learn}/rust-dialect.mdx | 0 .../standard-assets-and-authorization.mdx | 0 docs/standard-contracts/_category_.json | 4 + docs/standard-contracts/token-contract.mdx | 14 ++++ docs/tutorials/_category_.json | 4 + .../build-an-optimized-wasm-file.mdx | 0 .../build-and-run-a-contract.mdx} | 20 ++++- docs/tutorials/create-a-project.mdx | 74 +++++++++++++++++++ .../testing.mdx | 0 .../write-a-contract.mdx | 0 25 files changed, 119 insertions(+), 23 deletions(-) delete mode 100644 docs/getting-started/build-a-wasm-file.mdx rename docs/getting-started/{first-project.mdx => quick-start.mdx} (99%) rename docs/{guides => learn}/_category_.json (51%) rename docs/{guides => learn}/contract-lifecycle.mdx (100%) rename docs/{guides => learn}/debugging.mdx (100%) rename docs/{guides => learn}/environment-concepts.mdx (100%) rename docs/{guides => learn}/events.mdx (100%) rename docs/{guides => learn}/gas-and-metering.mdx (100%) rename docs/{guides => learn}/high-level-overview.mdx (100%) rename docs/{guides => learn}/interacting-with-contracts-2.mdx (100%) rename docs/{guides => learn}/interacting-with-contracts.mdx (100%) rename docs/{guides => learn}/persisting-data.mdx (100%) rename docs/{guides => learn}/rust-dialect.mdx (100%) rename docs/{guides => learn}/standard-assets-and-authorization.mdx (100%) create mode 100644 docs/standard-contracts/_category_.json create mode 100644 docs/standard-contracts/token-contract.mdx create mode 100644 docs/tutorials/_category_.json rename docs/{getting-started => tutorials}/build-an-optimized-wasm-file.mdx (100%) rename docs/{getting-started/run-a-wasm-file.mdx => tutorials/build-and-run-a-contract.mdx} (63%) create mode 100644 docs/tutorials/create-a-project.mdx rename docs/{getting-started => tutorials}/testing.mdx (100%) rename docs/{getting-started => tutorials}/write-a-contract.mdx (100%) diff --git a/docs/examples/_category_.json b/docs/examples/_category_.json index b3213599..64dda558 100644 --- a/docs/examples/_category_.json +++ b/docs/examples/_category_.json @@ -1,4 +1,4 @@ { "position": 3, - "label": "Tutorials / Examples" + "label": "Examples" } diff --git a/docs/examples/liquidity-pool.mdx b/docs/examples/liquidity-pool.mdx index ee362a44..a00652ef 100644 --- a/docs/examples/liquidity-pool.mdx +++ b/docs/examples/liquidity-pool.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 title: Liquidity Pool --- diff --git a/docs/examples/single-offer-sale.mdx b/docs/examples/single-offer-sale.mdx index dccf7b49..2c9c988f 100644 --- a/docs/examples/single-offer-sale.mdx +++ b/docs/examples/single-offer-sale.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 4 title: Single Offer Sale --- diff --git a/docs/getting-started/build-a-wasm-file.mdx b/docs/getting-started/build-a-wasm-file.mdx deleted file mode 100644 index 2855ef6a..00000000 --- a/docs/getting-started/build-a-wasm-file.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_position: 6 -title: Build a WASM File ---- - -To build a Soroban contract into a `.wasm` file, use the `cargo build` command. - -```sh -cargo build --target wasm32-unknown-unknown --release -``` - -A `.wasm` file should be outputted in the `target` directory: - -``` -target/wasm32-unknown-unknown/release/[project-name].wasm -``` diff --git a/docs/getting-started/first-project.mdx b/docs/getting-started/quick-start.mdx similarity index 99% rename from docs/getting-started/first-project.mdx rename to docs/getting-started/quick-start.mdx index 8d409146..af2c42b0 100644 --- a/docs/getting-started/first-project.mdx +++ b/docs/getting-started/quick-start.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: First Project +title: Quick Start --- Once you've [Setup] your development environment, you're ready to create your diff --git a/docs/guides/_category_.json b/docs/learn/_category_.json similarity index 51% rename from docs/guides/_category_.json rename to docs/learn/_category_.json index 1ba237c2..ed0717f9 100644 --- a/docs/guides/_category_.json +++ b/docs/learn/_category_.json @@ -1,4 +1,4 @@ { "position": 5, - "label": "Guides" + "label": "Learn" } diff --git a/docs/guides/contract-lifecycle.mdx b/docs/learn/contract-lifecycle.mdx similarity index 100% rename from docs/guides/contract-lifecycle.mdx rename to docs/learn/contract-lifecycle.mdx diff --git a/docs/guides/debugging.mdx b/docs/learn/debugging.mdx similarity index 100% rename from docs/guides/debugging.mdx rename to docs/learn/debugging.mdx diff --git a/docs/guides/environment-concepts.mdx b/docs/learn/environment-concepts.mdx similarity index 100% rename from docs/guides/environment-concepts.mdx rename to docs/learn/environment-concepts.mdx diff --git a/docs/guides/events.mdx b/docs/learn/events.mdx similarity index 100% rename from docs/guides/events.mdx rename to docs/learn/events.mdx diff --git a/docs/guides/gas-and-metering.mdx b/docs/learn/gas-and-metering.mdx similarity index 100% rename from docs/guides/gas-and-metering.mdx rename to docs/learn/gas-and-metering.mdx diff --git a/docs/guides/high-level-overview.mdx b/docs/learn/high-level-overview.mdx similarity index 100% rename from docs/guides/high-level-overview.mdx rename to docs/learn/high-level-overview.mdx diff --git a/docs/guides/interacting-with-contracts-2.mdx b/docs/learn/interacting-with-contracts-2.mdx similarity index 100% rename from docs/guides/interacting-with-contracts-2.mdx rename to docs/learn/interacting-with-contracts-2.mdx diff --git a/docs/guides/interacting-with-contracts.mdx b/docs/learn/interacting-with-contracts.mdx similarity index 100% rename from docs/guides/interacting-with-contracts.mdx rename to docs/learn/interacting-with-contracts.mdx diff --git a/docs/guides/persisting-data.mdx b/docs/learn/persisting-data.mdx similarity index 100% rename from docs/guides/persisting-data.mdx rename to docs/learn/persisting-data.mdx diff --git a/docs/guides/rust-dialect.mdx b/docs/learn/rust-dialect.mdx similarity index 100% rename from docs/guides/rust-dialect.mdx rename to docs/learn/rust-dialect.mdx diff --git a/docs/guides/standard-assets-and-authorization.mdx b/docs/learn/standard-assets-and-authorization.mdx similarity index 100% rename from docs/guides/standard-assets-and-authorization.mdx rename to docs/learn/standard-assets-and-authorization.mdx diff --git a/docs/standard-contracts/_category_.json b/docs/standard-contracts/_category_.json new file mode 100644 index 00000000..83474475 --- /dev/null +++ b/docs/standard-contracts/_category_.json @@ -0,0 +1,4 @@ +{ + "position": 3, + "label": "Standard Contracts" +} diff --git a/docs/standard-contracts/token-contract.mdx b/docs/standard-contracts/token-contract.mdx new file mode 100644 index 00000000..187bcf41 --- /dev/null +++ b/docs/standard-contracts/token-contract.mdx @@ -0,0 +1,14 @@ +--- +sidebar_position: 1 +title: Token Contract +--- + +The token contract is an implementation of [CAP-54 Smart Contract Standardized Asset]. + +[CAP-54 Smart Contract Standardized Asset]: https://stellar.org/protocol/cap-54 + +:::caution +The token contract is in early development, has not been audited, and is not +intended for use. Report issues +[here](https://github.com/stellar/soroban-token-contract). +::: diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json new file mode 100644 index 00000000..9a2d7cc5 --- /dev/null +++ b/docs/tutorials/_category_.json @@ -0,0 +1,4 @@ +{ + "position": 2, + "label": "Tutorials" +} diff --git a/docs/getting-started/build-an-optimized-wasm-file.mdx b/docs/tutorials/build-an-optimized-wasm-file.mdx similarity index 100% rename from docs/getting-started/build-an-optimized-wasm-file.mdx rename to docs/tutorials/build-an-optimized-wasm-file.mdx diff --git a/docs/getting-started/run-a-wasm-file.mdx b/docs/tutorials/build-and-run-a-contract.mdx similarity index 63% rename from docs/getting-started/run-a-wasm-file.mdx rename to docs/tutorials/build-and-run-a-contract.mdx index ef4de71b..9732320d 100644 --- a/docs/getting-started/run-a-wasm-file.mdx +++ b/docs/tutorials/build-and-run-a-contract.mdx @@ -1,8 +1,24 @@ --- -sidebar_position: 7 -title: Run a WASM File +sidebar_position: 6 +title: Build and Run --- +## Build a Contract + +To build a Soroban contract into a `.wasm` file, use the `cargo build` command. + +```sh +cargo build --target wasm32-unknown-unknown --release +``` + +A `.wasm` file should be outputted in the `target` directory: + +``` +target/wasm32-unknown-unknown/release/[project-name].wasm +``` + +## Run a Contract + If you have [`soroban-cli`] installed, you can invoke contract functions in a WASM file. diff --git a/docs/tutorials/create-a-project.mdx b/docs/tutorials/create-a-project.mdx new file mode 100644 index 00000000..3f234f36 --- /dev/null +++ b/docs/tutorials/create-a-project.mdx @@ -0,0 +1,74 @@ +--- +sidebar_position: 1 +title: Create a Project +--- + +Once you've [Setup] your development environment, you're ready to create your +first Soroban contract. + +[Setup]: setup.mdx + +Start by creating a new Rust library using the `cargo new` command. + +```sh +cargo new --lib [project-name] +``` + +Open the `Cargo.toml`, it should look something like this: + +```toml title="Cargo.toml" +[package] +name = "first-project" +version = "0.1.0" +edition = "2021" +``` + +## Add `soroban-sdk` Dependency + +Add the following sections to the `Cargo.toml` that will import the `soroban-sdk`. + +:::caution +The `soroban-sdk` is in early development. Report issues +[here](https://github.com/stellar/rs-soroban-sdk). +::: + +```toml +[lib] +crate-type = ["cdylib", "rlib"] + +[features] +default = ["export"] +export = [] +testutils = ["soroban-sdk/testutils"] + +[dependencies] +soroban-sdk = { git = "https://github.com/stellar/rs-soroban-sdk", rev = "32b76650" } + +[dev_dependencies] +first-project = { path = ".", features = ["testutils"] } + +[profile.release] +opt-level = "z" +overflow-checks = true +debug = 0 +strip = "symbols" +debug-assertions = false +panic = "abort" +codegen-units = 1 +lto = true +``` + +The `features` list and `dev_dependencies` configure three variations that the +contract can be built with: +- By `default`, with `export` enabled, contract functions will be exported and +available to be invoked when the contract is deployed. +- Optionally without `export` enabled, contract functions will not be exported. +Types will be still exposed, which is useful when developing multiple contracts +together and this contract is to be imported into another but its functions are +not intended to be invoked. +- And `testutils` which will cause additional test utilities to be generated for +calling the contract in tests. The library itself is added as a `dev_dependencies` +so that whenever its tests are running the `testutils` feature is enabled. + +The config for the `release` profile configures the Rust toolchain to produce +smaller contracts. diff --git a/docs/getting-started/testing.mdx b/docs/tutorials/testing.mdx similarity index 100% rename from docs/getting-started/testing.mdx rename to docs/tutorials/testing.mdx diff --git a/docs/getting-started/write-a-contract.mdx b/docs/tutorials/write-a-contract.mdx similarity index 100% rename from docs/getting-started/write-a-contract.mdx rename to docs/tutorials/write-a-contract.mdx