Type of repositories on Obyte Github page

Obyte Github page is located there https://github.com/byteball

ocore - main core library

• syncs full database if full node.

• relays storage units if full node.

obyte-gui-wallet - wallet apps with GUI

• inherits ocore library.

• light node or full node.

• wallet functionality.

• graphical user interface for Windows, MacOS, Linux, Android and iOS.

headless-obyte - wallet for server without GUI

• inherits ocore library.

• light node or full node.

• wallet functionality.

• can be controlled via chat.

obyte-witness - nodes that determine the main chain

• inherits headless-obyte and ocore library.

• only full node.

• recommended to be behind TOR.

obyte-relay - peer that can be connected directly

• inherits ocore library.

• only full node.

• accepts incoming connections.

• provides new units, stable units, balances & suitable parents to light nodes.

obyte-hub - hub that relays chat messages

• inherits obyte-relay and ocore library.

• relays encrypted chat messages between devices.

• notifies wallet apps about new app version.

bot-example - template for new projects

• inherits headless-obyte and ocore library.

• customized can be added.

• customized actions on and can be added.

Tutorials to setup a node

Examples of using these libraries

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

Most bot repositories have example .env.testnet file in their root folder. In order to connect use testnet network, just run cp .env.testnet .env. Backup and delete the database if you already ran it on MAINNET. Wallet app for website.

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

Storage backend -- mysql or sqlite, the default is sqlite. If sqlite, the database files are stored in the app data folder. If mysql, you need to also initialize the database with and set connection params:

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.

Accepting incoming connections

Obyte network works over secure WebSocket protocol wss://. To accept incoming connections, you'll need a valid TLS certificate (you can get a free one from ) and a domain name (you can get a free domain from ). Then you accept connections on standard port 443 and proxy them to your locally running Obyte daemon.

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

Many bots have a file named included in the repository, which looks like this

This can be executed with crontab with the command mentioned in and when the email is properly configured on the server and the node crashes, this script will notify you that the node went down.

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.

Above example is for wallet-less node, which will log the stdout and stderr (>> for appending) to file (). If the command uses parameters like --max-old-space-size=4096 then these should be added to both parameters, but output directing (1>log and 2>>err) should not be added to first parameter.

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.

An Autonomous Agent (AA) is a special address (account) on the ledger that acts according to a program associated with it. Its behavior is similar to that of a vending machine that receives coins and data entered on a keypad and in response, releases a cup of coffee, plays a song, or does whatever it was programmed to do.

Getting started developer guide

Introduction to Autonomous Agents (announcement post on Medium)

Oscript — the language of autonomous agents

Autonomous Agents are written in Oscript — a new programming language developed specifically for this purpose. The language is very simple and any developer who has experience in curly-brace languages such as JavaScript, PHP, Java, C/C++, etc should not have any difficulty learning it.

Some of the features of the language:

• convenient access to variables that describe the state of the ledger and the triggering (requesting, activating) transaction received. That’s what makes the language domain-specific. In particular, the following variables are available:

• amounts received in the triggering transaction;

• data received in the triggering transaction;

AA code can be deployed with and . There is also a and .

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:

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.

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:

Example:

Amount is in the smallest units, such as bytes. If you omit

There are two ways of making a contract between two Obyte users: either to agree on some conditions and formalize them in our Smart Contract Language, which later can be evaluated by machine code and decide who spends the money from the contract (), or just publish a hash of simple prosaic text of a contract into DAG ().

If you are looking to build more complex dApps that are as capable as Ethereum smart-contracts, then you need to use .

The smart contract language is declarative, meaning that it expresses what conditions must be met to allow movement of money, rather than how the decisions are made. This makes it easy to see that the implementation of the contract matches its intent, and hard to make mistakes (which cannot be undone in distributed ledgers).

However, the language is not as powerful as Ethereum’s Solidity, it is not Turing-complete, it doesn’t allow to code any program, rather it is a domain specific language for money on the distributed ledger. They are more like Discreet Log Contracts for Bitcoin. If you are looking to build more complex dApps that are as capable as Ethereum smart-contracts, then you need to use Autonomous Agents.

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

