@extrasafe/private-tokens

TypeScript SDK for private token operations on Avalanche C-Chain. Exchange, transfer, and manage EXTRASAFE private tokens (esAVAX, esETH, esUSD) with a clean wallet-integration API.

Installation

pnpm add @extrasafe/private-tokens viem

Quick Start

import {
  createPrivateTokensClient,
  avalancheFuji,
  MockPrivateTokenAdapter,
} from '@extrasafe/private-tokens'

const adapter = new MockPrivateTokenAdapter(avalancheFuji.chainId)

const client = createPrivateTokensClient({
  chain: avalancheFuji,
  adapter,
  account: '0x1234567890abcdef1234567890abcdef12345678',
  feeRecipient: '0x0000000000000000000000000000000000000001',
  feePolicy: {
    exchangeInBps: 20,
    exchangeOutBps: 20,
  },
})

// Show private tokens in wallet
const tokenList = client.getDefaultTokenList()

// Exchange to private token
const prepared = await client.prepareExchangeToPrivateToken({
  fromToken: 'AVAX',
  toPrivateToken: 'esAVAX',
  amount: 1000000000000000000n, // 1 AVAX
  autoRegister: true,
})

// Execute transaction steps
for (const step of prepared.steps) {
  console.log(`[${step.type}] ${step.title}`)
  // send step.tx via walletClient
}

Default Private Tokens

| Symbol | Name | Underlying | Decimals | |--------|------|-----------|----------| | esAVAX | EXTRASAFE Private AVAX | AVAX (native) | 18 | | esETH | EXTRASAFE Private ETH | ETH (wrapped/bridged) | 18 | | esUSD | EXTRASAFE Private USD | USDC (ERC-20) | 6 |

Supported Chains

| Chain | Chain ID | Status | |-------|----------|--------| | Avalanche C-Chain | 43114 | Mainnet | | Avalanche Fuji | 43113 | Testnet |

SDK API Overview

Client Methods

client.getSupportedPrivateTokens()
client.getDefaultTokenList()
client.getPrivateAccountStatus(address)
client.preparePrivateAccountRegistration(params)
client.registerPrivateAccount(params)
client.quoteExchangeToPrivateToken(params)
client.prepareExchangeToPrivateToken(params)
client.exchangeToPrivateToken(params)
client.quoteExchangeFromPrivateToken(params)
client.prepareExchangeFromPrivateToken(params)
client.exchangeFromPrivateToken(params)
client.getPrivateTokenBalance(params)
client.getPrivateBalances(address)
client.preparePrivateTransfer(params)
client.privateTransfer(params)
client.calculateSystemFee(params)

Wallet Integration Helpers

import {
  getDefaultTokenList,
  getTokenDisplayInfo,
  buildExchangeButtonLabel,
  buildRegistrationWarning,
  buildFeeDisclosure,
} from '@extrasafe/private-tokens'

Examples

See the examples/ folder:

• minimal-wallet-integration/ — Token list display
• exchange-to-private/ — Quote and prepare exchange
• private-transfer/ — Private token transfer
• exchange-from-private/ — Exchange back to regular asset

Security Notes

• The SDK does not handle or store private keys or mnemonics
• All token amounts use bigint to prevent floating-point errors
• Addresses are validated before any operation
• Fee recipients are always visible and configurable
• No silent chain switching
• Transaction steps are always previewable before execution

Privacy Disclaimer

This SDK provides a privacy-preserving token wrapper integration layer. The actual privacy guarantees depend on the underlying protocol adapter and deployed contracts.

The SDK does not make claims about:

• Anonymity of transactions
• Untraceability of transfers
• Impossibility of linking addresses

Privacy properties are determined by the adapter implementation (e.g., eERC encrypted tokens) and its cryptographic guarantees.

Development

pnpm install
pnpm run typecheck
pnpm run test
pnpm run build

License

MIT