zenroom

Use Zenroom in JavaScript

Zenroom js bindings 🧰 Zenroom js bindings provides a javascript wrapper of Zenroom, a secure and small virtual machine for crypto language processing.

💾 Install

yarn add zenroom
// or if you use npm
npm install zenroom

---

🎮 Usage

To start using the zenroom module just

const zenroom = require('zenroom')

or with ES6 syntax:

import zenroom from 'zenroom'

the zenroom javascript module is architectured as a Revealing Module Pattern this also means that once you set some options it will remain till the object lifetime, unless you reset or overwrite them.

Another used paradigm is method chaining this means that you can chain the different methods, let's see some hello worldish example:

import zenroom from 'zenroom'
// or without es6 syntax
// const zenroom = require('zenroom').default

const script = `print("hello world from zenroom in nodejs")`
zenroom.script(script).zenroom_exec()

// prints in the console.log "hello world from zenroom in nodejs"

To initialize the options there are two ways, the one with the chaining that we saw before or a handy init() method to make them in one shot

// method chaining
zenroom.script('print("hello world")')
       .success(() => { console.log('everything goes smooth') })
       .error(() => { console.error('something very bad happened') })
       .zenroom_exec()
       .reset() // cleans up the session

// using the init() method
options = {
	script: 'print("hello world")',
	success: () => { console.log('everything goes smooth') },
	error: () => { console.error('something very bad happened') }
}

zenroom.init(options).zenroom_exec()

All the available options and method are covered in the next API section

---

⚙️ API

script

First, you'll have create a script that Zenroom can execute. In this first section, we're covering Zenroom's scripts in Lua, if you want to execute smart contracts in Zencode (Zenroom's domain specific language), please see below.

This method set the zenroom lua or zencode to run.

The syntax of the Zenroom Lua scripts is documented at https://dev.zenroom.org/ You may want also to look at some example in a live executable environment at: https://dev.zenroom.org/demo

Parameters

• script string the lua script to be set

Examples

Example usage of script()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = 'print("hello")'
zenroom.script(script).zenroom_exec().reset()

Returns zenroom as zenroom module

keys

Set the parameter "keys" in JSON for the script/smart contract you're executing in Zenroom.

The keys will be available in the execution of the script/smart contract as the KEYS variable.

Parameters

• keys object the keys to be set as an object

Examples

Example usage of keys()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = `
                 keys = JSON.decode(KEYS)
                 print(keys)
`

const keys = {a: 1, b: 2}
zenroom.script(script).keys(keys).zenroom_exec().reset()

Returns object as zenroom module

data

Set the parameter "data" in JSON for the script/smart contract you're executing in Zenroom.

The data will be available in the execution of the script/smart contract as the DATA variable.

Parameters

• data string

Examples

Example usage of data()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = `
                 data = JSON.decode(DATA)
                 print(data)
`

const data = {a: 1, b: 2}
zenroom.script(script).data(data).zenroom_exec()

Returns object as zenroom module

conf

Set the configuration of zenroom execution.

