BLSCT Reference Documentation

This document provides comprehensive reference documentation for BLSCT (BLS Confidential Transactions) in Navio, including all RPC methods, opcodes, and transaction/block structures for de-serialization.

Table of Contents

1. BLSCT RPC Methods
2. Opcodes
3. Transaction Structure
4. Block Structure

BLSCT RPC Methods

All BLSCT RPC methods are prefixed with the blsct category. Below is a complete reference of all available methods.

Token and NFT Creation

createtoken

Creates a new token with specified metadata and maximum supply.

Method: createtoken

Parameters: - metadata (object, required): Token metadata as key-value pairs - max_supply (amount, required): Maximum supply of the token

Returns:

{
  "hash": "transaction_hash",
  "tokenId": "token_id"
}

Example:

navio-cli createtoken '{"name":"MyToken","symbol":"MTK","description":"A sample token"}' 1000000

createnft

Creates a new NFT collection with specified metadata and maximum supply.

Method: createnft

Parameters: - metadata (object, required): NFT collection metadata as key-value pairs - max_supply (number, required): Maximum number of NFTs in the collection

Returns:

{
  "hash": "transaction_hash",
  "tokenId": "token_id"
}

Example:

navio-cli createnft '{"name":"MyNFTCollection","description":"A collection of unique NFTs"}' 1000

Token and NFT Minting

minttoken

Mints additional tokens to a specified address. Only the token creator can mint new tokens.

Method: minttoken

Parameters: - token_id (string, required): The token ID (hex string) - address (string, required): BLSCT address to receive the minted tokens - amount (amount, required): Amount of tokens to mint

Returns:

"transaction_hash"

Example:

navio-cli minttoken "d46a375d31843d6a303dc7a8c0e0cccaa2d89f442052226fd5337b4d77afcc80" "navio1..." 1000

mintnft

Mints a specific NFT from a collection to an address.

Method: mintnft

Parameters: - token_id (string, required): The token ID (hex string) - nft_id (number, required): The NFT ID to mint - address (string, required): BLSCT address to receive the NFT - metadata (object, required): NFT-specific metadata

Returns:

"transaction_hash"

Example:

navio-cli mintnft "d46a375d31843d6a303dc7a8c0e0cccaa2d89f442052226fd5337b4d77afcc80" 1 "navio1..." '{"name":"Mona Lisa","artist":"Da Vinci"}'

Balance Queries

getblsctbalance

Returns the total available BLSCT balance in the wallet.

Method: getblsctbalance

Parameters: - minconf (number, optional, default=0): Minimum confirmations required - include_watchonly (boolean, optional): Include balance in watch-only addresses - avoid_reuse (boolean, optional, default=true): Exclude balance in dirty outputs

Returns:

"1.23456789"

Example:

navio-cli getblsctbalance

gettokenbalance

Returns the total available balance of a specific token.

Method: gettokenbalance

Parameters: - token_id (string, required): The token ID (hex string) - dummy (string, optional): Must be excluded or set to "*" (for backward compatibility) - minconf (number, optional, default=0): Minimum confirmations required - include_watchonly (boolean, optional): Include balance in watch-only addresses - avoid_reuse (boolean, optional, default=true): Exclude balance in dirty outputs

Returns:

"1000.0"

Example:

navio-cli gettokenbalance "d46a375d31843d6a303dc7a8c0e0cccaa2d89f442052226fd5337b4d77afcc80"

getnftbalance

Returns the NFTs owned from a specific collection.

Method: getnftbalance

Parameters: - token_id (string, required): The token ID of the NFT collection (hex string) - dummy (string, optional): Must be excluded or set to "*" (for backward compatibility) - minconf (number, optional, default=0): Minimum confirmations required - include_watchonly (boolean, optional): Include balance in watch-only addresses - avoid_reuse (boolean, optional, default=true): Exclude balance in dirty outputs

Returns:

[
  {
    "index": "1",
    "metadata": [
      {"key": "name", "value": "Mona Lisa"},
      {"key": "artist", "value": "Da Vinci"}
    ]
  }
]

Example:

navio-cli getnftbalance "d46a375d31843d6a303dc7a8c0e0cccaa2d89f442052226fd5337b4d77afcc80"

Transfer Commands

sendtoblsctaddress

Sends NAV to a BLSCT address.

Method: sendtoblsctaddress

Parameters: - address (string, required): The BLSCT address to send to - amount (amount, required): The amount in NAV to send - memo (string, optional, default=""): A memo for the transaction - verbose (boolean, optional, default=false): Return extra transaction information

Returns:

"transaction_hash"

Example:

navio-cli sendtoblsctaddress "navio1..." 0.1 "Payment"

sendtokentoblsctaddress

Sends tokens to a BLSCT address.

Method: sendtokentoblsctaddress

Parameters: - token_id (string, required): The token ID (hex string) - address (string, required): The BLSCT address to send to - amount (amount, required): The amount of tokens to send - memo (string, optional, default=""): A memo for the transaction - verbose (boolean, optional, default=false): Return extra transaction information

Returns:

"transaction_hash"

Example:

navio-cli sendtokentoblsctaddress "d46a375d31843d6a303dc7a8c0e0cccaa2d89f442052226fd5337b4d77afcc80" "navio1..." 1000 "Payment"

sendnfttoblsctaddress

Sends an NFT to a BLSCT address.

Method: sendnfttoblsctaddress

Parameters: - token_id (string, required): The token ID of the NFT collection (hex string) - nft_id (number, required): The specific NFT ID to send - address (string, required): The BLSCT address to send to - memo (string, optional, default=""): A memo for the transaction - verbose (boolean, optional, default=false): Return extra transaction information

Returns:

"transaction_hash"

Example:

navio-cli sendnfttoblsctaddress "d46a375d31843d6a303dc7a8c0e0cccaa2d89f442052226fd5337b4d77afcc80" 1 "navio1..." "Gift NFT"

Transaction Management

listblscttransactions

Lists BLSCT transactions in the wallet.

Method: listblscttransactions

Parameters: - label (string, optional): Filter by label name - count (number, optional, default=10): Number of transactions to return - skip (number, optional, default=0): Number of transactions to skip - include_watchonly (boolean, optional): Include transactions to watch-only addresses

Returns:

[
  {
    "account": "account_name",
    "address": "address",
    "category": "send|receive",
    "amount": 1.23,
    "label": "label",
    "vout": 0,
    "confirmations": 6,
    "blockhash": "block_hash",
    "blockindex": 1,
    "blocktime": 1234567890,
    "txid": "transaction_hash",
    "time": 1234567890,
    "timereceived": 1234567890,
    "comment": "comment",
    "to": "recipient_address"
  }
]

Example:

navio-cli listblscttransactions

listblsctunspent

Lists unspent BLSCT outputs in the wallet.

Method: listblsctunspent

Parameters: - minconf (number, optional, default=1): Minimum confirmations required - maxconf (number, optional, default=9999999): Maximum confirmations - addresses (array, optional): Array of addresses to filter by - include_unsafe (boolean, optional, default=true): Include outputs that are not safe to spend - query_options (object, optional): JSON object with query options

Returns:

[
  {
    "txid": "transaction_hash",
    "vout": 0,
    "address": "address",
    "account": "account_name",
    "scriptPubKey": "script",
    "amount": 1.23,
    "confirmations": 6,
    "spendable": true,
    "solvable": true,
    "safe": true
  }
]

Example:

navio-cli listblsctunspent

Staking Commands

stakelock

Locks an amount for staking.

Method: stakelock

Parameters: - amount (amount, required): Amount to lock for staking - verbose (boolean, optional, default=false): Return extra transaction information

Returns:

"transaction_hash"

Example:

navio-cli stakelock 1000

stakeunlock

Unlocks previously locked BLSCT outputs.

Method: stakeunlock

Parameters: - amount (amount, required): Amount to unlock - verbose (boolean, optional, default=false): Return extra transaction information

Returns:

"transaction_hash"

Example:

navio-cli stakeunlock 1000

Wallet Management

setblsctseed

Set or generate a new BLSCT wallet seed.

Method: setblsctseed

