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

Commit

Permalink
Format (#508)
Browse files Browse the repository at this point in the history
* package updates

* cleaned up formatting
  • Loading branch information
kalepail committed Jul 21, 2023
1 parent 64ca386 commit a569cf7
Show file tree
Hide file tree
Showing 32 changed files with 4,062 additions and 3,725 deletions.
4 changes: 1 addition & 3 deletions docs/advanced-tutorials/atomic-multi-swap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Swapping tokens between two groups of users.
---

The [atomic swap batching example] swaps a pair of tokens between the two groups
of users that authorized the `swap` operation from the [Atomic Swap] example.
of users that authorized the `swap` operation from the [Atomic Swap] example.

This contract basically batches the multiple swaps while following some simple
rules to match the swap participants.
Expand All @@ -15,7 +15,5 @@ Follow the comments in the code for more information.
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp]

[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.9.2

[Atomic Swap]: atomic-swap.mdx

[atomic swap batching example]: https://github.com/stellar/soroban-examples/tree/v0.9.2/atomic_multiswap
3 changes: 1 addition & 2 deletions docs/advanced-tutorials/atomic-swap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Atomic Swap
description: Swapping tokens and using the auth framework.
---

The [atomic swap example] swaps two tokens between two authorized parties
The [atomic swap example] swaps two tokens between two authorized parties
atomically while following the limits they set.

This is example demonstrates advanced usage of Soroban auth framework and
Expand All @@ -14,7 +14,6 @@ Soroban token usage.
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)][oigp]

