fixing better examples

doc_test.go

@@ -1,17 +1,27 @@
 package overflow_test
 
 // importing overflow using "." will yield a cleaner DSL
-import . "github.com/bjartek/overflow"
+import (
+	"fmt"
+	"time"
+
+	. "github.com/bjartek/overflow"
+)
 
 func Example() {
 
-	// create a new overflow emulator that will panic if scripts/transactions
-	//fail and print output
+	//in order to start overflow use the Overflow function
+	//it can be customized with lots of OverflowOption
 	o := Overflow(
 		StopOnError(),
 		PrintInteractionResults(),
-		// here you can send in more options to customize the way Overflow is started
 	)
+	fmt.Println(o)
+	//the result of the Overflow function is an OverflowState object
+}
+
+func ExampleOverflowState_Tx() {
+	o := Overflow(StopOnError(), PrintInteractionResults())
 
 	// start the Tx DSL with the name of the transactions file, by default this
 	// is in the `transactions` folder in your root dit
@@ -22,9 +32,43 @@ func Example() {
 		//Arguments are always passed by name in the DSL builder, order does not matter
 		Arg("test", "overflow ftw!"),
 	)
-	// Output: 👌 Tx:arguments computation:?? loops:? statements:? invocations:? id:?
-	// the standard output if you print results continas the name of the transaction,
-	// id and computation information if run on emulator
+}
+
+func ExampleOverflowState_Tx_inline() {
+	o := Overflow(StopOnError(), PrintInteractionResults())
+
+	//The Tx dsl can also contain an inline transaction
+	o.Tx(`
+		import Debug from "../contracts/Debug.cdc"
+		transaction(message:String) {
+		  prepare(acct: AuthAccount) {
+				Debug.log(message) 
+			} 
+		}`,
+		SignProposeAndPayAs("first"),
+		Arg("message", "overflow ftw!"),
+	)
+}
+
+func ExampleOverflowState_Tx_multisign() {
+	o := Overflow(StopOnError(), PrintInteractionResults())
+
+	//The Tx dsl can also contain an inline transaction
+	o.Tx(`
+		transaction {
+			prepare(acct: AuthAccount, acct2: AuthAccount) {
+			  //aact here is first
+				//acct2 here is second
+			} 
+		}`,
+		SignProposeAndPayAs("first"),
+		PayloadSigner("second"),
+	)
+
+}
+
+func ExampleOverflowState_Script() {
+	o := Overflow(StopOnError(), PrintInteractionResults())
 
 	// the other major interaction you can run on Flow is a script, it uses the script DSL.
 	// Start it by specifying the script name from `scripts` folder
@@ -36,8 +80,42 @@ func Example() {
 		// accordingly it will just work
 		Arg("account", "first"),
 	)
-	// Output: ⭐ Script test result:??
-	// will print out the name of the script and the result as json
+}
+
+func ExampleOverflowState_Script_inline() {
+	o := Overflow(StopOnError(), PrintInteractionResults())
+
+	//Script can be run inline
+	o.Script(`
+pub fun main(account: Address): String {
+    return getAccount(account).address.toString()
+}`,
+		Arg("account", "first"),
+	)
+}
+
+func ExampleOverflowState_FetchEvents() {
+	o := Overflow(
+		StopOnError(),
+		PrintInteractionResults(),
+		// here you can send in more options to customize the way Overflow is started
+	)
+
+	for {
+		events, err := o.FetchEvents(
+			TrackProgressIn("minted_tokens"),
+			WithEvent("A.0ae53cb6e3f42a79.FlowToken.TokensMinted"),
+		)
+		if err != nil {
+			panic(err)
+		}
+
+		if len(events) == 0 {
+			//here you can specify how long you will wait between polls
+			time.Sleep(10 * time.Second)
+		}
 
-	// This is just the simples example of an interaction using overflow but it has many hidden gems!
+		// do something with events, like sending them to discord/twitter or index in a database
+		fmt.Println(events)
+	}
 }

interaction_builder.go

@@ -34,14 +34,16 @@ type FlowInteractionBuilder struct {
 	//The list of raw arguments
 	Arguments []cadence.Value
 
-	//TODO: Should this be payer?
 	//The main signer used to sign the transaction
-	MainSigner *flowkit.Account
+	// Payer: the account paying for the transaction fees.
+	Payer *flowkit.Account
 
 	//The propser account
+	//    Proposer: the account that specifies a proposal key.
 	Proposer *flowkit.Account
 
 	//The payload signers that will sign the payload
+	//Authorizers: zero or more accounts authorizing the transaction to mutate their state.
 	PayloadSigners []*flowkit.Account
 
 	//The gas limit to set for this given interaction
@@ -212,7 +214,7 @@ func SignProposeAndPayAs(signer string) InteractionOption {
 			ftb.Error = err
 			return
 		}
-		ftb.MainSigner = account
+		ftb.Payer = account
 		ftb.Proposer = account
 	}
 }
@@ -222,7 +224,7 @@ func SignProposeAndPayAsServiceAccount() InteractionOption {
 	return func(ftb *FlowInteractionBuilder) {
 		key := ftb.Overflow.ServiceAccountName()
 		account, _ := ftb.Overflow.State.Accounts().ByName(key)
-		ftb.MainSigner = account
+		ftb.Payer = account
 		ftb.Proposer = account
 	}
 }
@@ -271,7 +273,7 @@ func (t FlowInteractionBuilder) Send() *OverflowResult {
 	}
 
 	if t.Proposer == nil {
-		result.Err = fmt.Errorf("%v You need to set the main signer", emoji.PileOfPoo)
+		result.Err = fmt.Errorf("%v You need to set the proposer signer", emoji.PileOfPoo)
 		return result
 	}
 