Parameters: - seed (string, optional): The WIF private key to use as the new HD seed. If omitted, a random seed is generated.

Returns:

null

Example:

navio-cli setblsctseed

Advanced Transaction Operations

createblsctrawtransaction

Creates an unsigned BLSCT transaction.

Method: createblsctrawtransaction

Parameters: - inputs (array, required): Array of input objects, each containing: - txid (string, required): Transaction ID - value (number, optional): Input value in satoshis - gamma (string, optional): Gamma value (hex string) - private_key (string, optional): Private key for signing (hex string) - is_staked_commitment (boolean, optional): Whether input is a staked commitment - scriptSig (string, optional): ScriptSig in hex format - outputs (array, required): Array of output objects, each containing: - address (string, optional): BLSCT address to send to - amount (amount, required): Amount to send - memo (string, optional): Memo for the transaction - token_id (string, optional): Token ID for token transactions - script (string, optional): Script in hex format - nonce (string, optional): Nonce for this output (hex string)

Returns:

"hex_transaction_string"

Example:

navio-cli createblsctrawtransaction '[{"txid":"myid","value":1000000}]' '[{"address":"navio1...","amount":0.01}]'

fundblsctrawtransaction

Adds inputs to a BLSCT transaction until it has enough value to cover outputs and fee.

Method: fundblsctrawtransaction

Parameters: - hexstring (string, required): The hex string of the raw transaction - changeaddress (string, optional): The BLSCT address to receive the change

Returns:

"hex_transaction_string"

Example:

navio-cli fundblsctrawtransaction "hexstring" "navio1..."

signblsctrawtransaction

Signs a BLSCT raw transaction by adding BLSCT signatures.

Method: signblsctrawtransaction

Parameters: - hexstring (string, required): The transaction hex string

Returns:

"hex_signed_transaction_string"

Example:

navio-cli signblsctrawtransaction "hexstring"

decodeblsctrawtransaction

Decodes a BLSCT raw transaction and returns a JSON object describing the transaction structure.

Method: decodeblsctrawtransaction

Parameters: - hexstring (string, required): The transaction hex string

Returns:

{
  "inputs": [
    {
      "txid": "transaction_id",
      "value": 1000000,
      "gamma": "gamma_hex",
      "is_staked_commitment": false
    }
  ],
  "outputs": [
    {
      "amount": "0.01",
      "blinding_key": "blinding_key_hex",
      "gamma": "gamma_hex"
    }
  ],
  "fee": "0.0001"
}

Example:

navio-cli decodeblsctrawtransaction "hexstring"

Recovery and Proof Operations

createblsctbalanceproof

Creates a zero-knowledge proof that the wallet has at least the specified balance.

Method: createblsctbalanceproof

Parameters: - amount (amount, required): The minimum balance to prove - additional_commitment (string, optional): Additional commitment for the proof signature

Returns:

{
  "proof": "serialized_proof_hex"
}

Example:

navio-cli createblsctbalanceproof 1.0 "order id: 100"

getblsctrecoverydata

Gets BLSCT recovery data for transaction output(s).

Method: getblsctrecoverydata

Parameters: - txid_or_hex (string, required): The transaction ID or raw transaction hex - vout (number, optional): The output index. If omitted, shows data for all outputs.

Returns:

{
  "outputs": [
    {
      "vout": 0,
      "out_hash": "output_hash_hex",
      "script": "script_hex",
      "amount": "1.0",
      "gamma": "gamma_hex",
      "message": "memo"
    }
  ]
}

Example:

navio-cli getblsctrecoverydata "mytxid" 1

getblsctrecoverydatawithnonce

Gets BLSCT recovery data for outputs in a transaction using a specified nonce. Only accepts hex transaction format.

Method: getblsctrecoverydatawithnonce

Parameters: - hexstring (string, required): The transaction hex string - nonce (string, required): The nonce to use for recovery (hex string) - vout (number, optional): If specified, only return data for this output index

Returns:

{
  "txid": "transaction_id",
  "outputs": [
    {
      "vout": 0,
      "out_hash": "output_hash_hex",
      "script": "script_hex",
      "amount": "1.0",
      "gamma": "gamma_hex",
      "message": "memo"
    }
  ]
}

