git clone https://github.com/xJeneKx/Tutorial-2-source
cd Tutorial-2-source
npm install

If you run project you will see a blog with articles. After opening any article you will see a request to log in. Let’s create an authorization. First we need a pairing code, you could see it on startup

Copy it and change our code a bit

pairingCode = 'Aly99HdWoCFaxJiIHs1ldREAN/sMDhGsRHNQ2RYU9gCj@byteball.org/bb#' + code;

eventBus.on('paired', (from_address, pairing_secret) => {
  console.error('paired', from_address, pairing_secret);
});

Run and see the link. Сlick on it and bot will be added. Now let’s look at the console.

Add the link

b = '<br>Please login using this pairing code: <a href="obyte:' + pairingCode + '">' + pairingCode + '</a>';

And QR

let dataURL = await QRCode.toDataURL("obyte:" + pairingCode);
b = '<br>Please login using this pairing code: <a href="obyte:' + pairingCode + '">' + pairingCode + '</a><br><img src="' + dataURL + '">';

Save our device address, we will need it later.

eventBus.on('paired', (from_address, pairing_secret) => {
  let device = require('ocore/device');
  assocCodeToDeviceAddress[pairing_secret] = from_address;
  device.sendMessageToDevice(from_address, 'text', 'ok');
});

Now we need to tell the browser that we are logged in To implement this, we add function in start.js

async function amILogged(ctx) {
  let url = ctx.request.url;
  let match = url.match(/code=([0-9]+)/);
  if (match && assocCodeToDeviceAddress[match[1]]) {
     ctx.cookies.set('ac', match[1]);
     ctx.body = 'true';
  } else {
     ctx.body = 'false';
  }
}

And also one more routing

app.use(mount('/amilogged', amILogged));

In article.html we will add a request to check

var step = '<%= step %>';
var code = '<%= code %>';
if (step === 'login') {
  setInterval(() => {
     fetch('/amilogged?code=' + code)
        .then((response) => {
           return response.text();
        }).then(result => {
        if (result === 'true') {
           location.reload(true);
        }
     })
        .catch(alert);
  }, 5000);
}

What’s going on here? The user scans the QR code, adds our bot. Bot associates code with his device_address. In the browser, we knock and ask: did we logged in? and adding cookies.

Now we need to create an address and associate it with the user and the article. Add a variable

let assocCodeAndNumberToAddress = {};

Add the address and display it

step = 'paid';
let address = await getAssocAddress(assocCode, 1);
let dataURL = await QRCode.toDataURL("obyte:" + address + '?amount=100');
b = '<br>Please pay for the article. <br>Address: ' + address + '<br>Amount: 100<br><img src="' + dataURL + '"><br>' +
  '<a href="obyte:' + address + '?amount=100">Pay</a>';

And finally the function getAssocAddress

function getAssocAddress(assocCode, number) {
  return new Promise(resolve => {
     let name = assocCode + '_' + number;
     if (assocCodeAndNumberToAddress[name]) {
        return resolve(assocCodeAndNumberToAddress[name]);
     } else {
        headlessWallet.issueNextMainAddress(address => {
           assocCodeAndNumberToAddress[name] = address;
           return resolve(address);
        });
     }
  });
}

This time we will not wait for the stabilization of the unit and immediately open access. Add a variable

let assocCodeToPaid = {};

Add a check that the user has paid for

async function amIPaid(ctx) {
  let code = ctx.cookies.get('ac');
  ctx.body = (code && itPaid(code)) ? 'true' : 'false';
}

function itPaid(code) {
  return !!assocCodeToPaid[code];
}

Add a routing

app.use(mount('/amipaid', amIPaid));

And payment processing

eventBus.on('new_my_transactions', (arrUnits) => {
  const device = require('ocore/device.js');
  db.query("SELECT address, amount, asset FROM outputs WHERE unit IN (?)", [arrUnits], rows => {
     rows.forEach(row => {
        if (row.amount === 100 && row.asset === null) {
           for (let key in assocCodeAndNumberToAddress) {
              if (assocCodeAndNumberToAddress[key] === row.address) {
                 let assocCode = key.split('_')[0];
                 assocCodeToPaid[assocCode] = true;
                 device.sendMessageToDevice(assocCodeToDeviceAddress[assocCode], 'text', 'I received your payment');
                 return;
              }
           }
        }
     })
  });
});

Authentication

These clauses authenticate the author(s) of the unit.

sig

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 sig 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.

hash

This clause evaluates to true if the author supplies a preimage of the hash specified in the address definition.

["hash", {"hash": "value of sha256 hash in base64"}]

Logical operators

These clauses allow to combine other conditions with logical operators.

and, or

All expressions in this language evaluate to a boolean value, and multiple boolean subexpressions can be combined using boolean operators and and or. 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"}]
]]

r of set

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, or to move the funds to another address.

weighted and

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"}] }
    ]
}]

not

Subsequent conditions can be negated with not clause:

["not", ["in data feed", [["NOAA ADDRESS"], "wind_speed", ">", "200"]]]

Since it is legal to select very old parents (that didn’t see the newer data feed posts), one usually combines negative conditions such as the above with the requirement that the timestamp is after a certain date.

sig, hash, address, cosigned by, and in merkle cannot be negated.

References

These clauses redirect the evaluation of the subdefinition to something else.

address

A definition can contain reference to another address using address clause:

["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 in contracts). This syntax gives the users the flexibility to change definitions of their own component addresses whenever they like, without bothering the other user.

definition template

A definition can reference a definition template:

["definition template", [
    "hash of unit where the template was defined",
    {param1: "value1", param2: "value2"}
]]

The parameters specify values of variables to be replaced in the template. The template needs to be saved before (and as usual, be stable before use) with a special message type app=“definition_template”, the template itself is in message payload, and the template looks like normal definition but may include references to variables in the syntax @param1, @param2. Definition templates enable code reuse. They may in turn reference other templates.

Extrospection

These clauses inspect data outside of the current unit.

in data feed

in data feed clause can be used to make queries about data previously stored on Obyte:

["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 Obyte database that has “data feed name” equal to “expected value”. Instead of =, you can also use >, <, >=, <=, or != The data feed must be posted to Obyte 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.2500"]]
    ]],
    ["and", [
        ["address", "ADDRESS 2"],
        ["timestamp", [">", Math.round(Date.now()/1000 + timeout_seconds)]]
    ]]
]]

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.2500, the first party can sweep the funds. If this doesn’t happen before timeout period, 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"],
        ["timestamp", [">", Math.round(Date.now()/1000 + timeout_seconds)]]
    ]]
]]

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 timeout period, the customer can take his money back. This example is somewhat crazy because it requires FedEx to post each and every shipment. See in merkle clause below for a more practical way to achieve the same result.

in merkle

in merkle is a more economical way to query the presence of a particular data entry in a large data set. Instead of posting every data entry in a data_feed message, only the merkle root of the large data set is posted as a data_feed, and the signer has to provide the data entry and its merkle path:

["in merkle", [
    ["ADDRESS1", "ADDRESS2", ...],
    "data feed name",
    "expected value"
]]

seen address

["seen address", "ANOTHER ADDRESS IN BASE32"]

This clause evaluates to true if the specified address was seen as author in at least one past unit included in the last stable unit.

seen

["seen", {
    what: "output",
    address: "ADDRESS",
    asset: "asset or base",
    amount: 12345
}]

This clause evaluates to true if there was an input or output in the past (before last stable unit) that satisfies the specified condition. The syntax for the search condition is the same as for has clause below.

seen definition change

["seen definition change", ["ADDRESS", "NEW DEFINITION CHASH"] ]

This clause evaluates to true if there was a definition change of the specified address and the c-hash (checksummed hash) of the new definition is equal to the specified value.

age

["age", [">", 1234]]

This clause evaluates to true if the age of all inputs spent from this address satisfies the specified condition. The age is the difference between last ball mci and the input’s mci.

attested

["attested", ["ADDRESS", ["ATTESTOR1", "ATTESTOR2", ...]]]

This clause evaluates to true if the specified address is attested by one of the listed attestors. The address can also be “this address”.

Introspection

These clauses inspect data within the current unit

cosigned by

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

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

has, has one

A definition can also include queries about the transaction itself, which can be used for example to code limit orders on a trustless 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 Obyte). 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, which makes use of has clause:

["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.

The has clause evaluates to true if the transaction has at least one input or output that satisfies all the set conditions:

• what: input or output, required

• asset: ID of asset (44-character string) or base for bytes

• type: for inputs only, transfer or issue. If specified, it searches only transfers or only issues

• amount_at_least, amount_at_most, amount: amount must be at least, at most, or exactly equal to the specified value

• address: address where the output is sent to or the input is spent from, can be literal address or “this address” or “other address”

Similar clause has one has exactly the same syntax but evaluates to true if there is exactly one input or output that satisfies the search conditions.

has equal, has one equal

The following requirement can also be included in a subdefinition:

["has equal", {
    equal_fields: ["address", "amount"],
    search_criteria: [
        {what: "output", asset: "asset1", address: "ADDRESS IN BASE32"},
        {what: "input", asset: "asset2", type: "issue", address: "ANOTHER ADDRESS IN BASE32"}
    ]
}]

It evaluates to true if there is at least one pair of inputs or outputs that satisfy the search criteria and the fields specified in equal_fields are equal. The first element of the pair is searched by the first set of filters, the second by the second, and the syntax for the search conditions is the same as in has clause.

A similar condition has one equal requires that there is exactly one such pair.

sum

This clause evaluates to true if the sum of inputs or outputs that satisfy the filter is equal, at least, or at most the target value.

["sum", {
    filter: {
        what: "input"|"output", asset: "asset or base", type: "transfer"|"issue",
        address: "ADDRESS IN BASE32"
    },
    at_least: 120,
    at_most: 130,
    equals: 123
}]

The syntax for the filter is the same as for has clause.

has definition change

["has definition change", ["ADDRESS", "NEW DEFINITION CHASH"] ]

This clause evaluates to true if the unit has a definition change of the specified address and the c-hash (checksummed hash) of the new definition is equal to the specified value.

mci

["mci", ">", 123456]

This clause evaluates to true if last_ball_mci of the current unit is greater than (other possible comparisons: >=, <, <=, =) than the specified value. It can be useful to make the address spendable only after some point in the future and not rely on any timestamp oracles.

timestamp

['timestamp', ['>', Math.round(Date.now() / 1000 + 2 * 3600)]]

This clause evaluates to true If the time is longer than the specified time. You can also use "=", "<", ">=", "<=", "!=". This example returns true 2 hours after the deployment.

Hi, everybody. Today we will create our own oracle. To do this, we need a bot-example. Let’s install it.

git clone https://github.com/byteball/bot-example
cd bot-example
npm install
cp .env.testnet .env

Our oracle will accept a message like City: timestamp, where timestamp is the time to publish. Let’s write a message handler

headlessWallet.readSingleAddress(address => {
  my_address = address;
  console.error('my_address', address)
});

eventBus.on('text', (from_address, text) => {
  text = text.trim();
  const device = require('ocore/device.js');
  const args = text.toLowerCase().split(':');
  if (args.length === 2){
     switch (args[0]) {
        case 'berlin':
        case 'moscow':
        case 'helsinki':
        case 'washington':
           if(parseInt(args[1]) <= Date.now()){
              console.error('dateNow', Date.now());
              device.sendMessageToDevice(from_address, 'text', "Incorrect time");
           }else {
              arrQueue.push({city: args[0], time: args[1], device_address: from_address});
              device.sendMessageToDevice(from_address, 'text', "ok");
           }
           break;
        default:
           device.sendMessageToDevice(from_address, 'text', "City not support");
           break;
     }
  }else {
     device.sendMessageToDevice(from_address, 'text', "Incorrect command");
  }
});

Add a variable to store the queue

let arrQueue = [];

Now add to the queue

if(parseInt(args[1]) <= Date.now()){
  device.sendMessageToDevice(from_address, 'text', "Incorrect time");
}else {
  arrQueue.push({city: args[0], time: args[1], device_address: from_address});
  device.sendMessageToDevice(from_address, 'text', "ok");
}

Now we need to check the queue once a minute

function checkQueue(){
  arrQueue.forEach((el, index) => {
     if(el.time <= Date.now()){
        let result = JSON.parse(body);
        postDataFeed(el.city, el.time, result.current.temp_c);
     }
  });
}
setTimeout(checkQueue, 60000);

Now we come to the main point. We need to publish data_feed

function postDataFeed(city, time, temp){
  const network = require('ocore/network.js');
  const composer = require('ocore/composer.js');

  let data_feed = {};
  data_feed[city + '_' + time] = temp;
  let params = {
     paying_addresses: [my_address],
     outputs: [{address: my_address, amount: 0}],
     signer: headlessWallet.signer,
     callbacks: composer.getSavingCallbacks({
        ifNotEnoughFunds: console.error,
        ifError: console.error,
        ifOk: function(objJoint){
           network.broadcastJoint(objJoint);
        }
     })
  };
  let objMessage = {
     app: "data_feed",
     payload_location: "inline",
     payload: data_feed
  };
  params.messages = [objMessage];
  composer.composeJoint(params);
}

What is happening?

1) We create an object in data_feed and keep the temperature in it.