The possible configurations are available [here](https://github.com/DECODEproject/Zenroom/blob/master/src/zen_config.c #L104-L111)

Parameters

• conf string the string of configuration to be set

Examples

Example usage of conf()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = 'print("hello")'
const conf = 'debug=1,memwipe=0'
zenroom.script(script).conf(conf).zenroom_exec()

Returns object as zenroom module

print_err

Set the print_err callback: customize the behaviour of the print_err calls made to stderr,by default it prints to the console.error

Type: Function

Examples

Example usage of print_err()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const savedLines = []
const print_err_fn = (text) => { savedLines.push(text) }
const script = 'print("hello")'
zenroom.print_err(print_err_fn).script(script).zenroom_exec()

Returns object as zenroom module

print

Set the print callback: customize * the behavior of the print calls made to stdout,by default it prints to the console.log

Type: Function

Examples

Example usage of print()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const savedLines = []
const printFunction = (text) => { savedLines.push(text) }
const script = 'print("hello")'
zenroom.print(printFunction).script(script).zenroom_exec()

Returns object as zenroom module

success

Set the success callback that is executed after a successful execution of Zenroom

Type: Function

Examples

Example usage of success()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = 'print("hello")'
zenroom.script(script).success(()=>{
   pleaseRunSomeOtherMethodAfter()
}).zenroom_exec()

Returns object as zenroom module

error

Set the "error callback" that is executed after an unsuccessful execution of Zenroom

Type: Function

Examples

Example usage of error()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = 'print("hello")';
zenroom.script(script).error(()=>{
   pleaseRunSomeOtherMethodAfterError()
}).zenroom_exec()

Returns object as zenroom module

zenroom_exec

Starts the Zenroom VM, using the parameters previously set.

This is usually the last method of the chain. Just like the other methods, it returns the zenroom module itself, so it can be used for other calls if you need to run more executions in a row.

Examples

Example usage of zenroom_exec()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = 'print("hello")';
zenroom.script(script).zenroom_exec()

Returns object as zenroom module

zencode_exec

Execute Zencode smart contracts, using the previously setted options.

This is usually the last method of the chain. Just like the other methods, it returns the zenroom module itself, so it can be used for other calls if you need to run more executions in a row.

Examples

Example usage of zencode_exec()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const zencode = 'print("hello")';
zenroom.script(script).zencode_exec()

Returns object as zenroom module

init

This method allows the configuration of your call by passing one configuration option object. You can chain methods after this anyway.

If some attribute is already set, those will be overwritten by the new options.

The following options are available:

• script
• keys
• conf
• data
• print
• print_err
• success
• error

Parameters

• options

Examples

Example usage of init()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const encrypt_secret_to_many = {
 script: `keyring = ECDH.new()
           secret = str(DATA)
           keys = JSON.decode(KEYS)
           keyring:private( base64(keys.keyring.secret) )
           res = {}
           for name,pubkey in pairs(keys.recipients) do
             pub = base64(pubkey)
             enc = ECDH.encrypt(keyring,pub,secret,keyring:public())
             res[name] = str( MSG.pack( map(enc,base64) ) ):base64()
           end
           print(JSON.encode(res))`,

 keys: {
     keyring : {
       public : "BHMjcDM/aljpi8pNxFQ436R6F3J+kaB/Xk1kAVFPmkoLVyeFltDZPgiIYRquh+m2IfvPioBfet7YCd5vVXYoRTk=",
       secret : "ChW5qi5y//ISDIHKx5Fvxl+XY8IyDGVBHUfELp3PqJQ="
     },
     recipients : {
       paulus : "BBUw6Nr3A30cN65maERvAk1cEv2Ji6Vs80kSlpodOC0SCtM8ucaS7e+s158uVMSr3BsvIXVspBeafiL8Qb3kcgc=",
       mayo : "BHqBoQ2WJ3/FGVNTXzdIc+K/HzNx05bWzEhn8m58FvSsaqWVdH52jI6fQWdkdjnbqVKCJGmbjA/OCJ+IKHbiySI=",
       mark : "BFgkjrRMvN+wkJ6qA4UvMaNlYBvl37C9cNYGkqOE4w43AUzkEzcyIIdE6BrgOEUEVefhOOnO6SCBQMgXHXJUUPY=",
       francesca : "BCo102mVybieKMyhex8tnVtFM5+Wo1oP02k8JVwKF9OLIjw7w0LmofItbuAcfWl9rcoe++XLI3sySZnqljIfeyU=",
       jim : "BEs1jeqL0nVwFi7OmG4YdtlWuKADyOvZR4XHpLAEswg8ONPXQHvwJ8+PkHkphoORfSjk2045bMdYkwboU4FdG2Y=",
       jaromil : "BBZYJtHvFg0vGCxPROAWrThcGZ+vFZJj86k+uncjvbm4DysIg7cWS3J6GrcJKCY55Uf40m2KfBwfaT+T7TTO1e8="
     }
 },

 data: 'This is a secret message.'
}


zenroom.init(encrypt_secret_to_many).zenroom_exec()

Returns object as zenroom module

reset

Reset the options previously set, and cleans up the zenroom module.

This is can easily be the last method of the chain. Just like the other methods, it returns the zenroom module itself, so it can be used for other calls if you need to run more executions in a row.

Examples

Example usage of reset()

// returns zenroom
import zenroom from 'zenroom'
// or without ES6 syntax
// const zenroom = require('zenroom')

const script = 'print("hello")';
zenroom.script(script)
       .zenroom_exec()    // This runs the script
       .reset()
       .zenroom_exec()    // This does not run the script anymore

Returns object as zenroom module

😍 Acknowledgements

Copyright (C) 2018 by Dyne.org foundation, Amsterdam

Designed, written and maintained by Puria Nafisi Azizi.

This project is receiving funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement nr. 732546 (DECODE).

---

👤 Contributing

Please first take a look at the Dyne.org - Contributor License Agreement then

1. FORK IT
2. Create your feature branch git checkout -b feature/branch
3. Commit your changes git commit -am 'Add some fooBar'
4. Push to the branch git push origin feature/branch
5. Create a new Pull Request
6. Thank you

---

💼 License

  Zenroom javascript - a javascript wrapper of zenroom
  Copyright (c) 2020 Dyne.org foundation, Amsterdam

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU Affero General Public License as
  published by the Free Software Foundation, either version 3 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.