[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.9.2

[atomic swap example]: https://github.com/stellar/soroban-examples/tree/v0.9.2/atomic_swap

## Run the Example
Expand Down
4 changes: 2 additions & 2 deletions docs/advanced-tutorials/custom-account.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Stellar operations.

Implementing a custom account contract requires a very good understanding of
authentication and authorization and requires rigorous testing and review. The
example here is *not* a full-fledged account contract - use it as an API
example here is _not_ a full-fledged account contract - use it as an API
reference only.

:::
Expand Down Expand Up @@ -124,7 +124,7 @@ pub fn add_limit(env: Env, token: BytesN<32>, limit: i128) {
```

This function allows users to set and modify the per-token spend limit described
above. The neat trick here is that `require_auth` can be used for the
above. The neat trick here is that `require_auth` can be used for the
`current_contract_address()`, i.e. the account contract may be used to verify
authorization for its own administrative functions. This way there is no need
to write duplicate authorization and authentication logic.
Expand Down
38 changes: 4 additions & 34 deletions docs/advanced-tutorials/fuzzing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,6 @@ It builds on the [timelock example].
[`proptest-arbitrary-interop`]: https://docs.rs/proptest-arbitrary-interop
[timelock example]: https://github.com/stellar/soroban-examples/tree/v0.9.2/timelock




## Run the example

First go through the [setup] process to get your development environment
Expand Down Expand Up @@ -77,9 +74,6 @@ The rest of this tutorial will explain how to set up this fuzz test,
interpret this output,
and remedy fuzzing failures.




## Background: fuzz testing and Rust

Fuzzing is a kind of testing where new inputs are repeatedly fed into
Expand Down Expand Up @@ -135,9 +129,6 @@ which also maintains a "trophy case" of Rust bugs found through fuzzing.

[`rust-fuzz`]: https://github.com/rust-fuzz




## About the example

The example used for this tutorial is based on the [`timelock`]
Expand Down Expand Up @@ -174,7 +165,6 @@ pub enum TimeBoundKind {
`ClaimableBalanceContract` has two methods,
`deposit` and `claim`:


```rust
pub fn deposit(
env: Env,
Expand All @@ -198,9 +188,6 @@ until the balance is completely drained,
at which point the contract becomes dormant
and may no longer be used.




## Fuzz testing setup

For these examples, the fuzz tests have been created for you,
Expand Down Expand Up @@ -267,10 +254,10 @@ For fuzzing though, the fuzzing crate needs to be able to link
to the contract crate as a Rust library, an "rlib".

> Note that cargo has a [feature/bug that inhibits LTO][lto] of cdylibs when
a crate is both a "cdylib" and "rlib".
This can be worked around by building the contract with either
`soroban contract build` or `cargo rustc --crate-type cdylib`
instead of the typical `cargo build`.
> a crate is both a "cdylib" and "rlib".
> This can be worked around by building the contract with either
> `soroban contract build` or `cargo rustc --crate-type cdylib`
> instead of the typical `cargo build`.
[lto]: https://github.com/stellar/soroban-docs/pull/476

Expand Down Expand Up @@ -302,9 +289,6 @@ path = ".."
features = ["testutils"]
```




## A simple fuzz test

First let's look at [`fuzz_target_1.rs`].
Expand Down Expand Up @@ -503,9 +487,6 @@ fn assert_invariants(
}
```




## Interpreting `cargo-fuzz` output

If you run `cargo-fuzz` with `fuzz_target_1`,
Expand Down Expand Up @@ -750,9 +731,6 @@ See the [`libfuzzer` documentation] for more.

[`libfuzzer` documentation]: https://llvm.org/docs/LibFuzzer.html#output




## Accepting Soroban types as input with the `SorobanArbitrary` trait

Inputs to the `fuzz_target!` macro must implement the [`Arbitrary`] trait,
Expand Down Expand Up @@ -810,9 +788,6 @@ must turn that feature on.

[`contracttype`]: https://docs.rs/soroban-sdk/latest/soroban_sdk/macro.contracttype.html




## A more complex fuzz test

The [`fuzz_target_2.rs`] example, demonstrates the use of `SorobanArbitrary`,
Expand Down Expand Up @@ -971,8 +946,6 @@ for step in &config.input.steps {
}
```



## Converting a fuzz test to a property test

In addition to fuzz testing,
Expand All @@ -997,6 +970,3 @@ The [`proptest.rs`] file is a translation of `fuzz_target_1.rs`
to a property test.

[`proptest.rs`]: https://github.com/stellar/soroban-examples/tree/v0.9.2/fuzzing/src/proptest.rs



16 changes: 8 additions & 8 deletions docs/advanced-tutorials/stellar-asset-contract.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,7 @@ description: An implementation of CAP-46-6 smart contract standardized assets.
The Stellar Asset Contract is an implementation of [CAP-46-6 Smart Contract
Standardized Asset].

[CAP-46-6 Smart Contract Standardized Asset]:
https://stellar.org/protocol/cap-46-06
[CAP-46-6 Smart Contract Standardized Asset]: https://stellar.org/protocol/cap-46-06

:::caution

Expand Down Expand Up @@ -93,14 +92,14 @@ Stellar classic, which you can learn more about [here](https://developers.stella
- `AUTH_REVOCABLE_FLAG` is not required to be set on the issuer to deauthorize a
balance.
- Balances are stored in a 128-bit signed integer.
- A balance can only be clawed back if the issuer account had the
- A balance can only be clawed back if the issuer account had the
`AUTH_CLAWBACK_ENABLED_FLAG` set when the balance was created. A balance is
created when either an `Address::Contract` is on the receiving end of a successful
transfer, or if the admin sets the authorization state. Read more
about `AUTH_CLAWBACK_ENABLED_FLAG` [here](https://developers.stellar.org/docs/issuing-assets/control-asset-access#clawback-enabled-0x8).


### Balance Authorization Required

In the `Address::Contract` case, if the issuer has `AUTH_REQUIRED_FLAG` set, then the
specified `Address::Contract` will need to be explicitly authorized with
`set_auth` before it can receive a balance. This logic lines up with how
Expand All @@ -127,7 +126,7 @@ Getters require no authorization because they do not change the state of the
contract and all contract data is public. For example, `balance` simply returns
the balance of the specified `Address` without changing it.

Unprivileged mutators require authorization from the `Address` that spends or
Unprivileged mutators require authorization from the `Address` that spends or
allows spending their balance. The exceptions are `xfer_from` and `burn_from`
operations where the `Address` that require authorization from the 'spender'
entity that has got an allowance from another `Address` beforehand.
Expand Down Expand Up @@ -163,8 +162,9 @@ impl MyContract {

### Examples

See the full examples that utilize the token contract in various ways for more
See the full examples that utilize the token contract in various ways for more
details:

- [Timelock](timelock.mdx) and [single offer](single-offer-sale.mdx) move token
via `xfer` to and from the contract
- [Atomic swap](atomic-swap.mdx) uses `incr_allow` to transfer token on behalf
Expand All @@ -174,7 +174,7 @@ Notice, that these examples don't do anything to support SAC specifically.

### Testing

Soroban Rust SDK provides an easy way to instantiate a Stellar Asset Contract
Soroban Rust SDK provides an easy way to instantiate a Stellar Asset Contract
tokens using `register_stellar_asset_contract`. For example:

```rust
Expand All @@ -189,7 +189,7 @@ implementation.

## Contract Interface

This interface can be found in the [SDK]. It extends the common
This interface can be found in the [SDK]. It extends the common
[token interface](tokens.mdx).

[SDK]: https://github.com/stellar/rs-soroban-sdk/blob/v0.9.2/soroban-sdk/src/token.rs
4 changes: 2 additions & 2 deletions docs/advanced-tutorials/tokens.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ title: Tokens
description: A token contract that implements the standard Token Interface.
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

The [token example] demonstrates how to write a token contract that implements
the [Token Interface].
Expand Down
14 changes: 7 additions & 7 deletions docs/basic-tutorials/auth.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ This example is an extension of the [storing data example].
[oigp]: https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v0.9.2

[storing data example]: ../getting-started/storing-data.mdx

[auth example]: https://github.com/stellar/soroban-examples/tree/v0.9.2/auth

## Run the Example
Expand Down Expand Up @@ -115,18 +114,18 @@ pub enum DataKey {
}
```

`Address` is a universal Soroban identifier that may represent a Stellar
`Address` is a universal Soroban identifier that may represent a Stellar
account, a contract or an 'account contract' (a contract that defines a custom
authentication scheme and authorization policies). Contracts don't need to
distinguish between these internal representations though. `Address` can be
distinguish between these internal representations though. `Address` can be
used any time some network identity needs to be represented, like to
distinguish between counters for different users in this example.

:::tip Enum keys like `DataKey` are useful for organizing contract storage.

Different enum values create different key 'namespaces'.

In the example the counter for each address is stored against
In the example the counter for each address is stored against
`DataKey::Counter(Address)`. If the contract needs to start storing other types
of data, it can do so by adding additional variants to the enum.
:::
Expand Down Expand Up @@ -220,7 +219,7 @@ Soroban environment that the contract will run in.
let env = Env::default();
```

The test instructs the environment to mock all auths. All calls to
The test instructs the environment to mock all auths. All calls to
`require_auth` or `require_auth_for_args` will succeed.

```rust
Expand Down Expand Up @@ -305,7 +304,7 @@ target/wasm32-unknown-unknown/release/soroban_auth_contract.wasm

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

But since we are dealing with authorization and signatures, we need to set up
But since we are dealing with authorization and signatures, we need to set up
some identities to use for testing and get their public keys:

```sh
Expand Down Expand Up @@ -377,6 +376,7 @@ View the data that has been stored against each user with `soroban contract read
```sh
soroban contract read --id 1
```

```
"[""Counter"",""GA6S566FD3EQDUNQ4IGSLXKW3TGVSTQW3TPHPGS7NWMCEIPBOKTNCSRU""]",5
"[""Counter"",""GAJGHZ44IJXYFNOVRZGBCVKC2V62DB2KHZB7BEMYOWOLFQH4XP2TAM6B""]",15
Expand All @@ -396,13 +396,13 @@ soroban contract invoke \
--user GAJGHZ44IJXYFNOVRZGBCVKC2V62DB2KHZB7BEMYOWOLFQH4XP2TAM6B \
--value 123
```

```json
Contract auth: [{"address_with_nonce":null,"root_invocation":{"contract_id":"0000000000000000000000000000000000000000000000000000000000000001","function_name":"increment","args":[{"object":{"address":{"account":{"public_key_type_ed25519":"c7bab0288753d58d3e21cc3fa68cd2546b5f78ae6635a6f1b3fe07e03ee846e9"}}}},{"u32":123}],"sub_invocations":[]},"signature_args":[]}]
```

[`soroban-cli`]: ../getting-started/setup#install-the-soroban-cli


## Further reading

[Authorization documentation](../fundamentals-and-concepts/authorization.mdx) provides more details
Expand Down
Loading

0 comments on commit a569cf7

Please sign in to comment.