let data_feed = {};
data_feed[city + '_' + time] = temp;

2) We send the payment to ourselves as we only need to publish data_feed

paying_addresses: [my_address],
outputs: [{address: my_address, amount: 0}]

3) Create a message with data and signature

let objMessage = {
     app: "data_feed",
     payload_location: "inline",
     payload: data_feed
  };

4) Publish

composer.composeJoint(params);

Requesting payments

When you include a valid Obyte address anywhere in the text of your response to the user, the address will be automatically highlighted in the user's chat window, and after clicking it the user will be able to pay arbitrary amount of arbitrary asset to this address.

When you want to request a specific amount of a specific asset, format your payment request this way:

Any text before [payment description, will be ignored](obyte:ACCOUNT_ADDRESS?amount=123000&asset=base) any text after

Amount is in the smallest units, such as bytes. If you omit &asset=... part, base asset (bytes) is assumed. If you want to request payment in another asset, indicate its identifier such as oj8yEksX9Ubq7lLc+p6F2uyHUuynugeVq4+ikT67X6E= for blackbytes (don't forget to url-encode it).

You will likely want to generate a unique payment address per user, per transaction. This code sample might help:

var headlessWallet = require('headless-obyte');

eventBus.once('headless_wallet_ready', () => {

    eventBus.on('text', function(from_address, text) {
        const device = require('ocore/device.js');
        
        if (text === 'resend') {
            headlessWallet.issueNextMainAddress((deposit_address) => {
                // send it over to the user
                device.sendMessageToDevice(from_address, 'text',
                    '[...](obyte:'+ deposit_address +'?amount=123000&asset=base)');
                });
            });
        }
    });
});

Payments from single address wallet

It is possible to request that the payment would be done from any single address wallet or specific single address wallet. This works only in chat messages.

[...](obyte:ACCOUNT_ADDRESS?amount=1&single_address=1)
[...](obyte:ACCOUNT_ADDRESS?amount=1&single_address=1&from_address=UEPO3OD2TUUJUOECVMKVSRHRDJ4ST2FS)

Requesting multiple payments

To request the user to pay multiple payments at once, create the below Javascript object objPaymentRequest which can contain multiple addresses and multiple assets, encode the object in base64, and send it over to the user:

var payments = [
    {address: address1, amount: amount1, asset: asset1},
    {address: address1, amount: amount2, asset: asset2},
    {address: address2, amount: amount3, asset: asset1}
];
var objPaymentRequest = {payments};
var paymentJson = JSON.stringify(objPaymentRequest);
var paymentJsonBase64 = Buffer.from(paymentJson).toString('base64');
var paymentRequestCode = 'payment:'+paymentJsonBase64;
var paymentRequestText = '[...]('+paymentRequestCode+')';

device.sendMessageToDevice(from_address, 'text', paymentRequestText);

The user's wallet will parse this message, display the multiple payments in a user-readable form, and offer the user to pay the requested amounts. Your payment-waiting code will be called when the payment is seen on the DAG.

Waiting for payments

If you include a headless wallet

var headlessWallet = require('headless-obyte');

you can get notified when any of your addresses receives a payment

eventBus.on('new_my_transactions', function(arrUnits){
	// fetch more data about my addresses
	db.query("SELECT outputs.address, amount, asset FROM outputs \
			JOIN my_addresses USING (address) \
			WHERE unit IN(?);", [arrUnits], (rows) => {
		if (rows.length === 0) return;
		rows.forEach((row) => {
		    // react to each unconfirmed payment
		});
	});
});

arrUnits is an array of units (more accurately, unit hashes) that contained any transaction involving your addresses. The event new_my_transactions is triggered for outgoing transactions too, you should check if the new transaction credits one of the addresses you are expecting payments to.

Waiting for finality of payments

To get notified when any of your transactions become stable (confirmed), subscribe to my_transactions_became_stable event:

eventBus.on('my_transactions_became_stable', function(arrUnits){
	// fetch more data about my addresses
	db.query("SELECT outputs.address, amount, asset FROM outputs \
			JOIN my_addresses USING (address) \
			WHERE unit IN(?);", [arrUnits], (rows) => {
		if (rows.length === 0) return;
		rows.forEach((row) => {
		    // react to each confirmed payment
		});
	});
});

arrUnits is again the array of units that just became stable and they contained at least one transaction involving your addresses.

The above events work in both full and light nodes. If your node is full, you can alternatively subscribe to event mci_became_stable which is emitted each time a new main chain index (MCI) becomes stable:

eventBus.on('mci_became_stable', function(mci){
    // check if there are any units you are interested in 
    // that had this MCI and react to their becoming stable
});

Sending payments from chat bot

To send payments, you need to include a headless wallet

var headlessWallet = require('headless-obyte');

and use this function after the headless wallet becomes ready:

eventBus.once('headless_wallet_ready', () => {
    headlessWallet.issueChangeAddressAndSendPayment(asset, amount, account_address, from_address, (err, unit) => {
        if (err){
            // something went wrong, maybe put this payment on a retry queue
            return;
        }
        // handle successful payment
    });
});

asset is the asset you are paying in (null for bytes), amount is payment amount in the smallest units. If the payment was successful, you get its unit in the callback and can save it or watch further events on this unit.

Textcoin is a payment sent though email or other text based media, such as chat apps. Textcoins can also be printed on paper, scratch cards, or PIN envelopes and passed on like paper wallets.

Sending textcoins with bot

Sending textcoins from server-side (headless) wallets is easy: you use the same functions you normally use to send to Obyte addresses but instead of the recipient's Obyte address you write:

• textcoin:userEmailAddress for sending to email, or

• textcoin:someUniqueIdentifierOtherThanEmail for sending via any other text based media

Examples: textcoin:pandanation@wwfus.org or textcoin:ASDFGHJKL.

Sample code:

var headlessWallet = require('headless-obyte');

let opts = {
    asset: null, 
    amount: 1000, // bytes
    to_address: "textcoin:pandanation@wwfus.org",
    email_subject: "Payment in textcoin"
};

headlessWallet.issueChangeAddressAndSendMultiPayment(opts, (err, unit, assocMnemonics) => {
    ....
});

Sending textcoin emails

• from_email: the address your emails are sent from. Must be on your domain, otherwise the emails are likely to be non-delivered or labeled as spam

• smtpTransport: type of SMTP transport used to deliver emails:

  • local: (this is the default) use /usr/sbin/sendmail

  • direct: connect directly to the recipient's MX server, this minimizes the number of intermediaries who are able to see and potentially steal the textcoin, but this method is not reliable as there are no retries

  • relay: send through a relay server. In this case, you need to also set its host name in smtpRelay. If it requires authentication, you need to also set smtpUser and smtpPassword.

Callback response

The callback of issueChangeAddressAndSendMultiPayment and all similar functions has an optional 3rd parameter assocMnemonics which is an associative array of all generated textcoins (BIP39 mnemonics) indexed by the address from the input parameters.

{
    "textcoin:pandanation@wwfus.org": "barely-album-remove-version-endorse-vocal-weasel-kitten-when-fit-elbow-crop"
}

All the keys of the array have a textcoin: prefix, like in input parameters.

If you are sending though any media other than email, you use assocMnemonics to find mnemonics generated for each output address (in the example above, you would find it by the key textcoin:ASDFGHJKL) and then deliver them yourself.

For example, if you are writing a Telegram bot that rewards users for certain actions, you create a clickable link by prefixing the mnemonic with https://obyte.org/#textcoin?:

https://obyte.org/#textcoin?barely-album-remove-version-endorse-vocal-weasel-kitten-when-fit-elbow-crop

and send it in chat.

More resources

Hello, everybody. Today we will learn how to create our first contract. We will do this on the example of a bot that accepts a bet on the weather.

git clone https://github.com/byteball/bot-example
cd bot-example
npm install
cp .env.testnet .env

First, let’s create variables.

const request = require('request');
const correspondents = require('./correspondents');

let steps = {}; // store user steps
let assocDeviceAddressToCurrentCityAndTemp = {}; 
let assocDeviceAddressToAddress = {};
let bets = [];
let KEY_API = '50ace22603c84daba1780432180111'; // apixu.com
let my_address;

Save our address for use in the contract

headlessWallet.readSingleWallet(walletId => {
  db.query("SELECT address FROM my_addresses WHERE wallet=?", [walletId], function (rows) {
     if (rows.length === 0)
        throw Error("no addresses");
     my_address = rows[0].address;
  });
});

Let’s add a text handler and analyze what happens:

eventBus.on('text', (from_address, text) => {
     text = text.trim().toLowerCase();
     if (!steps[from_address]) steps[from_address] = 'start';
     let step = steps[from_address];
     const device = require('ocore/device.js');
     if (validationUtils.isValidAddress(text.toUpperCase())) { // If address sent to us - save it.
        assocDeviceAddressToAddress[from_address] = text.toUpperCase();
        return device.sendMessageToDevice(from_address, 'text', 'I saved your address. Send me the name of the city');
     } else if (!assocDeviceAddressToAddress[from_address]) { // If we do not know the address - asking it to send for us.
        return device.sendMessageToDevice(from_address, 'text', 'Please send me your byteball address(... > Insert my address)');
     } else if (step === 'city' && (text === 'more' || text === 'less')) { // Create a contract and ask to pay for it
        let time = Date.now() + 20 * 60 * 1000;
        let name = assocDeviceAddressToCurrentCityAndTemp[from_address].city + '_' + time;
        let operator = text === 'more' ? '>=' : '<=';
        let value = assocDeviceAddressToCurrentCityAndTemp[from_address].temp;
        createContract(my_address, assocDeviceAddressToAddress[from_address], 2001, 2000, from_address, name, operator, value, time,
           (err, paymentRequestText, shared_address, timeout) => {
              if (err) throw err;
              findOracleAndSendMessage(assocDeviceAddressToCurrentCityAndTemp[from_address].city + ':' + time, () => {
                 bets.push({
                    myAmount: 2001,
                    peerAmount: 2000,
                    myAddress: my_address,
                    peerAddress: assocDeviceAddressToAddress[from_address],
                    sharedAddress: shared_address,
                    peerDeviceAddress: from_address,
                    name,
                    operator,
                    value,
                    timeout
                 });
                 device.sendMessageToDevice(from_address, 'text', paymentRequestText);
                 setTimeout(() => { // If the payment was not made for 10 minutes-we take the money
                    headlessWallet.sendAllBytesFromAddress(shared_address, my_address, from_address, (err, unit) => {
                       if (!err) console.error('unit:: ', unit);
                    });
                 }, 15 * 60 * 1000);
              });
           });
     } else if (step === 'start') { // Check the weather and specify what rate the user wants to make
        switch (text) {
           case 'berlin':
           case 'moscow':
           case 'helsinki':
           case 'washington':
              request('https://api.apixu.com/v1/current.json?key=' + KEY_API + '&q=' + text, function (error, response, body) {
                 if (error) {
                    console.error(error);
                    device.sendMessageToDevice(from_address, 'text', 'An error occurred. Try again later.');
                 } else {
                    let result = JSON.parse(body);
                    let temp = result.current.temp_c;
                    device.sendMessageToDevice(from_address, 'text', 'Want to bet that in an hour the weather in ' + text + ' will be\n[more ' + temp + 'c](command:more) or [less ' + temp + 'c](command:less)?');
                    steps[from_address] = 'city';
                    assocDeviceAddressToCurrentCityAndTemp[from_address] = {city: text, temp};
                 }
              });
              break;
           default:
              device.sendMessageToDevice(from_address, 'text', "City not support");
              break;
        }
     } else {
        device.sendMessageToDevice(from_address, 'text', "unknown command");
     }
  });
});

Now let’s talk about contract creation. We need a separate function

function createContract(myAddress, peerAddress, myAmount, peerAmount, peerDeviceAddress, name, operator, value, time, cb) {
  const device = require('ocore/device');
  let timeout = Date.now() + 10 * 60 * 1000;
  let inverseOperator = operator === '>=' ? '<' : '>';
  let arrSeenConditionPeer = ['seen', {
     what: 'output',
     address: 'this address',
     asset: 'base',
     amount: peerAmount
  }];
  let arrSeenConditionMyInput = ['seen', {
     what: 'input',
     address: 'this address',
     asset: 'base'
  }];
  let arrDefinition = ['or', [
     ['or', [
        ['and', [
           ['address', peerAddress],
           arrSeenConditionPeer,
           arrSeenConditionMyInput
        ]],
        ['or', [
           ['and', [
              ['address', peerAddress],
              ['in data feed', [[conf.oracle_address], name, operator, value]],
           ]],
           ['and', [
              ['address', myAddress],
              ['in data feed', [[conf.oracle_address], name, inverseOperator, value]]
           ]]
        ]],
     ]],
     ['and', [
        ['address', myAddress],
        ['not', arrSeenConditionPeer],
        ['in data feed', [[conf.TIMESTAMPER_ADDRESS], 'timestamp', '>', timeout]]
     ]]
  ]];
  let assocSignersByPath = {
     'r.0.0.0': {
        address: peerAddress,
        member_signing_path: 'r',
        device_address: peerDeviceAddress
     }, 'r.0.1.0.0': {
        address: peerAddress,
        member_signing_path: 'r',
        device_address: peerDeviceAddress
     },
     'r.1.0': {
        address: myAddress,
        member_signing_path: 'r',
        device_address: device.getMyDeviceAddress()
     },
     'r.0.1.1.0': {
        address: myAddress,
        member_signing_path: 'r',
        device_address: device.getMyDeviceAddress()
     }
  };
 
  let walletDefinedByAddresses = require('ocore/wallet_defined_by_addresses.js');
  walletDefinedByAddresses.createNewSharedAddress(arrDefinition, assocSignersByPath, {
     ifError: (err) => {
        cb(err);
     },
     ifOk: (shared_address) => {
        headlessWallet.issueChangeAddressAndSendPayment('base', myAmount, shared_address, peerDeviceAddress, (err, unit) => {
           if (err) return cb(err);
           let arrPayments = [{
              address: shared_address,
              amount: peerAmount,
              asset: 'base'
           }];
           let assocDefinitions = {};
           assocDefinitions[shared_address] = {
              definition: arrDefinition,
              signers: assocSignersByPath
           };
           let objPaymentRequest = {payments: arrPayments, definitions: assocDefinitions};
           let paymentJson = JSON.stringify(objPaymentRequest);
           let paymentJsonBase64 = Buffer.from(paymentJson).toString('base64');
           let paymentRequestCode = 'payment:' + paymentJsonBase64;
           let paymentRequestText = '[...](' + paymentRequestCode + ')';
           cb(null, paymentRequestText, shared_address, timeout);
        });
     }
  });
}

