@fairblock/stabletrust-stellar

Overview

The Stabletrust Stellar SDK by Fairblock provides a robust interface for executing confidential transfers on the Stellar network using Soroban smart contracts, homomorphic encryption, and zero-knowledge proofs. This package enables developers to integrate privacy features directly into their Stellar applications, allowing for secure token deposits, private transfers, and withdrawals while maintaining the integrity and auditability of the underlying blockchain transactions.

For a comprehensive technical understanding of the architecture and cryptographic primitives, please refer to the following documentation:

• Technical Overview: Fairblock Confidential Transfers
• Stabletrust Protocol: Stabletrust Documentation
• Stellar SDK Documentation: Stabletrust Stellar Docs

Requirements

Before using this SDK, ensure you have the following installed:

• Node.js: Version 16.0 or higher
• npm or yarn: For package management
• @stellar/stellar-sdk: Version 11.0 or higher (automatically installed as a dependency)

Installation

To install the package in your project, execute the following command:

npm install @fairblock/stabletrust-stellar

Or with yarn:

yarn add @fairblock/stabletrust-stellar

Available Confidential Contract Addresses (Testnet)

The following contract addresses are available for confidential transfers on the Stellar Testnet. These are test deployments and should not be used with mainnet assets:

| Network | Passphrase | Contract ID | | :------------------ | :---------------------------------- | :--------------------------------------------------------- | | Stellar Testnet | Test SDF Network ; September 2015 | CDTFREQO7URZD6QASSKZASOGEZZZWBJ5ELPAG3MYEWNSMDX5RASR4PZV |

Supported Tokens (Testnet)

| Token | Symbol | Contract ID | Decimals | | :------- | :----- | :--------------------------------------------------------- | :------- | | USDC | USDC | CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA | 7 | | EURC | EURC | CCUUDM434BMZMYWYDITHFXHDMIVTGGD6T2I5UKNX5BSLXLW7HVR4MCGZ | 7 | | XLM | XLM | CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC | 7 |

Usage

The SDK revolves around the StellarConfidentialClient, which manages interactions with the Soroban confidential contract and handles the necessary cryptographic operations.

Initialization

Import and initialize the client with your network configuration.

import {
  StellarConfidentialClient,
  STELLAR_NETWORKS,
} from "@fairblock/stabletrust-stellar";

const network = STELLAR_NETWORKS.testnet;

const client = new StellarConfidentialClient({
  rpcUrl: network.rpcUrl,
  networkPassphrase: network.networkPassphrase,
  contractId: network.contractAddress,
});

Token Denomination

Stellar assets (SAC tokens) typically use 7 decimals. The SDK provides helper functions to handle these conversions easily.

• Use parseTokenAmount(amount, decimals) to convert a human-readable string (e.g., "1.5") to raw units (15000000n).
• Use formatTokenAmount(rawAmount, decimals) to convert raw units back to a readable string.

import {
  parseTokenAmount,
  formatTokenAmount,
} from "@fairblock/stabletrust-stellar";

const decimals = 7;
const amountToDeposit = parseTokenAmount("100.0", decimals); // 1000000000n

Key Functions

The SDK simplifies the confidential flow by internalizing state synchronization and pending action management.

deriveKeys(keypair)

Derives the deterministic ElGamal keypair for a Stellar account. This keypair is used for encrypting and decrypting confidential balances.

• Parameters: keypair (Stellar SDK Keypair).
• Returns: { publicKey, keypairBase64 }.

ensureAccount(keypair, keys)

Initializes a confidential account onchain if it doesn't already exist. It also performs an initial synchronization to ensure the account state is ready.

• Parameters:
  • keypair: Stellar SDK Keypair (signing account).
  • keys: Derived ElGamal keys.
• Returns: { alreadyExists, hash }.

getConfidentialBalance(keypair, keys, tokenContractId)

Retrieves the total confidential balance (Available + Pending), decrypted into raw units.

• Parameters:
  • keypair: Stellar SDK Keypair.
  • keys: Derived ElGamal keys.
  • tokenContractId: The SAC token address.
• Returns: bigint (total decrypted balance).

confidentialDeposit(keypair, tokenContractId, amount)

Deposits public tokens into the confidential contract. The SDK automatically syncs the account after the transaction is confirmed.

• Parameters:
  • keypair: Stellar SDK Keypair.
  • tokenContractId: The SAC token address.
  • amount: Raw units to deposit (bigint).

confidentialTransfer(keypair, keys, recipientPublicKey, tokenContractId, amount)

Executes a private transfer to another account. The SDK automatically handles internal "apply pending" operations if the available balance is locked or insufficient.

• Parameters:
  • keypair: Sender's Keypair.
  • keys: Sender's ElGamal keys.
  • recipientPublicKey: Recipient's G-address.
  • tokenContractId: The SAC token address.
  • amount: Raw units to transfer.

withdraw(keypair, keys, tokenContractId, amount)

Withdraws funds from the confidential balance back to the public wallet.

• Parameters:
  • keypair: Stellar SDK Keypair.
  • keys: Derived ElGamal keys.
  • tokenContractId: The SAC token address.
  • amount: Raw units to withdraw.

Examples

For a complete implementation demonstrating the full lifecycle of a confidential transactionfrom account creation to withdrawalplease refer to the examples/complete-flow.js file included in this repository.

# Run the complete flow example
npm run example

Error Handling

The SDK provides descriptive error messages. A common pattern is waiting for the sequencer to finalize state:

try {
  await client.confidentialTransfer(
    sender,
    keys,
    recipientAddr,
    tokenAddr,
    amount,
  );
} catch (error) {
  if (error.message.includes("Insufficient confidential balance")) {
    console.error("Total balance is less than transfer amount");
  } else if (
    error.message.includes("Timeout waiting for account synchronization")
  ) {
    console.error("The ledger is busy; try again in a few blocks");
  } else {
    console.error("Operation failed:", error.message);
  }
}

Security Best Practices

1. Deterministic Key Derivation: Always use deriveKeys to ensure your ElGamal keys are tied to your Stellar identity.
2. Private Key Safety: The keypairBase64 returned by deriveKeys is your "confidential private key". Never expose it.
3. Account Readiness: Always call ensureAccount before performing operations for a new user to ensure their ElGamal public key is registered onchain.
4. Token Decimals: Always verify the decimals of the SAC token. Standard Stellar assets use 7 decimals, but custom tokens may vary.

Resources

• Website: Stabletrust App
• Documentation: Stellar SDK Docs
• Twitter: @0xfairblock
• GitHub: Fairblock Repository

License

This package is licensed under the Apache-2.0 License.