SDK Reference

npm install @fairblock/stellar-stabletrust
# or
yarn add @fairblock/stellar-stabletrust
# or
pnpm add @fairblock/stellar-stabletrust

import { StellarStabletrustClient } from "@fairblock/stellar-stabletrust";
import { SorobanRpc, Keypair } from "@stellar/stellar-sdk";

// 1. Initialise the client
const client = new StellarStabletrustClient({
  sorobanRpcUrl: "https://soroban-rpc.testnet.stellar.org",
  contractAddress: "CAAAA...",          // Soroban confidential-mirror contract
  networkPassphrase: "Test SDF Network ; September 2015",
});

// 2. One-time account creation (generates ElGamal keypair from wallet signature)
const keypair = Keypair.fromSecret("S...");
await client.createAccount(keypair);
// Waits for FairyPort relay and Fairyring confirmation (~10–30s)

// 3. Deposit Stellar tokens into the confidential layer
await client.deposit({
  keypair,
  tokenAddress: "CBBBB...",  // Stellar token contract address
  amount: 100n,              // plaintext amount (BigInt, in token's base unit)
});

// 4. Send a private confidential transfer
await client.transfer({
  keypair,
  tokenAddress: "CBBBB...",
  recipientAddress: "GABC...",
  amount: 50,                // Number; generates ZK proofs client-side
  useOffchainVerify: false,  // false = onchain ZKP via Fairyring (trustless)
});

// 5. Apply incoming pending credits (must be called to make received funds spendable)
await client.applyPending({ keypair });

// 6. Query encrypted balance (decrypted client-side with your private key)
const balance = await client.getBalance({
  keypair,
  tokenAddress: "CBBBB...",
});
// { available: "50", pending: "0" }

// 7. Withdraw back to standard Stellar tokens
await client.withdraw({
  keypair,
  tokenAddress: "CBBBB...",
  amount: 25,
  useOffchainVerify: false,
});

import { StellarStabletrustClient } from "@fairblock/stellar-stabletrust";

// The SDK derives your ElGamal keypair deterministically from a signature
// over a well-known message, using your Stellar keypair.
// The private key is NEVER transmitted to any server.

const client = new StellarStabletrustClient({ ... });

// Option A: derive and cache the keypair in-memory
const elgamalKeypair = await client.deriveElGamalKeypair(keypair);
// { publicKey: Uint8Array, secretKey: Uint8Array }

// Option B: supply a pre-derived keypair directly (for hardware wallets)
const balance = await client.getBalance({
  keypair,
  tokenAddress: "CBBBB...",
  elgamalSecretKey: storedSecretKey, // Uint8Array (32 bytes)
});

// Proofs are generated entirely client-side inside the SDK.
// No proof material leaves the user's device.

// Transfer proof bundle contains three proofs:
// 1. Equality proof      same plaintext encrypted under both pubkeys
// 2. Range proof         sender balance after deduction is >= 0
// 3. Ciphertext validity transfer ciphertexts are well-formed

// Withdraw proof bundle contains two proofs:
// 1. Equality proof correctly links ciphertext to amount
// 2. Range proof    balance after deduction is >= 0 (bound to tx_id nonce)

// The SDK handles all proof generation transparently:
await client.transfer({
  keypair,
  tokenAddress: "...",
  recipientAddress: "...",
  amount: 10,
  // useOffchainVerify defaults to false (trustless, onchain ZKP)
});