Example:

navio-cli getblsctrecoverydatawithnonce "hexstring" "nonce_hex" 1

Message Signing

signblsmessage

Signs a message using a BLS private key.

Method: signblsmessage

Parameters: - private_key (string, required): The BLS private key in hex format (32 bytes) - message (string, required): The message to sign

Returns:

{
  "signature": "signature_hex",
  "public_key": "public_key_hex"
}

Example:

navio-cli signblsmessage "private_key_hex" "Hello, world!"

verifyblsmessage

Verifies a BLS message signature.

Method: verifyblsmessage

Parameters: - public_key (string, required): The BLS public key in hex format (48 bytes) - message (string, required): The message that was signed - signature (string, required): The signature in hex format (96 bytes)

Returns:

true

Example:

navio-cli verifyblsmessage "public_key_hex" "Hello, world!" "signature_hex"

Opcodes

Navio introduces a new opcode for BLS signature verification:

OP_BLSCHECKSIG

Opcode: 0xb3 (also known as OP_NOP4)

Stack Operation: (pubkey -- bool)

Description: Verifies a BLS signature against a public key. This opcode replaces the traditional OP_CHECKSIG for BLS-based signature verification in Navio.

Usage:

<pubkey> OP_BLSCHECKSIG

Example Script:

<BLS_public_key> OP_BLSCHECKSIG

Notes: - The public key must be a valid BLS public key (48 bytes) - The signature must be a valid BLS signature (96 bytes) - Returns 1 (true) if the signature is valid, 0 (false) otherwise - Used in atomic swaps and other BLS-based operations

Transaction Structure

BLSCT transactions extend the standard Bitcoin transaction format with additional fields for confidential transactions.

Serialization Format

Basic Transaction Structure

int32_t nVersion
std::vector<CTxIn> vin
std::vector<CTxOut> vout
uint32_t nLockTime

Extended Format (with Witness)

int32_t nVersion
unsigned char dummy = 0x00
unsigned char flags (!= 0)
std::vector<CTxIn> vin
std::vector<CTxOut> vout
if (flags & 1):
    CScriptWitness scriptWitness (deserialized into CTxIn)
uint32_t nLockTime

BLSCT Extension

If the transaction is a BLSCT transaction (tx.IsBLSCT() returns true):

blsct::Signature txSig

CTxIn Structure

class CTxIn {
    COutPoint prevout;        // Output hash (Outid type)
    CScript scriptSig;        // Script signature
    uint32_t nSequence;       // Sequence number
    CScriptWitness scriptWitness; // Witness data
};

COutPoint:

class COutPoint {
    Outid hash;  // Output hash (32 bytes), not transaction ID
};

Note: Navio uses output hash indexing instead of (transaction ID, output index) pairs.

CTxOut Structure

class CTxOut {
    CAmount nValue;              // Value (or max if flags present)
    CScript scriptPubKey;        // Script public key
    CTxOutBLSCTData blsctData;   // BLSCT-specific data
    TokenId tokenId;             // Token ID (if token/NFT)
    blsct::VectorPredicate predicate; // Predicate (if present)
};

Serialization Flags: - BLSCT_MARKER (0x1 << 0): Transaction has BLSCT data - TOKEN_MARKER (0x1 << 1): Transaction has token data - PREDICATE_MARKER (0x1 << 2): Transaction has predicate - TRANSPARENT_VALUE_MARKER (0x1 << 3): Value is transparent (not hidden)

Serialization Logic: 1. If any flags are set, serialize std::numeric_limits<CAmount>::max() as a marker 2. Serialize flags 3. If TRANSPARENT_VALUE_MARKER is set, serialize nValue 4. Serialize scriptPubKey 5. If BLSCT_MARKER is set, serialize blsctData 6. If TOKEN_MARKER is set, serialize tokenId 7. If PREDICATE_MARKER is set, serialize predicate

CTxOutBLSCTData Structure