Let’s analyze what happens arrSeenConditionPeer - watching if there was a payment in the contract with the amount same of the user. arrSeenConditionMyInput - сhecking, did we withdraw bytes? If yes, then allow the user to pick up their bytes.

arrDefinition - this is what our contract looks like, let’s look at it in details. When we need some address to subscribe we use [‘address’, address] When we need to check the publication data_feed we use [‘in data feed’, [[conf.oracle_address], name, operator, value]]

assocSignersByPath - in this object, we prescribe the path in the array of the contract before you need to sign and who should sign it. In our example, we sign all ‘address’. The path starts with r-this is the first element in the array, in our case ‘or’ construction. Other examples with signatures will be discussed in the following lessons.

walletDefinedByAddresses.createNewSharedAddress - we create a contract address headlessWallet.issueChangeAddressAndSendPayment - we add the address of the contract and make a payment to it

let arrPayments = [{
              address: shared_address,
              amount: peerAmount,
              asset: 'base'
           }];
           let assocDefinitions = {};
           assocDefinitions[shared_address] = {
              definition: arrDefinition,
              signers: assocSignersByPath
           };
           let objPaymentRequest = {payments: arrPayments, definitions: assocDefinitions};
           let paymentJson = JSON.stringify(objPaymentRequest);
           let paymentJsonBase64 = Buffer(paymentJson).toString('base64');
           let paymentRequestCode = 'payment:' + paymentJsonBase64;
           let paymentRequestText = '[your share of payment to the contract](' + paymentRequestCode + ')';

This is how we create a message that contains a contract and a payment request.

Create correspondents.js

const db = require('ocore/db');

exports.addCorrespondent = (code, name, cb) => {
  let device = require('ocore/device');
 
  function handleCode(code) {
     let matches = code.match(/^([\w\/+]+)@([\w.:\/-]+)#([\w\/+-]+)$/);
     if (!matches)
        return cb("Invalid pairing code");
     let pubkey = matches[1];
     let hub = matches[2];
     let pairing_secret = matches[3];
     if (pubkey.length !== 44)
        return cb("Invalid pubkey length");
    
     acceptInvitation(hub, pubkey, pairing_secret, cb);
  }
 
  function acceptInvitation(hub_host, device_pubkey, pairing_secret, cb) {
     if (device_pubkey === device.getMyDevicePubKey())
        return cb("cannot pair with myself");
     if (!device.isValidPubKey(device_pubkey))
        return cb("invalid peer public key");
     // the correspondent will be initially called 'New', we'll rename it as soon as we receive the reverse pairing secret back
     device.addUnconfirmedCorrespondent(device_pubkey, hub_host, name, (device_address) => {
        device.startWaitingForPairing((reversePairingInfo) => {
           device.sendPairingMessage(hub_host, device_pubkey, pairing_secret, reversePairingInfo.pairing_secret, {
              ifOk: () =>{
                 cb(null, device_address);
              },
              ifError: cb
           });
        });
     });
  }
 
  handleCode(code);
};

exports.findCorrespondentByPairingCode = (code, cb) => {
  let matches = code.match(/^([\w\/+]+)@([\w.:\/-]+)#([\w\/+-]+)$/);
  if (!matches)
     return cb("Invalid pairing code");
  let pubkey = matches[1];
  let hub = matches[2];
 
  db.query("SELECT * FROM correspondent_devices WHERE pubkey = ? AND hub = ?", [pubkey, hub], (rows) => {
     return cb(rows.length ? rows[0] : null);
  });
};

We need to tell the oracle to check and publish the weather at the specified time, for this we use this feature.

function findOracleAndSendMessage(value, cb) {
  const device = require('ocore/device');
  correspondents.findCorrespondentByPairingCode(conf.oracle_pairing_code, (correspondent) => {
     if (!correspondent) {
        correspondents.addCorrespondent(conf.oracle_pairing_code, 'flight oracle', (err, device_address) => {
           if (err)
              throw new Error(err);
           device.sendMessageToDevice(device_address, 'text', value);
           cb();
        });
     } else {
        device.sendMessageToDevice(correspondent.device_address, 'text', value);
        cb();
     }
  });
}

We check whether there is an oracle in our correspondents and if it is not - we add.

They operate based on code that is deployed on the ledger once and can never be changed. The code is open and is executed by all nodes on the network.

Anybody can activate an AA just by sending a transaction to its address. Here is an example of a simple AA:

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{trigger.output[[asset=base]] - 1000}"
                    }
                ]
            }
        }
    ]
}]

messages is a template of the response transaction that will be generated by the AA. It follows the structure of a regular Obyte transaction but its sections between curly braces {} contain code that makes the resulting transaction dependent on the triggering (activating) transaction. This is similar to how PHP code can be inserted into HTML to make the resulting page dependent on the request. The language autonomous agents are written in is called Oscript.

The above example of an AA just sends the received money less 1000 bytes back to the sender. trigger.address is the address of the sender who activated the AA. trigger.output allows to find the amounts in different currencies sent to the AA, trigger.output[[asset=base]] is the amount in the base asset -- bytes.

Another example that sells tokens for bytes at 1.5 tokens per byte:

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                // this is the token being sold
                asset: "n9y3VomFeWFeZZ2PcSEcmyBb/bI7kzZduBJigNetnkY=",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{ round(trigger.output[[asset=base]] * 1.5) }"
                    }
                ]
            }
        }
    ]
}]

Passing data to AA

AA's response can also depend on data it receives in the triggering transaction.

In Obyte, any transaction can contain one or more messages of different types. These types are called apps. The most common app is payment. At least one payment is mandatory in every transaction, it is necessary to at least pay fees. Another app is data. This type of message delivers an arbitrary json object that can contain any data:

{
    app: "data",
    payload: {
        withdrawal_amount: 25000,
        nested_array: [
            99,
            {another_field: 44}
        ],
        nested_object: {yet_another_field: "value2"}
    },
     ...
}

The object in payload is the data this message delivers.

When an AA receives a data message (along with a payment message, of course) in the triggering transaction, it can access the data through trigger.data and its action can depend on the data received:

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{trigger.data.withdrawal_amount}"
                    }
                ]
            }
        }
    ]
}]

The above AA tries to send trigger.data.withdrawal_amount bytes back to the sender. withdrawal_amount is a field in the data message of the triggering transaction:

{
    withdrawal_amount: 3000
}

Handling errors

In the above example, if the withdrawal_amount is greater than the balance that the AA has (including the amount received from the triggering transaction), the AA's response will fail. When an AA fails to handle a trigger transaction for any reason, it rolls back all changes and attempts to send back to sender all the received funds, in all assets, less the bounce fees. By default, the bounce fees are 10000 bytes for "base" asset and 0 for all other assets. This is also the minimum. The default can be overridden by adding a bounce_fees field in the autonomous agent definition:

["autonomous agent", {
    bounce_fees: {
        base: 20000,
        "n9y3VomFeWFeZZ2PcSEcmyBb/bI7kzZduBJigNetnkY=": 100
    },
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{trigger.data.withdrawal_amount}"
                    }
                ]
            }
        }
    ]
}]

The above AA will charge 20000 bytes and 100 units of the asset "n9y3VomFeWFeZZ2PcSEcmyBb/bI7kzZduBJigNetnkY=" if it has to bounce back a triggering transaction. Sending less than 20000 bytes to the AA will result in the AA silently eating the coins (they are not enough even for the bounce fees). When non-zero amount of asset "n9y3VomFeWFeZZ2PcSEcmyBb/bI7kzZduBJigNetnkY=" is sent to the AA, it should also be at least 100, otherwise the AA eats the coins.

Sending data messages

As said above, payment is the most common message but other messages can be sent as well by any address, AA included.

Sending data feeds

AA can act as an oracle by sending a data feed:

["autonomous agent", {
    messages: [
        {
            app: "data_feed",
            payload: {
                "{trigger.data.feed_name}": "{trigger.data.feed_value}"
            }
        }
    ]
}]

This example shows that object keys can also be parameterized through Oscript, like object values.

The above AA doesn't have a payment message, it will be added automatically just to pay for the fees.

Sending data

An AA can also send any structured data:

["autonomous agent", {
    messages: [
        {
            app: "data",
            payload: {
                forwarded: 1,
                initial_data: "{trigger.data}"
            }
        },
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY",
                        amount: "{trigger.output[[asset=base]] - 1000}"
                    }
                ]
            }
        }
    ]
}]

Unlike data_feed messages, data messages:

• can have any structure with any nesting depth (data feeds are flat key-value pairs);

• are not indexed for search;

• can be used to pass data to other AAs.

The above AA forwards the received money (less 1000 bytes) to another address, which might be an AA. It also passes data, which includes the initially received data parameters. The value of trigger.data will be expanded into an object and added as value of initial_data field.

If the secondary recipient (JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY) happens to be an AA, its execution will start only after the execution of the current AA is finished. There is no reentrancy issue.

Sending texts

["autonomous agent", {
    messages: [
        {
            app: "text",
            payload: "{'Hello, ' || trigger.data.name || '!'}"
        }
    ]
}]

This AA will create a simple text message and store it on the DAG. || is the operator for string concatenation.

Defining new assets

["autonomous agent", {
    messages: [
        {
            app: "asset",
            payload: {
                cap: "{trigger.data.cap otherwise ''}",
                is_private: false,
                is_transferrable: true,
                auto_destroy: "{!!trigger.data.auto_destroy}",
                fixed_denominations: false,
                issued_by_definer_only: "{!!trigger.data.issued_by_definer_only}",
                cosigned_by_definer: false,
                spender_attested: false,
                attestors: [
                    "{trigger.data.attestor1 otherwise ''}",
                    "{trigger.data.attestor2 otherwise ''}",
                    "{trigger.data.attestor3 otherwise ''}",
                ]
            }
        }
    ]
}]

The above AA creates a definition of a new asset based on parameters passed in data.

Some syntax elements that we see here for the first time:

• ! is a logical NOT operator;

• otherwise is an operator that returns the first operand if it is truthy (anything except false, 0, and empty string) or the second operand otherwise;

• when an object or array value evaluates to an empty string, the corresponding object/array element is removed. This means that if cap parameter is not passed then cap in payload evaluates to an empty string, therefore cap is removed from asset definition and an asset with infinite supply will be defined;

• fields whose value is an empty array/object are also removed. Therefore, if none of the attestor1, attestor2, attestor3 fields was set, the attestors array becomes empty and will be excluded from the final definition.

Querying state

The AA's behavior can also depend on various state variables that describe the ledger as a whole.

Balance

["autonomous agent", {
	messages: [
		{
			app: "payment",
			payload: {
				asset: "base",
				outputs: [
					{
						address: "{trigger.address}",
						amount: "{ round(balance[base]/2) }"
					}
				]
			}
		}
	]
}]

Balance of other AAs (but not regular addresses) can also be queried:

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{ (balance['JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY'][base] < 1e6) ? 'JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY' : trigger.address }",
                        amount: "{ trigger.output[[asset=base]] - 1000 }"
                    }
                ]
            }
        }
    ]
}]

The above AA forwards any received payment (less 1000 bytes) to another AA JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY if its balance is less than 1,000,000 bytes, or returns to sender otherwise.

Data feeds

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{(data_feed[[oracles='TKT4UESIKTTRALRRLWS4SENSTJX6ODCW', feed_name='BROOKLYNNETS_CHARLOTTEHORNETS_2019-07-21']] == 'CHARLOTTEHORNETS') ? '7XZSBB32I5XPIAVWUYCABKO67TZLHKZW' : 'FDZVVIOJZZVFAP6FLW6GMPDYYHI6W4JG'}"
                    }
                ]
            }
        }
    ]
}]

The above AA pays to 7XZSBB32I5XPIAVWUYCABKO67TZLHKZW if Charlotte Hornets won and to FDZVVIOJZZVFAP6FLW6GMPDYYHI6W4JG otherwise TKT4UESIKTTRALRRLWS4SENSTJX6ODCW is the address of a sports oracle that posts the results of sports events.

