Skip to content
This repository has been archived by the owner on Aug 21, 2024. It is now read-only.

docs: Written content for the liquidity pool advanced tutorial #549

Merged
merged 10 commits into from
Aug 22, 2023
175 changes: 175 additions & 0 deletions docs/TUTORIAL-TEMPLATE.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
---
sidebar_position: 1000
title: How-To Guides Template
description: A description of the how-to guide that is being written
draft: true
---

Quick note about what this [example demonstrates]. Maybe it's also based on some
other example.

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp]

:::tip

Place each link definition at the bottom of the section it (first) is used In

:::

[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.9.2
[example demonstrates]: https://github.com/stellar/soroban-examples/tree/v0.9.2/hello_world
[other example]: getting-started/

## Run the Example

First go through the [Setup] process to get your development environment
configured, then clone the `v0.9.2` tag of `soroban-examples` repository:

```bash
git clone -b v0.9.2 https://github.com/stellar/soroban-examples
```

Or, skip the development environment setup and open this example in
[Gitpod][oigp].

To run the tests for the example, navigate to the `hello_world` directory, and
use `cargo test`.

```bash
cd hello_world
cargo test
```

You should see the output:

```bash
running 1 test
test test::test ... ok
```

[Setup]: ./getting-started/setup.mdx

## Code

```rust title="hello_world/src/lib.rs"
#![no_std]
use soroban_sdk::{contractimpl, vec, Env, Symbol, Vec};

pub struct HelloContract;

#[contractimpl]
impl HelloContract {
pub fn hello(env: Env, to: Symbol) -> Vec<Symbol> {
vec![&env, Symbol::short("Hello"), to]
}
}

mod test;
```

Ref: https://github.com/stellar/soroban-examples/tree/v0.9.2/hello_world

## How it Works

This is the written part of each guide. You can call out each thing unique to
this contract, sometimes referencing other important concepts from other example
contracts, too.

### Major Concepts

You could add sub-headings for highlighting even further important bits or
concepts to know. The `events` example guide has the following `h3` headings:

- Event Topics
- Event Data
- Publishing

Underneath each of those headings is a brief discussion of how that concept ties
into the example contract code.

## Tests

Open the `/hello_world/src/test.rs` file to follow along.

```rust title="hello_world/src/test.rs"
#![cfg(test)]

use super::*;
use soroban_sdk::{vec, Env, Symbol};

#[test]
fn test() {
let env = Env::default();
let contract_id = env.register_contract(None, HelloContract);
let client = HelloContractClient::new(&env, &contract_id);

let words = client.hello(&Symbol::short("Dev"));
assert_eq!(
words,
vec![&env, Symbol::short("Hello"), Symbol::short("Dev"),]
);
}
```

You can describe what's happening in the above test here. Some of the stuff will
likely be the same from one guide to another. It looks like, in particular, the
following chunk is shared among a few of them:

{/* BEGIN shared chunk */}

In any test the first thing that is always required is an `Env`, which is the
Soroban environment that the contract will run in.

```rust
let env = Env::default();
```

The contract is registered with the environment using the contract type.

```rust
let contract_id = env.register_contract(None, IncrementContract);
```

All public functions within an `impl` block that is annotated with the
`#[contractimpl]` attribute have a corresponding function generated in a
generated client type. The client type will be named the same as the contract
type with `Client` appended. For example, in our contract the contract type is
`Contract`, and the client is named `ContractClient`.

{/* /END shared chunk */}

Then you can describe the intricacies of what your contract test does uniquely.

## Build the Contract

To build the contract, use the `cargo build` command.

```bash
cargo build --target wasm32-unknown-unknown --release
```

A `.wasm` file should be outputted in the `target` directory:

```bash
target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm
```

## Run the Contract

If you have [`soroban-cli`] installed, you can invoke contract functions using
it.

```bash
soroban contract invoke \
--wasm target/wasm32-unknown-unknown/release/soroban_hello_world_contract.wasm \
--id 1 \
-- \
hello \
--to Soroban
```

## Further Reading

If you have some further links to share or background knowledge you can link to,
this is the place to share it. Or, maybe you want to point out how this example
is similar or not when compared with other examples.
Loading