{"id":19620070,"url":"https://github.com/bjartek/overflow","last_synced_at":"2025-04-28T03:31:51.407Z","repository":{"id":36994176,"uuid":"433569196","full_name":"bjartek/overflow","owner":"bjartek","description":"a DSL to do awesome stuff on the flow blockchain","archived":false,"fork":false,"pushed_at":"2025-04-23T22:08:24.000Z","size":2121,"stargazers_count":38,"open_issues_count":6,"forks_count":20,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-23T23:21:17.675Z","etag":null,"topics":["flow-blockchain","onflow","overflow"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bjartek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-30T20:02:02.000Z","updated_at":"2025-04-23T22:08:27.000Z","dependencies_parsed_at":"2023-02-18T05:01:18.640Z","dependency_job_id":"9c580faa-0211-4ac2-9369-f16687118f65","html_url":"https://github.com/bjartek/overflow","commit_stats":null,"previous_names":[],"tags_count":158,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjartek%2Foverflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjartek%2Foverflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjartek%2Foverflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjartek%2Foverflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjartek","download_url":"https://codeload.github.com/bjartek/overflow/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251245938,"owners_count":21558759,"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":["flow-blockchain","onflow","overflow"],"created_at":"2024-11-11T11:16:02.867Z","updated_at":"2025-04-28T03:31:51.107Z","avatar_url":"https://github.com/bjartek.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Coverage Status](https://coveralls.io/repos/github/bjartek/overflow/badge.svg?branch=main)](https://coveralls.io/github/bjartek/overflow?branch=main) [![ci](https://github.com/bjartek/overflow/actions/workflows/ci.yaml/badge.svg)](https://github.com/bjartek/overflow/actions/workflows/ci.yaml)\n\n# Overflow\n\nThis is the v2 version of overflow to be used with cadence 1.0, for the v1 version that targets 0.x look in the v1 branch.\n\nA DSL written in golang to be used in tests or to run a `story` of interactions against either an local emulator, testnet, mainnet or an in memory instance of the flow-emulator.\n\nUse case scenarios include:\n - demo purposes\n - integration testing of combinations of scripts/transactions\n - batch jobs.\n\nFor a standalone example on how overflow can be used look at https://github.com/bjartek/flow-nft-overflow it has both an interactive demo and unit tests for an example NFT contract. \n\n## Main features\n\n- Uses a shared golang builder pattern for almost all interactions. \n- Well documented source code\n- supports all variants of multi-sign, Two authorizers, proposer and payer can be different. \n- when refering to an account/address you can use the logical name for that stakeholder defined in flow json. the same stakeholder IE admin can have different addresses on each network\n- can be run in embedded in memory mode that will start emulator, deploy contracts, create stakeholders and run interactions (scripts/transactions) against this embedded system and then stop it when it ends. \n- has a DSL to fetch Events and optionally store progress in a file. This can be chained into indexers/crawlers/notification services. \n- all interactions can be specified inline as well as from files\n- transform all interactions into a NPM module that can be published for the frontend to use. this json file that is generate has the option to filter out certain interactions and to strip away network suffixes if you have multiple local interactions that should map to the same logical name in the client for each network\n- the interaction (script/tx) dsl has a rich set of assertions \n- arguments to interactions are all _named_ that is the same name in that is in the argument must be used with the `Arg(\"name\", \"value\")` builder. The `value` in this example can be either a primitive go value or a `cadence.Value`. \n- supports shared instance in test to collect coverage report and rollback after/before each test. See `example` folder.\n\n## Gotchas\n\n- When specifying extra accounts that are created on emulator they are created in alphabetical order, the addresses the emulator assign is always fixed.\n- tldr; Name your stakeholder accounts in alphabetical order, we suggest admin, bob, charlie, demi, eddie\n- When writing integration tests, tests must be in the same folder as flow.json\nwith contracts and transactions/scripts in subdirectories in order for the path resolver\nto work correctly\n\n## Resources\n\n- Check [other codebases](https://github.com/bjartek/overflow/network/dependents) that use this project\n- Feel free to ask questions to @bjartek in the Overflow Discord. https://discord.gg/t6GEtHnWFh\n\n## Usage\n\nFirst create a project directory, initialize the go module and install `overflow`:\n\n```sh\nmkdir test-overflow \u0026\u0026 cd test-overflow\nflow init\ngo mod init example.com/test-overflow\ngo get github.com/bjartek/overflow/v2\n```\n\nThen create a task file:\n\n```sh\ntouch tasks/main.go\n```\n\nIn that task file, you can then import `overflow` and use it to your convenience, for example:\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    //if you imports this with .  you do not have to repeat overflow everywhere \n    . \"github.com/bjartek/overflow/v2\"\n)\n\nfunc main() {\n\n\t//start an in memory emulator by default\n  // there are two interfaces published for Overflow, `OverflowClient` and `OverrflowBetaClient` that has unstable api, I urge you to store this as the client and not the impl. Currenly the Overflow method returns the impl so you can choose.\n\to := Overflow()\n\t\n\t//the Tx DSL runs an transaction\n\to.Tx(\"name_of_transaction\", SignProposeAndPayAs(\"bob\"), Arg(\"name\", \"bob\")).Print()\n\t\n\t//Run a script/get interaction against the same in memory chain\n\to.Script(\"name_of_script\", Arg(\"name\", \"bob\")).Print()\n}\n```\n\nThen you can run\n\n```sh\ngo run ./tasks/main.go\n```\n\nThis is a minimal example that run a transction and a script, but from there you can branch out.\n\nThe following env vars are supported\n - OVERFLOW_ENV : set the environment to run against \"emulator|embedded|testnet|mainnet|testing\" (embedded is standard)\n - OVEFFLOW_CONTINUE: if you do not want overflow to deploy contracts and accounts on emulator you can set this to true\n - OVERFLOW_LOGGING: Set this to 0-4 to get increasing log\n\n## Usage flix\n```package main\n\nimport (\n\t. \"github.com/bjartek/overflow/v2\"\n)\n\nfunc main() {\n\to := Overflow(WithNetwork(\"mainnet\"))\n\n\to.FlixTx(\"transfer-flow\",\n\t\tWithSigner(\"\u003cyoursigner\u003e\"),\n\t\tWithArg(\"amount\", 0.42),\n\t\tWithArg(\"to\", \"0x886f3aeaf848c535\"),\n\t).Print()\n}```\n\nThis will send 0.42 flow to me on mainnet. You need a go file with that content and a valid flow.json that is it\n\n\n\n## Migrating from v1 api\n\nYou need to change your imports to be v2 and not v1\n\n## Credits\n\nThis project is the successor of https://github.com/bjartek/go-with-the-flow\nThe v0 version of the code with a set of apis that is now deprecated is in https://github.com/bjartek/overflow/tree/v0\nThe v1 version of the code with a set of apis that is now deprecated is in https://github.com/bjartek/overflow/tree/v1\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjartek%2Foverflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjartek%2Foverflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjartek%2Foverflow/lists"}