Before the data feed is posted, any attempt to evaluate it will fail the AA and bounce the triggering transaction.

Note that the amount field in the output is omitted, which means that the entire AA balance will be paid out.

Attestations

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{ (attestation[[attestors='JEDZYC2HMGDBIDQKG3XSTXUSHMCBK725', address=trigger.address]].reputation >= 50) ? 50000 : 0 }"
                    }
                ]
            }
        }
    ]
}]

The above AA pays to the triggering user 50000 bytes if his address is attested by Steem attestation bot JEDZYC2HMGDBIDQKG3XSTXUSHMCBK725 and his Steem reputation is at least 50. Otherwise, it "pays" 0 bytes. Trying to pay 0 amount results in the output being removed. Since it is the only output in this case and it is removed, the resulting response transaction would produce no effect, therefore it is not created at all.

Variables

State variables

An autonomous agent can have its own state saved between invocations. Use var to access and assign state variables:

["autonomous agent", {
    messages: [
        {
            if: "{ var['previous_address'] }",
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{ var['previous_address'] }",
                        amount: "{ trigger.output[[asset=base]] - 1000 }"
                    }
                ]
            }
        },
        {
            app: "state",
            state: `{
                var['previous_address'] = trigger.address;
            }`
        }
    ]
}]

The above AA saves the address that sent the previous triggering transaction, waits for the next invocation, and sends the received money less 1000 bytes to the previous user.

Assigning state variables is only allowed in the special message with app set to state. This message must have a single other field called state which is a set of Oscript statements. These statements are allowed to assign state variables. The state message is not included in the final response transaction, it can only affect state by modifying the state variables.

When an uninitialized var is accessed, it evaluates to false.

The above example has an if field in the first message. When var['previous_address'] is not initialized yet (first call), the if oscript evaluates to false and the entire first message is excluded from the transaction.

State variables of other AAs can also be read, but not assigned:

var['JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY']['var_name']

Local constants

Use local constants to save intermediate results during script execution.

["autonomous agent", {
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{ trigger.address }",
                        amount: `{
                            $amount1 = trigger.output[[asset=base]] - 5000;
                            $amount2 = round(balance[base] * 0.9);
                            max($amount1, $amount2)
                        }`
                    }
                ]
            }
        }
    ]
}]

Local constant names are prefixed with $. Unlike state variables, they are not saved between invocations.

To make it easier to argue about a local constant's value, there is one restriction that is not common in other languages: single-assignment rule. A local constant can be assigned a value only once and that value remains constant until the end of the script. An attempt to re-assign a value will fail the script and make the AA bounce.

Conditional sections

As we've seen in the State variables example before, some parts of the response transaction generated by the AA can be excluded by adding an if field. If the Oscript in the if evaluates to true or any truthy value (anything except false, 0, and empty string), the enclosing object is included in the final response, otherwise, it is excluded.

The if field itself is of course always removed from the final response.

Initialization code

Along with if, any object can have an init field that includes initialization code:

["autonomous agent", {
    messages: [
        {
            if: "{ trigger.data.pay }",
            init: `{
                $amount1 = trigger.output[[asset=base]] - 5000;
                $amount2 = round(balance[base] * 0.9);
            }`,
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{ trigger.address }",
                        amount: "{max($amount1, $amount2)}"
                    }
                ]
            }
        }
    ]
}]

The init code contains only statements, it does not return any value unlike most other Oscripts. The other exception is state message described in State variables above, it is also statements-only. All other Oscripts can contain 0 or more statements but must end with an expression (without a ;) whose value becomes the value of the Oscript.

Init code is evaluated immediately after if (if it is present and evaluated to true of course) and before everything else. It is often used to set local constants that are used later.

Local constants in if and init

Local constants that are set in if and init are also available in all other Oscripts of the current and nested objects. In the above example, $amount1 and $amount2 were set in init of the message object, and they are used in payload/outputs/output-0/amount of this message.

Local constants set in if are also available in the corresponding init.

Statements-only vs return-value Oscripts

As said above, there are two types of Oscripts: those that contain only statements and those that return a value.

There are only two statements-only Oscripts: init and state script. Here is an example of an init script that we've seen before:

{
    init: `{
        $amount1 = trigger.output[[asset=base]] - 5000;
        $amount2 = round(balance[base] * 0.9);
    }`,
     ...
}

All other Oscripts return a value. They either contain a single expression:

{
    address: "{ trigger.address }",
     ...
}

or a set of statements and an expression at the end:

{
    amount: `{
        $amount1 = trigger.output[[asset=base]] - 5000;
        $amount2 = round(balance[base] * 0.9);
        max($amount1, $amount2)
    }`,
     ...
}

The value of the last expression is the value of the Oscript.

Cases

When you need to route the code execution along several mutually exclusive paths depending on input and environment parameters, use cases:

["autonomous agent", {
    messages: {
        cases: [
            {
                if: "{trigger.data.define}",
                messages: [
                    // first version of messages
                    ....
                ]
            },
            {
                if: "{trigger.data.issue}",
                init: "{$amount = trigger.output[[asset=base]];}",
                messages: [
                    // second version of messages
                    ....
                ]
            },
            {
                messages: [
                    // default version of messages
                    ....
                ]
            }
        ]
    }
}]

The regular messages array is replaced with an object with a single element called cases. cases is an array that lists several mutually exclusive alternatives. Every alternative except the last must have an if field. The first alternative whose if evaluates to true defines the messages that will take the place of the higher-level messages field.

The conditions in the ifs may not be mutually exclusive but the alternative that is listed earlier in the list takes precedence. Only one alternative is always taken.

In the above example, if trigger.data has no define field but has a truthy issue field, the 2nd alternative is selected, and the original object folds into:

["autonomous agent", {
    messages: [
        // second version of messages
        ....
    ]
}]

Cases can be nested. Everything said above about if, init, and local constants, applies to cases as well.

if else

The above examples showed how execution can be branched along different parts of json template.

Oscript code itself can be branched as well by using if/else:

if (var['started']){
    $amount = balance[base];
    $current_winner = var['current_winner'];
}
else{
    $amount = trigger.output[[asset=base]];
    $current_winner = trigger.address;
}

return

If you want to interrupt a script's execution and return from it, with or without a value, use return.

Here is an example of return in a return-value Oscript, it must return a value:

$amount = trigger.output[[asset=base]];
if ($amount > 1e6)
    return $amount;
// here comes some other code that will not be executed if $amount > 1e6

A return in a statements-only Oscript, such as init, doesn't return any value, it just interrupts the script:

$amount = trigger.output[[asset=base]];
if ($amount > 1e6)
    return;
// here comes some other code that will not be executed if $amount > 1e6

bounce/require

If you find an error condition and want to prematurely stop the AA execution and bounce, use bounce:

$maturity = var['maturity_timestamp'];
if (timestamp < $maturity) {
    bounce("too early");
}

or require:

$maturity = var['maturity_timestamp'];
require(timestamp >= $maturity, "too early");

In this example, timestamp is roughly the current timestamp (number of seconds since Jan 1, 1970 00:00:00 UTC).

All applied changes will be rolled back and any received coins will be bounced back to the sender less the bounce fees.

_________________

The default settings are in the core library's conf.js file, they can be overridden in your project root's conf.js and then in conf.json in the app data folder. The app data folder is:

• macOS: ~/Library/Application Support/<appname>

• Linux: ~/.config/<appname>

• Windows: %LOCALAPPDATA%\<appname>

<appname> is name in your package.json, e.g. headless-obyte.

Database location

At some point you'll surely want to have a peek into the database, or even make a modification in it. Default SQLite database file and RocksDB folder are located near the config file, you can find the correct paths for each platform above.

Testnet network

If you don't have .env.testnet example file then just create a .env file that contains this row:

Settings

This is the list of some of the settings that the library understands (your app can add more settings that only your app understands):

conf.port

The port to listen on. If you don't want to accept incoming connections at all, set port to null, which is the default. If you do want to listen, you will usually have a proxy, such as nginx, accept websocket connections on standard port 443 and forward them to your Obyte daemon that listens on port 6611 on the local interface.

conf.storage

MySQL conf for faster syncing

To lower disk load and increase sync speed, you can optionally disable flushing to disk every transaction, instead doing it once a second. This can be done by setting innodb_flush_log_at_trx_commit=0 in your MySQL server config file (my.ini)

conf.bLight

Work as light node (true) or full node (false). The default is full client. Light node only holds data that is relevant to your wallet, full node sync all the data in public database. Benefit of light node is that you can start using it immediately, but the downside is that you might not get updates about new transactions and confirmations as fast as full node does.

conf.bServeAsHub

Whether to serve as hub on the Obyte network (store and forward e2e-encrypted messages for devices that connect to your hub). The default is false.

conf.myUrl

If your node accepts incoming connections, this is its URL. The node will share this URL with all its outgoing peers so that they can reconnect in any direction in the future. By default the node doesn't share its URL even if it accepts connections.

conf.bWantNewPeers

Whether your node wants to learn about new peers from its current peers (true, the default) or not (false). Set it to false to run your node in stealth mode so that only trusted peers can see its IP address (e.g. if you have online wallets on your server and don't want potential attackers to learn its IP).

conf.socksHost, conf.socksPort, and conf.socksLocalDNS

Settings for connecting through optional SOCKS5 proxy. Use them to connect through TOR and hide your IP address from peers even when making outgoing connections. This is useful and highly recommended when you are running an online wallet on your server and want to make it harder for potential attackers to learn the IP address of the target to attack. Set socksLocalDNS to false to route DNS queries through TOR as well.

Email notifications

Most bots out there expect user's machine to have UNIX sendmail and by default sendmail function in mail module will try to use that, but it is possible to configure your node to use SMTP relay. This way you could use Gmail or Sendmail SMTP server or even something like Mailtrap.io (excellent for testing purposes if you don't want the actual email recipient to receive your test messages). This is how the configuration would look:

smtpTransport can take one of three values:

• local: send email using locally installed sendmail. Normally, sendmail is not installed by default and when installed, it needs to be properly configured to actually send emails. If you choose this option, no other conf settings are required for email. This is the default option.

• direct: send email by connecting directly to the recipient's SMTP server. This option is not recommended.

• relay: send email through a relay server, like most email apps do. You need to also configure the server's host smtpRelay, its port smtpPort if it differs from the default port 25, and smtpUser and smtpPassword for authentication to the server.

Accepting incoming connections

This is an example configuration for nginx to accept websocket connections at wss://obyte.one/bb and forward them to locally running daemon that listens on port 6611:

If your server doesn't support IPv6, comment or delete the two lines containing [::] or nginx won't start

By default Node limits itself to 1.76GB the RAM it uses. If you accept incoming connections, you will likely reach this limit and get this error after some time:

To prevent this, increase the RAM limit by adding --max_old_space_size=<size> to the launch command where size is the amount in MB you want to allocate.

For example --max-old-space-size=4096, if your server has at least 4GB available.

Checking if the node is running

Sending the notification to admin when node stops

If you are executing your node with node start.js --max-old-space-size=4096 command then you should also change the checkDaemonAndNotify parameter.

Restarting the node automatically when it stops

If you are running a wallet-less node (Hub, Relay or Explorer) or password-less headless wallet (conf.bNoPassphrase=true) then you can restart the node automatically when it stops. In order to do that, you could use checkDaemonAndRestart function, instead of checkDaemonAndNotify.

The first parameter in checkDaemonAndRestart is the process that gets searched from ps x command response, the second parameter is a command that will get executed when node has stopped.

If you are using NVM to manage your Node.js versions then you might need to add PATH and LD_LIBRARY_PATH to your crontab configuration as well, otherwise crontab might not be able to restart the node.

Prosaic contracts are the feature of Obyte platform that helps people to make an agreement on, basically, anything, as text of contracts is a simple text. The benefit of using Obyte prosaic contracts is that after both sides of the contract sign it, a unit, which in fact is a public proof of contract agreement, is posted into DAG, which contains a hash of contract text, while being signed by both peers of the contract. So anyone can check the fact of agreement on the exact same text by those two contract peers. The contract text itself is not revealed but stored in peers wallets.

To offer a prosaic contract from your bot, you have to follow these steps:

• user pairs with your bot.

• you ask the user to send his payment address (it will be included in the contract) in the chat.

• you create a new prosaic contract using the user's address and your address as parties of the contract (also defining contract's title, text and how long the offer is valid).

• you send specially formatted chat message with the contract to the user and wait for the response on it ('accept' or 'decline').

• the user views the contract in his wallet and agrees or declines it.

• on receiving 'accepted' response, you generate new shared address with special definition ('and' between two addresses).

• then you top up this shared address to compensate fees.

• you initiate posting a 'data' message from this shared address, containing contract text hash. User will then be asked to sign this transaction from the same shared address (as he is a part of its definition).

• after getting the user's signature for the 'data' unit, you post it into DAG. Mission accomplished.

We have a special wrapper API for all of these steps in ocore/prosaic_contract_api.js, which in turn is calling ocore/prosaic_contract.js methods. For simplicity, here is an example of using *_api.js, you can check it's code to get a better understanding of what's going on.

