/qubic-js

Primary LanguageJavaScriptOtherNOASSERTION

qubic-js

Qubic client library. This is work in progress.

Installation

With pnpm:

pnpm add qubic-js

With yarn:

yarn add qubic-js

With npm:

npm i qubic-js

Include in your project

import * as qubic from 'qubic-js';


qubic


qubic.exports.crypto : Promise.<Crypto>

A promise which always resolves to object with crypto functions.


qubic.client(options) ⇒ Client

Emits: info, open, close, error, inclusion, rejection

Param Type Default Description
options object Client options.
options.seed string Seed in 55 lowercase latin chars.
[options.index] number 0 Identity index.
[options.connection] Connection Client connection.
[options.computors] Array.<object> Specifies 3 computors to connect to, and with what options. Ignored when connection option is used.
options.computors[].url string Computor url.
[options.computors[].options] object WebSocket options.
[options.synchronizationInterval] number If no new tick appears after this interval an info event is emitted with updated sync status. Ignored when connection option is used.
[options.adminPublicKey] string Admin public key, for verification of current epoch and tick which are signed by admin. Ignored when connection option is used.
[options.reconnectTimeoutDuration] number 100 Reconnect timeout duration. Ignored when connection option is used.
[options.db] object Database implementing the level interface, for storing transactions.
[options.dbPath] string Database path.

Example

import qubic from 'qubic-js';

const client = qubic.client({
  seed: 'vmscmtbcqjbqyqcckegsfdsrcgjpeejobolmimgorsqwgupzhkevreu',
  computors: [
    { url: 'wss://AA.computor.com' },
    { url: 'wss://AB.computor.com' },
    { url: 'wss://AC.computor.com' },
  ],
  synchronizationInterval: 60 * 1000,
  adminPublicKey: '97CC65D1E59351EEFC776BCFF197533F148A8105DA84129C051F70DD9CA0FF82',
});

client.addListener('error', function (error) {
  console.log(error.message);
});
client.addListener('info', console.log);


qubic.connection(params) ⇒ Connection

Emits: info, open, close, error

Param Type Default Description
params object Connection params.
params.computors Array.<object> Specifies 3 computors to connect to, and with what options.
params.computors[].url string Computor url.
[params.computors[].options] object WebSocket options. Node.js only.
params.synchronizationInterval number If no new tick appears after this interval an info event is emitted with updated sync status.
params.adminPublicKey string Admin public key, for verification of current epoch and tick which are signed by admin.
[params.reconnectTimeoutDuration] number 100 Reconnect timeout duration.

Example

import qubic from 'qubic-js';

const connection = qubic.connection({
  computors: [
    { url: 'wss://AA.computor.com' },
    { url: 'wss://AB.computor.com' },
    { url: 'wss://AC.computor.com' },
  ],
  synchronizationInterval: 60 * 1000,
  adminPublicKey: '97CC65D1E59351EEFC776BCFF197533F148A8105DA84129C051F70DD9CA0FF82',
});

connection.addListener('error', function (error) {
  console.log(error.message);
});
connection.addListener('info', console.log);


qubic.privateKey(seed, index, K12) ⇒ Uint8Array

Generates a private key from seed.

Returns: Uint8Array - Private key bytes.

Param Type Description
seed string Seed in 55 lowercase latin chars.
index number Identity index.
K12 K12 K12 function.


qubic.identity(seed, index) ⇒ Promise.<string>

Creates an identity with checksum.

Returns: Promise.<string> - Identity with checksum in uppercase hex.

Param Type Description
seed string Seed in 55 lowercase latin chars.
index number Identity index.


qubic.verifyChecksum(identity) ⇒ Promise.<boolean>

Validates integrity of identity with checksum.

Param Type Description
identity string Identity in uppercase hex.


qubic.seedChecksum(seed) ⇒ Promise.<string>

Returns: Promise.<string> - Seed checksum in uppercase hex.

Param Type Description
seed string Seed in 55 lowercase latin chars.


qubic.transaction(params) ⇒ Promise.<Transaction>

