@spatium/sdk

Classes

• MemoryStorageDriver
• SimpleTransportDriver
• SpatiumCrypto
• SpatiumProtocol

Interfaces

• Crypto
• Protocol
• StorageDriver
• TransportDriver

Type Aliases

Curve

Ƭ Curve: EcdsaCurve | EddsaCurve

EcdsaCurve

Ƭ EcdsaCurve: "secp256k1"

EcdsaSignature

Ƭ EcdsaSignature: Object

Type Declaration

EddsaCurve

Ƭ EddsaCurve: "ed25519"

EddsaSignature

Ƭ EddsaSignature: Object

Type Declaration

StorageData

Ƭ StorageData: unknown

Stored data blob

SDK stores only serializable JSON data

StorageFilter

Ƭ StorageFilter: Partial<{ room: string ; topic: string }>

StorageMeta

Ƭ StorageMeta: Object

Storage entry identification data

Each unique combination of room and topic should uniquely identify a storage entry

Type Declaration

StoragePayload

Ƭ StoragePayload: StorageMeta & { data: StorageData }

TransportCallback

Ƭ TransportCallback: (meta: TransportMeta, data: TransportData) => Promise<void>

Type Declaration

▸ (meta, data): Promise<void>

Parameters

Returns

Promise<void>

TransportData

Ƭ TransportData: unknown

Message data blob

The SDK sends only serializable JSON data

TransportFilter

Ƭ TransportFilter: Partial<TransportMeta>

Message filter

Partial meta is used as a message filter, receiving side may decide to wait for messages with a specific room, a specific topic, or even any message (with {} as a filter)

TransportMeta

Ƭ TransportMeta: Object

Message identification data

Each transfered message contains these fields in order to be correctly identified and caught

Type Declaration

TransportPayload

Ƭ TransportPayload: TransportMeta & { data: TransportData }

Variables

NIL

• Const NIL: string = _NIL

Functions

decrypt

▸ decrypt(data, key): string

Parameters

Returns

string

deriveHDKey

▸ deriveHDKey(secret, coin, account): string

Parameters

Returns

string

deserialize

▸ deserialize(data): unknown

Parameters

Returns

unknown

encodeEddsaBN

▸ encodeEddsaBN(curve, s): string

Parameters

Returns

string

encodeEddsaPoint

▸ encodeEddsaPoint(curve, p): string

Parameters

Returns

string

encrypt

▸ encrypt(data, key, randomSource): string

Parameters

Returns

string

fromInternal

▸ fromInternal(value, decimals): string

Parameters

Returns

string

generatePoint

▸ generatePoint(curve, x): string

Parameters

Returns

string

getCompoundEcdsaPrivateKey

▸ getCompoundEcdsaPrivateKey(secretLeft, secretRight, curve, derivationCoin, derivationAccount): string

Parameters

Returns

string

getCompoundEddsaPrivateKey

▸ getCompoundEddsaPrivateKey(secretLeft, secretRight, curve, derivationCoin, derivationAccount): string

Parameters

Returns

string

getEcdsaPublicKey

▸ getEcdsaPublicKey(driver, secretId, syncSessionId): Promise<string>

Get a compound public key from an already performed synchronization session (standalone helper)

See

getEcdsaPublicKey

Example

// Assume an already performed synchronization procedure

const publicKey = await getEcdsaPublicKey(protocol, secretId, syncSessionId);

Parameters

Returns

Promise<string>

compound public key, synchronized during that session

getEddsaPublicKey

▸ getEddsaPublicKey(driver, secretId, syncSessionId): Promise<string>

Get a compound public key from an already performed synchronization session (standalone helper)

See

getEddsaPublicKey

Example

// Assume an already performed synchronization procedure

const publicKey = await getEddsaPublicKey(protocol, secretId, syncSessionId);

Parameters

Returns

Promise<string>

compound public key, synchronized during that session

matchOptional

▸ matchOptional<T>(a, b): boolean

Type Parameters

Parameters

Returns

boolean

matchTransportMeta

▸ matchTransportMeta(meta, filter): boolean

Match a filter against a meta

A useful implementation helper for message filtering

Parameters

Returns

boolean

true if provided meta matches the filter

pack

▸ pack<T>(_schema, v): unknown

Type Parameters

Parameters

Returns

unknown

randomBytes

▸ randomBytes(length): string

Parameters

Returns

string

read

▸ read(driver, meta): Promise<StorageData | null>

Read data stored under the provided meta (standalone helper)

This method is typically used in a permanent storage strategy

See

read

Parameters

Returns

Promise<StorageData | null>

stored data, or null if not found

receive

▸ receive(driver, filter): Promise<TransportPayload>

Receive a specific message

