description |
---|
Obyte is cryptocurrency platform, which is written with NodeJS. This site is for developers and should help developers to get started using Obyte platform in their projects. |
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:
{% code title="package.json" %}
"dependencies": {
"headless-obyte": "git+https://github.com/byteball/headless-obyte.git",
"ocore": "git+https://github.com/byteball/ocore.git"
}
{% endcode %}
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:
{% code title="conf.js" %}
exports.bLight = true;
exports.hub = process.env.testnet ? 'obyte.org/bb-test' : 'obyte.org/bb';
{% endcode %}
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:
testnet=1
{% code title="index.js" %}
var headlessWallet = require('headless-obyte');
var eventBus = require('ocore/event_bus.js');
function onReady() {
let amount = 1; //in bytes
let user_address = "62SU7724ME5MWB7VEP64VURYZHDRSDWN"; // account address
let user_device_address = null; // device address
headlessWallet.issueChangeAddressAndSendPayment(
null /*asset, null for bytes*/,
amount,
user_address,
user_device_address,
(err, unit) => {
if (err){
return console.error(err);
}
// handle successful payment
});
// received new payment
eventBus.on('new_my_transactions', (arrUnits) => {
// handle new unconfirmed units here
// at this stage, payment is not yet confirmed
});
// payment is confirmed
eventBus.on('my_transactions_became_stable', (arrUnits) => {
// handle payments becoming confirmed
});
};
eventBus.once('headless_wallet_ready', onReady);
{% endcode %}
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.
====== my first address: 2PJHQKMP7NH6MUYUQPZ4S46C2Q7CQI32
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 https://github.com/byteball/headless-obyte/blob/master/start.js.
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:
{% code title="index.js" %}
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
});
{% endcode %}
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:
====== my pairing code: [email protected]/bb#0000
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):
<a href="byteball:[email protected]/bb#0000">Chat with my test bot</a>
You also need this pairing code to add your bot to the Bot Store.
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:
{% code title="index.js" %}
eventBus.on('paired', function(from_address, pairing_secret){
var device = require('ocore/device.js');
device.sendMessageToDevice(from_address, 'text', 'Hi! I am bot.');
});
{% endcode %}
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 Authenticating users on websites.
To receive chat messages, subscribe to 'text' events on event bus:
{% code title="index.js" %}
eventBus.on('text', function(from_address, user_message){
// your code here
});
{% endcode %}
from_address
is user's device address (not to be confused with payment addresses), user_message
is their message.
Messages to user's device can be sent with sendMessageToDevice
function in device
module:
{% code title="index.js" %}
var device = require('ocore/device.js');
var message_to_user = 'Message from bot to user';
device.sendMessageToDevice(from_address, 'text', message_to_user);
{% endcode %}
So, in case we want to echo back what user wrote, we could combine those two above examples into this:
{% code title="index.js" %}
var eventBus = require('ocore/event_bus.js');
var device = require('ocore/device.js');
eventBus.on('text', function(from_address, user_message){
device.sendMessageToDevice(from_address, 'text', user_message);
});
{% endcode %}
Great success, we now have a bot, which is like a parrot (repeating everything you wrote to it).
To give access to predefined commands, format your responses this way:
click this link: [Command name](command:command code)
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.
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:
Example command: we suggest to [buy (number) apples](suggest-command:buy 5 apples)
Here is how the result looks like:
That's it. You've completed your first chat bot on Obyte platform. You can check other chat bot examples provided by our team:
- Bot example: start from here
- Faucet: sending payments
- ICO bot: sending and receiving payments
- Merchant: receiving payments without storage of private keys
- Flight delay insurance: offering contracts
- Internal asset exchange: offering contracts
- GUI wallet: not a bot, but you'll find code for offering contracts
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. Tutorials for newcomers.