Creates a transaction which includes a transfer of energy between 2 entities, or an effect, or both. Transaction is atomic, meaaning that both transfer and effect will be proccessed or none.

Param Type
params TransferParams, EffectParams, TransferAndEffectParams

Example

import qubic from 'qubic-js';

qubic
  .transaction({
    seed: 'vmscmtbcqjbqyqcckegsfdsrcgjpeejobolmimgorsqwgupzhkevreu',
    senderIdentity: 'DCMJGMELMPBOJCCOFAICMJCBKENNOPEJCLIPBKKKDKLDOMKFBPOFHFLGAHLNAFMKMHHOAE',
    index: 1337,
    identityNonce: 0,
    recipientIdentity: 'BPFJANADOGBDLNNONDILEMAICAKMEEGBFPJBKPBCEDFJIALDONODMAIMDBFKCFEEMEOLFK',
    energy: qubic.energy(1),
  })
  .then(function (transaction) {
    console.log(transaction);
  })
  .catch(function (error) {
    console.log(error.message);
  });


Client

Mixes: Connection


"inclusion"

Inclusion event.

Properties

Name Type Description
messageDigest string Hash of included transaction in uppercase hex.
epoch number Epoch at which transaction was included.
tick number Tick at which transaction was included.


"rejection"

Rejection event.

Properties

Name Type Description
messageDigest string Hash of rejected transaction in uppercase hex.
reason string Reason of rejection.


Client.identity : string

Client identity in uppercase hex.


Client.transaction(params) ⇒ Transaction

Creates a transaction which includes a transfer of energy between 2 entities, or an effect, or both. Transaction is atomic, meaaning that both transfer and effect will be proccessed or none.

Transactions are stored in database and their inclusion or rejection are monitored.

Returns: Transaction - Transaction object.

Param Type Description
params object
params.recipientIdentity string Recipient identity in uppercase hex.
params.energy bigint Transferred energy to recipient identity.
params.effectPayload TypedArray Effect payload.


Client.addEnvironmentListener(environment, listener)

Subcribes to an environment.

Param Type Description
environment string Environment hash.
listener function

Example

const listener = function (data) {
  console.log(data);
};

client.addEvironmentListener(
  'BPFJANADOGBDLNNONDILEMAICAKMEEGBFPJBKPBCEDFJIALDONODMAIMDBFKCFEE',
  listener
);


Client.removeEnvironmentListener(environment, listener)

Unsubscribes from an environment.

Param Type Description
environment string Environment hash.
listener function


Client.terminate([options])

Closes database and connections to computors.

Param Type Default
[options] object
[options.closeConnection] boolean true


Client.launch()

Launches client by opening database and connections to computors.

Emits: info, open, close, error, inclusion, rejection


Client.close()

Terminates all 3 WebSocket connections.

Mixes: close


Client.sendCommand(command, payload) ⇒ Promise.<object> | EventEmitter | void

Sends a client command to each connected computor, and compares responses before resolving. Available client commands:

Command Request Response Description
1 { identity } { identity, identityNonce } Fetches identityNonce.
2 { identity } { identity, energy } Fetches energy.
3 { message, signature } void Sends a transaction with base64-encoded message & signature fields.
4 { messageDigest } { messageDigest, inclusionState, tick, epoch } or { messageDigest, reason } Fetches status of a transaction. Rejects with reason in case identity nonce has been overwritten.
5 { environmentDigest } { environmentDigest, epoch, tick, data } Subscribes to an environment by its digest.
6 { environmentDigest } { environmentDigest } Cancels environment subscription.

Mixes: sendCommand

Param Type Description
command number Command index, must be an integer.
payload object Request payload.


Client.setComputorUrl(index, url)

Sets one of the 3 computors url each time.

Mixes: setComputorUrl

Param Type Description
index number Index of computor connection, 0, 1 or 2.
url string Computor url.


Client.open()

Opens all 3 WebSocket connections.

Mixes: open
Emits: info, open, close, error


Client.computors() ⇒ Array.<string>

Mixes: computors
Returns: Array.<string> - Array of computor urls.


Connection


"info"

