ces

README

CES Go Parser

ces-go-parser parses contract-level events that follow the Casper Event Standard.

The library is built on top of the casper-go-sdk and operates on types defined by the SDK.

Install

go get github.com/make-software/ces-go-parser

Usage

Here is an example of parsing CES events using ces-go-parser from a real Testnet deploy loaded with casper-go-sdk:

package main

import (
  "context"
  "fmt"
  "net/http"

  "github.com/make-software/casper-go-sdk/casper"

  "github.com/make-software/ces-go-parser"
)

func main() {
  testnetNodeAddress := "<put testnet node address here>"
  rpcClient := casper.NewRPCClient(casper.NewRPCHandler(testnetNodeAddress, http.DefaultClient))

  ctx := context.Background()
  deployResult, err := rpcClient.GetDeploy(ctx, "19ee17d9e3b4c1527b433598e647b69aa9a153864eb12433489f99224bfc9442")
  if err != nil {
    panic(err)
  }

  contractHash, err := casper.NewHash("e7062b42c9a22002fa3cd216debd605b7056ad180efb3c99555676f1a1e801e5")
  if err != nil {
    panic(err)
  }

  parser, err := ces.NewParser(rpcClient, []casper.Hash{contractHash})
  if err != nil {
    panic(err)
  }

  parseResults, err := parser.ParseExecutionResults(deployResult.ExecutionResults[0].Result)
  if err != nil {
    panic(err)
  }
  for _, result := range parseResults {
    if result.Error != nil {
      panic(err)
    }
    fmt.Println(result.Event)
  }
}

API

Go CES Parser provides several public types and functions:

• Parser
  • NewParser
  • Parser.ParseExecutionResults
  • Parser.FetchContractSchemasBytes
• NewSchemasFromBytes
• EventData
• Event
  • ParseEventNameAndData
• ParseResult
• Schemas
• SchemaData

Parser

Parser that accepts a list of observed contracts and provides possibility to parse CES events out of deploy execution results

NewParser

NewParser constructor that accepts casper-go-sdk client:

Argument	Type	Description
casperRPCClient	casper.RPCClient	Instance of the casper-go-sdk RPC client
contracts	[]casper.Hash	List of the observed contract hashes

Example

package main

import (
	"net/http"

	"github.com/make-software/casper-go-sdk/casper"

	"github.com/make-software/ces-go-parser"
)

func main() {
	rpcClient := casper.NewRPCClient(casper.NewRPCHandler("http://localhost:11101/rpc", http.DefaultClient))
	contractHash, err := casper.NewHash("e7062b42c9a22002fa3cd216debd605b7056ad180efb3c99555676f1a1e801e5")
	if err != nil {
		panic(err)
	}

	parser, err := ces.NewParser(rpcClient, []casper.Hash{contractHash})
	if err != nil {
		panic(err)
	}
	_ = parser
}

ParseExecutionResults

ParseExecutionResults method that accepts deploy execution results and returns []ces.ParseResult:

Argument	Type	Description
executionResults	casper.ExecutionResults	Deploy execution results provided as the corresponding type from casper-go-sdk

FetchContractSchemasBytes

FetchContractSchemasBytes method that accepts contract hash and return bytes representation of stored schema:

Argument	Type	Description
contractHash	casper.Hash	Contract hash schema want to be fetched

NewSchemasFromBytes

NewSchemasFromBytes constructor that accepts raw CES schema bytes stored under the contract __events_schema URef and returns ces.Schemas:

Argument	Type	Description
rawSchemas	[]byte	Raw contract schemas bytes

ParseEventNameAndData

Function that accepts raw event bytes and contract event schemas and returns ParseResult:

Argument	Type	Description
event	string	Raw event bytes in hex
schemas	ces.Schemas	The list of contract schemas

Example

schemas, err := ces.NewSchemasFromBytes(rawSchemas)
rawEvent  := BytesFromString("some real example here")

eventData, err := ces.ParseEvent(rawEvent, schemas)

EventData

Value-object that represents an event data:

Property	Type	Description
Name	string	Event name
Data	map[string]casper.CLValue	Event Data

Event

Value-object that represents an event:

Property	Type	Description
Name	string	Event Name
EventData	ces.EventData	EventData
ContractHash	casper.Hash	Event ContractHash
ContractPackageHash	casper.Hash	Event ContractPackageHash

ParseResult

Value-object that represents a parse result. Contains error representing weather parsing was successful or not.

Property	Type	Description
Error	error	Parse result error
Event	ces.Event	ces Event

SchemaData

SchemaData is - value-object that represents an schema item.

Property	Type	Description
ParamName	string	Name of the param
ParamType	casper.CLType	casper CLType

Schemas

Schemas represent a map of event name and list of SchemaData.

Tests

To run unit tests for the library, make sure you are in the root of the library:

go test ./...

Documentation

Index

