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

qubic

• qubic
  • .exports.crypto : Promise.<Crypto>
  • .createClient(options) ⇒ Client
  • .createConnection(params) ⇒ Connection
  • .privateKey(seed, index, K12) ⇒ Uint8Array
  • .createIdentity(seed, index) ⇒ Promise.<string>
  • .verifyChecksum(identity) ⇒ Promise.<boolean>
  • .seedChecksum(seed) ⇒ Promise.<string>
  • .createTransfer(params) ⇒ Promise.<object>

qubic.exports.crypto : Promise.<Crypto>

A promise which always resolves to object with crypto functions.

qubic.createClient(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 transfers. | | [options.dbPath] | string | | Database path. |

Example

import { createClient } from 'qubic-js';

const client = createClient({
  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.createConnection(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 { createConnection } from 'qubic-js';

const connection = createConnection({
  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.createIdentity(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.createTransfer(params) ⇒ Promise.<object>

Creates a transfer of energy between 2 entities.

| Param | Type | Description | | --- | --- | --- | | params | object | | | params.seed | string | Seed in 55 lowercase latin chars. | | params.from | object | | | params.from.identity | string | Sender identity in uppercase hex. | | params.from.index | number | Index of private key which was used to derive sender identity. | | params.from.identityNonce | number | Identity nonce. | | params.from.enery | bigint | Energy of sender identity. | | params.to | object | | | params.to.identity | string | Recipient identity in uppercase hex. | | params.to.energy | bigint | Transferred energy to recipient identity. |

Example

import { createTransfer } from 'qubic-js';

createTransfer({
  seed: 'vmscmtbcqjbqyqcckegsfdsrcgjpeejobolmimgorsqwgupzhkevreu',
  from: {
    identity: '9F6ADD0C591DBB8C0CE1EDF6F63A9E1C7BD22CFBD20DE1469ADAA76A9C0023707BE416',
    index: 1337,
    identityNonce: 0,
    energy: bigInt(2),
  },
  to: {
    identity: 'CD5B4A78521A9F9428F442E60E25DA63247817AB6BBF406CC91393F6664E38CBFE68DC',
    energy: bigInt(1),
  },
})
  .then(function (transfer) {
    console.log(transfer);
  })
  .catch(function (error) {
    console.log(error.message);
  });

Client

Mixes: Connection

• Client
  • instance
    • "inclusion"
    • "rejection"
  • static
    • .identity : string
    • .createTransfer(to) ⇒ object
    • .terminate([options])
    • .launch()
    • .close()
    • .sendCommand(command, payload) ⇒ Promise.<(object|void)>
    • .setComputorUrl(index, url)
    • .open()
    • .computors() ⇒ Array.<string>

"inclusion"

Inclusion event.

Properties

| Name | Type | Description | | --- | --- | --- | | hash | string | Hash of included transfer in uppercase hex. | | epoch | number | Epoch at which transfer was included. | | tick | number | Tick at which transfer was included. |

"rejection"

Rejection event.

Properties

| Name | Type | Description | | --- | --- | --- | | hash | string | Hash of rejected transfer in uppercase hex. | | reason | string | Reason of rejection. |

Client.identity : string

Client identity in uppercase hex.

Client.createTransfer(to) ⇒ object

Returns: object - Transfer object.

| Param | Type | Description | | --- | --- | --- | | to | object | | | to.identity | string | Recipient identity in uppercase hex. | | to.energy | bigint | Transferred energy to recipient identity. |

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|void)>

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

| Command | Payload | Response | Description | | --- | --- | --- | --- | | 1 | { identity } | { identity, identityNonce } | Fetches identityNonce. | | 2 | { identity } | { identity, energy } | Fetches energy. | | 3 | { message, signature } | void | Sends a transfer with base64-encoded message & signature fields. | | 4 | { hash } | { hash, inclusionState, tick, epoch } or { hash, reason } | Fetches status of a transfer. Rejects with reason in case account nonce has been overwritten. |

Mixes: sendCommand

| Param | Type | Description | | --- | --- | --- | | command | number | Command index, must be an integer. | | payload | object | 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

• Connection
  • instance
    • "info"
    • "open" (event)
    • "error" (event)
    • "close" (event)
  • static
    • .close()
    • .sendCommand(command, payload) ⇒ Promise.<(object|void)>
    • .setComputorUrl(index, url)
    • .open()
    • .computors() ⇒ Array.<string>

"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|void)>

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

| Command | Payload | Response | Description | | --- | --- | --- | --- | | 1 | { identity } | { identity, identityNonce } | Fetches identityNonce. | | 2 | { identity } | { identity, energy } | Fetches energy. | | 3 | { message, signature } | void | Sends a transfer with base64-encoded message & signature fields. | | 4 | { hash } | { hash, inclusionState, tick, epoch } or { hash, reason } | Fetches status of a transfer. Rejects with reason in case account nonce has been overwritten. |

| Param | Type | Description | | --- | --- | --- | | command | number | Command index, must be an integer. | | payload | object | 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 : object
  • .schnorrq : object
    • .generatePublicKey(secretKey) ⇒ Uint8Array
    • .sign(secretKey, publicKey, message) ⇒ Uint8Array
    • .verify(publicKey, message, signature) ⇒ number
  • .K12(input, output, outputLength, outputOffset)

Crypto.schnorrq : object

• .schnorrq : object
  • .generatePublicKey(secretKey) ⇒ Uint8Array
  • .sign(secretKey, publicKey, message) ⇒ Uint8Array
  • .verify(publicKey, message, signature) ⇒ number

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.K12(input, output, outputLength, outputOffset)

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