When you entrust your money to a smart contract, you want to be absolutely sure that the contract operates as you expect (remember TheDAO?). One way to achieve this is by having a smart contract language that is designed to express what the contract expects, rather than how it accomplishes its goals. This is exactly what declarative languages do.

The purpose of this post is to introduce the declarative smart contract language I chose for Byteball, the cryptocurrency I recently launched. The language is designed to be as easy to understand as possible, so that even non-developer can immediately see what a contract means by just looking at its code. The language values clarity over power and it is not as powerful as Ethereum's Solidity. It is not turing-complete, and you cannot write even 'Hello world' program in this language. But it is able to solve many practical business tasks.

Money in Byteball are stored on addresses. Address is just a hash (plus checksum) of an address definition, and the address definition is an expression in the Byteball smart contract language that evaluates to either true or false.

Here is an example of the simplest address definition that defines an address controlled by a single private key:

["sig",{"pubkey":"Ald9tkgiUZQQ1djpZgv2ez7xf1ZvYAsTLhudhvn0931w"}]

The pubkey above is base64-encoded public key. The expression evaluates to true if the signature provided with the transaction is valid and produced by the private key that corresponds to the above public key. The address (checksummed hash in base32) corresponding to this definition is A2WWHN7755YZVMXCBLMFWRSLKSZJN3FU.

All expressions in this language evaluate to a boolean value, and multiple boolean subexpressions can be combined using boolean operators. For example, this is a definition that requires two signatures:

["and", [

["sig", {pubkey: "one pubkey in base64"}], ["sig", {pubkey: "another pubkey in base64"}]

]]

To spend funds from the address equal to the hash of the above definition, one would need to provide two signatures.

As you noticed, we use JSON to construct the language expressions. This is an unusual choice but allows to use existing well-debugged, well-supported, and well-optimized JSON parsers rather than invent our own.

"Or" condition can be used to require signatures by any one of the listed public keys:

["or", [

["sig", {pubkey: "laptop pubkey"}], ["sig", {pubkey: "smartphone pubkey"}], ["sig", {pubkey: "tablet pubkey"}]

]]

The above is useful when you want to control the same address from any of the 3 devices: your laptop, your phone, and your tablet.

The conditions can be nested:

["and", [

["or", [ ["sig", {pubkey: "laptop pubkey"}], ["sig", {pubkey: "tablet pubkey"}] ]], ["sig", {pubkey: "smartphone pubkey"}]

]]

A definition can require a minimum number of conditions to be true out of a larger set, for example, a 2-of-3 signature:

["r of set", {

required: 2, set: [ ["sig", {pubkey: "laptop pubkey"}], ["sig", {pubkey: "smartphone pubkey"}], ["sig", {pubkey: "tablet pubkey"}] ]

}]

("r" stands for "required") which features both the security of two mandatory signatures and the reliability, so that in case one of the keys is lost, the address is still usable and can be used to change its definition and replace the lost 3rd key with a new one.

Also, different conditions can be given different weights, of which a minimum is required:

["weighted and", {

required: 50, set: [ {weight: 40, value: ["sig", {pubkey: "CEO pubkey"}] }, {weight: 20, value: ["sig", {pubkey: "COO pubkey"}] }, {weight: 20, value: ["sig", {pubkey: "CFO pubkey"}] }, {weight: 20, value: ["sig", {pubkey: "CTO pubkey"}] } ]

}]

A definition can contain reference to another address:

["and", [

["address", "ADDRESS 1 IN BASE32"], ["address", "ADDRESS 2 IN BASE32"]

]]

which delegates signing to another address and is useful for building shared control addresses (addresses controlled by several users). This syntax gives the users the flexibility to change definitions of their own component addresses whenever they like, without bothering the other user.

A subdefinition may require that the transaction be cosigned by another address:

["cosigned by", "ANOTHER ADDRESS IN BASE32"]

One very useful condition can be used to make queries about data previously stored in Byteball:

["in data feed", [

["ADDRESS1", "ADDRESS2", …], "data feed name", "=", "expected value"

]]

This condition evaluates to true if there is at least one previous message stored in Byteball database that has "data feed name" equal to "expected value". The data feed must be posted to Byteball decentralized database by one of the oracles whose addresses are "ADDRESS1", "ADDRESS2", ... Since oracles post to the common database, we call them on-chain oracles.

On-chain oracles are a very powerful thing indeed. For example, this address definition represents a binary option:

["or", [

["and", [ ["address", "ADDRESS 1"], ["in data feed", [["EXCHANGE ADDRESS"], "EURUSD", ">", "1.1500"]] ]], ["and", [ ["address", "ADDRESS 2"], ["in data feed", [["TIMESTAMPER ADDRESS"], "datetime", ">", "2016-10-01 00:00:00"]] ]]

]]

It relies on two oracles, one is posting EUR/USD exchange rate, the other is posting the current time. Initially, the two parties fund the address defined by this definition by sending their respective stakes to the address. Then if the EUR/USD exchange rate published by the exchange address ever exceeds 1.1500, the first party can sweep the funds. If this doesn’t happen before Oct 1, 2016 and the timestamping oracle posts any later date, the second party can sweep all the funds stored on this address.

Another example would be a customer who buys goods from a merchant but he doesn’t quite trust that merchant and wants his money back in case the goods are not delivered. The customer pays to a shared address defined by:

["or", [

["and", [ ["address", "MERCHANT ADDRESS"], ["in data feed", [["FEDEX ADDRESS"], "tracking", "=", "123456"]] ]], ["and", [ ["address", "BUYER ADDRESS"], ["in data feed", [["TIMESTAMPER ADDRESS"], "datetime", ">", "2016-10-01 00:00:00"]] ]]

]]

The definition depends on the FedEx oracle that posts tracking numbers of all successfully delivered shipments. If the shipment is delivered, the merchant will be able to unlock the money using the first condition. If it is not delivered before the specified date, the customer can take his money back. This example is somewhat crazy because it requires FedEx to post each and every shipment. See the white paper for a more practical way to achieve the same result.

A definition can also include queries about the transaction itself, which can be used for example to code limit orders on a decentralized exchange. Assume that a user wants to buy 1,200 units of some asset for which he is willing to pay no more than 1,000 bytes (the native currency of Byteball). Also, he is not willing to stay online all the time while he is waiting for a seller. He would rather just post an order at an exchange and let it execute when a matching seller comes along. He can create a limit order by sending 1,000 bytes to an address defined by this definition:

["or", [

["address", "USER ADDRESS"], ["and", [ ["address", "EXCHANGE ADDRESS"], ["has", { what: "output", asset: "ID of alternative asset", amount_at_least: 1200, address: "USER ADDRESS" }] ]]

]]

The first or-alternative lets the user take back his bytes whenever he likes, thus cancelling the order. The second alternative delegates the exchange the right to spend the funds, provided that another output on the same transaction pays at least 1,200 units of the other asset to the user’s address. The exchange would publicly list the order, a seller would find it, compose a transaction that exchanges assets, and sign it together with the exchange. Note that the exchange does not receive arbitrary control over the user's funds, it can spend them only if it simultaneously pays the alternative asset to the user, while the user retains full control over his funds and can withdraw them from the contract when he likes.

You can combine the above and a few other boolean constructs (see the white paper) to encode many of the clauses you are likely to see in real-life legal contracts. And the language is clear, straightforward, and it directly expresses the intent of the contract parties.

This language is already used in Byteball, you can view the source code and create tools that make use of the language.

/*jslint node: true */
"use strict";

var conf = require('byteballcore/conf.js');
var db = require('byteballcore/db.js');
var eventBus = require('byteballcore/event_bus.js');
var headlessWallet = require('headless-byteball');
var desktopApp = require('byteballcore/desktop_app.js');
var objectHash = require('byteballcore/object_hash.js');
var notifications = require('./notifications.js');
var ValidationUtils = require("byteballcore/validation_utils.js");
var my_address;
var wallet_id;

var feedname;
var feedvalue;
var paired_device_address;
var state = '';
var welcometext = "";

welcometext += "コマンド\n"; welcometext += "[スマートコントラクト作成](command:contract)\n";

if (conf.bRunWitness)

require('byteball-witness');

const RETRY_TIMEOUT = 5 * 60 * 1000;
var assocQueuedDataFeeds = {};

const WITNESSING_COST = 600; // size of typical witnessing unit
var count_witnessings_available = 0;

if (!conf.bSingleAddress)

throw Error('oracle must be single address');

if (!conf.bRunWitness)

headlessWallet.setupChatEventHandlers();

