diff --git a/README.md b/README.md
index a79e1ebc..252c2edd 100644
--- a/README.md
+++ b/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
diff --git a/account/README.md b/account/README.md
new file mode 100644
index 00000000..1dfa3dd6
--- /dev/null
+++ b/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)
+- [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)
+
+
diff --git a/alloc/README.md b/alloc/README.md
new file mode 100644
index 00000000..6fd16f8f
--- /dev/null
+++ b/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, `alloc/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)
+- [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)
+
diff --git a/atomic_multiswap/README.md b/atomic_multiswap/README.md
new file mode 100644
index 00000000..0eff96e1
--- /dev/null
+++ b/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)
+- [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)
diff --git a/atomic_swap/README.md b/atomic_swap/README.md
new file mode 100644
index 00000000..a780419b
--- /dev/null
+++ b/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)
+- [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)
diff --git a/auth/README.md b/auth/README.md
new file mode 100644
index 00000000..f9378518
--- /dev/null
+++ b/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)
+- [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)
diff --git a/bls_signature/README b/bls_signature/README
deleted file mode 100644
index 54f1d13a..00000000
--- a/bls_signature/README
+++ /dev/null
@@ -1,11 +0,0 @@
-# BLS Signature Custom Account
-
-This repository contains a basic custom account contract implementing the `FastAggregateVerify` function, following the specifications outlined in the [BLS Signatures](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#name-fastaggregateverify) draft.
-
-## ⚠️ WARNING: Demonstration Use Only
-
-**This project is for demonstration purposes only.**  
-- It has **not** undergone security auditing.  
-- It is **not** safe for use in production environments.  
-
-**Use at your own risk.**
\ No newline at end of file
diff --git a/bls_signature/README.md b/bls_signature/README.md
new file mode 100644
index 00000000..d4b78b35
--- /dev/null
+++ b/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)
+- [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)
+
diff --git a/cross_contract/README.md b/cross_contract/README.md
new file mode 100644
index 00000000..7147aa54
--- /dev/null
+++ b/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)
+- [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)
diff --git a/custom_types/READMe.md b/custom_types/READMe.md
new file mode 100644
index 00000000..6e4a3f66
--- /dev/null
+++ b/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)
+- [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)
diff --git a/deep_contract_auth/README.md b/deep_contract_auth/README.md
new file mode 100644
index 00000000..5b0ded46
--- /dev/null
+++ b/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)
+- [Authorization documentation](https://developers.stellar.org/docs/learn/encyclopedia/security/authorization)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
diff --git a/deployer/README.md b/deployer/README.md
new file mode 100644
index 00000000..438bf8da
--- /dev/null
+++ b/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)
+- [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)
+
diff --git a/errors/README.md b/errors/README.md
new file mode 100644
index 00000000..46104eef
--- /dev/null
+++ b/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)
+- [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)
diff --git a/eth_abi/README.md b/eth_abi/README.md
new file mode 100644
index 00000000..54fe524d
--- /dev/null
+++ b/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)
+- [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)
diff --git a/events/README.md b/events/README.md
new file mode 100644
index 00000000..5028211c
--- /dev/null
+++ b/events/README.md
@@ -0,0 +1,28 @@
+# Events
+
+The events example demonstrates how to publish events from a contract. 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, `events/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)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/events)
+- [Events documentation](https://developers.stellar.org/docs/learn/encyclopedia/contract-development/events)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/fuzzing/README.md b/fuzzing/README.md
new file mode 100644
index 00000000..43801771
--- /dev/null
+++ b/fuzzing/README.md
@@ -0,0 +1,25 @@
+# Fuzz Testing
+The fuzzing example demonstrates how to fuzz test Soroban contracts with `cargo-fuzz` and customize the input to fuzz tests with the `arbitrary` crate. It also demonstrates how to adapt fuzz tests into reusable property tests with the `proptest` and `proptest-arbitrary-interop` crates. It builds on the timelock example.
+
+## Test
+You will need the cargo-fuzz tool, and to run cargo-fuzz you will need a nightly Rust toolchain:
+
+```
+cargo install cargo-fuzz
+rustup install nightly
+```
+
+To run one of the fuzz tests, navigate to the fuzzing directory and run the cargo fuzz subcommand with the nightly toolchain:
+
+```
+cd fuzzing
+cargo +nightly fuzz run fuzz_target_1
+```
+
+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)
+- [Unit test documentation](https://developers.stellar.org/docs/build/guides/testing/unit-tests)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/fuzzing)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
diff --git a/hello_world/README.md b/hello_world/README.md
new file mode 100644
index 00000000..bf85f60d
--- /dev/null
+++ b/hello_world/README.md
@@ -0,0 +1,26 @@
+# Hello World
+The hello world example demonstrates how to create, build and deploy a simple smart contract on Soroban. The example is used for the [Getting Started](https://developers.stellar.org/docs/build/smart-contracts/getting-started) guide in the documentation.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `hello_world/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)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/getting-started/hello-world)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/increment/README.md b/increment/README.md
new file mode 100644
index 00000000..0f033542
--- /dev/null
+++ b/increment/README.md
@@ -0,0 +1,26 @@
+# Increment
+This contract will get a counter value from storage (or use the value 0 if no value has been stored yet), and increment this counter every time it's called. The example is used for the [Storage](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/storage) example contract in the documentation.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `increment/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)
+- [Storing Data documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/increment_with_fuzz/README.md b/increment_with_fuzz/README.md
new file mode 100644
index 00000000..e03e2c90
--- /dev/null
+++ b/increment_with_fuzz/README.md
@@ -0,0 +1,11 @@
+# Increment With Fuzz
+Demonstrates how to fuzz test the increment contract, which increments a stored value and returning the updated value.
+
+For information about how to setup fuzz testing, and run the fuzz test, see the step-by-step guide in the [Fuzz Testing](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/fuzzing) documentation.
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples)
+- [Storing Data documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data)
+- [Fuzz Testing](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/fuzzing)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/increment_with_pause/README.md b/increment_with_pause/README.md
new file mode 100644
index 00000000..1bc59ff4
--- /dev/null
+++ b/increment_with_pause/README.md
@@ -0,0 +1,32 @@
+# Increment With Pause
+This contract is built on top of the increment contract, and let's the contract be paused by a dependency. 
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `increment_with_pause/src/test_real.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. 
+
+Besides the test file mentioned above, there's also a mock test file, `increment_with_pause/src/test_mock.rs`. The first test file requires a pausing dependency ([pause](../pause)) to exist, and the mock test can run without a pausing dependency. In the example below, the test with a dependency is used. It is necessary to build the dependency before running the test.
+
+From the root of the contract run this command:
+
+```
+cd ../pause
+stellar contract build
+
+cd ../increment_with_pause
+cargo test test_real
+```
+
+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)
+- [Storing Data documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started/storing-data)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/liquidity_pool/README.md b/liquidity_pool/README.md
new file mode 100644
index 00000000..b844c173
--- /dev/null
+++ b/liquidity_pool/README.md
@@ -0,0 +1,26 @@
+# Liquidity Pool
+The liquidity pool example demonstrates how to write a constant product liquidity pool contract. A liquidity pool is an automated way to add liquidity for a set of tokens that will facilitate asset conversion between them. Users can deposit some amount of each token into the pool, receiving a proportional number of "token shares." The user will then receive a portion of the accrued conversion fees when they ultimately "trade in" their token shares to receive their original tokens back.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `liquidity_pool/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)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/liquidity-pool)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/logging/README.md b/logging/README.md
new file mode 100644
index 00000000..711b5e13
--- /dev/null
+++ b/logging/README.md
@@ -0,0 +1,28 @@
+# Logging
+The logging example demonstrates how to log for the purpose of debugging.
+
+Logs in contracts are only visible in tests, or when executing contracts using `stellar-cli`. Logs are only compiled into the contract if the `debug-assertions` Rust compiler option is enabled.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `logging/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)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/logging)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/mint-lock/README.md b/mint-lock/README.md
new file mode 100644
index 00000000..14279e04
--- /dev/null
+++ b/mint-lock/README.md
@@ -0,0 +1,27 @@
+# Mint Lock
+The mint lock example demonstrates how to write a contract that can delegate minting tokens from another address with limits on how much those addresses can mint across a specified time period.
+
+The admin of the token contracts used must be the mint lock contract.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `mint-lock/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)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/other_custom_types/README.md b/other_custom_types/README.md
new file mode 100644
index 00000000..dbc6e8b0
--- /dev/null
+++ b/other_custom_types/README.md
@@ -0,0 +1,26 @@
+# Other 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 `custom_types` example smart contract, and implements more custom types.
+
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `other_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)
+- [Custom types documentation](https://developers.stellar.org/docs/learn/encyclopedia/contract-development/types/custom-types)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
diff --git a/simple_account/README.md b/simple_account/README.md
new file mode 100644
index 00000000..d27c7444
--- /dev/null
+++ b/simple_account/README.md
@@ -0,0 +1,26 @@
+# Simple Account
+This a minimal exapmle of an account contract. The account is owned by a single ed25519 public key that is also used for authentication. For a more advanced example that demonstrates all the capabilities of the soroban account contracts see the `account` example.
+
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `simple_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)
+- [Accounts documentation](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
diff --git a/single_offer/README.md b/single_offer/README.md
new file mode 100644
index 00000000..98829d5b
--- /dev/null
+++ b/single_offer/README.md
@@ -0,0 +1,26 @@
+# Single Offer
+This contract implements trading of one token pair between one seller and multiple buyer. It demonstrates one of the ways of how trading might be implemented.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `single_offer/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)
+- [Accounts documentation](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/timelock/README.md b/timelock/README.md
new file mode 100644
index 00000000..9fef4ac7
--- /dev/null
+++ b/timelock/README.md
@@ -0,0 +1,27 @@
+# Timelock
+This contract demonstrates the timelock concept and implements a greatly simplified Claimable Balance (similar to https://developers.stellar.org/docs/glossary/claimable-balance).
+
+The contract allows to deposit some amount of token and allow another account(s) claim it before or after provided time point. For simplicity, the contract only supports invoker-based auth.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `timelock/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)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/token/README.md b/token/README.md
new file mode 100644
index 00000000..fa6b3747
--- /dev/null
+++ b/token/README.md
@@ -0,0 +1,26 @@
+# Tokens
+The token example demonstrates how to write a token contract that implements the [Token Interface](https://developers.stellar.org/docs/tokens/token-interface).
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `token/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)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/tokens)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/ttl/README.md b/ttl/README.md
new file mode 100644
index 00000000..4dfe0a5f
--- /dev/null
+++ b/ttl/README.md
@@ -0,0 +1,25 @@
+# Tokens
+This is a simple contract that just extends TTL for its keys. It's main purpose is to demonstrate how TTL extension can be tested, so the most interesting part here is test file `test.rs`.
+
+## Test
+For a quick test of the smart contract, run a test using the provided test file, `ttl/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)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/upgradeable_contract/README.md b/upgradeable_contract/README.md
new file mode 100644
index 00000000..d65fcb7a
--- /dev/null
+++ b/upgradeable_contract/README.md
@@ -0,0 +1,11 @@
+# Upgradeable Contract
+Upgrading a smart contract allows you to improve or modify your contract without changing its address. 
+
+This [guide](https://developers.stellar.org/docs/build/guides/conventions/upgrading-contracts) will walk you through the process of upgrading a WebAssembly (Wasm) bytecode contract using the Soroban SDK and the code in this repo.
+
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/guides/conventions/upgrading-contracts)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+
diff --git a/workspace/README.md b/workspace/README.md
new file mode 100644
index 00000000..aaa665e5
--- /dev/null
+++ b/workspace/README.md
@@ -0,0 +1,10 @@
+# Workspace
+The workspace example demonstrates how multiple smart contracts can be developed, tested, and built side-by-side in the same Rust workspace. 
+
+See how to run this example the guide [Practical Use-Case Examples](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/workspace) in the documentation. 
+
+## Relevant Links
+- [Open example in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples)
+- [Detailed description of this example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/workspace)
+- [Getting Started documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started)
+