{"id":42254620,"url":"https://github.com/bandprotocol/band-std-reference-contracts-soroban","last_synced_at":"2026-01-27T05:18:36.677Z","repository":{"id":208978793,"uuid":"647640688","full_name":"bandprotocol/band-std-reference-contracts-soroban","owner":"bandprotocol","description":"A Rust implementation of Band Protocol's Soroban Standard Reference smart contract","archived":false,"fork":false,"pushed_at":"2024-02-29T06:21:47.000Z","size":90,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-13T19:00:28.921Z","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/bandprotocol.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}},"created_at":"2023-05-31T08:04:18.000Z","updated_at":"2024-03-08T04:28:18.000Z","dependencies_parsed_at":"2024-01-11T06:35:53.816Z","dependency_job_id":"440ae53d-9b05-430b-8f2f-86ef44223d96","html_url":"https://github.com/bandprotocol/band-std-reference-contracts-soroban","commit_stats":null,"previous_names":["bandprotocol/band-std-reference-contracts-soroban"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bandprotocol/band-std-reference-contracts-soroban","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Fband-std-reference-contracts-soroban","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Fband-std-reference-contracts-soroban/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Fband-std-reference-contracts-soroban/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Fband-std-reference-contracts-soroban/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bandprotocol","download_url":"https://codeload.github.com/bandprotocol/band-std-reference-contracts-soroban/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bandprotocol%2Fband-std-reference-contracts-soroban/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28803650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T03:44:14.111Z","status":"ssl_error","status_checked_at":"2026-01-27T03:43:33.507Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-01-27T05:18:36.118Z","updated_at":"2026-01-27T05:18:36.670Z","avatar_url":"https://github.com/bandprotocol.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Soroban - Band Standard Reference Contract\n\nThis repository contains a Rust implementation of the Band `StandardReference` Soroban smart contract. The contract\nprovides functionality for querying prices (reference data) of supported symbols from the BandChain. It allows relayers\nto update and retrieve reference data for the supported symbols\n\n## Components\n\nThere are 2 key components in this repository:\n\n1. [`src/contract.rs`](https://github.com/bandprotocol/band-std-reference-contracts-soroban/blob/main/src/contract.rs):\n   contains core `StandardReference` contract functionality\n2. [`examples/mock_consumer_contract/src/lib.rs`](https://github.com/bandprotocol/band-std-reference-contracts-soroban/blob/main/examples/mock_consumer_contract/src/lib.rs):\n   contains an example implementation of a contract which uses the prices from the `StandardReference` contract.\n\n## Standard Reference Contract\n\n### Functionality\n\nThe `StandardReferenceTrait` trait defines the contract interface, which includes the following functions:\n\n- `init`: Initializes the contract with the given admin address and adds the admin address to the relayers list.\n- `upgrade`: Upgrades the contract to a new wasm code at the provided wasm hash.\n- `version`: Returns the version of the contract.\n- `current_admin`: Returns the current admin address.\n- `transfer_admin`: Transfers the admin role to the new admin address and revokes relayer status from the old admin.\n- `is_relayer`: Checks if the given address is a relayer.\n- `add_relayers`: Adds the given addresses to the relayers list.\n- `remove_relayers`: Removes the given addresses from the relayers list.\n- `relay`: Relays symbol rates to the contract. The caller must be a relayer.\n- `force_relay`: Forces relay of symbol rates to the contract. The caller must be a relayer.\n- `delist`: Delists symbols from the contract. The caller must be a relayer.\n- `get_ref_data`: Retrieves reference data for the specified symbols.\n- `get_reference_data`: Retrieves reference data for the specified symbol pairs.\n\nThe `StandardReference` struct implements the `StandardReferenceTrait` trait, providing the actual implementation for\nthe contract functions.\n\n### Testing\n\nThe code includes a set of unit tests in the `tests` module. These tests cover various scenarios and verify the\ncorrectness of the contract implementation. Here are some key test cases:\n\n- `test_reinit`: Verifies that initializing the contract multiple times results in a panic.\n- `test_transfer_admin`: Tests the transfer of admin role to a new admin address.\n- `test_add_relayers`: Tests adding relayers to the contract.\n- `test_remove_relayers`: Tests removing relayers from the contract.\n- `test_relay`: Tests the relay of symbol rates by relayers and verifies the updated reference data.\n- `test_unauthorized_relay`: Ensures that unauthorized relayers cannot update the reference data.\n- `test_force_relay`: Tests the forced relay of symbol rates by relayers and verifies the updated reference data.\n- `test_delist`: Tests the delisting of symbols from the contract and verifies the removal of reference data.\n\n### Usage\n\nThere are three types of players: admin, relayer and consumer.\n\n1. The admin has the authority to assign and revoke admin and relayer roles from any addresses.\n2. The relayer is responsible for relaying the prices or data from BandChain to `StandardReference` contract via\n   the `relay` and `force_relay` functions. The admin and relayer roles will be maintained by Band Protocol.\n3. The consumer retrieves the prices for supported symbols via the `get_ref_data` and `get_reference_data` functions.\n   Please refer to `MockConsumer` contract for guidance.\n\n### RefData and ReferenceData\n\n#### [RefData](https://github.com/bandprotocol/band-std-reference-contracts-soroban/blob/main/src/ref_data.rs)\n\nThe `RefData` struct is used to store reference data for a specific symbol pair. It includes information such as the\nrate, resolve time, and request ID for a specific symbol.\n\n```rust    \npub struct RefData {\n    pub rate: u64,\n    pub resolve_time: u64,\n    pub request_id: u64,\n}\n```\n\nThe `RefData` struct has the following fields:\n\n- `rate`: Represents the rate of the symbol against USD.\n- `resolve_time`: Represents the Unix time when the reference data was resolved.\n- `request_id`: Represents the ID of the request associated with the reference data.\n\n#### [get_ref_data()](https://github.com/bandprotocol/band-std-reference-contracts-soroban/blob/2589e8211485af1ed2ac84f413bbe960df7af72d/src/contract.rs#L228)\n\nThis function is intended for obtaining reference data rate with Quote asset as USD.\n\n```rust\nfn get_ref_data(env: Env, symbols: Vec\u003cSymbol\u003e) -\u003e\nResult\u003cVec\u003cRefData\u003e, StandardReferenceError\u003e\n```\n\n##### Parameters\n\n`symbols`: A vector of symbols for which reference data is requested.\n\n##### Return Value\n\nThe function returns a `Result` containing the reference data as a vector of `RefData` objects if successful. If there\nis an error during the execution of the function, an `Err` variant of `StandardReferenceError` is returned.\n\n#### [Reference Data](https://github.com/bandprotocol/band-std-reference-contracts-soroban/blob/main/src/reference_data.rs)\n\nThe `ReferenceData`struct is similar `RefData` but the quote asset can be specified. It includes information such as the\nrate of the pair, and the last update times of the base and quote assets.\n\n```rust    \npub struct ReferenceData {\n    pub rate: u128,\n    pub last_updated_base: u64,\n    pub last_updated_quote: u64,\n}\n```\n\nThe `ReferenceData` struct has the following fields:\n\n- `rate`: Represents the rate of the symbol pair. For example, the rate of BTC/USD.\n- `last_updated_base`: Represents the Unix time when the base asset (e.g., BTC) was last updated.\n- `last_updated_quote`: Represents the Unix time when the quote asset (e.g., USD) was last updated.\n\n#### [get_reference_data()](https://github.com/bandprotocol/band-std-reference-contracts-soroban/blob/2589e8211485af1ed2ac84f413bbe960df7af72d/src/contract.rs#L252)\n\nThis function is used for obtaining the reference data rate by specifying both Base and Quote assets.\n\n```rust\nfn get_reference_data(\n    env: Env,\n    symbol_pairs: Vec\u003c(Symbol, Symbol)\u003e,\n) -\u003e Result\u003cVec\u003cReferenceData\u003e, StandardReferenceError\u003e\n```\n\n##### Parameters\n\n`symbol_pairs`: A vector of symbol pairs (Base and Quote assets) for which reference data is requested.\n\n##### Return Value\n\nThe function returns a `Result` containing the reference data as a vector of `ReferenceData` objects if successful. If\nthere is an error during the execution of the function, an `Err` variant of `StandardReferenceError` is returned.\n\n## Mock Consumer Contract\n\nThe mock consumer contract provides an example of how to interact with a `StandardReference` contract. It provides\nfunctionality to set the address of the standard reference contract and retrieve the price of symbol pairs.\n\nThe mock consumer contract provides the following functionality:\n\n- `set_std_reference_address`: Sets the address of the `StandardReference` contract in the contract storage.\n- `get_price_of`: Retrieves the price of the specified symbol pair from the `StandardReference` contract. It uses the\n  stored address of the `StandardReference` contract to create a client and fetch the reference data.\n\n## Example Usage\n\nFor example, if we want to query the price of BTC/USD, the demo contract below shows how this can be done.\n\n```rust\n#![no_std]\n\nuse soroban_sdk::{contractimpl, contracttype, Address, Env, Symbol, Vec};\n\nmod std_reference {\n    soroban_sdk::contractimport!(file = \"../../dist/std_reference.wasm\");\n}\n\npub struct Demo;\n\n#[contractimpl]\nimpl Demo {\n    pub fn set_std_reference_address(env: Env, std_reference_address: Address) {\n        env.storage()\n            .set(\u0026DataKey::StdReferenceAddress, \u0026std_reference_address);\n    }\n\n    pub fn demo(env: Env) -\u003e u128 {\n        let addr = env\n            .storage()\n            .get_unchecked(\u0026DataKey::StdReferenceAddress)\n            .unwrap();\n        let client = std_reference::Client::new(\u0026env, \u0026addr);\n        client\n            .get_reference_data(\u0026Vec::from_array(\u0026env, [(\"BTC\", \"USD\")]))\n            .get_unchecked(0)\n            .unwrap()\n            .rate\n    }\n}\n```\n\nAfter the `StandardReference` contract address is set, the BTC/USD price can be queried via the `demo()` function. An\nexample of result from `demo()` would be: `30065900000000000000000`, which is equivalent to 30,065.90 USD. Note that the\noutput rate is multiplied by `1e18`.\n\n## Setup - Build - Deploy\n\n### Prerequisites\n\nThe followings are prerequisites required to compile the contract:\n\n- A Rust toolchain\n- An editor that supports Rust\n- Soroban CLI\n\nPlease refer to [Soroban Documentation](https://soroban.stellar.org/docs/getting-started/setup) for installation\ninstructions.\n\n### Build the Contract\n\nTo build a Soroban contract for deployment or local testing, use the following command:\n\n```\nmake all\n```\n\nA `.wasm` file will be outputted in the target directory. The `.wasm` file is the built contract. For example:\n\n```\ntarget/wasm32-unknown-unknown/std_reference/std_reference.wasm\n```\n\n### Deploy the Contract\n\nTo deploy, use the deploy script at `scripts/deploy.sh`. For example:\n\n```bash\nscripts/deploy.sh -s \u003csource\u003e -n \u003cnetwork\u003e\n```\n\nWhere `\u003csource\u003e` is the source account and can either be a secret key, seed phrase or identity account and `\u003cnetwork\u003e`\nis the network to deploy to where the current network options are `futurenet` and `localnet`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbandprotocol%2Fband-std-reference-contracts-soroban","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbandprotocol%2Fband-std-reference-contracts-soroban","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbandprotocol%2Fband-std-reference-contracts-soroban/lists"}