Adding/updating READMEs

README.md

@@ -9,7 +9,7 @@ The examples in this repository:
 
 - **account**: This a basic multi-sig account contract that with a customizable per-token authorization policy
 - **alloc**: Allocates a temporary vector holding values (0..count), then computes and returns their sum
-atomic_multiswap**: This contract performs a batch of atomic token swaps between multiple parties and does a simple price matching
+- **atomic_multiswap**: This contract performs a batch of atomic token swaps between multiple parties and does a simple price matching
 - **atomic_swap**: This contract performs an atomic token swap between two parties that don't need to know each other 
 - **auth**: This contract demonstrates how to implement authorization using Soroban-managed auth framework for a simple case
 - **bls_signature**: This is a basic custom account contract that implements the FastAggregateVerify function in BLS Signatures
@@ -23,10 +23,13 @@ atomic_multiswap**: This contract performs a batch of atomic token swaps between
 - **fuzzing**: This is the 'timelock' example modified slightly to demonstrate Soroban's fuzzing capabilities.
 - **hello_world**: The simplest smart contract, it takes a parameter value and add it to a vector and returns it
 - **increment**: Demonstrates how to increment a stored value and returning the updated value
+- **increment_with_fuzz**: Demonstrates how to fuzz test the increment contract
+- **increment_with_pause**: Demonstrates how the increment contract can be paused by a dependency
 - **liquidity_pool**: A minimalistic implementation of a liquidity pool and token swap
 - **logging**: A basic example of how to use the standard Soroban terminal logging
 - **mint-lock**: Demonstrates token minting, including minting authorization
 - **other_custom_types**: The smart contract implements types, including custom types
+- **pause**: The pausing dependency used in the increment_with_pause contract
 - **simple_account**: A minimal example of an account contract, owned by a single ed25519 public key
 - **single_offer**: This contract implements trading of one token pair between one seller and multiple buyers
 - **time_lock**: This contract demonstrates how to write a timelock and implements a greatly simplified claimable balance

account/README.md

@@ -0,0 +1,32 @@
+# Account
+Accounts are the central data structure in Stellar- they hold balances, sign transactions, and issue assets. Accounts can only exist with a valid keypair and the required minimum balance of XLM. 
+
+This example is a basic multi-sig account contract with a customizable per-token authorization policy. This example contract demonstrates how to build the account contract, and how to implement custom authorization policies that can govern all the account contract interactions.
+
+Custom accounts are exclusive to Soroban and can't be used to perform other Stellar operations.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `account/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Accounts documentation](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/custom-account)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
+

alloc/README.md