Info event.

Properties

Name Type Description
syncStatus number Indicates which of the 3 computors have provided the same tick and epoch. 0 when offline, 3 when fully synced.
epoch number Current epoch.
tick number Current tick.


"open" (event)

Open event. Emitted when a WebSocket connection opens.

Param Type Description
event event WebSocket event.


"error" (event)

Error event. Emitted when a WebSocket connection errors.

Param Type Description
event event WebSocket event.


"close" (event)

Close event. Emitted when a WebSocket connection closes.

Param Type Description
event event WebSocket event.


Connection.close()

Terminates all 3 WebSocket connections.


Connection.sendCommand(command, payload) ⇒ Promise.<object> | EventEmitter | void

Sends a client command to each connected computor, and compares responses before resolving. Available client commands:

Command Request Response Description
1 { identity } { identity, identityNonce } Fetches identityNonce.
2 { identity } { identity, energy } Fetches energy.
3 { message, signature } void Sends a transaction with base64-encoded message & signature fields.
4 { messageDigest } { messageDigest, inclusionState, tick, epoch } or { messageDigest, reason } Fetches status of a transaction. Rejects with reason in case identity nonce has been overwritten.
5 { environmentDigest } { environmentDigest, epoch, tick, data } Subscribes to an environment by its digest.
6 { environmentDigest } { environmentDigest } Cancels environment subscription.
Param Type Description
command number Command index, must be an integer.
payload object Request payload.


Connection.setComputorUrl(index, url)

Sets one of the 3 computors url each time.

Param Type Description
index number Index of computor connection, 0, 1 or 2.
url string Computor url.


Connection.open()

Opens all 3 WebSocket connections.

Emits: info, open, close, error


Connection.computors() ⇒ Array.<string>

Returns: Array.<string> - Array of computor urls.


Crypto : object


Crypto.schnorrq : object


schnorrq.generatePublicKey(secretKey) ⇒ Uint8Array

Param Type
secretKey Uint8Array


schnorrq.sign(secretKey, publicKey, message) ⇒ Uint8Array

Param Type
secretKey Uint8Array
publicKey Uint8Array
message Uint8Array


schnorrq.verify(publicKey, message, signature) ⇒ number

Returns: number - 1 if valid, 0 if invalid

Param Type
publicKey Uint8Array
message Uint8Array
signature Uint8Array


Crypto.kex : object


kex.generateCompressedPublicKey(secretKey) ⇒ Uint8Array

Returns: Uint8Array - Public key

Param Type
secretKey Uint8Array


kex.compressedSecretAgreement(secretKey, publicKey) ⇒ Uint8Array

Returns: Uint8Array - Shared key

Param Type
secretKey Uint8Array
publicKey Uint8Array


Crypto.K12(input, output, outputLength, outputOffset)

Param Type Default
input Uint8Array
output Uint8Array
outputLength number
outputOffset number 0


TransferParams : object

Properties

Name Type Description
seed string Seed in 55 lowercase latin chars.
index number Index of private key which was used to derive sender identity.
senderIdentity string Sender identity in uppercase hex.
identityNonce number Identity nonce.
energy bigint Transferred energy to recipient identity.
recipientIdentity string Recipient identity in uppercase hex.


EffectParams : object

Properties

Name Type Description
seed string Seed in 55 lowercase latin chars.
index number Index of private key which was used to derive sender identity.
senderIdentity string Sender identity in uppercase hex.
identityNonce number Identity nonce.
effectPayload Uint8Array Effect payload


TransferAndEffectParams : object

Properties

Name Type Description
seed string Seed in 55 lowercase latin chars.
index number Index of private key which was used to derive sender identity.
senderIdentity string Sender identity in shifted uppercase hex.
identityNonce number Identity nonce.
energy bigint Transferred energy to recipient identity.
recipientIdentity string Recipient identity in shifted uppercase hex.
effectPayload Uint8Array Effect payload


Transaction : object

Properties

Name Type Description
hash string Transaction hash in shifted uppercase hex.
message string Base64-encoded signed message.
signature string Base64-encoded signature.