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.