@@ -0,0 +1,27 @@
+# Alloc
+The allocator example demonstrates how to utilize the allocator feature when writing a contract. The `soroban-sdk` crate provides a lightweight bump-pointer allocator which can be used to emulate heap memory allocation in a Wasm smart contract.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `account/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Allocation documentation](https://developers.stellar.org/docs/learn/encyclopedia/contract-development/rust-dialect#limited-ideally-zero-dynamic-memory-allocation)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/alloc)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+

atomic_multiswap/README.md

@@ -0,0 +1,26 @@
+# Atomic Multiswap
+This atomic swap batching example swaps a pair of tokens between the two groups of users that authorized the swap operation from the [Atomic Swap](../atomic_swap) example. This contract basically batches the multiple swaps while following some simple rules to match the swap participants.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `atomic_multiswap/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Authorization documentation](https://developers.stellar.org/docs/learn/encyclopedia/security/authorization)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/atomic-multi-swap)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

atomic_swap/README.md

@@ -0,0 +1,26 @@
+# Atomic Swap
+This example contract swaps two tokens between two authorized parties atomically while following the limits they set. This example demonstrates advanced usage of Soroban auth framework and assumes the reader is familiar with the [auth](../auth) example and with Soroban token usage.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `atomic_swap/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Authorization documentation](https://developers.stellar.org/docs/learn/encyclopedia/security/authorization)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/atomic-swap)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

auth/README.md

@@ -0,0 +1,26 @@
+# Auth
+The auth example demonstrates how to implement authentication and authorization using the Soroban Host-managed auth framework. This example is an extension of the storing data example.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `auth/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Authorization documentation](https://developers.stellar.org/docs/learn/encyclopedia/security/authorization)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/auth)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

bls_signature/README.md

@@ -0,0 +1,28 @@
+# BLS Signature Custom Account
+
+This is a basic custom account contract that implements the `FastAggregateVerify` function in [BLS Signatures](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#name-fastaggregateverify). 
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `bls_signature/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [BLS Signatures](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#name-fastaggregateverify)
+- [Hashing to Elliptic Curves](https://datatracker.ietf.org/doc/html/rfc9380)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+

cross_contract/README.md

@@ -0,0 +1,40 @@
+# Cross Contract Calls
+The cross contract call example demonstrates how to call a contract from another contract. In this example there are two contracts that are compiled separately, deployed separately, and then tested together. There are a variety of ways to develop and test contracts with dependencies on other contracts, and the Soroban SDK and tooling is still building out the tools to support these workflows.
+
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file. Most examples only have one contract, but since this example is demonstrating how to make cross contract calls, two contracts are needed. They are named `contract_a` and `contract_b`.
+
+To run the tests for the example, navigate to the `cross_contract/contract_b` directory, which will contain the test file `auth/src/test.rs`, and run cargo test. Before running the test, `contract_a` must be built.
+
+The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+
+```
+cd contract_a
+stellar contract build
+```
+
+
+
+From the root of the contract run this command:
+
+```
+cd ../contract_b
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Cross contract documentation](https://developers.stellar.org/docs/learn/encyclopedia/contract-development/contract-interactions/cross-contract)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/cross-contract-call)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

custom_types/READMe.md

@@ -0,0 +1,27 @@
+# Custom Types
+The custom types example demonstrates how to define your own data structures that can be stored on the ledger, or used as inputs and outputs to contract invocations. This example is an extension of the [storing data example](https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data).
+
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `custom_types/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Custom types documentation](https://developers.stellar.org/docs/learn/encyclopedia/contract-development/types/custom-types)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/custom-types)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

deep_contract_auth/README.md

@@ -0,0 +1,29 @@
+# Deep Contract Auth
+This example demonstrates how a contract can authorize deep subcontract calls on its behalf.
+
+By default, only direct calls that contracts make are authorized. However, in some scenarios one may want to authorize a deeper call (a common example would be token transfer).
+
+Here we provide the abstract example: contract A calls contract B, then contract B calls contract C. Both contract B and contract C `require_auth` for contract A address and contract A provides proper authorization to make the calls succeed.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `deep_contract_auth/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Authorization documentation](https://developers.stellar.org/docs/learn/encyclopedia/security/authorization)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

deployer/README.md

@@ -0,0 +1,40 @@
+# Deployer
+The deployer example demonstrates how to deploy contracts using a contract.
+
+Here we deploy a contract on behalf of any address and initialize it atomically.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file. Most examples only have one contract, but since this example is demonstrating deploying one contract from another, two contracts are needed. They are named `contract` and `deployer`.
+
+To run the tests for the example, navigate to the `deployer/deployer` directory, which will contain the test file `deployer/src/test.rs`, and run cargo test. Before running the test, `contract` must be built.
+
+The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+
+```
+cd contract
+stellar contract build
+```
+
+From the root of the contract run this command:
+
+```
+cd ../deployer
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Contract deployment documentation](https://developers.stellar.org/docs/build/guides/conventions/deploy-contract)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/deployer)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+

errors/README.md

@@ -0,0 +1,25 @@
+# Errors
+The errors example demonstrates how to define and generate errors in a contract that invokers of the contract can understand and handle. This example is an extension of the [storing data example](https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data).
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `errors/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/errors)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)

eth_abi/README.md

@@ -0,0 +1,25 @@
+# ETH ABI
+The custom types example demonstrates how to decode contract specs in the Application Binary Interface format. The example uses a provided JSON file `test_snapshot/test/test_exec.1.json`.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `eth_abi/src/test.rs`. The test will just return a pass/fail result, but it’s a convenient way to check if the code works, without deploying and invoking the contract manually. The test file also demonstates how to invoke the smart contract. 
+
+From the root of the contract run this command:
+
+```
+cargo test
+```
+
+You should see the output:
+
+```
+running 1 test
+test test::test ... ok
+```
+
+See the main [README](../README.md) file for information about how to build and invoke the code using the CLI.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)
+- [Understanding the contract specification](https://developers.stellar.org/docs/build/guides/dapps/working-with-contract-specs#understanding-the-contract-specification)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)