Portal Deposit Addresses

Give a user a reusable, public, exchange-style deposit address. Anyone can fund it with standard ERC-20 transfers, and the funds are credited into the owner’s shielded balance without revealing which account was credited. See Portal Deposit Addresses for the concept and trust model. The TypeScript SDK exposes the full portal lifecycle through the sdk.portal resource.

Checking support

delegateAddress() returns the portal delegate address advertised by the server’s /info, or undefined when the server does not support portals:

if (!(await sdk.portal.delegateAddress())) {
  throw new Error('This server does not support portal deposits.');
}

Creating a portal

create does everything in one call: it derives a fresh portal address E from your seed, delegates it to the portal implementation, registers the on-chain owner binding, and publishes the discovery registry entry.

const portal = await sdk.portal.create();
console.log('Deposit address:', portal.address); // share this E publicly
console.log('Derivation index:', portal.index);

Pin a derivation index to re-derive a specific portal deterministically:

const portal = await sdk.portal.create({ index: 0 });

Listing your portals

const page = await sdk.portal.listPage({ limit: 100 });
for (const p of page.items) {
  console.log(p.address, p.status.registered, p.status.published);
}
// Fetch the next page with { cursor: page.nextCursor, limit: 100 } when present.

Checking a portal’s status

const status = await sdk.portal.status(portal.address);
// { registered: boolean, delegated: boolean, published: boolean }

Receiving deposits

ETH deposits are wrapped automatically when swept. Read the current requirements for the delegate’s registered wrapped-native token without unlocking or signing. A valid read session is required: locked but readable sessions work; signed-out or expired sessions must sign in first.

const requirements = await sdk.portal.sweepRequirements();
const minimumWeth = requirements.minSweepAmount > 0n
  ? requirements.minSweepAmount
  : 1n;
const minimumEth = requirements.nativeGasReserve + minimumWeth;
// Base units for an empty address; existing funds can reduce the deposit needed.

minSweepAmount is the current on-chain token threshold. nativeGasReserve is the supported delegate version’s gas reserve (0.001 ETH), not an on-chain getter. Even a zero threshold requires a positive sweep. Smaller deposits remain at the address until enough accumulates. Refresh the threshold periodically because the pool owner can change it. Any USD conversion is approximate and should be omitted when a price is unavailable. Each call reads the minimum on-chain. Deployment metadata is cached within the SDK instance for five minutes, with concurrent metadata requests sharing one lookup. Chain or deployment changes trigger a new lookup. Older custom key vaults without this operation receive an explicit unsupported-operation error. A sender funds a portal with an ordinary ERC-20 transfer to E — they need nothing from Privacy Boost. List the deposits observed at a portal:

const page = await sdk.portal.depositsPage(portal.address, { limit: 100 });
for (const d of page.items) {
  console.log(d.portalDepositId, d.state, d.grossAmount, d.feeAmount, d.netAmount);
}
// Fetch the next page with { cursor: page.nextCursor, limit: 100 } when present.

A deposit moves through these states:

`state`	Meaning
`pending_sweep`	Funds are swept into pool escrow and await note credit
`credited`	Swept and credited to your shielded balance
`cancellable`	Eligible to be reclaimed
`cancelled`	Reclaimed back to `E`
`unknown`	State could not be determined

Each deposit reports the sweepFeeBps snapshotted at sweep time; feeAmount is grossAmount - netAmount.

Sweeping

Sweeping moves a portal’s balance into the pool. It is permissionless and deployments normally run a keeper, so you rarely call it, but sweep is available as a self-service backstop. It returns the sweep transaction hash:

const txHash = await sdk.portal.sweep(portal.address, tokenId);

Reclaiming an un-credited deposit

If a swept deposit is never credited, reclaim it after the cancel delay. The funds return to the portal address E, never to the caller:

const txHash = await sdk.portal.reclaim(depositId);

Withdrawing raw funds from `E` (escape hatch)

For funds resting at E that can never be swept (for example a token that is not registered with the protocol), withdraw builds a signed raw EIP-1559 transaction you broadcast yourself. Read the nonce and gas/fee values from your own RPC:

const signedRawTx = await sdk.portal.withdraw({
  index: portal.index,
  token: '0x...token-address',
  to: '0xDestination',
  amount: 1000000000000000000n,
  nonce: await publicClient.getTransactionCount({ address: portal.address }),
  gasLimit: 100000n,
  maxFeePerGas: 20000000000n,
  maxPriorityFeePerGas: 1000000000n,
});
// Broadcast signedRawTx yourself, e.g. publicClient.sendRawTransaction({ serializedTransaction: signedRawTx })

Types

interface Portal {
  address: string; // the portal deposit address E
  index: number;   // seed-derivation index — re-derives E's key
  bindH: string;   // on-chain owner binding H (0x-prefixed 32-byte hex)
}

type PortalDepositState =
  | 'pending_sweep'
  | 'credited'
  | 'cancellable'
  | 'cancelled'
  | 'unknown';

interface PortalStatus {
  registered: boolean;
  delegated: boolean;
  published: boolean;
}

interface PortalInfo {
  address: string;
  index?: number;
  status: PortalStatus;
}

interface PortalDeposit {
  portalDepositId: string; // key for reclaim()
  portal: string;
  tokenId: number;
  grossAmount: bigint;
  netAmount: bigint;
  sweepFeeBps: number;
  feeAmount: bigint;
  state: PortalDepositState;
  requestBlock: number;
  cancellableAtBlock: number;
}

interface CreatePortalOptions {
  index?: number;
}

interface WithdrawPortalParams {
  index: number;
  token: string;
  to: string;
  amount: bigint;
  nonce: number | bigint;
  gasLimit: bigint;
  maxFeePerGas: bigint;
  maxPriorityFeePerGas: bigint;
}

Quickstart

Setup

SDKs

Portal deposits

Portal Deposit Addresses

Checking support

Creating a portal

Listing your portals

Checking a portal’s status

Receiving deposits

Sweeping

Reclaiming an un-credited deposit

Withdrawing raw funds from `E` (escape hatch)

Types

​Portal Deposit Addresses

​Checking support

​Creating a portal

​Listing your portals

​Checking a portal’s status

​Receiving deposits

​Sweeping

​Reclaiming an un-credited deposit

​Withdrawing raw funds from E (escape hatch)

​Types

Portal Deposit Addresses

Checking support

Creating a portal

Listing your portals

Checking a portal’s status

Receiving deposits

Sweeping

Reclaiming an un-credited deposit

Withdrawing raw funds from `E` (escape hatch)

Types