• Variables
• func ParseEventDataFromSchemaBytes(schemas []SchemaData, buf *bytes.Buffer) (map[EventName]casper.CLValue, error)
• type ContractMetadata
  • func LoadContractMetadataWithoutSchema(contractResult casper.Contract) (ContractMetadata, error)
• type Event
• type EventMetadata
  • func ParseEventMetadataFromTransform(transform casper.TransformKey) (EventMetadata, error)
• type EventName
  • func ParseEventNameAndData(eventHex string, schemas Schemas) (EventName, map[string]casper.CLValue, error)
• type EventParser
  • func NewParser(casperClient casper.RPCClient, contractHashes []casper.Hash) (*EventParser, error)
  • func (p *EventParser) FetchContractSchemasBytes(contractHash casper.Hash) ([]byte, error)
  • func (p *EventParser) ParseExecutionResults(executionResult casper.ExecutionResult) ([]ParseResult, error)
• type ParseResult
• type SchemaData
  • func (t *SchemaData) MarshalJSON() ([]byte, error)
  • func (t *SchemaData) UnmarshalJSON(data []byte) error
• type Schemas
  • func LoadContractEventSchemas(casperClient casper.RPCClient, stateRootHash string, ...) (Schemas, error)
  • func NewSchemasFromBytes(rawSchemas []byte) (Schemas, error)
  • func (t *Schemas) Scan(value interface{}) error
  • func (t Schemas) Value() (driver.Value, error)

Variables

var (
	ErrFailedDeploy                     = errors.New("error: failed deploy, expected successful deploys")
	ErrEventNameNotInSchema             = errors.New("error: event name not found in Schema")
	ErrFailedToParseContractEventSchema = errors.New("error: failed to parse contract event Schema")
	ErrExpectContractStoredValue        = errors.New("error: expect contract stored value")
	ErrExpectCLValueStoredValue         = errors.New("error: expect clValue stored value")
	ErrMissingRequiredNamedKey          = errors.New("error: missing required named key")
	ErrNoEventPrefixInEvent             = errors.New("error: no event_ prefix in event")
	ErrNilDictionaryInTransform         = errors.New("error: nil dictionary in transform")
)

var ErrInvalidSchemaFormat = errors.New("invalid schema format")

Functions

func ParseEventDataFromSchemaBytes

func ParseEventDataFromSchemaBytes(schemas []SchemaData, buf *bytes.Buffer) (map[EventName]casper.CLValue, error)

Types

type ContractMetadata

type ContractMetadata struct {
	Schemas             Schemas
	ContractHash        casper.Hash
	ContractPackageHash casper.Hash
	EventsSchemaURef    casper.Uref
	EventsURef          casper.Uref
}

func LoadContractMetadataWithoutSchema

func LoadContractMetadataWithoutSchema(contractResult casper.Contract) (ContractMetadata, error)

type Event

type Event struct {
	ContractHash        casper.Hash
	ContractPackageHash casper.Hash
	Data                map[string]casper.CLValue
	Name                string
}

type EventMetadata

type EventMetadata struct {
	Name    string
	Uref    casper.Uref
	Payload *bytes.Buffer
}

func ParseEventMetadataFromTransform

func ParseEventMetadataFromTransform(transform casper.TransformKey) (EventMetadata, error)

type EventName

type EventName = string

func ParseEventNameAndData

func ParseEventNameAndData(eventHex string, schemas Schemas) (EventName, map[string]casper.CLValue, error)

ParseEventNameAndData parse provided rawEvent according to event schema, return EventName and EventData

type EventParser

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

func NewParser

func NewParser(casperClient casper.RPCClient, contractHashes []casper.Hash) (*EventParser, error)

func (*EventParser) FetchContractSchemasBytes

func (p *EventParser) FetchContractSchemasBytes(contractHash casper.Hash) ([]byte, error)

FetchContractSchemasBytes accept contract hash to fetch stored contract schema

func (*EventParser) ParseExecutionResults

func (p *EventParser) ParseExecutionResults(executionResult casper.ExecutionResult) ([]ParseResult, error)

ParseExecutionResults accept casper.ExecutionResult analyze its transforms and trying to parse events according to stored contract schema

type ParseResult

type ParseResult struct {
	Error error
	Event Event
}

type SchemaData

type SchemaData struct {
	ParamName string
	ParamType cltype.CLType
}

func (*SchemaData) MarshalJSON

func (t *SchemaData) MarshalJSON() ([]byte, error)

func (*SchemaData) UnmarshalJSON

func (t *SchemaData) UnmarshalJSON(data []byte) error

type Schemas

type Schemas map[EventName][]SchemaData

func LoadContractEventSchemas

func LoadContractEventSchemas(casperClient casper.RPCClient, stateRootHash string, eventSchemaUref casper.Uref) (Schemas, error)

func NewSchemasFromBytes

func NewSchemasFromBytes(rawSchemas []byte) (Schemas, error)

func (*Schemas) Scan

func (t *Schemas) Scan(value interface{}) error

Scan rewrite behaviour for selecting Hash from db

func (Schemas) Value

func (t Schemas) Value() (driver.Value, error)