Offering smart contracts

When you want to create a new smart contract with a user, your sequence is usually as follows:

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

• you define a new contract using the user's address and your address as parties of the contract

• you pay your share to the contract

• at the same time, you send a specially formatted payment request (different from the payment request above) to the user to request his share. You start waiting for the user's payment

We'll discuss creating and offering contracts below. These two steps are similar to what happens in the GUI wallet when a user designs a new contract.

Creating contract definition

Create a JSON object that defines the contract:

Create another object that describes the positions of your and user addresses in the above definition:

The keys of this object are r (from "root") followed by indexes into arrays in the definition's orand and conditions. Since the conditions can be nested, there can be many indexes, they are separated by dot.

Then you create the smart contract address:

If the address was successfully created, it was also already automatically sent to the user, so the user's wallet will know it.

Example of vesting contracts: , , . Examples with oracles: , . Examples with tokens: , .

More definition examples can be seen on .

Sending a request for contract payment

To request the user to pay his share to the contract, create the below Javascript object objPaymentRequest which contains both the payment request and the definition of the contract, encode the object in base64, and send it over to the user:

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

Re-sending lost smart-contracts

Since smart-contracts are private until they have been spent, users might loose them if they probably didn't backup their wallet or restored from seed words. Some attestation bots lock user's reward for months or years into smart-contracts and it would be more user-friendly if users could still restore the smart-contract even after they have lost it. Since all parties (2 or more) have the definition of the smart-contract in their wallet, one could ask to resend it from the other. With chat bots, this could be done like this:

Hello. I’m starting a series of tutorials about creating projects on Obyte. Today we will consider the creation of ping-pong payment bot. First we will need Linux or MacOS, node.js, and . So, let's clone it and run

We run cp .env.testnet .env for changing it configuration to testnet network. When you starting bot at first, he will ask you passphrase(don’t forget it, since you need to enter each time you start). When starting bot in console you will see “my pairing code”. It looks like this: Copy this pairing code.

Now add our bot, open the Obyte wallet and go to Chat (below) > Add a new device > Accept invitation from the other device then insert your pairing code (instead of an asterisk any word, for example, test) and click "PAIR”

After that you will have a chat with your bot, write to him and he will answer you with your message. All right, now let's teach the bot to give us our money back.

To begin developing any app which is based on headless-obyte, first thing to do is to set up your machine, install Node.js and tools. Complete guide of preparing your blank Debian-based machine for Obyte development. You can skip this step if you are familiar with Node.js development and already know how to do it in your way.

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.

Full configuration options are described in Configuration section. As for now, in your configuration file (conf.js in project folder or conf.json in user folder) switch your app to light node and add hub URL:

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.

There are many other functions for sending payments, for example sending multiple payments in multiple assets at the same time, see exports of .

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 [email protected]: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):

You also need this pairing code to add your bot to the .

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:

The behavior of your event handler can depend on pairing_secret, the second argument of the event handler. For example, you can have a one-time (non-permanent) pairing secret equal to session ID on your website; after the user clicks the pairing link and opens chat, you can link his chat session with his web session, see .

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:

The user will see the text in square brackets "Command name", it will be highlighted as a link, and when the user clicks it, his app will send command code text to your bot.

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:

Here is how the result looks like:

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:

• : start from here

• : sending payments

• : sending and receiving payments

• : receiving payments without storage of private keys

Now you are ready to make something useful, go ahead to our Tutorials section and carefully read all of them to get better understanding of Obyte code API. .

• - official core networking and consensus library for node.js

• - official wallet and messaging library for node.js

• - official messaging library for node.js and browsers

You can also verify ownership of address by requesting a payment from their address and this method is more appropriate if you need to receive a payment anyway.

To request the user to sign a message, send this message in chat:

where challenge is the message to be signed. This request will be displayed in the user's wallet as a link that the user can click and confirm signing. Once the user signs it, your chat bot receives a specially formatted message:

You can parse and validate it, here is an example how to verify user's account address:

The above code also checks that the user signed the correct message and with the correct address.

objSignedMessage received from the peer has the following fields:

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.

The first thing you should consider, is whether you want to run your bot on a full node or a light node. When setting up the server, the choice to run on a full node will mean you need to make sure to have enough disk space available. The installation is the same whether you run a full node or a light node, but running a full node will allow your bot to have access to all units ever posted to the DAG and thereby be able to perform more complex tasks. If light wallet is enough for you and have no interest in renting a VPS then you can run a light Obyte headless wallet also on Raspberry Pi 3+.

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.

• 1 server (with Debian in this case)

• At least 140-150 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.

Having created the server, I need to connect to the server. I use a super lightweight SSH terminal called “putty” from my Windows laptop.(available on )

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

(thanks to for the above two commands)

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

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

You will also need for cases where the pre-built binaries (secp256k1, sqlite, rocksdb) are not available for your system configuration. That you can install with this command: npm install -g node-gyp

Installing the Headless Wallet

So far so good - we’re now almost ready to start actually installing the headless wallet. But first. We need to find the repository that we want to clone. Go to and click the “Clone or download” button:

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)

There is also a detailed explanation of the values on at the section called “Customize”.

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

Since Obyte runs on an SQLite database by default, which is , you might want to be able to explore the data stored yourself, thereby making it easier to create the logic for the bot if you need to access data in the databases. If you wish to then that can be changed with a configuration file. apt-get install sqlite3

Monitoring logs

Checking the log to see if things are running (by default, log file is in ):

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

Full documentation for headless Obyte node can be found there

Data with any structure

To send data to DAG database, code below is a minimal that you can use. Since the opts.messages is array, it means that all the examples on this page can be changed to multi-message transactions.

AAs can be triggered with data by manually entering the key/value pairs to GUI wallet, prompting users to submit pre-filled Send screen, making the AA to trigger another AA or with the script from headless wallet.

Key-value data feed

Previous example shows how to send any data to DAG, but if you would want to store data that is searchable and can be used in or then you would need to post it as key-value pairs and with app type data_feed. If we also send it always from the same first address in our wallet then we have basically become an oracle.

Profile about yourself

Anybody on Obyte network can post some data about themselves, which will be linked to their address. This app type is called profile. Payload for that message can contain any keys. For example, web service lets you post a profile with keys like this:

Attestation profile

Attestation profile is similar to previous one with one difference that attestation type message are posted by somebody and they describe somebody else. These profiles are used to do KYC by .

Private/Public attestations

