Skip to content

SDK Reference

Soqucoin provides three SDKs at different maturity levels. The TypeScript SDK is the primary tool for browser-based development.

SDKs at a glance

SDK Language Status Use case
soqucoin-sdk Go Public Exchange and server-side integration: key derivation, signing, UTXO management
soq-lightning-sdk TypeScript Preview In-browser ML-DSA-44 signing, transaction building, Lightning (in progress)
soqushield_sdk Dart Alpha Mobile wallet primitives (SoquShield app)

TypeScript SDK (soq-lightning-sdk)

The browser-facing SDK. Generates ML-DSA-44 keypairs locally and builds and signs transactions client-side; you broadcast the signed transaction through a node. Keys never leave the browser.

Key generation

import { onchain } from "soq-lightning-sdk";

let publicKey, secretKey;
do ({ publicKey, secretKey } = onchain.mlDsaKeygen());
while (publicKey[0] === 0xff);
// publicKey: Uint8Array (1,312 bytes, ML-DSA-44 public key)
// secretKey: Uint8Array (2,560 bytes, ML-DSA-44 secret key)

Regenerate a key that begins with 0xFF

The node treats a public key whose first byte is 0xFF as its invalid-key marker. About one random keypair in 256 has that first byte, and its address can receive SOQ but never spend it. mlDsaKeygen() does not check for this yet, so regenerate until the first byte is not 0xFF, as above. Wallets that derive keys from a recovery phrase (the node, SoquShield and the web wallet) apply the same rule deterministically: they re-derive with a retry byte appended to the derivation info.

Uses @noble/post-quantum (audited, pure-JS Dilithium implementation).

Address derivation

const address = onchain.deriveAddress(publicKey, "sq");
// → "sq1p..." (Bech32m, witness version 1)
// address = bech32m(hrp, 1, SHA256(pubkey₁₃₁₂))

Pass the HRP explicitly: the SDK's default is still ssq, the stagenet test network's prefix.

Parameter Value
HRP (mainnet) sq
Witness version 1
Hash SHA-256 of the 1,312-byte ML-DSA-44 public key
Encoding Bech32m (BIP-350)

Build and sign

const { rawTxHex, txid } = onchain.buildSignedSend({
  hrp: "sq",
  utxos,                    // the sender's unspent outputs
  recipientAddress,         // Bech32m destination
  amount,                   // in shors (1 SOQ = 100,000,000 shors)
  changeAddress: address,   // sender's own address
  senderPubkey: publicKey,  // 1,312-byte ML-DSA-44 pubkey
  senderSecret: secretKey,  // 2,560-byte ML-DSA-44 secret
  feeRate,                  // shors per virtual byte (bigint)
});

The SDK assembles a witness-v1 transaction with the ML-DSA-44 signature inline. See Transaction format for the byte-level layout.

Broadcast

Send the signed transaction through your own node (Install & run a node):

soqucoin-cli sendrawtransaction <rawTxHex>

From 2.5.1, mainnet nodes accept a transaction into the mempool only if every output is OP_RETURN data, a witness version 1 program, or a program of a witness version whose deployment is active; anything else is refused with the reason scriptpubkey.

Reading the chain

Your node's RPC API is the authoritative source. The public explorer at explorer.soqu.org shows blocks, transactions and addresses, and serves the current height at https://explorer.soqu.org/api/blocks/tip/height.

Go SDK (soqucoin-sdk)

Server-side SDK for exchanges and services: key derivation and withdrawal signing in your own infrastructure, with the node's wallet disabled as a chain reader and broadcaster. It powers SOQUPOOL.

Next steps