callbacks object consists of four optional callback functions, which called in following sequence:

• onOfferCreated is called right after the contract was created and sent to peer. Always called.

• onResponseReceived is called when peer respond to the contract, supplying the response in accepted bool argument.

• onSigned indicates that the contract was successfully signed and unit with contract's hash was posted into DAG.

• onError can only happen when handling the response, if your bot did receive any response, either onError or onSigned will be called.

If you are developing a bot that makes contract offers, here is an outline of the contract's lifecycle:

• Your bot (offerer) receives a user's address in chat from a user.

• The bot then sends a contract with arbitration offer to the user. In the offer, it sets the user's address as the other party of the contract, amount of the contract, and an arbiter's address of your choosing. You can also choose the role for your bot in this contract (buyer or seller).

• The user reviews the offer in their wallet and accepts the contract.

• Your bot receives the user's acceptance, generates a new shared address with smart contract definition, and initiates signing and posting of a special data unit with the hash of the agreed contract text. The unit is to be signed by the shared address (shared between the bot and the user) and each party's signature means that they agree with the contract's text. Your bot signs first, then waits for the user to sign the transaction.

• After the unit has been posted, the buyer side of the contract should pay to this contract's address the full amount that was specified in the contract.

• As soon as the funds are locked on the contract, the seller of the goods/services starts fulfilling their obligations.

• When all the work is done and the buyer is satisfied with the result, they can release the funds from the contract sending them to the seller's address. Also at any time the seller can refund the full amount back to the buyer. The smart contract ensures that in the absence of any arbiter decision each party can send the contract's funds only to the other party: buyer to the seller to release the funds after the work is done, or seller to the buyer to refund. Either outcome completes the contract.

• In case of a disagreement, the user can open a dispute and invoke the arbiter by clicking the corresponding button in their wallet, or your bot can call an API method to open a dispute. The plaintiff has to pay for the arbiter's service before the arbiter starts looking into the case. After the contract status becomes in_dispute, both parties have to wait for the arbiter to post a resolution unit. After the arbiter has studied the contract and the evidence provided by the parties, they make a decision and post the resolution unit. Then, the winning side can claim the funds from the contract.

Note that in order to open a dispute from the bot, your bot should implement the corresponding API (see below). After you open a dispute, the arbiter will set a fee for their service and the arbstore will send a payment request to your bot. Your bot should be able to handle such requests and decide about paying them, either autonomously, or forward them to a human operator.

Example

Basically, all you need to do is calling the exported methods of arbiter_contract.js module and reacting to arbiter_contract_* events on the event bus.

API reference:

1. createAndSend(contractObj, callback(contract){})

   This method creates a contract from the provided object and sends it to the peer. contractObj should contain all the fields needed to assemble a new contract offer. The function is then sends the offer to the contractObj.peer_device_address via chat. The contract received in the callback function has hash field, it is the contract's hash which acts as the primary key when referencing contracts.

   contractObj required fields:

   1. title - contract title, string

   2. text - contract text, string

   3. arbiter_address - the address of the picked arbiter, string

   4. amount - amount in asset to be paid to the seller, int

   5. asset - asset in which the payment should be done, can be null or "base" for Bytes, or any other asset ID, string

   6. peer_address - address of the other side of the contract, string

   7. my_address - your address, string

   8. me_is_payer - flag specifying if you are the buyer or seller, bool

   9. peer_device_address - the device address of the other side of the contract, string

   10. ttl - Time-To-Live, in hours, till which the contract can be accepted, then it expires, float

   11. cosigners - array of your wallet cosigners that would be used when posting contract signature unit, leave empty if not multi-sig or when you want to use all of the cosigners, array of device addresses

   12. my_contact_info - free-form text with your contact info so the peer and arbiter can contact you, it is important to note that if you are sending contract offers from a bot, then arbiter can only pair with your bot and not you, therefore you should put your own wallet's pairing code here or other contacts by which you (as a human) can be reached,string

   contract object supplied to your callback will mostly be identical to the contractObj that you provided to this function, but with some additional fields populated, such as hash, creation_date, my_pairing_code.\

2. createSharedAddressAndPostUnit(contract_hash, walletInstance, callback(error, contract){})

   This method is used to react to the peer accepting your offer. It creates a new shared address with smart contract definition and posts the unit into the DAG. walletInstance is a reference to wallet that has sendMultiPayment() method with an appropriate signer inside. For bots, it is usually the main headlessWallet module. If the error argument for the callback is null, it means that the unit was posted successfully, the contract object is returned with the updated fields.\

3. pay(contract_hash, walletInstance, arrSigningDeviceAddresses, callback(error, contract, unit){})

   This method pays to the contract if you are the buyer side. If you use a multi-signature wallet, then fill the arrSigningDeviceAddresses array with signing device addresses, otherwise provide an empty array. The unit argument in the callback function is the unit ID in case the payment succeeded.\

4. complete(contract_hash, walletInstance, arrSigningDeviceAddresses, callback(error, contract, unit){})

   This method sends the funds locked on the contract to the peer. Depending on your role, this action performs either a successful completion (you are a buyer), or a refund (you are the seller).\

5. respond(contract_hash, status, signedMessageBase64, signer, callback(error, contract){})
6. openDispute(contract_hash, callback(error, response, contract){})

   This function raises a dispute by making an HTTPS request to the contract arbiter's current ArbStore web address. Callback is provided with an error, if any, http response and the updated contract object.\

7. appeal(contract_hash, callback(error, response, contract){})

   This method is similar to the previous one, but is used when you are not satisfied with the arbiter's decision. Also makes an HTTPS request to the ArbStore, but this time calls to ArbStore moderator, who can penalize the arbiter, in case they find the arbiter's decision / actions inappropriate.\

8. getByHash(contract_hash, callback(contract){}) / getBySharedAddress(address, callback(contract){}) / getAllBy*()

   These are all similar functions to retrieve one or many contracts by specific criteria. To get a detailed overview of all the methods you can look at exported methods of arbiter_contract.js module.

Event reference

Almost every event is supplied with additional arguments that you can use in your event handler functions. For examples, see the code snippet above.

1. arbiter_contract_offer : (contract_hash) - this event is fired when core received new contract with arbitration offer from any correspondent.

2. arbiter_contract_response_received : (contract) - fired when user responds to your contract offer. To get their response, check the status field of the contract, it should be either "accepted" or "declined".

3. arbiter_contract_update : (contract, field, value, unit, winner, isPrivate) - this is the most common event that you will react to. It is raised in many situations, like:

   • changed status of a contract: field = "status" (contract was revoked, or put in_dispute, in_appeal, was paid, completed, etc.). This is the full list of the contract statuses: 'pending', 'revoked', 'accepted', 'signed', 'declined', 'paid', 'in_dispute', 'dispute_resolved', 'in_appeal', 'appeal_approved', 'appeal_declined', 'cancelled', 'completed'

   • unit with contract hash was posted: field = "unit"

Create a new node.js package for your chatbot: npm init. You will definitely need modules from ocore and if you are going to send payments, you will also need headless-obyte. Your package.json should list these dependencies:

Now run npm install to fetch dependencies.

If you want to connect to testnet network instead of spamming mainnet for development then you can do that by adding .env file, which should contain just one line:

Sending / receiving txs:

Go ahead and run the code: node index.js. You'll see initialization lines printed by ocore in console, which contain your wallet first address printed and an error saying that There are no funded addresses. This is our failed attempt to issueChangeAddressAndSendPayment(), as you don't have any bytes in your wallet yet.

We wrapped all of our code in 'headless_wallet_ready' event handler, at this point the private keys of your wallet are decrypted and are ready for use.

Find out in console output your first address.

You can deposit some bytes on it to be able to make outbound transactions. Right after ocore is done with initialization (onReady function), we send one byte to some address. First argument is an asset, its the asset you are paying in (null for bytes), amount is payment amount in the smallest units. If the payment was successful, you get its unit in the callback and can save it or watch further events on this unit.

The new_my_transactions and my_transactions_became_stable event handlers are to be invoked after any new transaction received to any of your wallet addresses and when this transactions become stable, respectively. arrUnits is an array of units (more accurately, unit hashes) that contained any transaction involving your addresses. The event new_my_transactions is triggered for outgoing transactions too, you should check if the new transaction credits one of the addresses you are expecting payments to.

The above events work in both full and light nodes. If your node is full, you can alternatively subscribe to event mci_became_stable which is emitted each time a new main chain index (MCI) becomes stable:

Simple chat bot

Every Obyte wallet can be paired with any other Obyte wallet, because every wallet has it's unique pairing code. Headless wallet will print it's pairing code to console right after the launch. Depending on what kind of app you want to build, you will or will not need this pairing code. Simplest operations on Obyte platform require no chat bot (like sending/receiving txs, for example).

For more handy interaction with your userbase, you mostly surely need to write a chat bot, to set up direct interaction between your clients Obyte apps and your wallet (this process is called 'pairing'). Chat bot is Obyte wallet which can receive chat messages and react to them. Clients can pair and chat with your chat bot inside their Obyte wallet app, your task is to handle incoming messages and act accordingly. Through chat, users can provide to your chat bot their addresses, KYC profiles, or any other information with couple of clicks.

You can use bot-example repository as a starting point for your chat bot. You can also use the module from previous step, but it will require you to add some more config lines, so its better to git clone git@github.com:byteball/bot-example.git, remove .git folder rm -fr bot-example/.git and tweak some default configs there (remember to give a name to your bot, switch to light node, set up a pairing secret, etc.)

When you start your node, it will print its full pairing code:

The pairing code consists of your node's public key (device public key), hub address, and pairing secret (after #).

Publish this pairing code anywhere as a link with byteball: scheme, users will be able to open a chat with your bot by clicking your link (the link opens in their Obyte app and starts a chat):

When a user pairs his device with your bot (e.g. by clicking the link to your bot), you receive a pairing notification and can welcome the user:

Receiving chat messages

To receive chat messages, subscribe to 'text' events on event bus:

from_address is user's device address (not to be confused with payment addresses), user_message is their message.

Sending chat messages

Messages to user's device can be sent with sendMessageToDevice function in device module:

So, in case we want to echo back what user wrote, we could combine those two above examples into this:

Great success, we now have a bot, which is like a parrot (repeating everything you wrote to it).

Predefined chat commands

To give access to predefined commands, format your responses this way:

Command suggestion

Sometimes you might want to suggest the command without actually sending it immediately, so user could have the possibility to edit the command before sending, this could be done like this:

Next step

That's it. You've completed your first chat bot on Obyte platform. You can check other chat bot examples provided by our team:

Setting up a Headless wallet is required for those wanting to build their own chat bots. That is, if they want to host the bot on their own server, at least. This guide will take you through the installation in a step by step process but won’t venture into how to build the chat bot itself. There are several possibilities to rent a Virtual Private Server (VPS) and apart from a fairly fast SSD storage there are not a lot of requirements.

Most VPS providers allow you to choose an operating system, and since this guide will be based on Debian 9, you might want to find a provider that offers this as one of their options. Since I will be running a full node, I also must make sure to have enough disk space available and that it is on SSD, since HDD will be too slow. At the time of writing this guide, the required disk space for the full Obyte DAG is about 38 GB but always make sure to have enough or at least the option to add more, should you need it.

• 1 server (with Debian in this case)

• At least 50-70 GB of fast SSD disk space (HDD is too slow for initial syncing)

• 1 GB RAM (hubs/relays that accept incoming connections might need up to 4GB)

Setting up the server.

First time you log on, you will see a notice that you have not connected to this host before. Click “Yes” to save the key.

You are now logged on to your server:

Running the headless wallet as root is not recommended, so the first thing I do, is create the user we will run the hub as. I chose the username “obyte”.

adduser obyte

I will be installing all prerequisites as root for this guide. Only the actual headless wallet stuff will be installed from the user we just created. For now, stay logged in as root.

The fundamentals

First, we need some basic tools. To make sure we get the newest versions, first run an update of the apt tool: apt update

Then install following software: apt-get install -y git curl software-properties-common

To make sure all binaries build properly, we need the build-essentials as well: apt-get install -y build-essential

Now log on with the user we initially created (obyte in this example) su -l obyte

The headless wallet is based on nodejs, and one of the easiest way to control node versions is by the script called “nvm”. Just fire these three commands, and you’re all set (make sure not to miss any of the backticks in the above): nvm_version=`curl --silent -L https://api.github.com/repos/nvm-sh/nvm/releases/latest | /usr/bin/awk '/tag_name/ { print $2 }' | /bin/sed 's/[",]//g'` curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/$nvm_version/install.sh | bash

Then exit user, log in again and install version 10 of nodejs: exit su -l obyte nvm install 10

Build tools for Windows can be installed with following command (you need to run PowerShell or CMD.exe as Administrator to install this): npm install --global --production windows-build-tools

Installing the Headless Wallet

Copy the URL from there and clone the repository

git clone https://github.com/byteball/headless-obyte.git

It creates a directory called headless-obyte.

cd headless-obyte

Then install it

npm install

Configuring and starting your headless wallet

In your .config folder, you should create a file called conf.json and edit it. It will contain values that is used by the headless wallet. They override the values that you can find in the file called conf.js located in your headless-obyte folder.

mkdir -p ~/.config/headless-obyte nano ~/.config/headless-obyte/conf.json