@@ -288,17 +290,21 @@ func (t FlowInteractionBuilder) Send() *OverflowResult {
 
 	t.Overflow.Log.Reset()
 	t.Overflow.EmulatorLog.Reset()
-	// we append the mainSigners at the end here so that it signs last
+	/*
+		❗ Special case: if an account is both the payer and either a proposer or authorizer, it is only required to sign the envelope.
+	*/
+	// we append the payer at the end here so that it signs last
 	signers := t.PayloadSigners
-	if t.MainSigner != nil {
-		signers = append(signers, t.MainSigner)
+	if t.Payer != nil {
+		signers = append(signers, t.Payer)
 	}
 
 	var authorizers []flow.Address
 	for _, signer := range signers {
 		authorizers = append(authorizers, signer.Address())
 	}
-	if t.MainSigner == nil {
+
+	if t.Payer == nil {
 		signers = append(signers, t.Proposer)
 	}
 

script_integration_old_test.go

@@ -58,6 +58,7 @@ pub struct Report{
 				 }
 			 }
 
+	//👌 Inline Tx computation:?? loops:? statements:? invocations:? id:?
 			 pub fun main() : [Report] {
 				 return [Report(name:"name1", test: "test1"), Report(name:"name2", test: "test2")]
 			 }

state.go

@@ -229,6 +229,7 @@ func (f *OverflowState) CreateAccountsE() (*OverflowState, error) {
 			continue
 		}
 
+		f.Logger.Info(fmt.Sprintf("Creating account %s", account.Name()))
 		_, err := f.Services.Accounts.Create(
 			signerAccount,
 			[]crypto.PublicKey{account.Key().ToConfig().PrivateKey.PublicKey()},
@@ -451,7 +452,7 @@ func (o *OverflowState) BuildInteraction(filename string, interactionType string
 	}
 	ftb := &FlowInteractionBuilder{
 		Overflow:       o,
-		MainSigner:     nil,
+		Payer:          nil,
 		Arguments:      []cadence.Value{},
 		PayloadSigners: []*flowkit.Account{},
 		GasLimit:       uint64(o.Gas),

stop_on_failure_test.go

@@ -11,7 +11,7 @@ func TestPanicIfStopOnFailure(t *testing.T) {
 	assert.NoError(t, err)
 
 	t.Run("transaction", func(t *testing.T) {
-		assert.PanicsWithError(t, "💩 You need to set the main signer", func() {
+		assert.PanicsWithError(t, "💩 You need to set the proposer signer", func() {
 			o.Tx("create_nft_collection")
 		})
 	})

transaction_integration_old_test.go

@@ -18,15 +18,15 @@ func TestTransactionIntegrationLegacy(t *testing.T) {
 	t.Parallel()
 
 	t.Run("fail on missing signer with run method", func(t *testing.T) {
-		assert.PanicsWithError(t, "💩 You need to set the main signer", func() {
+		assert.PanicsWithError(t, "💩 You need to set the proposer signer", func() {
 			g.TransactionFromFile("create_nft_collection").Run()
 		})
 	})
 
 	t.Run("fail on missing signer", func(t *testing.T) {
 		g.TransactionFromFile("create_nft_collection").
-			Test(t).                                         //This method will return a TransactionResult that we can assert upon
-			AssertFailure("You need to set the main signer") //we assert that there is a failure
+			Test(t).                                             //This method will return a TransactionResult that we can assert upon
+			AssertFailure("You need to set the proposer signer") //we assert that there is a failure
 	})
 
 	t.Run("fail on wrong transaction name", func(t *testing.T) {

transaction_integration_test.go

@@ -16,7 +16,7 @@ func TestTransactionIntegration(t *testing.T) {
 	t.Parallel()
 
 	t.Run("fail on missing signer", func(t *testing.T) {
-		o.Tx("create_nft_collection").AssertFailure(t, "💩 You need to set the main signer")
+		o.Tx("create_nft_collection").AssertFailure(t, "💩 You need to set the proposer signer")
 	})
 
 	t.Run("fail on wrong transaction name", func(t *testing.T) {

transactions_old.go

@@ -22,7 +22,7 @@ func (o *OverflowState) TransactionFromFile(filename string) FlowInteractionBuil
 	return FlowInteractionBuilder{
 		Overflow:       o,
 		FileName:       filename,
-		MainSigner:     nil,
+		Payer:          nil,
 		Arguments:      []cadence.Value{},
 		PayloadSigners: []*flowkit.Account{},
 		GasLimit:       uint64(o.Gas),
@@ -38,7 +38,7 @@ func (o *OverflowState) Transaction(content string) FlowInteractionBuilder {
 		Overflow:       o,
 		FileName:       "inline",
 		Content:        content,
-		MainSigner:     nil,
+		Payer:          nil,
 		Arguments:      []cadence.Value{},
 		PayloadSigners: []*flowkit.Account{},
 		GasLimit:       uint64(o.Gas),
@@ -112,7 +112,7 @@ func (t FlowInteractionBuilder) SignProposeAndPayAs(signer string) FlowInteracti
 		return t
 	}
 	t.Proposer = account
-	t.MainSigner = account
+	t.Payer = account
 	return t
 }
 
@@ -123,7 +123,7 @@ func (t FlowInteractionBuilder) SignProposeAndPayAsService() FlowInteractionBuil
 	key := t.Overflow.ServiceAccountName()
 	//swallow error as you cannot start a overflow without a valid sa
 	account, _ := t.Overflow.State.Accounts().ByName(key)
-	t.MainSigner = account
+	t.Payer = account
 	t.Proposer = account
 	return t
 }