function readNumberOfWitnessingsAvailable(handleNumber) {

count_witnessings_available--; if (count_witnessings_available > conf.MIN_AVAILABLE_WITNESSINGS) return handleNumber(count_witnessings_available); db.query( "SELECT COUNT(*) AS count_big_outputs FROM outputs JOIN units USING(unit) \n\ WHERE address=? AND is_stable=1 AND amount>=? AND asset IS NULL AND is_spent=0", [my_address, WITNESSING_COST], function(rows) { var count_big_outputs = rows[0].count_big_outputs; db.query( "SELECT SUM(amount) AS total FROM outputs JOIN units USING(unit) \n\ WHERE address=? AND is_stable=1 AND amount<? AND asset IS NULL AND is_spent=0 \n\ UNION \n\ SELECT SUM(amount) AS total FROM witnessing_outputs \n\ WHERE address=? AND is_spent=0 \n\ UNION \n\ SELECT SUM(amount) AS total FROM headers_commission_outputs \n\ WHERE address=? AND is_spent=0", [my_address, WITNESSING_COST, my_address, my_address], function(rows) { var total = rows.reduce(function(prev, row) { return (prev + row.total); }, 0); var count_witnessings_paid_by_small_outputs_and_commissions = Math.round(total / WITNESSING_COST); count_witnessings_available = count_big_outputs + count_witnessings_paid_by_small_outputs_and_commissions; handleNumber(count_witnessings_available); } ); } );

}