I will briefly explain each of the entries, you should put in the file (if you’re not familiar with the structure of a json object, you could check out sites such as jsoneditoronline.org)

deviceName config

This is pretty much self explanatory. The name of your device. This is the name that others will see when they pair with your bot. It’s not to be confused with the bot’s name, which you will have to have the Obyte hub-operator create for you.

permanent_pairing_secret config

This is the part that goes after the # in your pairing invitation that you will use from your control device - usually a GUI wallet.

control_addresses config

This is one of the two most important settings. This is an array of device addresses (not wallet addresses) that are allowed to control your headless wallet and request payments from it. You will most likely want to control the headless wallet from a GUI wallet on a phone or desktop. You find the device address by clicking the burger-menu and clicking “Settings” and then scrolling down to the section saying “Device Address” on the wallet(s) you want to be able to connect to the headless wallet from.

payout_address config

The other important setting is the payout_address which is the wallet address that the bot is allowed to send funds to. When a device with the correct device address requests the bot to send a payment of X bytes, the bot automatically pays it to the wallet you specify here. If you are installing the bot to allow users to send funds to it or to be part of smart contracts that it will potentially withdraw from, you might want to periodically send funds away from the headless wallet and into another wallet you control.

bLight config

This setting determines whether your headless wallet will run as a full node or a light node. If your bot needs access to all transactions on the DAG, you will need to run a full node. Therefore, in most cases, this should be set to false.

The final file would look something like this:

Wallet is ready to be started

That’s it, your headless wallet is now ready to be started. If you set bLight = false; your wallet will start synchronizing the entire DAG. This can take a long time depending on the speed of your server and particularly the SSD disk.

To make sure the process doesn’t run out of memory (which can cause crashes) you should manually assign additional memory to the nodejs process:

node --max-old-space-size=4096 start.js

Run on background using "bg" and "fg"

Send to background

ctrl+z bg

Stop the headless wallet

fg ctrl+c

Run on background using “screen”

It might just be me, but I always found that a better way to leave processes running even after I log off the server, is to use the program screen. It’s super easy to use. So I suggest, that even though the bot say you can send the process to the background by using ctrl+z and bg, i have a harder time separating the various background processes. So I suggest you simply do this:

sudo apt-get install screen

This allows you to start, detach and re-attach screens as you please.

Start a new screen

screen - run it when you have detached from screen and want to start a totally new screen.

Send screen to background

ctrl+a and d - this detaches from screens and sends it to background (be careful not to miss pressing a before d.

Resuming a screen from background

screen -r - this reattaches to most recently started screen. If you have started multiple then use screen -list to get a list of all started screens and then reattached with screen -r PPID

Stop the headless wallet

ctrl+d - while attached to screen, this terminates the screen and stops the headless wallet

Run on background non-interactively

If you are unable to enter a passphrase every time the wallet starts and/or are willing to accept the security risks, set bNoPassphrase to true and daemonize the app when starting:

Starting the daemon

Stopping the daemon

Checking if node runs

ps -ef | { head -1; grep node; } or ps -fp $(pgrep -d, -x node)

kill PID - sends SIGTERM command to stop the process by PID number.

If you want to automatically stop all node processes then use pkill node

Useful extras

Monitoring logs

tail -f ~/headless-obyte/log.txt

Disabling logs

By default, headless wallets are set to write logs into a file, but you make them to write to console instead by setting logToSTDOUT configuration to true.

If don't wish to get the logs to console and you also would like to disable writing the log file then this can be done by adding a variable like this to the configuration file:

Documentation

Autonomous agents

Autonomous agents (AA) are special addresses (accounts) on the ledger that do not belong to anybody. An AA can send transactions only in response to a triggering transaction sent to it and strictly according to a program associated with the AA. This program is open and known in advance, it specifies the AA's reaction to triggering transactions. The reaction depends on:

• coins sent by the triggering transaction: how much of which asset were sent;

• data sent by the triggering transaction;

• environment that exists in the ledger when the trigger is received: balances, data posted by oracles, attestations, state variables.

The AA's reaction can be one or a combination of:

• sending some other coins back to the sender or to a third party (which can be another AA);

• changing the environment of the ledger by posting data feeds, attestations, updating state variables, etc.

The behavior of autonomous agents is similar to vending machines: they accept coins and data entered on a keypad (the triggering action), and in response they release a cup of coffee or play a song, or do whatever they are programmed to do. What's common between them, their behavior is predictable, known in advance.

There are no private/public keys associated with AAs. Their transactions do not have signatures. Their transactions are created by all (full) nodes just by following the common protocol rules and executing the code associated with the AA. All nodes always come to the same result and produce exactly the same transaction that should be sent on behalf of the AA. As one comes to expect from a DAG, all nodes arrive at the same view of the ledger state just by following the rules, without any votings, proof-of competitions, or leaders.

The AA-generated transactions are not broadcast to peers as peers are expected to generate the same transactions on their own.

The language used to specify the AA behavior is a domain specific language that we call Oscript. It was designed specifically for AAs to make it easy to write an autonomous agent behavior, make it easy to argue about what is going on in the AA code, and make it hard to make difficult-to-track errors.

To control the resource consumption, the language does not support loops. Resource usage is controlled by setting a cap on the complexity of the program -- too resource heavy programs are simply not allowed. However, the resource caps provide enough room for the vast majority of practical applications.

AAs can "call" other AAs by sending coins to them. All the scripts in the calling AA are finished and all changes committed before passing control on to the next AA, this avoids completely the reentrancy problem common in other smart contract platforms.

Autonomous agent definition

Addresses of autonomous agents follow the same general rules as all other Obyte addresses: their definitions are two-element arrays and the address is a checksummed hash of the array encoded in base32.

AA address is defined as:

["autonomous agent", {
    // here goes the AA code
}]

The second element of the above array is an object that defines a template for future units created by the AA. The template's structure follows the structure of a regular unit in general, with some elements dynamic and dependent upon the input and state parameters. The dynamic elements are designated with special markup and include code in a domain specific language called Oscript:

{
    address: "{trigger.address}",
    amount: "{trigger.output[[asset=base]] - 1000}"
}

The concept is similar to how such languages as PHP, ASP, and JSP work. For example, a PHP script is a HTML file interspersed with fragments of PHP code enclosed between <?php and ?> tags. These fragments make the HTML page dynamic while keeping its HTML structure. While this mix can quickly become messy when PHP is used to generate HTML code, the ease of creating dynamic web pages by just inserting small pieces of code into HTML was one of the main selling points of these programming languages in the early days of the web. And it enabled quick prototyping, iteration, experimentation, and eventually led to the creation of some of the biggest pieces of the modern Internet (wordpress and facebook, to name a few).

Transactions, or storage units as we call them in Obyte, are similarly the basic building units of distributed ledgers. They are usually represented as JSON objects, which are the counterparts of HTML pages on the web. Now, to make it easy to create dynamic, parameterized JSON objects representing transactions, we allow to inject some code into JSON and invite the developers to apply their creativity and do the rest.

This is an example of autonomous agent definition:

["autonomous agent", {
    bounce_fees: { base: 10000 },
    doc_url: "https://example.com/doc_urls/{{aa_address}}.json",
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{trigger.output[[asset=base]] - 1000}"
                    }
                ]
            }
        }
    ]
}]

Here messages is a template for the AA's response transaction. It has only one message -- a payment message that will send the received amount less 1000 bytes back to sender. Omitting the amount entirely would send everything back (minus the fees). There are code fragments in strings enclosed in curly braces "{}", they are evaluated and the result is inserted in place of the code.

Before sending the resulting response transaction, the nodes on the network will also enhance it with change outputs (if necessary) and add other necessary fields in order to attach the transaction to the DAG: parents, last stable unit, authors, timestamp, fees, etc.

Below is a specification of the unit template format.

JSON format

bounce_fees

["autonomous agent", {
    bounce_fees: {
        base: 10000,
        "n9y3VomFeWFeZZ2PcSEcmyBb/bI7kzZduBJigNetnkY=": 100
    },
    ...
}]

This is an optional field of the unit template that specifies the fees charged from sender if the AA execution fails. In this case, all the received money in all assets is automatically bounced back to sender, less the bounce fees. The fees are keyed by asset ID (base for bytes).

The minimum and default bounce fee for bytes is 10000 bytes. The minimum and default bounce fee for all other assets is 0. Non-base bounce fees apply only to those assets that were actually received by the autonomous agent.

Sending to an autonomous agent anything less than the bounce fees will result in no response and the AA silently eating the coins. However this rule applies only to money sent from regular addresses. Bounce fees are not checked when the money is received from another AA.

bounce_fees field is removed from the final unit.

doc_url

Each deployed autonomous agent can have a URL that points to a JSON formatted documentation file, which content will be shown to users in wallet app. URL can contain {{aa_address}} placeholder, which will be replaced with actual AA address before fetching the JSON file. The structure of the JSON file should look like this:

{
	"version": "1.0",
	"description": "Description shown to users",
	"homepage_url": "https://example.com",
	"source_url": "https://github.com/byteball/ocore",
	"field_descriptions": {
		"some_field_name": "Description how to use this parameter",
		"some_other_field_name": "Description how to use this other parameter",
		...
	}
}

Keys in field_descriptions object should match all the keys in trigger.data that users can use with this AA, wallet app will add value of that fields as an explanation what it does. The value of version should be as shown above ("1.0") - it should NOT used as version of AA.

messages

This is the main field of autonomous agent definition. It specifies templates for the messages to be generated, and the templates are parameterized with oscript code.

The messages can be of any type (called app) that Obyte supports. The most common app is payment, it is used to send payments in any asset back to sender or to a third party. Other apps are:

• data: used to send data, this includes sending data parameters to other (secondary) AAs;

• data_feed: used to send data feeds. By doing this, the AA becomes an oracle;

• profile: used to send one's own profile. Maybe an AA wants to say something to the world about itself;

• text: used to save arbitrary text to the DAG;

• definition: used to post a definition of a new AA;

• asset_attestors: used to change the attestor list of an asset previously defined by this AA;

• attestation: used to post information about some other address. By doing this, the AA becomes an attestor;

• definition_template: used to post a template for smart contract definition;

• poll: used to create a poll;

• vote: used to vote in a poll. Every AA has voting rights after all.

There is also another, special, app called state, which is not possible in regular units but is used only in AAs to produce state changes. More about it in a separate chapter.

base_aa

It is possible to create parameterized Autonomous Agents, which are based on previously deployed templates. Their structure for that kind of Autonomous Agent would look like this:

["autonomous agent", {
    base_aa: "ADDRESS_OF_BASE_AA",
    params: {
        name1: "value1",
        name2: "value2",
        ...
    }
}]

The base AA template would need to reference these parameters as params.name1 and params.name2.

Oscript replacements

Any string, number, or boolean in the template can be calculated by a script. The script is evaluated and the result is inserted in place of the script, the type is preserved. For example, if 20000 bytes were sent from address 2QHG44PZLJWD2H7C5ZIWH4NZZVB6QCC7 to an AA, then this code

{
    address: "{trigger.address}",
    amount: "{trigger.output[[asset=base]] - 1000}"
}

would be replaced with

{
    address: "2QHG44PZLJWD2H7C5ZIWH4NZZVB6QCC7",
    amount: 19000
}

Object keys can also be parameterized with Oscript:

{
    "{trigger.data.key}": "value"
}

See the Oscript language reference below.

cases - template objects

JSON has scalars (strings, numbers, booleans) and objects (objects and arrays). Scalars can be parameterized through Oscript. Objects, on the other hand, are parameterized differently. They can have several alternative versions in the AA template, and only one version is selected based on input parameters and state. The versions and their selection criteria are specified using an object in cases array:

{
    messages: {
        cases: [
            {
                if: "{trigger.data.define}",
                messages: [
                    // first version of messages
                    ....
                ]
            },
            {
                if: "{trigger.data.issue}",
                init: "{$amount = trigger.output[[asset=base]];}",
                messages: [
                    // second version of messages
                    ....
                ]
            },
            {
                messages: [
                    // default version of messages
                    ....
                ]
            }
        ]
    }
}

The regular value of an object/array is replaced with an object whose single element is an array cases. Each element of the cases array is an object with up to 3 elements:

• if: an Oscript expression. If the result of its evaluation is truthy then this case is selected. All other cases are not evaluated. if is required for all cases except the last, the last one may or may not have an if. If all previous cases evaluated to a falsy value and the last one is without an if, the last one is selected;

• init: an optional statements-only Oscript that is evaluated immediately after if if this case is selected;

• a mandatory element that is named the same as the original field (messages in the above example). If this case is selected, the original (3 levels higher) field is replaced with the value of this element.

In the above example, if the 2nd case were selected, the original object would fold into:

{
    messages: [
        // second version of messages
        ....
    ]
}

Cases can be nested.

Cases can be used for any non-scalar value inside messages, not just messages themselves.

if - conditional objects

Similar to the cases above, any object can have an additional if field. It is evaluated first, and if it is falsy, the entire object is removed from the enclosing object or array. Its internal Oscripts are not evaluated in this case.

