Core library for Byteball
Switch branches/tags
Nothing to show
Clone or download
Failed to load latest commit information.
.circleci 46 (#48) Sep 22, 2017
test 57 (#58) Oct 11, 2017
.editorconfig tabs Aug 14, 2016
.gitignore Move getSourceString to String Utils Sep 23, 2017
LICENSE license Aug 14, 2017 new link Jun 26, 2017
archiving.js purge original_addresses when deleting unit Jun 23, 2018
balances.js ensure blackbytes come second if nonzero Jul 20, 2018
bots.js removed debugging line; May 31, 2017
breadcrumbs.js log when breadcrumbing May 9, 2017
byteball-sqlite-light.sql ios push notifications Jul 19, 2018
byteball-sqlite.sql Merge remote-tracking branch 'upstream/master' Jul 20, 2018
byteball.sql ios push notifications Jul 19, 2018
catchup.js order catchup units to minimize MC rebuilds Nov 10, 2017
chash.js try/catch invalid base32 and return false Sep 17, 2017
chat_storage.js message parsing in byteball, removed from core Apr 14, 2017
check_daemon.js check and restart daemon Aug 27, 2016
composer.js typo composeDedinitionTemplateJoint Sep 29, 2018
conf.js function removeCorrespondentDevice added (#15) Apr 16, 2017
constants.js witnessedLevelMustNotRetreatUpgradeMci Sep 10, 2018
db.js optional onDone Jul 15, 2018
definition.js remove own_funds Aug 17, 2018
desktop_app.js tabs Aug 20, 2016
device.js check fields in encrypted package Sep 12, 2018
divisible_asset.js don't check arrAttestedAddresses if light Sep 29, 2018
email_template.html openapp.html -> index.html Jan 25, 2018
enforce_singleton.js prevent loading multiple copies of byteballcore Aug 17, 2016
event_bus.js setMaxListeners 20 Dec 22, 2016
graph.js exit earlier in determineIfIncluded Sep 17, 2018
headers_commission.js option to run some operations in js thus reducing sql usage (still ex… Aug 17, 2018
indivisible_asset.js better logging Jul 10, 2018
initial.byteball-light.sqlite add index outputsIsSerial Mar 22, 2018
initial.byteball.sqlite initial dbs Mar 19, 2018
inputs.js spend unconfirmed funds Jul 5, 2018
joint_storage.js purge uncovered under handleJoint lock to make sure it is not overlap… Sep 13, 2018
light.js all parents when building link proof for light Oct 15, 2018
light.sql tabs Aug 20, 2016
light_wallet.js light wallets: request asset info as soon as a new asset is received Oct 4, 2018
mail.js custom smtp port May 25, 2018
main_chain.js exclude more best children that cannot be included in later units Sep 10, 2018
mc_outputs.js manually join conflicting units to avoid too many sql variables Jul 25, 2017
merkle.js expect element, not its hash, in the definition Mar 2, 2017
mutex.js better locks to avoid unnecessary db queries while processing private… Jun 25, 2018
my_witnesses.js index by sequence Mar 3, 2017
mysql_pool.js promises Sep 21, 2018
network.js notifyWatchers and emit new_my_transactions in light wallets too Sep 22, 2018
object_hash.js clean nulls from device messages Sep 12, 2018
object_length.js more info in exceptions Aug 19, 2017
package.json 0.2.93 Aug 17, 2018
paid_witnessing.js option to run some operations in js thus reducing sql usage (still ex… Aug 17, 2018
parent_composer.js more details about no new parents exception Jul 21, 2018
private_payment.js Fixed light client update (#27) May 14, 2017
private_profile.js insert only disclosed private profile fields Mar 31, 2018
profiler.js option to run some operations in js thus reducing sql usage (still ex… Aug 17, 2018
signature.js safer signature checking Jul 8, 2017
sqlite_migrations.js ios push notifications Jul 19, 2018
sqlite_pool.js promises Sep 21, 2018
storage.js attestor list for light wallets Sep 29, 2018
string_utils.js var for old androids Oct 24, 2017 style guide Feb 21, 2018
uri.js recognize textcoin uris without textcoin? prefix Sep 22, 2018
validation.js typo Sep 29, 2018
validation_utils.js send done Nov 9, 2017
wallet.js select only unspent outputs on textcoin address Oct 4, 2018
wallet_defined_by_addresses.js "secret" support in sendMultiPayment Mar 22, 2018
wallet_defined_by_keys.js check address on old index and create if none found Apr 25, 2018
wallet_general.js send done Nov 9, 2017
witness_proof.js faster reading of definitions of witnesses Jul 7, 2018
writer.js log unit in stats Sep 17, 2018

Byteball core

This is a library used in Byteball clients. Never used directly. Some of the clients that require the library:

  • Byteball - GUI wallet for Mac, Windows, Linux, iOS, and Android.
  • Headless Byteball - headless wallet, primarily for server side use.
  • Byteball Relay - relay node for Byteball network. It doesn't hold any private keys.
  • Byteball Hub - hub for Byteball network. Includes the relay, plus can store and forward end-to-end encrypted messages among devices on the Byteball network.

Developer guides

See the wiki. Many of the features are not documented yet, see other byteball repositories as samples, for APIs see the exports of node.js modules.


The default settings are in the library's conf.js, they can be overridden in your project root's conf.js (see the clients above as examples), 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.


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


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 byteball daemon that listens on port 6611 on the local interface.

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 byteball.sql and set connection params, e.g. in conf.json in the app data folder:

	"port": 6611,
	"storage": "mysql",
	"database": {
		"max_connections": 30,
		"host"     : "localhost",
		"user"     : "byteball",
		"password" : "yourmysqlpassword",
		"name"     : "byteball"


Work as light client (true) or full node (false). The default is full client.


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


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.


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.

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)

Accepting incoming connections

Byteball 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 Freenom). Then you accept connections on standard port 443 and proxy them to your locally running byteball daemon.

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

server {
	listen 80 default_server;
	listen [::]:80 default_server;
	listen 443 ssl;
	listen [::]:443 ssl;
	ssl_certificate "/etc/letsencrypt/live/";
	ssl_certificate_key "/etc/letsencrypt/live/";

	if ($host != "") {
		rewrite ^(.*)$$1 permanent;
	if ($https != "on") {
		rewrite ^(.*)$$1 permanent;

	location = /bb {
		proxy_pass http://localhost:6611;
		proxy_http_version 1.1;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";

	root /var/www/html;
	server_name _;