Skip to main content

TS Binding

· 3 min read
Benoit Rognier
Guillaume Duhamel

We are glad to present the new contract binding generation in TypeScript language. We consider this as a major improvement in the way we are working with Archetype and Michelson contracts.

Completium CLI now provides a simple command to generate the TypeScript binding:

completium-cli generate binding-ts mycontract.arl > mycontract.ts

Contract binding refers here to a generated interface to interact with a contract (mainly call its entry points and retrieve data from its storage); this interface is expressed in a native language with native types (here TypeScript).

The main benefits are that it removes the burden of manipulating complex JSON structures of Micheline values; it also integrates well with IDE and, in the case of TypeScript, provides strong type checking at compilation time, rather than at execution time.

As a consequence, it drastically reduces the effort to write Tests and DApps.

First example

Consider the following Archetype contract:

archetype binding_example

variable msg : string = "Hello Binding World!"

entry exec(
l : list<int>,
r : rational,
o : or<nat, string>) {
/* … do something … */
}

The following code illustrates how to interact in TypeScript with this contract:

import { bind_example } from './binding/bind_example'
import { get_account } from '@completium/experiment-ts'
import { Int, Or, Rational } from '@completium/archetype-ts-types'

const alice = get_account(‘alice’)

await bind_example.deploy({ as : alice })

const msg = await bind_example.get_msg()

assert(msg == "Hello Binding World!")

await bind_example.exec(
[new Int(4), new Int(-6)],
new Rational(0.2),
Or.Right<Nat, string>("Hello exec!"),
{ as : alice }
)

Note that the msg storage element is retrieved with the dedicated get_msg method of automatically generated binding object bind_example.

The exec entry point is called with the method with same name. Its signature is fully specified with native TS types:

(method) bind_example.exec(l: Int[], r: Rational, o: Or<Nat, string>, p : Optional<Parameters>): Promise<CallResult>

The mapping from Archetype/Michelson types to TypeScript types is presented here.

Test framework

The Archetype test framework has been totally redesigned to integrate the binding feature seamlessly.

The commands below creates an Node.js project in the myproject directory and installs the required packages.

$ completium-cli create project myproject
$ cd ./myproject
$ npm install

The command below generates the bindings for contracts found in ./contracts directory:

$ npm run gen-binding

The test framework is presented in details here.

DApp

Binding is also available to integrate smart contracts in Dapps.

The command to generate the binding for integration in a DApp:

completium-cli generate binding-dapp-ts mycontract.arl > mycontract.ts

General considerations about DApp are presented here. An fully functional DApp example with source code is presented here.