Private Transfers

This guide covers sending tokens privately between privacy addresses.

Basic Transfer

const result = await sdk.vault.send({
  to: '0x04...recipient-privacy-address',
  tokenAddress: '0x...token-address',
  amount: 1000000000000000000n, // 1 token
});

console.log('Transaction hash:', result.txHash);

Transfer Parameters

interface SendParams {
  to: PrivacyAddress;       // Recipient's privacy address
  tokenAddress: Hex;        // Token to send
  amount: bigint;           // Amount in wei
}

Parameter	Type	Required	Description
`to`	`PrivacyAddress`	Yes	Recipient’s privacy address
`tokenAddress`	`Hex`	Yes	Token contract address
`amount`	`bigint`	Yes	Amount in smallest unit

Transfer Result

interface TransactionResult {
  txHash: Hex;  // Transaction hash
}

Privacy Address Validation

Always validate privacy addresses before sending:

import { isValidPrivacyAddress, validatePrivacyAddress } from '@sunnyside-io/privacy-boost';

// Check if valid
if (!isValidPrivacyAddress(recipientAddress)) {
  throw new Error('Invalid privacy address');
}

// Or throw on invalid
validatePrivacyAddress(recipientAddress); // Throws if invalid

// Then send
await sdk.vault.send({
  to: recipientAddress,
  tokenAddress: '0x...',
  amount: 1000000000000000000n,
});

Transfer to MPK

If you have the recipient’s MPK instead of privacy address:

import { encodePrivacyAddress } from '@sunnyside-io/privacy-boost';

// Convert MPK to privacy address
const privacyAddress = encodePrivacyAddress(mpk, viewingKey);

await sdk.vault.send({
  to: privacyAddress,
  tokenAddress: '0x...',
  amount: 1000000000000000000n,
});

Paying Several Recipients at Once

sendBatch pays every recipient from one set of input notes, in a single request. You’re charged one fee instead of one per recipient, and the whole payout lands in one epoch slot rather than several.

const result = await sdk.vault.sendBatch({
  tokenAddress: '0x...token-address',
  recipients: [
    { recipient: '0x04...alice', amount: 400000n },
    { recipient: '0x04...bob', amount: 500000n },
  ],
});

interface SendBatchParams {
  recipients: SendBatchRecipient[];  // In output order, at least one
  tokenAddress: Hex;                 // Token to send
  signal?: AbortSignal;
}

interface SendBatchRecipient {
  recipient: PrivacyAddress;
  amount: bigint;
}

The same recipient may appear more than once, and the result has the same shape as send: one requestId and one placeholder txHash for the whole batch.

How many recipients fit

The server proves a fixed set of (inputs, outputs) shapes, and a transfer has to fit inside one of them. Its output count is your recipient count plus a change note, so a longer recipient list leaves room for fewer input notes:

Outputs (recipients + change)	Input notes that can be spent
1-2	up to 15
3-11	up to 4

So 5 inputs by 3 outputs is not provable, even though 15 inputs and 11 outputs are each individually fine. In practice: past two recipients, the transfer has to be coverable by at most four notes. If your notes are fragmented, run sdk.vault.consolidateNotes(tokenAddress) first. The SDK plans note selection against the shapes the server advertises, so a batch that can’t be proven fails before anything is submitted:

try {
  await sdk.vault.sendBatch({ tokenAddress, recipients });
} catch (error) {
  if (error.code === 'UNSUPPORTED_TRANSFER_SHAPE') {
    // Too many recipients for the notes available. Consolidate first, or
    // split the payout across two batches.
  }
}

A server older than this feature advertises no batch capability, and sendBatch refuses multi-recipient requests against it with the same code.

Checking Balance Before Transfer

async function safeTransfer(params: SendParams) {
  const balance = await sdk.vault.getBalance(params.tokenAddress);

  if (params.amount > balance) {
    throw new Error(
      `Insufficient balance. Have: ${balance}, Need: ${params.amount}`
    );
  }

  return sdk.vault.send(params);
}

Transfer Privacy

Private transfers provide:

Sender Privacy: Your wallet address is not linked to the transaction
Recipient Privacy: The recipient’s wallet address is not revealed
Amount Privacy: The transfer amount is encrypted
Relationship Privacy: No public link between sender and recipient

Only the sender and recipient can see the transfer details.

Error Handling

