flixkit

README

FlixKit

FlixKit is a Go package that provides functionalities for interacting with Flow Interaction Templates (aka FLIX). Please note that this package is currently in alpha and may undergo significant changes.

The flixkit package is a Go module designed to interact with Flow Interaction Templates (FLIX). It allows users to fetch, parse, and handle Flow interaction templates.

Structures

The package provides a range of structs to represent data fetched from FLIX service:

• Network: Contains information about a specific network like address, contract and pin.
• Argument: Represents the arguments that can be given to the contracts.
• Title, Description: Used for i18n (internationalization) purposes in messages.
• Messages: Contains a title and a description.
• Data: Provides detailed information about the Flow interaction template like type, interface, messages, dependencies and arguments.
• FlowInteractionTemplate: The main struct that contains all the details of a flow interaction template.

The package also defines the following interfaces:

• FlixService: This interface defines methods to interact with the FLIX service such as fetching raw data or parsed data by template name or template ID.

Usage

The package provides a FlixService interface with a constructor function NewFlixService(config *Config). Config contains FlixServerURL which should be provided. If no URL is provided, it defaults to "https://flix.flow.com/v1/templates".

The FlixService interface provides the following methods:

• GetFlixRaw(ctx context.Context, templateName string) (string, error): Fetches a raw Flix template by its name.
• GetFlix(ctx context.Context, templateName string) (*FlowInteractionTemplate, error): Fetches and parses a Flix template by its name.
• GetFlixByIDRaw(ctx context.Context, templateID string) (string, error): Fetches a raw Flix template by its ID.
• GetFlixByID(ctx context.Context, templateID string) (*FlowInteractionTemplate, error): Fetches and parses a Flix template by its ID.

Each FlowInteractionTemplate instance also provides the following methods:

• IsScript() bool: Checks if the template is of type "script".
• IsTransaction() bool: Checks if the template is of type "transaction".
• GetAndReplaceCadenceImports(networkName string) (string, error): Replaces cadence import statements in the cadence script with their respective network addresses.

Examples

Here is a simple example of creating a new FlixService and fetching a template:

flixService := flixkit.NewFlixService(&flixkit.Config{})

template, err := flixService.GetFlix(context.Background(), "transfer-flow")
if err != nil {
    log.Fatal(err)
}

fmt.Println(template)

Note: Remember to replace "transfer-flow" with the actual name of the template you wish to fetch.

To read more about Flow Interaction Templates, see the docs.

Bindings

Binding files are code files that bind consuming code with FLIX. The bindings module in Flixkit generates code that calls the FLIX cadence code. FLIX cadence is primarily transactions and scripts.

Usage

The bindings module has two public methods Generate and NewFclJSGenerator. FclJSGenerator takes a template directory. bindings has fcl-js templates.

• NewFclJSGenerator() *FclJSGenerator // uses default fcl-js vanilla javascript
• Generate(flix *flixkit.FlowInteractionTemplate, templateLocation string, isLocal bool) (string, error) // flix is the hydrated template struct, templateLocation is the file location of the flix json file, isLocal is a flag that indicates if the template is local or on remote server

Example

// uses default fcl-js templates
fclJsGen := bindings.NewFclJSGenerator() 

output, err := fclJsGen.Generate(template, flixQuery, isLocal)
if err != nil {
    log.Fatal(err)
}

// output is the javascript binding code
fmt.Println(output])

Documentation

Index

• func FetchFlixWithContext(ctx context.Context, url string) (string, error)
• func GenerateFlixID(flix *FlowInteractionTemplate) (string, error)
• func ShaHex(value interface{}, debugKey string) string
• func SortMapKeys[T any](m map[string]T) []string
• type Argument
• type ArgumentKey
• type ArgumentKeys
• type Arguments
  • func (args Arguments) SortArguments() ArgumentKeys
• type Config
• type Contracts
• type Data
• type Dependencies
• type Description
• type FlixService
  • func NewFlixService(config *Config) FlixService
