{"id":18417379,"url":"https://github.com/stellar/soroban-examples","last_synced_at":"2025-04-05T00:05:35.293Z","repository":{"id":46867252,"uuid":"515646831","full_name":"stellar/soroban-examples","owner":"stellar","description":"Example Soroban Contracts","archived":false,"fork":false,"pushed_at":"2025-03-25T07:32:08.000Z","size":1104,"stargazers_count":70,"open_issues_count":39,"forks_count":74,"subscribers_count":27,"default_branch":"main","last_synced_at":"2025-03-28T23:03:50.721Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stellar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-19T15:43:35.000Z","updated_at":"2025-03-19T12:59:46.000Z","dependencies_parsed_at":"2024-01-16T04:45:15.085Z","dependency_job_id":"774358d8-1c1f-46b7-9b07-30b3e22171b9","html_url":"https://github.com/stellar/soroban-examples","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroban-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroban-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroban-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroban-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stellar","download_url":"https://codeload.github.com/stellar/soroban-examples/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266562,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T04:09:14.702Z","updated_at":"2025-04-05T00:05:35.271Z","avatar_url":"https://github.com/stellar.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Soroban Examples \u003c!-- omit in toc --\u003e\n\nThis repository contains example smart contracts for key Soroban features and concepts. The examples illustrate how to use the features, in their simplest form. \n\n\u003e [!WARNING]  \n\u003e These implementations are educational examples, and have not been tested or audited. They are likely to have significant errors and security vulnerabilities. They should not be relied on for any purpose. Please refer to the license for more information.\n\nThe examples in this repository:\n\n- **account**: This a basic multi-sig account contract that with a customizable per-token authorization policy\n- **alloc**: Allocates a temporary vector holding values (0..count), then computes and returns their sum\natomic_multiswap**: This contract performs a batch of atomic token swaps between multiple parties and does a simple price matching\n- **atomic_swap**: This contract performs an atomic token swap between two parties that don't need to know each other \n- **auth**: This contract demonstrates how to implement authorization using Soroban-managed auth framework for a simple case\n- **bls_signature**: This is a basic custom account contract that implements the FastAggregateVerify function in BLS Signatures\n- **cross_contract**: Demonstrates how to make cross contract calls\n- **custom_types**: A basic increment contract that implements a custom type\n- **deep_contract_auth**: This example demonstrates how a contract can authorize deep subcontract calls on its behalf\n- **deployer**: This contract deploys another contract Wasm and after deployment it invokes the initialization function of the contract\n- **errors**: This contract demonstrates how to define and generate errors in a contract that invokers of the contract can understand and handle\n- **eth_abi**: Demonstrates how to decode contract specs in the Application Binary Interface format\n- **events**: This contract demonstrates how to publish events from a contract \n- **fuzzing**: This is the 'timelock' example modified slightly to demonstrate Soroban's fuzzing capabilities.\n- **hello_world**: The simplest smart contract, it takes a parameter value and add it to a vector and returns it\n- **increment**: Demonstrates how to increment a stored value and returning the updated value\n- **liquidity_pool**: A minimalistic implementation of a liquidity pool and token swap\n- **logging**: A basic example of how to use the standard Soroban terminal logging\n- **mint-lock**: Demonstrates token minting, including minting authorization\n- **other_custom_types**: The smart contract implements types, including custom types\n- **simple_account**: A minimal example of an account contract, owned by a single ed25519 public key\n- **single_offer**: This contract implements trading of one token pair between one seller and multiple buyers\n- **time_lock**: This contract demonstrates how to write a timelock and implements a greatly simplified claimable balance\n- **token**: This contract demonstrates how to write a token contract that implements the Token Interface.\n- **ttl**: The contract demonstrates how TTL can be extended for stored keys\n- **upgradeable_contract**: This contract demonstrates how to upgrade the Wasm bytecode using example contracts\n- **workspace**: This contract demonstrates how multiple smart contracts can be developed, tested, and built side-by-side in the same Rust workspace\n\n## Get Started\nThe easiest way to get started experimenting with the example smart contracts, is to use GitPod. Run the smart contracts directly from the browser, without having to install tools, cloning the repo, building the code and deploying it to testnet.\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/stellar/soroban-examples)\n\n## Installation\nStellar smart contracts are written in the [Rust](https://www.rust-lang.org/) programming language and can be deployed to the testnet or mainnet. \n\n### Prerequisites\nTo build and develop contracts you need only a couple prerequisites:\n\n- A [Rust](https://www.rust-lang.org/) toolchain\n- An editor that supports Rust\n- [Stellar CLI](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup#install-the-stellar-cli)\n\nSee the [documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup) for more prerequisites installation instructions. \n\n#### Create Identity\nIf an identity for signing transactions has already been created, this part can be skipped. \n\nWhen deploying a smart contract to a network, an identity that will be used to sign the transactions must be specified. Let's configure an identity called alice. Any name can be used, but it might be convenient to have some named identities for testing, such as alice, bob, and carol. Notice that the account will be funded using [Friendbot](https://developers.stellar.org/docs/learn/fundamentals/networks#friendbot). \n\n```\nstellar keys generate --global alice --network testnet --fund\n```\n\nGet the public key of alice with this command: \n\n```\nstellar keys address alice\n```\n\nSee the [documentation](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup#configure-an-identity) for more information about identities.\n\n### Clone Contracts\nThe example smart contracts don’t need installation, simply clone the repo:\n\n```\ngit clone https://github.com/stellar/soroban-examples\n```\n\n*Note all smart contract examples are cloned, not individual contracts.*\n\n### Run Smart Contracts\n*Note: The `increment` contract is used in these instructions, but the instructions are similar for the other contracts, except for how to invoke the contracts.*\n\nThe smart contracts can easily be run by deploying them to testnet. Choose a contract and follow these instructions. \n\n#### Build\nFirst the smart contract must be built with this command from the `increment` contract’s root folder:\n\n```\ncd increment\nstellar contract build\n```\n\nA `.wasm` file will be outputted in the target directory, at `target/wasm32-unknown-unknown/release/soroban_increment_contract.wasm`. The `.wasm` file is the built contract.\n\n#### Deploy\nThe WASM file can now be deployed to the testnet by running this command:\n\n```\nstellar contract deploy \\\n  --wasm target/wasm32-unknown-unknown/release/soroban_increment_contract.wasm \\\n  --source alice \\\n  --network testnet \\\n  --alias increment_contract\n```\n\nWhen the smart contract has been successfully deployed, the command will return the contract’s ID (e.g. CACDYF3CYMJEJTIVFESQYZTN67GO2R5D5IUABTCUG3HXQSRXCSOROBAN). This ID can be used to invoke the contract, but since an alias is added, the alias can be used for invoking the contract as well.\n\n#### Invoke\nNow the contract is on testnet, it can be invoked. For the increment contract there’s only one function to invoke, and that’s the increment() function. Look at the code for the other contracts to see which function to invoke as every example contract is different.\n\nRun this command to invoke the increment contract (the added alias is used as the contract ID):\n\n```\nstellar contract invoke \\\n  --id increment_contract \\\n  --source alice \\\n  --network testnet \\\n  -- \\\n  increment \n```\n\nThe contract will return 1 the first time it’s run, run it again and see the returned value is being incremented.\n\n## Testing\nEach of the example smart contracts also has a test file that has test cases for each of the features of the smart contracts. 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. \n\nFrom the root of the contract (e.g. `increment`) run this command:\n\n```\ncargo test\n```\n\nSome examples may contain multiple contracts and require contracts to be built before the test can be run. See the individual example contracts for details.\n\n## Licence\nThe example smart contracts are licensed under the Apache 2.0 license. See the LICENSE file for details.\n\n## Contributions\nContributions are welcome, please create a pull request with the following information: \n\n- Explain the changes/additions you made\n- Why are these changes/additions needed or relevant?\n- How did you solve the problem, or created the suggested feature?\n- Have your changes/additions been thoroughly tested?\n\n## Relevant Links:\n- [Smart Contract Documentation](https://developers.stellar.org/docs/build)\n- [Getting Started Guide](https://developers.stellar.org/docs/build/smart-contracts/getting-started)\n- [Example descriptions in the documentation](https://developers.stellar.org/docs/build/smart-contracts/example-contracts)\n- [Link to examples in GitPod](https://gitpod.io/#https://github.com/stellar/soroban-examples/tree/v21.6.0)\n- [Stellar Developers Discord server](https://discord.gg/stellardev)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellar%2Fsoroban-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstellar%2Fsoroban-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellar%2Fsoroban-examples/lists"}