{
    messages: [
        {
            app: "data",
            payload: {
                timestamp: "{timestamp}",
                subscriber: "{trigger.address}"
            }
        },
        {
            if: "{trigger.data.withdrawal_amount > 0}",
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{trigger.data.withdrawal_amount}"
                    }
                ]
            }
        }
   ]
}

In the above example, the payment message will be generated only if trigger.data.withdrawal_amount is a number greater than 0.

The if field itself is removed from the object.

init - statements object

Similar to the cases above, any object can have an additional init field. It is evaluated immediately after if when if is present and truthy. If there is no if, init is unconditionally evaluated first.

init must be a statements-only Oscript, it does not return a value.

Example:

{
    messages: [
        {
            init: "{ $addr = trigger.address; }",
            app: "data",
            payload: {
                timestamp: "{timestamp}",
                subscriber: "{$addr}"
            }
        },
        {
            if: "{trigger.data.withdrawal_amount > 1000}",
            init: "{ $amount = trigger.data.withdrawal_amount - 1000; }",
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{$amount}"
                    }
                ]
            }
        }
   ]
}

The init field itself is removed from the object.

Conditional object fields and array elements

If the value of any object field or array value evaluates to an empty string, this field or element is removed.

For example, object

{
    field1: "{ (1 == 2) ? 'value1' : '' }",
    field2: "value2"
}

will become

{
    field2: "value2"
}

Array

[ `{ (1 == 2) ? "value1" : "" }`, "value2" ]

will become

[ "value2" ]

Sending all coins

If the amount field in an output within a payment message is omitted or evaluates to an empty string (which results in its removal per the above rules), this output receives all the remaining coins.

{
    messages: [
        {
            if: "{trigger.data.send_all}",
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "2QHG44PZLJWD2H7C5ZIWH4NZZVB6QCC7",
                        amount: 1000
                    },
                    {
                        address: "{trigger.address}"
                    }
                ]
            }
        }
   ]
}

In the above example, 1000 bytes are sent to 2QHG44PZLJWD2H7C5ZIWH4NZZVB6QCC7, the rest of the AA's balance in bytes is sent to the address that triggered the AA.

Empty objects and arrays

If an object or array becomes empty as a result of various removals, it is also removed from the enclosing object or array.

State message

A state message is a special message in the messages array that performs state changes. It is the only oscript where state variables are assigned. Unlike regular messages that always have payload, state message has a field named state instead that contains a state changing script:

{
    messages: [
        {
            app: "payment",
            payload: {
                asset: "base",
                outputs: [
                    {
                        address: "{trigger.address}",
                        amount: "{trigger.output[[asset=base]] - 1000}"
                    }
                ]
            }
        },
        {
            app: "state",
            state: `{
                var['responded'] = 1;
                var['total_balance_sent_back'] += trigger.output[[asset=base]] - 1000;
                var[trigger.address || '_response_unit'] = response_unit;
            }`
        }
    ]
}

The state message must always be the last message in the messages array. It is not included in the final response unit and its script (state script) is evaluated after the response unit is already prepared. It is the only oscript where response_unit variable is available. State script contains only statements, it is not allowed to return any value.

Constants/Variables

Local constants

$name1 = 1;
$name2 = 'value';
${'name' || 3} = $name1 + 10;

Local constant names are always prefixed with $. If the constant name itself needs to be calculated, the expression is enclosed in curly braces.

Local constants exist only during AA evaluation. Each constant can be assigned a value only once (single-assignment rule).

Each local constant is visible only in its own oscript after it was assigned. If it was assigned in if block, it is also available in all adjacent and enclosed oscripts. If it was assigned in init block, it is also available in all adjacent oscripts except if and in all oscripts enclosed in the same object.

[
    {
        if: `{
            $amount = trigger.output[[asset=base]];
            // the result of the last expression is the result of if
            $amount == 10000
        }`,
        init: `{
            // here we can reference $amount set in if
            $half_amount = round($amount / 2); 
        }`,
        messages: [
            {
                app: "payment",
                payload: {
                    asset: "base",
                    outputs: [
                        {
                            address: "{ trigger.address }",
                            amount: `{
                                // we are in an enclosed oscript
                                // and can reference $half_amount set in init
                                $half_amount
                            }`
                        }
                    ]
                }
            },
            {
                app: "state",
                state: `{
                    // we are in an enclosed oscript
                    // and can reference $amount set in if
                    var['received'] = $amount;
                    // we are in an enclosed oscript
                    // and can reference $half_amount set in init
                    var['sent_back'] = $half_amount;
                }`
            }
        ]
    },
    {
        if: "{trigger.data.payout}",
        init: `{
            // here we cannot reference $amount nor $half_amount from the above
            // we can even assign other values to them without breaking the single-assignment rule
            $amount = 10;
        }`,
        ...
    }
]

If an unassigned local constant is referenced, it is taken as false.

If-else blocks in curly braces do not create separate scopes for local constants:

if (trigger.data.deposit){
    $amount = trigger.output[[asset=base]];
}
$fee = round($amount * 0.01); // we can reference the $amount from above

Local constants can hold values of any type: string, number, boolean, or object (including array).

Objects and arrays

When a local constant holds an object, individual fields of the object can be accessed through dot or [] selector:

$data = trigger.data;
$action = $data.params.action;
$player_score = $data.params[$player_name || '_score'];

If the specified object field does not exist, the value is taken as false.

Objects and arrays can be initialized using familiar syntax as in other languages:

$obj = {a: 3, b: 7 };
$arr = [7, 2, 's', {a: 6}];

Although all local constants are single-assignment, objects and arrays can be mutated by modifying, adding, or deleting their fields:

$obj = {a: 3, b: 7 };
$obj.a = 4; // modifies an existing field
$obj.c = 10; // adds a new field
delete($obj, 'b'); // deletes a field
freeze($obj); // prohibits further mutations of the object

$arr = [7, 2, 's', {a: 6}];
$arr[0] = 8; // modifies an existing element
$arr[] = 5; // adds a new element
delete($arr, 1); // removes element 1
freeze($arr); // prohibits further mutations of the array

The left-hand selectors can be arbitrarily long .a.b[2].c.3.d[].e. If some elements do not exist, an empty object or array is created automatically. [] adds to the end of an array. Array indexes cannot be skipped, i.e. if an array has length 5, you cannot assign to element 7. Once you are done mutating an object, can call freeze() to prevent further accidental mutations.

Local functions

$f = ($x) => {
	 $a = var['a'];
	 $x * $a
};

// one-line syntax for functions that have only one expression
$sq = $x => $x^2;

$res = $f(2);
$nine = $sq(3);

Functions are local constants and the same rules apply to them.

The return value is the value of the last expression or a return statement.

A function sees all other local constants and functions declared before it. Because of this, recursion is impossible.

Constants declared before the function cannot be shadowed by its arguments or other local constants declared within the function.

Complexity of a function is the sum of complexities of all operations within it. Every time a function is called, its complexity is added to the total complexity of the AA. If a function is declared but never called, its complexity doesn't affect the complexity of the AA.

Remote functions (getters)

Getters are read-only functions available to other AAs and non-AA code.

They are meant to extract information about an AA state that is not directly available through state vars. E.g. in order to fetch this information one needs to perform some calculation over state vars or access several state vars and have good knowledge about the way information is stored in the AA.

Examples:

• oswap could expose functions that would calculate the price of a future exchange. Otherwise, clients would have to do non-trivial math themselves.

• the token registry could expose a single getter $getTokenDescription($asset) for reading a token description, and a similar one for decimals. Otherwise, one has to read first $desc_hash = var['current_desc_' || $asset], then var['description_' || $desc_hash].

Getters are declared in a top-level getters section which is evaluated before everything else.

['autonomous agent', {
	getters: `{
		$sq = $x => $x^2;
		$g = ($x, $y) => $x + 2*$y;
		$h = ($x, $y) => $x||$y;
		$r = ($acc, $x) => $x + $acc;
	}`,
	init: `{
		// uncomment if the AA serves as library only
		// bounce("library only");
		...
	}`,
	...
}]

The code in getters section can contain only function declarations and constants. Request-specific information such as trigger.data, trigger.outputs, etc is not available in getters.

In the AA which declares them, getters can be accessed like normal functions.

Other AAs can call them by specifying the remote AA address before the function name using this syntax:

$nine = MXMEKGN37H5QO2AWHT7XRG6LHJVVTAWU.$sq(3);

or

$remote_aa = "MXMEKGN37H5QO2AWHT7XRG6LHJVVTAWU";
$nine = $remote_aa.$sq(3);

If $remote_aa is a variable that cannot be evaluated at deploy time, you need to indicate the max complexity of the remote call either explicitly, after a #:

$nine = $remote_aa#5.$sq(3);

or as a variable that can be evaluated at deploy time:

$max_complexity = 5;
$nine = $remote_aa#$max_complexity.$sq(3);

or by indicating a base AA that the $remote_aa is a parameterized AA of:

$base_aa = '3DGWRKKWWSC6SV4ZQDWEHYFRYB4TGPKX';
$nine = $remote_aa#$base_aa.$sq(3);

The complexity of a remote call is the complexity of its function, plus one.

All functions declared in the getters section are publicly available. If some of them are not meant for public use, one can indicate this by a naming convention, e.g. by starting their names with an underscore $_callPrivateFunction() but information hiding cannot be really enforced since all getters operate on public data anyway.

Getters can also be conveniently called from non-AAs. In node.js code:

const { executeGetter } = require('ocore/formula/evaluation.js');
const db = require('ocore/db.js');

const args = ["arg1", "arg2"];
const res = await executeGetter(db, aa_address, getter, args);

For remote clients, there is a light/execute_getter command in WebSocket API, hopefully it will be shortly available through obyte.js.

State variables

State variables are persisted across invocations of autonomous agents.

Accessing state variables:

// assigning current AAs state variable to local constant
$my_var_name1 = var['var_name1'];

// assigning other AAs state variable to local constant
$their_var_name1 = var['JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY']['var_name1'];

Assigning state variables:

var['var_name1'] = 'var_value';
var['var_name2'] = 10;
var['var_name3'] += 10;
var['var_name4'] = false;
var['var_name5'] = {a:8, b:2};
var['var_name5'] ||= {c:6};  // concat an object

var['var_name'] reads the value of state variable var_name stored under current AA.

var['AA_ADDRESS']['var_name'] reads the value of state variable var_name stored under AA AA_ADDRESS. AA_ADDRESS is a valid address or this_address to refer to the current AA.

If there is no such variable, false is returned.

State vars can temporarily hold strings, numbers, objects, and booleans but when persisting, true values are converted to 1 and false values result in removal of the state variable from storage. AAs are required to hold a minimum balance in bytes equal to the size of their storage (length of var names + length of var values). This will also incentivize them to free up unused storage. The size of AA’s storage occupied before the current invocation is in variable storage_size.

Internally, objects are stored as JSON strings and their length is limited. Don't try to store a structure in a state var if this structure can grow indefinitely.

In addition to regular assignment =, state variables can also be modified in place using the following operators:

• +=: increment by;

• -=: decrement by;

• *=: multiply by;

• /=: divide by;

• %=: remainder of division by;

• ||=: concatenate string/object/array.

For concatenation, the existing value of the var is converted to string.

For +=, -=, *=, /=, %=, the existing boolean value is converted to 1 or 0, strings result in error.

If the variable didn't exist prior to one of these assignments, it is taken as false and converted to number or string accordingly.

Each read or write operation on a state variable adds +1 to complexity. Assignment with modification also costs 1 in complexity.

Examples:

var['sent_back'] = $half_amount;
var['count_investors'] += 1;
var['amount_owed'] += trigger.output[[asset=base]];
var['pending'] = false;
$x = var['JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY']['var_name1'];

Response variables

response['key'] = 'text';

Adds a key to the response object. Response variables do not affect state, they are meant to only inform the caller, and other interested parties, about the actions performed by the AA.

Response vars can only be assigned, never read. Response vars can be assigned and reassigned multiple times in any oscript. They can hold values of types: string, number, boolean. Attempting to assign an object would result in true being assigned.

Example: assigning these response variables

response['message'] = "set exchange rate to 0.123 tokens/byte";
response['deposit'] = 2250000;

will result in the following response object:

{
    "responseVars": {
        "message": "set exchange rate to 0.123 tokens/byte",
        "deposit": 2250000
    }
}

Responses

The AAs are activated and responses are generated when the triggering unit gets stabilized. If the triggering unit triggers several AAs or there are several triggers that are included in the same MC unit and therefore get stabilized at the same time, the triggers are handled in deterministic order to ensure reproducibility on all nodes.

The first response unit has one or two parents:

• the MC unit that just got stabilized and which includes the triggering unit;

• the previous AA-generated unit (meaning, generated by any AA, not just the current one) if it is not already included in the first parent.

Any subsequent responses (generated by secondary AAs and in response to other triggers at the same MCI) are chained after the first response and then one after another.

After every response, 4 events are emitted:

• aa_response

• aa_response_to_unit- + trigger_unit

• aa_response_to_address- + trigger_address

• aa_response_from_aa- + aa_address

Applications, which are based on a full node can subscribe to these events to receive information about responses they are interested in, e.g.:

var trigger_address = '';

const eventBus = require('ocore/event_bus.js');
eventBus.on('aa_response_to_address-' + trigger_address, (objAAResponse) => {
    // handle event
});