This method awaits until a matching message is received (determined by filter) and resolves with message data. If an assert filter is specified, the message is also checked against it and throws if that assertion fails. Such behavior comes in handy for sudden unsubscribing, receiving messages out of order, and other erroneous situations.

Parameters

Returns

Promise<TransportPayload>

received message payload (both meta and data)

▸ receive(driver, filter, timeout?): Promise<TransportPayload>

Parameters

Returns

Promise<TransportPayload>

▸ receive(driver, filter, assert): Promise<TransportPayload>

Parameters

Returns

Promise<TransportPayload>

▸ receive(driver, filter, assert, timeout?): Promise<TransportPayload>

Parameters

Returns

Promise<TransportPayload>

removeDistributedEcdsaKey

▸ removeDistributedEcdsaKey(driver, secretId, syncSessionId): Promise<void>

Remove an already performed synchronization session from storage

See

removeDistributedEcdsaKey

Example

// Assume an already performed synchronization procedure

await removeDistributedEcdsaKey(protocol, secretId, syncSessionId);

Parameters

Returns

Promise<void>

removeDistributedEddsaKey

▸ removeDistributedEddsaKey(driver, secretId, syncSessionId): Promise<void>

Remove an already performed synchronization session from the storage

See

removeDistributedEddsaKey

Example

// Assume an already performed synchronization procedure

await removeDistributedEddsaKey(protocol, secretId, syncSessionId);

Parameters

Returns

Promise<void>

safeDecrypt

▸ safeDecrypt(data, key): null | string

Parameters

Returns

null | string

safeDeserialize

▸ safeDeserialize(data): unknown

Parameters

Returns

unknown

safeSecureUnpack

▸ safeSecureUnpack<T>(schema, data): null | TypeOf<T>

Type Parameters

Parameters

Returns

null | TypeOf<T>

safeUnpack

▸ safeUnpack<T>(_schema, data): null | TypeOf<T>

Type Parameters

Parameters

Returns

null | TypeOf<T>

securePack

▸ securePack<T>(schema, v, randomSource): string

Type Parameters

Parameters

Returns

string

secureUnpack

▸ secureUnpack<T>(schema, data): TypeOf<T>

Type Parameters

Parameters

Returns

TypeOf<T>

send

▸ send(driver, meta, data): Promise<void>

Send a message via transport (standalone helper)

