> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privacyboost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deposits

# Deposits

This guide covers depositing tokens from your wallet into your private balance using the Privacy Boost WASM SDK.

## Basic Deposit

```typescript theme={null}
import init, { PrivacyBoost } from '@sunnyside-io/privacy-boost-wasm';

await init();
const sdk = new PrivacyBoost(config);
// ... authenticate first ...

const result = await sdk.shield({
  tokenAddress: '0x...token-address',
  amount: '1000000000000000000', // 1 token in wei
});
console.log('Transaction hash:', result.txHash);
console.log('Commitment:', result.commitment);
```

## Deposit Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `tokenAddress` | `string` | Yes | ERC-20 token contract address |
| `amount` | `string` | Yes | Amount in wei (as string) |

## Deposit Steps

When a deposit is submitted, the SDK executes these steps in order:

| Step | Description |
| - | - |
| Wrapping | Wrapping ETH to WETH (if depositing ETH) |
| Approving | Approving token spending on the shield contract |
| Shielding | Executing the deposit transaction |
| Registering | Registering the deposit with the indexer |
| Compliance | Waiting for compliance verification |

## Deposit Result

```typescript theme={null}
interface ShieldResult {
  txHash: string;      // Main deposit transaction hash
  commitment: string;  // Note commitment
}
```

## Depositing ETH

To deposit native ETH, use the zero address. The SDK automatically wraps ETH to WETH:

```typescript theme={null}
const ethAddress = '0x0000000000000000000000000000000000000000';

const result = await sdk.shield({
  tokenAddress: ethAddress,
  amount: '1000000000000000000', // 1 ETH
});
```

The SDK automatically:

1. Wraps ETH to WETH
2. Approves WETH spending
3. Deposits WETH to the shield contract

## Parsing Amounts

```typescript theme={null}
// Parse human-readable amount to wei string
const weiAmount = sdk.parseAmount('1.5', 18);
// Returns: "1500000000000000000"

// Format wei string to human-readable
const formatted = sdk.formatAmount('1500000000000000000', 18);
// Returns: "1.5"
```

## Error Handling

```typescript theme={null}
try {
  const result = await sdk.shield({ tokenAddress, amount });
} catch (error) {
  if (error.message.includes('Insufficient balance')) {
    console.log('Not enough tokens in wallet');
  } else if (error.message.includes('Not authenticated')) {
    console.log('Please log in first');
  } else if (error.message.includes('Invalid amount')) {
    console.log('Invalid amount format');
  } else if (error.message.includes('Network error')) {
    console.log('Network error, please retry');
  } else {
    console.log('Deposit failed:', error.message);
  }
}
```

## Best Practices

### 1. Validate Amounts Before Depositing

Check the wallet balance before attempting a deposit to provide early feedback.

### 2. Refresh Balance After Deposit

```typescript theme={null}
const result = await sdk.shield({ tokenAddress, amount });
const balance = await sdk.getBalance(tokenAddress);
console.log('New shielded balance:', balance.shieldedBalance);
```

### 3. Handle Long Operations

Deposits involve multiple on-chain transactions. Show loading states in your UI.

## Relayed Deposits (build calldata, relay yourself)

If your users don't submit transactions directly — they hold funds at addresses
you relay for (a gasless relayer, an EIP-7702 session key, a custom pipeline) —
build the deposit calldata without submitting it, relay it through your own
infrastructure, then finalize from the mined receipt.

```typescript theme={null}
// 1. Build the calldata (nothing submitted)
const prepared = await sdk.prepareShield({
  tokenAddress: '0x...',
  amount: '1000000000000000000',
  // recipient: '0x04...',  // omit to shield to yourself
});

// prepared.wrap? / prepared.approve? / prepared.shield are { to, value, data }
// calls — relay them in order (wrap?, approve?, shield).
const calls = [prepared.wrap, prepared.approve, prepared.shield].filter(Boolean);
const receipt = await myRelayer.submit(calls);

// 2. Finalize from the mined receipt to recover the request id
const result = finalizeShield(
  receipt,
  prepared.finalize.shieldContract,
  prepared.commitment
);
console.log('Request ID:', result.requestId);
```

Each call is `{ to, value, data }`, so the array drops directly into an
EIP-5792 / Porto `wallet_prepareCalls` bundle.

### Server-side (no session)

A backend that holds only a recipient's privacy address can build a deposit on
their behalf with the stateless `buildShieldPayload` free function — no signed-in
session and no private keys:

```typescript theme={null}
import { buildShieldPayload } from '@sunnyside-io/privacy-boost-wasm';

const prepared = buildShieldPayload({
  tokenAddress: '0x...',
  amount: '1000000000000000000',
  recipient: userPrivacyAddress,
  tokenId,                 // from the token catalog
  shieldContractAddress,
  teePublicKey,
  minShieldAmount,         // optional: reject below the per-token minimum
});
```

The note's owner is bound cryptographically to the recipient's privacy address,
so only they can spend it; the ephemeral sender used to encrypt the deposit is
generated and discarded internally.

## Next Steps

* [Withdrawals Guide](./withdrawals)
* [Transfers Guide](./transfers)
* [Balances Guide](./balances)
* [Error Handling](./error-handling)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.