Applications, which are based on light node will also need to add the address to their watched list in order to subscribe to these events:

var aa_address = '';

const walletGeneral = require('ocore/wallet_general.js');
const eventBus = require('ocore/event_bus.js');
walletGeneral.addWatchedAddress(aa_address, () => {
    eventBus.on('aa_response_from_aa-' + aa_address, (objAAResponse) => {
        // handle event
    });
});

All 4 event handlers receive objAAResponse object as a single argument:

{ 
    mci: 2385,
    trigger_address: '2QHG44PZLJWD2H7C5ZIWH4NZZVB6QCC7',
    trigger_unit: 'f2S6Q3ufjzDyl9YcB51JUj2z9nE1sL4XL2VoYOrVRgQ=',
    aa_address: 'JVUJQ7OPBJ7ZLZ57TTNFJIC3EW7AE2RY',
    bounced: false,
    response_unit: 'JCJ1ZGkl2BtUlYoeu6U2yshp97pen/fIkTHvaKYjZa4=',
    objResponseUnit: {
        version: '2.0dev',
        alt: '3',
        timestamp: 1560939440,
        messages: [ ... ],
        authors: [ ... ],
        last_ball_unit: 'cxjDfHzWWgW8LqsC8yoDhgCYmwThmFfkdygGnDrxiFg=',
        last_ball: 'gjg8W2cE4WGFAIIsU2BvLOQKOpH/03Oo1SDS3/2SQDs=',
        witness_list_unit: '3gLI9EnI2xe3WJVPwRg8s4CB24ruetuddS0wYa2EI3c=',
        parent_units: [ 'f2S6Q3ufjzDyl9YcB51JUj2z9nE1sL4XL2VoYOrVRgQ=' ],
        headers_commission: 267,
        payload_commission: 157,
        unit: 'JCJ1ZGkl2BtUlYoeu6U2yshp97pen/fIkTHvaKYjZa4='
    },
    response: {} 
}

The object has the following fields:

• mci: the MCI of the triggering unit. The response unit is attached to the NC unit with the same MCI;

• trigger_address: the address that sent coins to the AA and thus triggered it;

• aa_address: AA address

• bounced: true if the trigger was bounced, false otherwise;

• response_unit: hash of the response unit or null if there is no response;

• objResponseUnit: response unit object or null if there is no response;

• response: response from the script. The object can have up to two fields: error for error message and responseVars for response variables set by scripts.

Secondary AAs

The generated response unit may contain outputs to other AAs. In this case, the receiving AAs are triggered too. They receive the outputs from the previous AA and the data (if any) from its generated data message.

Secondary AAs behave like the primary ones except that they may receive less than the minimum bounce fees.

If there are several secondary AAs triggered by a previous AA, they are handled in a deterministic order to make sure that the results are reproducible on all nodes. If a secondary AA triggers a ternary one in turn, it is handled before going on to the next secondary AA.

If any of the secondary AAs fails, the entire chain fails, all the changes produced by its AAs are rolled back, and the primary AA bounces.

The total number of secondary AAs stemming from a single primary AA cannot exceed 10, otherwise the primary AA fails and bounces.

Failures

If an AA fails for any reason (bad formula, attempt to send an invalid response, attempt to send more money than it has, etc), and attempt is made to bounce all the received coins back to sender, less bounce fees. All state changes are rolled back.

If creation of the bouncing transaction fails too, no transaction is created in response, i.e. the AA eats the coins.

The response object, which is not saved to the ledger, contains an error message explaining the reasons for failure.

Semicolon

Every variable assignment must be terminated by a semicolon ;. return and bounce statements are also terminated with a semicolon.

$amount = trigger.output[[asset=base]];
var['sent_back'] = round($half_amount/2);
response['message'] = "set exchange rate to 0.123 tokens/byte";
if ($amount >= 42000)
    bounce("amount too large");
if (balance[base] < 20000)
    return;

Two types of Oscripts

There are two types of Oscripts that can be used in AAs:

• statements-only scripts that consist only of statements (such as assignments) and don't return any value. init script and state message are the only two allowed statements-only scripts;

• scripts that return a value. They can have 0 or more statements but the last evaluated expression must not be a statement and its result is the result of the script.

Example of a statements-only script:

$amount = trigger.output[[asset=base]];
$action = trigger.data.action;

Example of a script that returns a value:

$amount = trigger.output[[asset=base]];
$action = trigger.data.action;
$amount*2

The result of evaluation of the last expression $amount*2 is returned.

Non-scalar return values

Usually, the return value of oscript is a scalar: string, number, or boolean. It is just inserted in place of the oscript.

If the return value is an object, it is similarly expanded and inserted in place of the original oscript. This can be used to send prepared objects through trigger.data.

For example, if trigger.data is

{
    output: {address: "BSPVULUCOVCNXQERIHIBUDLD7TIBIUHU", amount: 2e5}
}

and an AA has this message

{
    app: "payment",
    payload: {
        asset: "base",
        outputs: [
            `{trigger.data.output}`
        ]
    }
}

The resulting message will be

{
    app: "payment",
    payload: {
        asset: "base",
        outputs: [
            {
                address: "BSPVULUCOVCNXQERIHIBUDLD7TIBIUHU",
                amount: 2e5
            }
        ]
    }
}

Flow control

return

return expr;

Interrupts the script's execution and returns the value of expr. This syntax can be used only in oscripts that are supposed to return a value.

return;

Interrupts the script's execution without returning any value. This syntax can be used only in statements-only oscripts: init and state.

if else

if (condition){
    $x = 1;
    $y = 2 * $x;
}
else{
    $x = 2;
    $z = $x^3;
}

Evaluates the first block of statements if the condition is truthy, the second block otherwise. The else part is optional.

If the block includes only one statement, enclosing it in {} is optional:

if (condition)
    $x = 1;

Complexity

Like other smart contract definitions, AAs have a capped complexity which cannot exceed 100. Some operations involve complex computation or access to the database, such operations are counted and add to the total complexity count. Other operations such as +, -, etc, are relatively inexpensive and do not add to the complexity count. The language reference indicates which operations count towards complexity.

Total complexity is the sum of complexities of all oscripts. It is calculated and checked only during deployment and includes the complexity of all branches even though some of them might not be activated at run time.

If the complexity exceeds 100, validation fails and the AA cannot be deployed.

Operators

Arithmetic operators +, -, *, /, %, ^

$amount - 1000
$amount^2 / 4

Operands are numbers or converted to numbers if possible.

Additional rules for power operator ^:

• e^x is calculated with exact (not rounded) value of e,

• an exponent greater or equal to MAX_SAFE_INTEGER will cause an error,

• for non-integer exponents, the result is calculated as x^y = e^(y * ln(x)) with rounding of the intermediary result, which causes precision loss but guaranties reproducible results;

• this operator adds +1 to complexity count.

Concatenation operator ||

'abc' || 'def'              // 'abcdef'
[4, 6] || [3, 1]            // [4, 6, 3, 1]
{x: 1, y: 7} || {y: 8, a:9} // {x: 1, y: 8, a:9}

If the same key is found in both objects, the value from the right-hand one prevails.

Trying to concat an array with object results in error.

If either operand is a scalar (strings, numbers, booleans), both are converted to strings and concatenated as strings. Objects/arrays become "true".

Binary logical operators AND, OR

Lowercase names and, or are also allowed.

Non-boolean operands are converted to booleans.

The result is a boolean.

If the first operand evaluates to true, second operand of OR is not evaluated.

If the first operand evaluates to false, second operand of AND is not evaluated.

Unary logical operator NOT

Lowercase name not is also allowed. The operator can be also written as !.

Non-boolean operand is converted to boolean.

The result is a boolean.

Operator OTHERWISE

Lowercase name otherwise is also allowed.

expr1 OTHERWISE expr2

If expr1 is truthy, its result is returned and expr2 is not evaluated. Otherwise, expr2 is evaluated and its result returned.

Comparison operators ==, !=, >, >=, <, <=

If both operands are booleans or both operands are numbers, the result is straightforward.

If both operands are strings, they are compared in lexicographical order.

If both operands are objects, only == and != are allowed, other operators will cause an error.

If operands are of different types:

• if any of them is an object or boolean, it causes an error,

• if any of them is a string, only == and != are allowed and non-string operand will be converted to string before comparison, other operators will cause an error,

• all other combinations of types cause an error.

Ternary operator ? :

condition ? expr1 : expr2

If condition is truthy, expr1 is evaluated and returned, otherwise expr2 is evaluated and returned.

Operator precedence

Operators have the following precedence in the order of decreasing "stickiness":

• ^

• !

• *, /, %

• +, -, ||

• ==, !=, >, >=, <, <=

• AND

• OR

• ?:

• OTHERWISE

Global constants

pi

Pi constant rounded to 15 digits precision: 3.14159265358979.

e

Euler's number rounded to 15 digits precision: 2.71828182845905.

Built-in functions

Type of variable

typeof(anything)

Returns "string", "number", "boolean" or "object".

Square root and natural logarithm

sqrt(number)
ln(number)

These functions add +1 to complexity count.

Negative numbers cause an error. Non-number inputs are converted to numbers or result in error.

Absolute value

abs(number)

Returns absolute value of a number. Non-number inputs are converted to numbers or result in error.

Rounding (round, ceil, floor)

round(number [, decimal_places])
ceil(number [, decimal_places])
floor(number [, decimal_places])

Rounds the input number to the specified number of decimal places (0 if omitted). round uses ROUND_HALF_EVEN rules. Non-number inputs are converted to numbers or result in error. Negative or non-integer decimal_places results in error. decimal_places greater than 15 results in error.

Minimum and maximum

min(number1, [number2[, number3[, ...]]])
max(number1, [number2[, number3[, ...]]])

Returns minimum or maximum among the set of numbers. Non-number inputs are converted to numbers or result in error.

Square root of the sum of squares

hypot(number1, [number2[, number3[, ...]]])

Returns the square root of the sum of squares of all arguments. Boolean parameters are converted to 1 and 0, objects are taken as 1, all other types result in error. The function returns a non-infinity result even if some intermediary results (squares) would overflow.

This function adds +1 to complexity count.

Get part of a string

substring(string, start_index)
substring(string, start_index, length)

Returns part of the string. If length is not set then returns rest of the string from start index. If start_index is negative then substring uses it as a character index from the end of the string. If start_index is negative and absolute of start_index is larger than the length of the string then substring uses 0 as the start_index.

Find starting index of searched string

index_of(string, search_string)

Returns integer index (starting from 0) of searched string position in string. If searched string is not found then -1 is returned. Use contains if you don't need to know the index of the searched string.

String search within string

starts_with(string, prefix)
ends_with(string, suffix)
contains(string, search_string)

Returns boolean true if the string starts, ends or contains searched string.

Uppercase/Lowercase string

to_upper(string)
to_lower(string)

Returns the string with changed case.

Replace string

replace(str, search_str, replacement)

Replaces all occurrences of search_str in str with replacement and returns the new string.

Validate string

has_only(str, allowed_chars)

Returns true if str consists only of characters in allowed_chars. allowed_chars is a group of characters recognized by regular expressions, examples: a-z0-9, \w. has_only adds +1 to complexity.

Seconds until specified date

parse_date(ISO8601_date)
parse_date(ISO8601_datetime)

Convert seconds to date + time, date or time

timestamp_to_string(timestamp)
timestamp_to_string(timestamp, 'datetime')
timestamp_to_string(timestamp, 'date')
timestamp_to_string(timestamp, 'time')

Parse a JSON string into object

json_parse(string)

Attempts to parse the input JSON string. If the result of parsing is an object, the object is returned. If the result is a scalar (boolean, string, number), the scalar is returned.

This function adds +1 to complexity count.

If parsing fails, false is returned.

Non-string input is converted to string.

Serialize an object into JSON string

json_stringify(object)

Stringifies the input parameter into JSON. The parameter can also be a number, boolean, or string. If it is a number outside the IEEE754 range, the formula fails. Objects in the returned JSON are sorted by keys.

Iteration methods (map, reduce, foreach, filter)

$ar = [2, 5, 9];
$ar2 = map($ar, 3, $x => $x^2);

The function for map, foreach, and filter accepts 1 or 2 arguments. If it accepts 1 argument, the value of each element is passed to it. If it accepts 2 arguments, key and value for objects or index and element for arrays are passed.

The second argument is the maximum number of elements that an array or object can have. If it is larger, the script fails. This number must be a constant so that it can be known at deploy time, and the complexity of the entire operation is the complexity of the callback function times maximum number of elements. If the function has 0 complexity, the total complexity of map/reduce/foreach/filter is assumed to be 1 independently of the max number of elements. Max number of elements cannot exceed 100.

A function is executed over each element of an array or object. The callback function can be anonymous like in the example above, or referenced by name:

$f = $x => $x^2;
$ar = [2, 5, 9];
$ar2 = map($ar, 3, $f);

$ar2 = map($ar, 3, $remote_aa.$f);

reduce has one additional argument for initial value:

$c = 3;
$ar = [2, 5, 9];

// sums all elements, will return 16
$acc = reduce($ar, $c, ($acc, $x) => $acc + $x, 0);

The callback function for reduce accepts 2 or 3 arguments: accumulator and value or accumulator, key, and value (accumulator, index, and element for arrays).