function createOptimalOutputs(handleOutputs) {

var arrOutputs = [{ amount: 0, address: my_address }]; readNumberOfWitnessingsAvailable(function(count) { if (count > conf.MIN_AVAILABLE_WITNESSINGS) return handleOutputs(arrOutputs); // try to split the biggest output in two db.query( "SELECT amount FROM outputs JOIN units USING(unit) \n\ WHERE address=? AND is_stable=1 AND amount>=? AND asset IS NULL AND is_spent=0 \n\ ORDER BY amount DESC LIMIT 1", [my_address, 2 * WITNESSING_COST], function(rows) { if (rows.length === 0) { notifications.notifyAdminAboutPostingProblem('only ' + count + " spendable outputs left, and can't add more"); return handleOutputs(arrOutputs); } var amount = rows[0].amount; // notifications.notifyAdminAboutPostingProblem('only '+count+" spendable outputs left, will split an output of "+amount); arrOutputs.push({ amount: Math.round(amount / 2), address: my_address }); console.log(arrOutputs); handleOutputs(arrOutputs); } ); });

}



function postDataFeed(datafeed, onDone) {

function onError(err) { notifications.notifyAdminAboutFailedPosting(err); onDone(err); } var network = require('byteballcore/network.js'); var composer = require('byteballcore/composer.js'); createOptimalOutputs(function(arrOutputs) { let params = { paying_addresses: [my_address], outputs: arrOutputs, signer: headlessWallet.signer, callbacks: composer.getSavingCallbacks({ ifNotEnoughFunds: onError, ifError: onError, ifOk: function(objJoint) { network.broadcastJoint(objJoint); onDone(); } }) }; if (conf.bPostTimestamp) datafeed.timestamp = Date.now();

let objMessage = { app: "data_feed", payload_location: "inline", payload_hash: objectHash.getBase64Hash(datafeed), payload: datafeed }; params.messages = [objMessage]; composer.composeJoint(params); });

}

function reliablyPostDataFeed(datafeed) {

var feed_name, feed_value; for (var key in datafeed) { feed_name = key; feed_value = datafeed[key]; break; } if (!feed_name) throw Error('no feed name'); if (assocQueuedDataFeeds[feed_name]) // already queued return console.log(feed_name + " already queued"); assocQueuedDataFeeds[feed_name] = feed_value; var onDataFeedResult = function(err) { if (err) { console.log('will retry posting the data feed later'); setTimeout(function() { postDataFeed(datafeed, onDataFeedResult); }, RETRY_TIMEOUT + Math.round(Math.random() * 3000)); } else delete assocQueuedDataFeeds[feed_name]; }; postDataFeed(datafeed, onDataFeedResult);

}


function readExistingData(feed_name, handleResult) {

if (assocQueuedDataFeeds[feed_name]) { return handleResult(true, 0, assocQueuedDataFeeds[feed_name]); } db.query( "SELECT feed_name, is_stable, value \n\ FROM data_feeds CROSS JOIN unit_authors USING(unit) CROSS JOIN units USING(unit) \n\ WHERE address=? AND feed_name=?", [my_address, feed_name], function(rows) { if (rows.length === 0) return handleResult(false); if (rows.length > 1) notifications.notifyAdmin(rows.length + ' entries for feed', feed_name); return handleResult(true, rows[0].is_stable, rows[0].value); } );

}

function handleText(from_address, text, onUnknown){ text = text.trim(); var fields = text.split(/ /); var command = fields[0].trim().toLowerCase(); var params =[,]; if (fields.length > 1) params[0] = fields[1].trim(); if (fields.length > 2) params[1] = fields[2].trim();

var walletDefinedByKeys = require('byteballcore/wallet_defined_by_keys.js'); var device = require('byteballcore/device.js');

//状態に応じた処理＊コマンドで分けきれない細かい状態の管理＊ switch(state){ case 'contract': state = ''; text = text.trim(); if (text.match(/unrecognized/i)) return console.log("ignoring: "+text); var arrMatches = text.match(/\b[A-Z2-7]{32}\b/); if (!arrMatches) device.sendMessageToDevice(from_address, 'text', "Unrecognized"); var address = arrMatches[0]; if (!ValidationUtils.isValidAddress(address)){ device.sendMessageToDevice(from_address, 'text', "Please send a valid address.有効なアドレスを入力してください"); } else{ var arrDefinition = ['or', [ ['and', [ ['address',address],//useraddress ['in data feed', [['I2ADHGP4HL6J37NQAD73J7E5SKFIXJOT'], 'timestamp', '>', Date.now()]] //I2ADHGP4HL6J37NQAD73J7E5SKFIXJOTはタイムスタンプオラクルのアドレスです。 ] ], ['and', [ ['address', my_address],//myaddress ['in data feed', [['I2ADHGP4HL6J37NQAD73J7E5SKFIXJOT'], 'timestamp', '>', Date.now()]] ] ] ]]; } var device = require('byteballcore/device.js'); var assocSignersByPath = { 'r.0.0': { address:address,//user_address member_signing_path: 'r', // unused, should be always 'r' device_address: from_address //user device address }, 'r.1.0': { address: my_address,//my_address member_signing_path: 'r', // unused, should be always 'r' device_address: device.getMyDeviceAddress() } }; var walletDefinedByAddresses = require('byteballcore/wallet_defined_by_addresses.js'); walletDefinedByAddresses.createNewSharedAddress(arrDefinition, assocSignersByPath, { ifError: function(err){ // handle error device.sendMessageToDevice(from_address, 'text', 'contract create error:'+err); }, ifOk: function(shared_address){ device.sendMessageToDevice(from_address, 'text', "A Smart Contract was created. \ nYou can check the contents by clicking the link below.\nスマートコントラクトが作成されました。\n下記のリンクをクリックで内容を確認できます。"); // new sharer address created //1000は相手に要求する支払額。任意の値に変更可能 var arrPayments = [{address: shared_address, amount: 1000, asset: 'base'}]; var assocDefinitions = {}; assocDefinitions[shared_address] = { definition: arrDefinition, signers: assocSignersByPath }; var objPaymentRequest = {payments: arrPayments, definitions: assocDefinitions}; var paymentJson = JSON.stringify(objPaymentRequest); var paymentJsonBase64 = Buffer(paymentJson).toString('base64'); var paymentRequestCode = 'payment:'+paymentJsonBase64; var paymentRequestText = '[your share of payment to the contract]('+paymentRequestCode+')'; device.sendMessageToDevice(from_address, 'text', paymentRequestText); } }); return; }

//コマンド処理 switch(command){ case 'help': device.sendMessageToDevice(from_address, 'text',welcometext); break; case 'address': state = 'menu'; device.sendMessageToDevice(from_address, 'text',my_address); break; case 'contract': state = 'contract'; device.sendMessageToDevice(from_address, 'text', "Please enter your wallet address.\nあなたのウォレットアドレスを入力してください(Insert my addressで簡単に入力できます)"); break; default: if (onUnknown){ onUnknown(from_address, text); }else{ device.sendMessageToDevice(from_address, 'text', "unrecognized command"); } } }

eventBus.on('text', function(from_address, text){

console.log('text from '+from_address+': '+text);

handleText(from_address, text); }); eventBus.on('headless_wallet_ready', function() { headlessWallet.readSingleAddress(function(address) { my_address = address; //device.getMyDeviceAddress() }); });

eventBus.on('paired', function(from_address){ var device = require('byteballcore/device.js'); console.log('paired '+from_address); device.sendMessageToDevice(from_address, 'text',welcometext); });