try {
  await sdk.vault.send(params);
} catch (error) {
  switch (error.code) {
    case 'INSUFFICIENT_BALANCE':
      console.log('Not enough shielded balance');
      break;
    case 'INVALID_RECIPIENT':
      console.log('Invalid privacy address');
      break;
    case 'INVALID_AMOUNT':
      console.log('Invalid amount');
      break;
    case 'TRANSFER_FAILED':
      console.log('Transfer transaction failed');
      break;
    default:
      console.log('Transfer error:', error.message);
  }
}

UI Example

import { useState } from 'react';
import { isValidPrivacyAddress } from '@sunnyside-io/privacy-boost';

function TransferForm() {
  const [recipient, setRecipient] = useState('');
  const [amount, setAmount] = useState('');
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  const handleTransfer = async () => {
    setError('');

    // Validate recipient
    if (!isValidPrivacyAddress(recipient)) {
      setError('Invalid privacy address');
      return;
    }

    setLoading(true);
    try {
      const decimals = 18; // token decimals (fetch via sdk.vault.getToken)
      const parsedAmount = parseAmount(amount, decimals);

      await sdk.vault.send({
        to: recipient,
        tokenAddress,
        amount: parsedAmount,
      });

      alert('Transfer successful!');
      setRecipient('');
      setAmount('');
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <input
        type="text"
        value={recipient}
        onChange={(e) => setRecipient(e.target.value)}
        placeholder="Recipient privacy address"
        disabled={loading}
      />
      <input
        type="text"
        value={amount}
        onChange={(e) => setAmount(e.target.value)}
        placeholder="Amount"
        disabled={loading}
      />
      {error && <p style={{ color: 'red' }}>{error}</p>}
      <button onClick={handleTransfer} disabled={loading}>
        {loading ? 'Sending...' : 'Send'}
      </button>
    </div>
  );
}

Best Practices

1. Validate All Inputs

function validateTransferParams(params: SendParams) {
  if (!isValidPrivacyAddress(params.to)) {
    throw new Error('Invalid recipient privacy address');
  }
  if (params.amount <= 0n) {
    throw new Error('Amount must be positive');
  }
  if (!isEvmAddress(params.tokenAddress)) {
    throw new Error('Invalid token address');
  }
}

2. Confirm Large Transfers

async function transferWithConfirmation(params: SendParams) {
  const tokenMetadata = await sdk.vault.getToken(params.tokenAddress);
  const formattedAmount = formatAmount(
    params.amount,
    tokenMetadata.decimals
  );

  const confirmed = confirm(
    `Send ${formattedAmount} ${tokenMetadata.symbol} to ${params.to.slice(0, 10)}...?`
  );

  if (!confirmed) {
    throw new Error('Transfer cancelled by user');
  }

  return sdk.vault.send(params);
}

3. Handle Network Delays

async function transferWithRetry(params: SendParams, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await sdk.vault.send(params);
    } catch (error) {
      if (attempt === maxRetries) throw error;
      if (error.code === 'NETWORK_ERROR') {
        await new Promise((r) => setTimeout(r, 2000 * attempt));
        continue;
      }
      throw error;
    }
  }
}

Quickstart

Setup

SDKs

Transfers

Private Transfers

Basic Transfer

Transfer Parameters

Transfer Result

Privacy Address Validation

Transfer to MPK

Paying Several Recipients at Once

How many recipients fit

Checking Balance Before Transfer

Transfer Privacy

Error Handling

UI Example

Best Practices

1. Validate All Inputs

2. Confirm Large Transfers

3. Handle Network Delays

Next Steps

​Private Transfers

​Basic Transfer

​Transfer Parameters

​Transfer Result

​Privacy Address Validation

​Transfer to MPK

​Paying Several Recipients at Once

​How many recipients fit

​Checking Balance Before Transfer

​Transfer Privacy

​Error Handling

​UI Example

​Best Practices

​1. Validate All Inputs

​2. Confirm Large Transfers

​3. Handle Network Delays

​Next Steps

Private Transfers

Basic Transfer

Transfer Parameters

Transfer Result

Privacy Address Validation

Transfer to MPK

Paying Several Recipients at Once

How many recipients fit

Checking Balance Before Transfer

Transfer Privacy

Error Handling

UI Example

Best Practices

1. Validate All Inputs

2. Confirm Large Transfers

3. Handle Network Delays

Next Steps