@completium/event-well-crank
TypeScript icon, indicating that this package has built-in type declarations

0.0.7 • Public • Published

Event Well Crank

@completium/event-well-crank detects events emitted by smart contracts on the Tezos blockchain, and executes registered event handler functions.

API

register

Registers an event handler for a specific contract. It takes 3 arguments:

  • the address of the emitter contract
  • the function to create an event from its packed version
  • the event handler function that takes 2 arguments:
    • the emitted event
    • the event data (optional)

The function to create the event may be automatically generated (see Bindings below).

The event data provides information about the emitted event:

  • date
  • block hash
  • operation hash
  • source of the event (account address at the source of the event emission)

startCrank

Starts the crank process. It takes an optional CrankOptions object with optional fields:

Field Type Default Desc
bottom string head~4 block hash to start crawling from
delay number 2000 number of milliseconds between two lookups of the event well contract
horizon number 3 number of blocks to look back (the higher, the higher the probability to read the main branch)
endpoint string https://mainnet.api.tez.ie endpoint used by the event crank
well string (see below) address of the event well contract
verbose boolean false flag to turn crank's verbose mode on/off

The well contract is deployed on mainnet and testnets:

Network Well address
mainnet KT1AHVF5m8XaWPQCGgfAsZ9eSJJZ7WVGV2hE
ithacanet KT1ReVgfaUqHzWWiNRfPXQxf7TaBLVbxrztw
hangzhounet KT1Aho6K97CKApDSCxXEzvP14qd1qTHhF4uH

stopCrank

Stops the crank.

Bindings

@completium/completium-cli generates the TS bindings from an Archetype contract. It generates for each event emitted by a contract:

  • the event type
  • the make event function
  • the dedicated register function (calls register function with generated make function), which takes 2 arguments:
    • the address of the emitter contract
    • the event handler function

The completium CLI command to generate the bindings:

$ completium-cli generate bindings-ts mycontract.arl > mycontract-bindings.ts

Example

This example illustrates how to emit event from a smart contract and how to receive them in a Dapp.

Emit event

Declare the event type with the event declaration and emit an event with the emit instruction:

archetype event_demo

event TestEvent {
  val: string
}

entry emit_event(v : string) {
  if length(v) > 20 then
    emit<TestEvent>({ val })
}

Deploy the contract on the testnet with the following command:

$ completium-cli set endpoint https://ithacanet.ecadinfra.com
$ completium-cli deploy event_demo.arl

Receive event

Generate bindings with the following command:

$ completium-cli generate bindings-ts event_demo > bindings-event_demo.ts

It generates the following two elements:

  • EventDemo
  • register_TestEvent

These elements may be used to implement the event receiver application which registers an event handler and starts the cranks. Say the event demo contract deployed above is at address KT19EAMugKU416cbA9jL1XcukWArfpv4dLYA

import { runCrank } from '@completium/event-well-crank';
import { register_TestEvent, TestEvent } from './bindings-event_demo';

const handleTestEvent = (e : TestEvent) => {
  console.log(`Test Event received with value "${e.val}"!`);
}

const run = async () => {
  register_TestEvent('KT19EAMugKU416cbA9jL1XcukWArfpv4dLYA', handleTestEvent);
  runCrank({
    endpoint: 'https://ithacanet.ecadinfra.com',
    well: 'KT1ReVgfaUqHzWWiNRfPXQxf7TaBLVbxrztw'
  })
}

await run()

Execute

Compile and run the application above. Then call the contract with the following command:

$ completium-cli call event_demo --arg `{ "v" : "This is a long enough string." }`

After a few blocks generation, the application prints the following message:

Test Event received with value "This is a long enough string."!

Dependencies (5)

Dev Dependencies (3)

Package Sidebar

Install

npm i @completium/event-well-crank

Weekly Downloads

2

Version

0.0.7

License

MIT

Unpacked Size

26.8 kB

Total Files

18

Last publish

Collaborators

  • guillaumeedukera
  • benoitedukera