debug

README

Remote Debugger

Remote debugger provides utils needed to run transactions and scripts against live network data. It uses GRPC endpoints on an execution nodes to fetch registers and block info when running a transaction. This is mostly provided for debugging purpose and should not be used for production level operations. If you use the caching method you can run the transaction once and use the cached values to run transaction in debugging mode.

sample code

package debug_test

import (
	"fmt"
	"os"
	"testing"

	"github.com/rs/zerolog"
	"github.com/stretchr/testify/require"

	"github.com/onflow/flow-go/model/flow"
	"github.com/onflow/flow-go/utils/debug"
)

func TestDebugger_RunTransaction(t *testing.T) {

	grpcAddress := "localhost:3600"
	chain := flow.Emulator.Chain()
	debugger := debug.NewRemoteDebugger(grpcAddress, chain, zerolog.New(os.Stdout).With().Logger())

	const scriptTemplate = `
	import FlowServiceAccount from 0x%s
	transaction() {
		prepare(signer: AuthAccount) {
			log(signer.balance)
		}
	  }
	`

	script := []byte(fmt.Sprintf(scriptTemplate, chain.ServiceAddress()))
	txBody := flow.NewTransactionBody().
		SetGasLimit(9999).
		SetScript([]byte(script)).
		SetPayer(chain.ServiceAddress()).
		SetProposalKey(chain.ServiceAddress(), 0, 0)
	txBody.Authorizers = []flow.Address{chain.ServiceAddress()}

	// Run at the latest blockID
	txErr, err := debugger.RunTransaction(txBody)
	require.NoError(t, txErr)
	require.NoError(t, err)

	// Run with blockID (use the file cache)
	blockId, err := flow.HexStringToIdentifier("3a8281395e2c1aaa3b8643d148594b19e2acb477611a8e0cab8a55c46c40b563")
	require.NoError(t, err)
	txErr, err = debugger.RunTransactionAtBlockID(txBody, blockId, "")
	require.NoError(t, txErr)
	require.NoError(t, err)

	testCacheFile := "test.cache"
	defer os.Remove(testCacheFile)
	// the first run would cache the results
	txErr, err = debugger.RunTransactionAtBlockID(txBody, blockId, testCacheFile)
	require.NoError(t, txErr)
	require.NoError(t, err)

	// second one should only use the cache
	// make blockId invalid so if it endsup looking up by id it should fail
	blockId = flow.Identifier{}
	txErr, err = debugger.RunTransactionAtBlockID(txBody, blockId, testCacheFile)
	require.NoError(t, txErr)
	require.NoError(t, err)
}

Documentation

Index

• func GetHeapAllocsBytes() uint64
• type RemoteDebugger
  • func NewRemoteDebugger(grpcAddress string, chain flow.Chain, logger zerolog.Logger) *RemoteDebugger
  • func (d *RemoteDebugger) RunScript(code []byte, arguments [][]byte) (value cadence.Value, scriptError error, processError error)
  • func (d *RemoteDebugger) RunScriptAtBlockID(code []byte, arguments [][]byte, blockID flow.Identifier) (value cadence.Value, scriptError error, processError error)
  • func (d *RemoteDebugger) RunTransaction(txBody *flow.TransactionBody) (txErr error, processError error)
  • func (d *RemoteDebugger) RunTransactionAtBlockID(txBody *flow.TransactionBody, blockID flow.Identifier, regCachePath string) (txErr error, processError error)
• type RemoteStorageSnapshot
  • func NewRemoteStorageSnapshot(grpcAddress string, opts ...RemoteStorageSnapshotOption) *RemoteStorageSnapshot
  • func (snapshot *RemoteStorageSnapshot) Close() error
  • func (snapshot *RemoteStorageSnapshot) Get(id flow.RegisterID) (flow.RegisterValue, error)
• type RemoteStorageSnapshotOption
  • func WithBlockID(blockID flow.Identifier) RemoteStorageSnapshotOption
  • func WithCache(cache registerCache) RemoteStorageSnapshotOption

Functions

func GetHeapAllocsBytes

func GetHeapAllocsBytes() uint64

GetHeapAllocsBytes returns the value of /gc/heap/allocs:bytes.

Types

type RemoteDebugger

type RemoteDebugger struct {
	// contains filtered or unexported fields
}

func NewRemoteDebugger

func NewRemoteDebugger(grpcAddress string,
	chain flow.Chain,
	logger zerolog.Logger) *RemoteDebugger

Warning : make sure you use the proper flow-go version, same version as the network you are collecting registers from, otherwise the execution might differ from the way runs on the network

func (*RemoteDebugger) RunScript

func (d *RemoteDebugger) RunScript(
	code []byte,
	arguments [][]byte,
) (
	value cadence.Value,
	scriptError error,
	processError error,
)

func (*RemoteDebugger) RunScriptAtBlockID

func (d *RemoteDebugger) RunScriptAtBlockID(
	code []byte,
	arguments [][]byte,
	blockID flow.Identifier,
) (
	value cadence.Value,
	scriptError error,
	processError error,
)

func (*RemoteDebugger) RunTransaction

func (d *RemoteDebugger) RunTransaction(
	txBody *flow.TransactionBody,
) (
	txErr error,
	processError error,
)

RunTransaction runs the transaction given the latest sealed block data

func (*RemoteDebugger) RunTransactionAtBlockID

func (d *RemoteDebugger) RunTransactionAtBlockID(
	txBody *flow.TransactionBody,
	blockID flow.Identifier,
	regCachePath string,
) (
	txErr error,
	processError error,
)

RunTransaction runs the transaction and tries to collect the registers at the given blockID note that it would be very likely that block is far in the past and you can't find the trie to read the registers from. if regCachePath is empty, the register values won't be cached

type RemoteStorageSnapshot

type RemoteStorageSnapshot struct {
	Cache       registerCache
	BlockID     []byte
	BlockHeader *flow.Header
	// contains filtered or unexported fields
}

RemoteStorageSnapshot provides a storage snapshot connected to a live execution node to read the registers.

func NewRemoteStorageSnapshot

func NewRemoteStorageSnapshot(
	grpcAddress string,
	opts ...RemoteStorageSnapshotOption,
) *RemoteStorageSnapshot

func (*RemoteStorageSnapshot) Close

func (snapshot *RemoteStorageSnapshot) Close() error

func (*RemoteStorageSnapshot) Get

func (snapshot *RemoteStorageSnapshot) Get(
	id flow.RegisterID,
) (
	flow.RegisterValue,
	error,
)

type RemoteStorageSnapshotOption

type RemoteStorageSnapshotOption func(*RemoteStorageSnapshot) *RemoteStorageSnapshot

A RemoteStorageSnapshotOption sets a configuration parameter for the remote snapshot

func WithBlockID

func WithBlockID(blockID flow.Identifier) RemoteStorageSnapshotOption

WithBlockID sets the blockID for the remote snapshot, if not used remote snapshot will use the latest sealed block

func WithCache

func WithCache(cache registerCache) RemoteStorageSnapshotOption

WithFileCache sets the output path to store register values so can be fetched from a file cache it loads the values from the cache upon object construction