This method awaits until the message is sent (not until it's delivered) and throws if sending is impossible. A specific destination and delivery are handled by implementation.

See

send

Parameters

Returns

Promise<void>

serialize

▸ serialize(data): string

Parameters

Returns

string

signEcdsaMessage

▸ signEcdsaMessage(driver, secretId, syncSessionId, signSessionId, message): Promise<EcdsaSignature>

Generate a distributed ECDSA signature for a given message (standalone helper)

This method requires an already performed synchronization procedure and does not store anything in permanent storage. Messages of a length different from 32 bytes are padded/truncated according to the ECDSA algorithm.

See

signEcdsaMessage

Example

// Assume an already performed synchronization procedure and an established connection

// Generate a random session ID for a new signing session
const signSessionId = uuid(randomBytes);

// Message to be signed
const message = '7hJ9yN2OdIQo2kJu0arZgw2EKnMX5FGtQ6jlCWuLXCM='

// Generate an ECDSA signature
const signature = await signEcdsaMessage(protocol, secretId, syncSessionId, signSessionId, message);

// Verify the resulting signature against a compound public key with an external library (elliptic.js here)
expect(new ec('secp256k1').verify(
  Buffer.from(message, 'base64'),
  {
    s: Buffer.from(signature.s, 'base64'),
    r: Buffer.from(signature.r, 'base64'),
    recoveryParam: signature.recovery,
  },
  Buffer.from(publicKey, 'base64'),
)).toBeTruthy();

Parameters

Returns

Promise<EcdsaSignature>

ECDSA signature in standard format

signEddsaMessage

▸ signEddsaMessage(driver, secretId, syncSessionId, signSessionId, message): Promise<EddsaSignature>

Generate a distributed EDDSA signature for a given message (standalone helper)

This method requires an already performed synchronization procedure and does not store anything in permanent storage. Messages of a length different from 32 bytes are padded/truncated according to the EDDSA algorithm.

See

signEddsaMessage

Example

// Assume an already performed synchronization procedure and an established connection

// Generate a random session ID for a new signing session
const signSessionId = uuid(randomBytes);

// Message to be signed
const message = '7hJ9yN2OdIQo2kJu0arZgw2EKnMX5FGtQ6jlCWuLXCM='

// Generate an EDDSA signature
const signature = await signEddsaMessage(protocol, secretId, syncSessionId, signSessionId, message);

// Verify the resulting signature against a compound public key with an external library (elliptic.js here)
expect(new ed('ed25519').verify(
  Buffer.from(message, 'base64').toString('hex'),
  Buffer.concat([
    Buffer.from(encodeEddsaPoint('ed25519', signature.R), 'base64'),
    Buffer.from(encodeEddsaBN('ed25519', signature.s), 'base64'),
  ]).toString('hex'),
  Buffer.from(encodeEddsaPoint('ed25519', publicKey), 'base64').toString('hex'),
)).toBeTruthy();

Parameters

Returns

Promise<EddsaSignature>

EDDSA signature in standard format

syncDistributedEcdsaKey

▸ syncDistributedEcdsaKey(driver, secretId, syncSessionId, curve, derivationCoin, derivationAccount): Promise<string>

Perform a distributed key synchronization procedure (standalone helper)

Each secret is independently used to generate distributed key fragments (BIP-44 with path m/44'/(coin)'/(account)'/0'/0'), and then MPC key synchronization is performed over these fragments in order to get a compound public key for that pair.

Despite each session bearing a unique set of data, the resulting key is deterministic in regards to further synchronizations, e.g. each set of secrets, coin, and account always result in the same compound public key (and ephemeral private keys).

As a result of this operation, new synchronization session data is saved to permanent storage, accessible by the provided session ID. From this point, one may freely call getEcdsaPublicKey or signEcdsaMessage as long as synchronization data (and secret) is accessible in the storage.

See

syncDistributedEcdsaKey

Example

// Assume an already generated secret and an established connection

// Generate a random session ID for a new synchronization session
const syncSessionId = uuid(randomBytes);

// Perform an ECDSA-over-secp256k1 synchronization procedure for a key with path ```m/44'/0'/0'/0'/0'```
const publicKey = await syncDistributedEcdsaKey(protocol, secretId, syncSessionId, 'secp256k1', 0, 0);

// At this point, synchronization data is saved to the storage, so one may access it to get a compound public key
const _publicKey = await getEcdsaPublicKey(protocol, secretId, syncSessionId);

// Which is obviously the same key that was returned from the synchronization procedure itself
expect(publicKey).toBe(_publicKey);

Parameters

Returns

Promise<string>

compound public key (which may also be accessed via getEcdsaPublicKey later)

syncDistributedEddsaKey

▸ syncDistributedEddsaKey(driver, secretId, syncSessionId, curve, derivationCoin, derivationAccount): Promise<string>

Perform a distributed key synchronization procedure (standalone helper)

Each secret is independently used to generate distributed key fragments (BIP-44 with path m/44'/(coin)'/(account)'/0'/0'), and then MPC key synchronization is performed over these fragments in order to get a compound public key for that pair.

Despite each session bearing a unique set of data, the resulting key is deterministic in regards to further synchronizations, e.g. each set of secrets, coin, and account always result in the same compound public key (and ephemeral private keys).

As a result of this operation, new synchronization session data is saved to persistent storage, accessible by the provided session ID. From this point, one may freely call getEddsaPublicKey or signEddsaMessage as long as synchronization data (and secret) is accessible in the storage.

See

syncDistributedEddsaKey

Example

// Assume an already generated secret and an established connection

// Generate a random session ID for a new synchronization session
const syncSessionId = uuid(randomBytes);

// Perform an EDDSA-over-secp256k1 synchronization procedure for a key with path ```m/44'/0'/0'/0'/0'```
const publicKey = await syncDistributedEddsaKey(protocol, secretId, syncSessionId, 'ed25519', 0, 0);

// At this point, synchronization data is saved to the storage, so one may access it to get a compound public key
const _publicKey = await getEddsaPublicKey(protocol, secretId, syncSessionId);

// Which is obviously the same key that was returned from the synchronization procedure itself
expect(publicKey).toBe(_publicKey);

Parameters

Returns

Promise<string>

compound public key (which may also be accessed via getEddsaPublicKey later)

take

▸ take(driver, meta): Promise<StorageData | null>

Take the data stored under the provided meta and remove the original (standalone helper)

This method is typically used in a temporary storage strategy and as a mean to delete stored entry

See

take

Parameters

Returns

Promise<StorageData | null>

stored data, or null if not found

toInternal

▸ toInternal(value, decimals): string

Parameters

Returns

string

unpack

▸ unpack<T>(_schema, data): TypeOf<T>

Type Parameters

Parameters

Returns

TypeOf<T>

uuid

▸ uuid(randomSource): string

Parameters

Returns

string

write

▸ write(driver, meta, data): Promise<void>

Write a unit of data into storage, uniquely identified by meta (standalone helper)

If such unit of data already exists, it is silently overwritten

See

write

Parameters

Returns

Promise<void>