Skip to content

a DSL to do awesome stuff on the flow blockchain

License

Notifications You must be signed in to change notification settings

bjartek/overflow

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

976548e · Feb 8, 2023
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Coverage Status ci

Overflow

A 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.

Use case scenarios include:

  • demo purposes
  • integration testing of combinations of scripts/transactions
  • batch jobs.

For 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.

Main features

  • Uses a shared golang builder pattern for almost all interactions.
  • Well documented source code
  • supports all variants of multi-sign, Two authorizers, proposer and payer can be different.
  • 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
  • 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.
  • has a DSL to fetch Events and optionally store progress in a file. This can be chained into indexers/crawlers/notification services.
  • all interactions can be specified inline as well as from files
  • 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
  • the interaction (script/tx) dsl has a rich set of assertions
  • 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.

Gotchas

  • When specifying extra accounts that are created on emulator they are created in alphabetical order, the addresses the emulator assign is always fixed.
  • tldr; Name your stakeholder accounts in alphabetical order, we suggest admin, bob, charlie, demi, eddie
  • When writing integration tests, tests must be in the same folder as flow.json with contracts and transactions/scripts in subdirectories in order for the path resolver to work correctly

Resources

Usage

First create a project directory, initialize the go module and install overflow:

mkdir test-overflow && cd test-overflow
flow init
go mod init example.com/test-overflow
go get github.com/bjartek/overflow

Then create a task file:

touch tasks/main.go

In that task file, you can then import overflow and use it to your convenience, for example:

package main

import (
    "fmt"

    //if you imports this with .  you do not have to repeat overflow everywhere 
    . "github.com/bjartek/overflow"
)

func main() {

	//start an in memory emulator by default
	o := Overflow()
	
	//the Tx DSL runs an transaction
	o.Tx("name_of_transaction", SignProposeAndPayAs("bob"), Arg("name", "bob")).Print()
	
	//Run a script/get interaction against the same in memory chain
	o.Script("name_of_script", Arg("name", "bob")).Print()
}

Then you can run

go run ./tasks/main.go

This is a minimal example that run a transction and a script, but from there you can branch out.

The following env vars are supported

  • OVERFLOW_ENV : set the environment to run against "emulator|embedded|testnet|mainnet|testing" (embedded is standard)
  • OVEFFLOW_CONTINUE: if you do not want overflow to deploy contracts and accounts on emulator you can set this to true
  • OVERFLOW_LOGGING: Set this to 0-4 to get increasing log

Migrating from v0 api

Please note the following if you migrate from an earlier version of overflow that was not tagged

  • "github.com/bjartek/overflow/overflow" -> "github.com/bjartek/overflow"
  • overflow.Overflow -> overflow.OverflowState
  • on OverflowState Script -> InlineScript
  • FlowTransationBuilder -> OverflowInteractionBuilder
  • FlowArgumentsBuilder -> OverflowArgumentsBuilder
  • Discord dependency is gone, if you need the code ask
  • almost all of the v0 is deprecated in favor of the functional builders Overflow to set up the client and , Tx, Script, FetchEvents to interact with it

Credits

This project is the successor of https://github.com/bjartek/go-with-the-flow The v0 version of the code with a set of apis that is now deprecated is in https://github.com/bjartek/overflow/tree/v0