• type FlowInteractionTemplate
  • func ParseFlix(template string) (*FlowInteractionTemplate, error)
  • func (flix FlowInteractionTemplate) EncodeRLP() (result string, err error)
  • func (t *FlowInteractionTemplate) GetAndReplaceCadenceImports(networkName string) (string, error)
  • func (t *FlowInteractionTemplate) GetDescription() string
  • func (t *FlowInteractionTemplate) IsScript() bool
  • func (t *FlowInteractionTemplate) IsTransaction() bool
• type Generator
• type MapKeySorter
• type Messages
  • func (msgs *Messages) GetTitleValue(placeholder string) string
• type Network
• type Networks
• type Title

Functions

func FetchFlixWithContext

func FetchFlixWithContext(ctx context.Context, url string) (string, error)

func GenerateFlixID

func GenerateFlixID(flix *FlowInteractionTemplate) (string, error)

func ShaHex

func ShaHex(value interface{}, debugKey string) string

func SortMapKeys

func SortMapKeys[T any](m map[string]T) []string

Types

type Argument

type Argument struct {
	Index    int      `json:"index"`
	Type     string   `json:"type"`
	Messages Messages `json:"messages"`
	Balance  string   `json:"balance"`
}

type ArgumentKey

type ArgumentKey struct {
	Key string
	Argument
}

type ArgumentKeys

type ArgumentKeys []ArgumentKey

type Arguments

type Arguments map[string]Argument

func (Arguments) SortArguments

func (args Arguments) SortArguments() ArgumentKeys

type Config

type Config struct {
	FlixServerURL string
	FileReader    fs.ReadFileFS
}

type Contracts

type Contracts map[string]Networks

type Data

type Data struct {
	Type         string       `json:"type"`
	Interface    string       `json:"interface"`
	Messages     Messages     `json:"messages"`
	Cadence      string       `json:"cadence"`
	Dependencies Dependencies `json:"dependencies"`
	Arguments    Arguments    `json:"arguments"`
}

type Dependencies

type Dependencies map[string]Contracts

type Description

type Description struct {
	I18N map[string]string `json:"i18n"`
}

type FlixService

type FlixService interface {
	GetFlixRaw(ctx context.Context, templateName string) (string, error)
	GetFlix(ctx context.Context, templateName string) (*FlowInteractionTemplate, error)
	GetFlixByIDRaw(ctx context.Context, templateID string) (string, error)
	GetFlixByID(ctx context.Context, templateID string) (*FlowInteractionTemplate, error)
}

func NewFlixService

func NewFlixService(config *Config) FlixService

type FlowInteractionTemplate

type FlowInteractionTemplate struct {
	FType    string `json:"f_type"`
	FVersion string `json:"f_version"`
	ID       string `json:"id"`
	Data     Data   `json:"data"`
}

func ParseFlix

func ParseFlix(template string) (*FlowInteractionTemplate, error)

func (FlowInteractionTemplate) EncodeRLP

func (flix FlowInteractionTemplate) EncodeRLP() (result string, err error)

func (*FlowInteractionTemplate) GetAndReplaceCadenceImports

func (t *FlowInteractionTemplate) GetAndReplaceCadenceImports(networkName string) (string, error)

func (*FlowInteractionTemplate) GetDescription

func (t *FlowInteractionTemplate) GetDescription() string

func (*FlowInteractionTemplate) IsScript

func (t *FlowInteractionTemplate) IsScript() bool

func (*FlowInteractionTemplate) IsTransaction

func (t *FlowInteractionTemplate) IsTransaction() bool

type Generator

type Generator interface {
	Generate(ctx context.Context, code string, preFill *FlowInteractionTemplate) (*FlowInteractionTemplate, error)
}

type MapKeySorter

type MapKeySorter[T any] func(map[string]T) []string

type Messages

type Messages struct {
	Title       *Title       `json:"title,omitempty"`
	Description *Description `json:"description,omitempty"`
}

func (*Messages) GetTitleValue

func (msgs *Messages) GetTitleValue(placeholder string) string

type Network

type Network struct {
	Address        string `json:"address"`
	FqAddress      string `json:"fq_address"`
	Contract       string `json:"contract"`
	Pin            string `json:"pin"`
	PinBlockHeight uint64 `json:"pin_block_height"`
}

type Networks

type Networks map[string]Network

type Title

type Title struct {
	I18N map[string]string `json:"i18n"`
}