class CTxOutBLSCTData {
    bulletproofs_plus::RangeProof<Mcl> rangeProof;  // Range proof
    MclG1Point spendingKey;                          // Spending public key
    MclG1Point blindingKey;                          // Blinding public key
    MclG1Point ephemeralKey;                         // Ephemeral public key
    uint16_t viewTag;                                // View tag
};

Serialization Order: 1. rangeProof 2. spendingKey 3. blindingKey 4. ephemeralKey 5. viewTag

TokenId Structure

class TokenId {
    uint256 tokenId;  // Token ID hash (32 bytes)
    uint64_t nftId;   // NFT ID (if NFT, otherwise 0)
};

Serialization: - Serializes as uint256 (token ID) followed by uint64_t (NFT ID) if NFT

De-serialization Example

// Pseudo-code for de-serializing a BLSCT transaction

// Read version
int32_t version;
stream >> version;

// Read inputs (with witness handling)
std::vector<CTxIn> vin;
unsigned char flags = 0;
stream >> vin;
if (vin.empty() && allow_witness) {
    stream >> flags;
    if (flags != 0) {
        stream >> vin;
        stream >> vout;
    }
} else {
    stream >> vout;
}

// Read witness if present
if ((flags & 1) && allow_witness) {
    for (auto& input : vin) {
        stream >> input.scriptWitness.stack;
    }
}

// Read locktime
uint32_t nLockTime;
stream >> nLockTime;

// Read BLSCT signature if transaction is BLSCT
if (transaction.IsBLSCT()) {
    blsct::Signature txSig;
    stream >> txSig;
}

Block Structure

Navio blocks extend the standard Bitcoin block format with Proof of Stake (PoS) support.

CBlockHeader Structure

class CBlockHeader {
    int32_t nVersion;          // Block version (with BLSCT bit)
    uint256 hashPrevBlock;     // Previous block hash
    uint256 hashMerkleRoot;    // Merkle root
    uint32_t nTime;            // Block timestamp
    uint32_t nBits;            // Difficulty target
    uint32_t nNonce;           // Nonce
};

Version Bits: - VERSION_BIT_POS (0x01000000UL): Proof of Stake block - VERSION_BIT_BLSCT (0x40000000UL): BLSCT-enabled block

Serialization:

int32_t nVersion
uint256 hashPrevBlock
uint256 hashMerkleRoot
uint32_t nTime
uint32_t nBits
uint32_t nNonce

CBlock Structure

class CBlock : public CBlockHeader {
    blsct::ProofOfStake posProof;  // PoS proof (if PoS block)
    std::vector<CTransactionRef> vtx; // Transactions
    mutable bool fChecked;            // Memory-only flag
};

Serialization:

CBlockHeader (base class)
if (IsProofOfStake()):
    blsct::ProofOfStake posProof
    std::vector<CTransactionRef> vtx
else:
    std::vector<CTransactionRef> vtx

De-serialization Example

// Pseudo-code for de-serializing a Navio block

CBlock block;

// Read header
stream >> block.nVersion;
stream >> block.hashPrevBlock;
stream >> block.hashMerkleRoot;
stream >> block.nTime;
stream >> block.nBits;
stream >> block.nNonce;

// Read PoS proof if PoS block
if (block.IsProofOfStake()) {
    stream >> block.posProof;
}

// Read transactions
stream >> block.vtx;

Additional Notes

Output Hash Indexing

Navio uses output hash indexing instead of traditional (transaction ID, output index) pairs. This means:

• COutPoint.hash contains the output hash (32 bytes), not the transaction ID
• Outputs are identified by their hash, enabling direct lookup
• This is essential for BLSCT privacy features

BLSCT Transaction Detection

A transaction is considered a BLSCT transaction if: - It has at least one output with BLSCT data (HasBLSCTRangeProof() or HasBLSCTKeys()) - The transaction signature field (txSig) is present

Range Proofs

BLSCT uses Bulletproofs+ for range proofs, which prove that a value is within a valid range without revealing the actual value.

Token and NFT Support

• Tokens: Fungible assets identified by tokenId (uint256)
• NFTs: Non-fungible assets identified by tokenId (uint256) + nftId (uint64)
• Both use the same BLSCT infrastructure for privacy