{"id":18417419,"url":"https://github.com/stellar/soroflare","last_synced_at":"2025-04-07T12:32:33.181Z","repository":{"id":102492845,"uuid":"609223533","full_name":"stellar/soroflare","owner":"stellar","description":"The Soroban environment and vm running on a Cloudflare Worker. (a simplified version of the backend running fca00c.com)","archived":false,"fork":false,"pushed_at":"2024-03-18T21:41:50.000Z","size":202,"stargazers_count":5,"open_issues_count":1,"forks_count":4,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-04-24T03:54:40.386Z","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":"2023-03-03T16:26:37.000Z","updated_at":"2024-04-30T16:45:01.556Z","dependencies_parsed_at":null,"dependency_job_id":"9773da5c-ba17-40d6-bbd2-d1f6b82a0315","html_url":"https://github.com/stellar/soroflare","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroflare","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroflare/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroflare/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stellar%2Fsoroflare/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stellar","download_url":"https://codeload.github.com/stellar/soroflare/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247653247,"owners_count":20973788,"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:24.191Z","updated_at":"2025-04-07T12:32:28.171Z","avatar_url":"https://github.com/stellar.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Soroflare\n\u003e Careful:  \n\u003e This repository is an early stage of development.   \n\u003e It is not recommended to use this code in an production enviroment!\n\nThis repository contains the environment and virtual machine running as the backbone for the [FCA00C][fca00c] contest.  \n\n## Virtual Machine \nThe virtual machine contained in [soroflare-vm] is designed as a standalone rust crate.  \nThis allows an easy implementation of Soroban contract execution in arbitrary applications.\n\n## FCA00C backend\nA modified version of the actual [FCA00C][fca00c] backend is given in [soroflare-wrangler].  \nThe backend is built using the Cloudflare Wrangler stack and uses the [worker-rs] framework to compile to\nWebAssembly.  \nThe [soroflare-wrangler] can is as an exemplary implementation of the [soroflare-vm].\n\n\n[fca00c]: https://fca00c.com\n[soroflare-vm]: ./soroflare-vm/\n[soroflare-wrangler]: ./soroflare-wrangler/\n[worker-rs]: https://github.com/cloudflare/workers-rs\n\n\n# Usage\n\nIn the newly updated soroflare version, you have the possibility of setting up an API for running and testing webassembly modules (more specifically Soroban contracts) from your clients.\n\nSoroflare enables you to define every variable within your testing workflow, and can be specifically useful for testing contracts from your clients while being able to manipulate\nthe context in which your contracts get executed (for instance, test agains state expiration). At the current stage, you can build and populate the execution context of a contract call with all the\nentries the invocation you send to soroflare encompasses.\n\nTo make requests lighter and reduce overhead, you can also deploy your binaries to soroflare and then reference them within the snapshot you're sending.\n\n## API\n\n### Upload your binary\n\nPOST request to `/uploadwasm`, with the WASM binary as raw body.\n\n\n### Execute invocation with ledger snapshot\n\nPOST request to `/executesnapshot` with the snapshot as JSON body:\n\nFor example:\n\n```json\n{\n    \"contract_id\": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],\n    \"fname\": \"hello\",\n    \"keys\": [\n        {\n            \"contract_data\": {\n                \"contract\": \"CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4\",\n                \"durability\": \"persistent\",\n                \"key\": \"ledger_key_contract_instance\"\n            }\n        }\n    ],\n    \"ledger_sequence\": 500,\n    \"params\": [\n        {\n            \"symbol\": \"tdep\"\n        }\n    ],\n    \"vals\": [\n        {\n            \"entry\": {\n                \"data\": {\n                    \"contract_data\": {\n                        \"contract\": \"CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4\",\n                        \"durability\": \"persistent\",\n                        \"ext\": \"v0\",\n                        \"key\": \"ledger_key_contract_instance\",\n                        \"val\": {\n                            \"contract_instance\": {\n                                \"executable\": {\n                                    \"wasm\": \"cb212e08157def179b96989e9178d8cae62ce7b2155497ade08b08156f1921e8\"\n                                },\n                                \"storage\": null\n                            }\n                        }\n                    }\n                },\n                \"ext\": \"v0\",\n                \"last_modified_ledger_seq\": 0\n            },\n            \"live_until\": 100\n        }\n    ]\n}\n```\n\n\u003e Note: We're testing entry expiration here as we've set the snapshot's `ledger_sequence` to `500` and our contract instance entry's `live_until` to ledger `100`. This means that we'll receive an `Expired entries` error in the response along with the information about the expired entries.\n\n\u003e Note: above we're not providing the `LedgerEntry::ContractCode` entry in the snapshot, that's because I've already installed in Soroflare the binaries used by the contracts we're invoking in the call (`cb212e08157def179b96989e9178d8cae62ce7b2155497ade08b08156f1921e8`).\n\u003e If you try to run this without having installed the contract code in soroflare, you will receive an error about the module not being found.\n\n## Generating Snapshots\n\nThe snapshot format that soroflare accepts is the following:\n\n```rust\npub struct WithSnapshotInput {\n    ledger_sequence: u32,\n    keys: Vec\u003cLedgerKey\u003e,\n    vals: Vec\u003cEntryWithLifetime\u003e,\n    contract_id: [u8; 32],\n    fname: String,\n    params: Vec\u003cScVal\u003e,\n}\n```\n\nWith `LedgerKey` and `ScVal` being Stellar XDR objects and `EntryWithLifetime` defined as follows:\n\n```rust\n#[derive(Serialize, Deserialize, Debug)]\npub struct EntryWithLifetime {\n    pub entry: LedgerEntry,\n    pub live_until: Option\u003cu32\u003e,\n}\n```\n\nTo build a correctly-formed JSON snapshot, you can either serialize to JSON a `WithSnapshotInput` struct (for example, with `serde_json`) or simply follow the objects structure. \n\nExamples of built Snapshots can be found in the `soroflare-wrangler/src/routes/generic.rs` `test` module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellar%2Fsoroflare","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstellar%2Fsoroflare","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstellar%2Fsoroflare/lists"}