bot creates an attestation profile, which keeps all the data private on user device while makes it possible for the others to recognize unique users by user_id (it's a salted hash of first_name, last_name, dob and country) and also makes it possible to validate with profile_hash if user provides them a private profile.

In case user would want to make their profile public like with and , true could be sent as a second parameter of hideProfile() function. To avoid people doxxing themselves, the possibility to make public attestation with Real Name Attestation has not been included. This choice is only on Email Attestation and Steem Attestation.

In order for the user to share private profile with others, your bot should also .

Public only attestations

If there is no plan to provide private attestations and all the attestation will always be public then there is no need for user_id. Then the attestation profile can be as simple as this, but the attestator needs to make sure that the same username attestation is not done to multiple users. One example of that kind is .

For public attestation, there is not private profile to send to user's wallet because the bots who need information about the user could simply just .

Poll question and choices

Anybody can post a poll and let others vote on it, this can be done like this data and it will also appear on web service from where it will direct users to .

Plain text data

And last and not the least, it is possible to post plain text to DAG too.

More examples

Shorter code examples using composer library are available in .

If you wish to send data to DAG database periodically then full code examples for , or can be found on Github.

Contracts with arbitration are peer-to-peer free-form textual contracts coupled with simple smart contracts that safely lock the money for the duration of the contract and allow disputes to be resolved by mutually agreed arbiters. In other words, a contract with arbitration is a prosaic contract plus a smart contract that guarantees that the parties faithfully follow the contract.

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.

All the API methods available for your bot are located in file.

Example

There is an example script for a part of the API functionality in inside headless-wallet repository, you can start by modifying it to your needs:

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:

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

This is API documentation to integrate cashback to your point of sale device, but you could also build your own cashback app, where this API has already been implemented. The first thing you need sign up to Cashback Program in order to get partner name and partner key.

After you accepted payment from the customer, you use this API to request cashback for your customer. You send a POST request to:

https://byte.money/new_purchase

(for testnet use https://byte.money/test/new_purchase)

and pass the following parameters:

• partner: (string) your partner name you were assigned when you signed up for the program.

• partner_key: (string) partner key used to authenticate your requests.

• customer: (string) any id of the customer who made a purchase such as customer name or id in your database. This field must be the same when the same customer makes another purchase.

• order_id: (string) unique id of the order associated with the purchase. You should never request cashback for the same order id again.

• description: (string) description of the purchase.

• merchant: (string) this field is used by payment processors only to identify the individual merchant. When another purchase is made from the same merchant, this fiels should be the same.

• address: (string) Wallet address or email address of the customer. The cashback will be sent to this address. If it is email address, a will be sent. If the textcoin is not claimed within 1 week, it will be taken back.

• currency: (string) currency of the purchase. Supported values: USD, EUR, RUR, GBYTE, BTC. If the purchase was paid in any other currency, you should convert its amount to any of the supported currencies except GBYTE.

• currency_amount: (number) amount of the purchase in currency.

• partner_cashback_percentage: (number) the percentage of the amount you want to pay to the customer out of your own funds in addition to the regular cashback. Obyte will add the same percentage out of the distribution fund (merchant match). Default it 0. You have to deposit the funds in advance in order to fund this option.

• purchase_unit: (string) unit (transaction id) of the customer's purchase if it was paid in GBYTE.

Response format

The response is in JSON format. It always contains a result field, which is either 'ok' or 'error'.

If the cashback was successfully sent to the customer, the response has "result": "ok" and also indicates the cashback amount and the unit it was sent in:

In case of an error, the response has "result": "error" and error description in error field:

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.

We will need bot-example. Let’s install it.

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

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

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

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

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

Create correspondents.js

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

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

That’s all. I also have a homework for you. Complete the oracle and our bot so that oracle informs us that he published and the publication has become stable. After oracle message, notify the user that he lost or won. And if he lost then take the money out of the contract. All code is available on . Did you like the lesson? Any questions? What topics have caused you difficulties and it is worth talking about them? Write in the comments and I will help you. Also join my telegram chat - .

To start a user-defined asset on Obyte, you need to complete two steps

• Define your asset. Asset definition is a special type of message (distinct from payments) that you send to the Obyte DAG

• Issue the asset by sending the 1st transaction that spends it

Asset ID

After an asset is defined, the hash of the unit where it was defined becomes the unique ID of the asset. The asset is referenced by this ID in future payments and definitions (smart contracts). There are no user-assignable names of assets in the protocol, but there are independent registries that link asset IDs to user-friendly names for a fee. One such registry is , another decentralized registry is

If you are not a developer, but wish to issue an asset on Obyte then you can also use to do that without writing any code. If Obyte Asset Registry is too limited for your needs or you need to issue an asset on TESTNET then continue reading.

Defining a new asset

See a sample of asset-defining transaction at .

To define a new asset you need a headless wallet. In your dependencies:

Call this function to create a new asset definition and broadcast it:

Here my_address is your address you use to post the asset-defining message. The address must be funded to pay at least the transaction fees (about 1000 bytes).

asset is a javascript object that describes the properties of your asset. Here is an example:

cap is the total number of coins that can be issued (money supply). If omitted, the number is unlimited.

is_private: indicates whether the asset is private (such as blackbytes) or publicly traceable (similar to bytes).

is_transferrable: indicates whether the asset can be freely transferred among arbitrary parties or all transfers should involve the definer address as either sender or recipient. The latter can be useful e.g. for loyalty points that cannot be resold.

auto_destroy: indicates whether the asset is destroyed when it is sent to the definer address.

fixed_denominations: indicates whether the asset exists as coins (banknotes) of a limited set of denominations, similar to blackbytes. If it is true, the definition must also include property denominations, which is an array of all denominations and the number of coins of that denomination:

issued_by_definer_only: indicates whether the asset can be issued only by the definer address. If false, anyone can issue the asset, in this case cap must be unlimited and it would make sense that issuing is limited by issue_condition.

cosigned_by_definer: indicates whether each operation with the asset must be cosigned by the definer address. Useful for regulated assets where the issuer (bank) wants to perform various compliance checks (such as the funds are not arrested by a court order) prior to approving a transaction. This could also be used to allow fee-less asset transfers for users (paid by definer), but wallets don't support that yet.

spender_attested: indicates whether the spender of the asset must be attested by one of approved attestors. Also useful for regulated assets e.g. to limit the access to the asset only to KYC'ed users. If true, the definition must also include the list of approved attestor addresses:

The definition can also include two optional properties issue_condition and transfer_condition which specify the restrictions when the asset can be issued and transferred. They evaluate to a boolean and are coded in the same as address definitions.

The above conditions stipulate that the newly defined asset can be issued if the issuer also sends equal amount of bytes to the address MO7ZZIU5VXHRZGGHVSZWLWL64IEND5K2, and it can be transferred if equal amount of bytes is transferred to the same address at the same time.

Issuance of a new asset

The new asset can be issued after its definition is confirmed. To issue, you need just to spend the asset from an address that is allowed to issue and it will be issued to address you transferred it.

You cannot use wallet.sendMultiPayment(), headlessWallet.issueChangeAddressAndSendPayment()and similar functions because they can do only transfers and they don't know about addresses that can issue new coins. Instead, you have to use lower level functions:

• composeAndSaveDivisibleAssetPaymentJoint from ocore/divisible_asset.js

• composeAndSaveIndivisibleAssetPaymentJoint from ocore/indivisible_asset.js

See (assets without fixed denominations) and (assets with fixed denominations) for examples.

See an example of how an asset can be both defined and issued in a single script

Whitepaper

For more details see chapter 24 of the .

Authentication

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

sig

Requirements

• A Obyte light wallet to provide us with your merchant Obyte address (you do not need to run the heavy full wallet, we are running it for you). Download the wallet from .

For exchanges and other custody wallets, there is a specialized JSON RPC service. However it is limited and exposes only those functions that the exchanges need.

If you are developing a service on Obyte and your programming language is node.js, your best option is to just require() the ocore modules that you need (most likely you need headless-obyte and various modules inside ocore). This way, you'll also be running a Obyte node in-process.

If you are programming in another language, or you'd like to run your Obyte node in a separate process, you can still access many of the functions of headless-obyte and ocoreby creating a thin RPC wrapper around the required functions and then calling them via JSON-RPC.

Get started

To get started, we can add RPCify to existing project or directly to headless-obyte with this command:

See the documentation about for more details.

Exposing functions and events

To expose the required functions via JSON-RPC, create a project that has headless-obyte, ocore (and any other ocore modules) and as dependencies:

Calling with HTTP requests

From another Node.js app, calling the function would look something like this:

Listening via WebSockets

From another Node.js app, sending function calls and listening to events would look something like this:

Example:

Following is a list of justsaying type JSON messages that are sent over the network:

Send version information

By default, RPC service is not enabled for security reasons. To enable it, you should start your headless node differently: instead of node start.js, cd to tools folder and start RPC-enabled node:

This headless node works as usual, plus it listens to port 6332 of loop-back interface (configured in or conf.json) for JSON-RPC commands. Here are some of the commands that are usually needed by custody wallet solutions, like exchanges (these are similar to older Bitcoin node RPC methods): getinfo, getnewaddress, validateaddress, getbalance, listtransactions, sendtoaddress