> ## 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.

# Fireblocks Setup

> Configure Fireblocks policies so a vault account can use Privacy Boost with every spend approved in Fireblocks

# Fireblocks Setup

This page is for the Fireblocks admin connecting a vault account to the [Privacy Boost app](https://app.privacyboost.io).

In Privacy Boost, the vault account gets a private balance. Moving tokens from the vault into it is called shielding. From the private balance, the account can send privately to other Privacy Boost accounts, unshield back to a public address, swap, or use Earn.

When the vault account connects over WalletConnect, the app sets it up as an approval-only account. Every spend from the private balance needs an approval transaction sent from the vault account, and Privacy Boost has no key that can spend without one. Your Fireblocks policy and its approvers decide what gets paid.

## What the app asks Fireblocks to do

Two Privacy Boost contracts are involved: the PrivacyBoost pool, which holds shielded funds, and AuthRegistry, which records accounts and spend approvals. Each request the app makes falls under one of these Fireblocks policy types.

| App action | Fireblocks policy type | Destination | Method or message |
| - | - | - | - |
| Connect | dApp connection | `https://app.privacyboost.io` | |
| Sign in | Typed message | None | Sign-in message (EIP-191) |
| First-time setup | Typed message | None | Vault backup message (EIP-191), signed twice |
| First-time setup | Contract call | AuthRegistry | `createAccount(uint256)` (`0xcab13915`), once per chain |
| Shield native ETH | Contract call | WETH | `deposit()` (`0xd0e30db0`), with the ETH amount as value |
| Shield | Approve | Token contract (WETH for ETH), pool as spender | `approve(address,uint256)` (`0x095ea7b3`), only if the allowance is too low |
| Shield | Contract call | PrivacyBoost pool | `requestDeposit(...)` (`0x9848bf45`) |
| Send, Unshield, Earn, Swap | Contract call | AuthRegistry | `approveSpendBatch(uint256,uint64,uint256[])` (`0x67fb0fd4`) |
| First shield or spend after the app loads | Typed message | None | Key export message (EIP-191) |

The hex value next to each method is its selector, the first four bytes of the transaction's call data. The app never asks an approval-only account for EIP-712 typed data or raw signing, so you don't need rules for those.

### Why amount limits don't apply to payments

A spend approval carries an account ID and a commitment, which is a hash of the private transaction. Fireblocks sees a contract call to AuthRegistry with no ETH attached. It can't see the token, amount, or recipient, and the same zero-value call can approve a payment of any size. Amount conditions on the AuthRegistry rule don't limit payments, and you can't route large and small payments to different approvers.

What you control in Fireblocks is who can start a payment and who has to approve it. The app shows the payment details and the commitment on a review sheet, and checks that they match before it sends the request. Approvers working from the Fireblocks Console or mobile app don't see that sheet, so give them a way to: for example, have the initiator post it in your internal approval channel before the request reaches Fireblocks.

## Before you start

* A Fireblocks Mainnet or Testnet workspace that supports the chain you'll use. Try everything in a Testnet workspace first; the app has a testnet mode in its network selector. A Developer Sandbox won't work, because its policies can't be edited. See Fireblocks' [workspace comparison](https://fireblocks.readme.io/docs/workspace-environments).
* A vault account that hasn't been used with Privacy Boost before, with wallets for the chain's native asset and each token you'll shield. If the address already has a standard Privacy Boost account, it can't be switched to approval-only.
* ETH in the vault account for gas. Account creation, each shield, and each spend approval is an on-chain transaction from the vault account.
* The Console users who will use the app. This page calls them initiators. You'll also need the approver set and threshold for payments.
* Someone to keep the account's recovery phrase, which the app shows during setup. See [Connect the app](#connect-the-app) for what it can and can't do.

## Allowlist the app and contracts

Add the app through **Whitelisted addresses > Add > Whitelisted dApp wallet**, using the URL `https://app.privacyboost.io`. This entry covers the dApp connection. Contract destinations need their own address entries.

For AuthRegistry, the PrivacyBoost pool, each token you'll shield, and WETH if you'll shield native ETH, repeat these steps using the addresses below:

1. Choose **Whitelisted addresses > Add > Whitelisted address wallet**.
2. Set the type to **Contract**, enter a descriptive name such as `PrivacyBoost pool OP Mainnet`, and choose **Create wallet**.
3. Open the wallet and choose **Add address**. Creating the wallet alone leaves it empty.
4. Select the asset on the contract's network. For OP Mainnet, search for **Optimism** and select **ETH (Ether)** on **Optimism**. The next screen labels the asset **Ether**, so check the network in the asset picker before continuing.
5. Paste the contract address for that network and choose **Add address**.
6. If the entry shows **Pending approval**, have the configured workspace approvers approve the address request in Fireblocks before using it in a policy.

Each whitelisted wallet holds one address per asset. Use separate wallets for different contracts on the same network and asset, such as the pool and AuthRegistry. If your workspace has an address whitelist suspension period, wait until it ends before using the entry.

### Contract addresses

| Network | Chain ID | PrivacyBoost pool | AuthRegistry |
| - | - | - | - |
| OP Mainnet | `10` | `0xca689828854a422CF1f778be03CA80549408F620` | `0x54e87D7D0E420B24B9FdFE9cFcAe88162093A48f` |
| Base | `8453` | `0x71A0fD3C76E3E937d8275A3cb6a467b70123bD40` | `0x4daC7dA2c8cA097B3e0FF42aBFCebd2833196eB3` |
| Soneium | `1868` | `0x8E11DC9a3579aBfC0eCFBFb70be36808DEE59E6D` | `0xAd409A1da7E77Db25d5F6272CEADE2cEC1D590b7` |
| OP Sepolia (testnet) | `11155420` | `0x9E39743dE6559aCE249bE425E5DD9991b4650Bfd` | `0x5c72Bf7FE97d0223F0E06728fC531158cF371F2F` |
| Base Sepolia (testnet) | `84532` | `0x29294CdF5682953161c6672bd4C43a0a5B42AE0c` | `0x65B5299571b3aa2E74e3fb42a33eAE57D279E431` |

Both contracts are upgradeable proxies, so these addresses stay the same across upgrades. To double-check one, each network's server reports `poolAddress` and `authRegistryAddress`, for example at `https://optimism.privacyboost.io/api/v1/info`.

WETH is `0x4200000000000000000000000000000000000006` on all of these networks.

For tokens, use the token's own contract on that network. USDC and USDT on the mainnets:

| Network | Token | Address |
| - | - | - |
| OP Mainnet | USDC | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` |
| OP Mainnet | USDT | `0x94b008aA00579c1307B0EF2c499aD98a8ce58e58` |
| Base | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Base | USDT | `0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2` |
| Soneium | USDC.e | `0xbA9986D2381edf1DA03B0B9c1f8b00dc4AacC369` |

Any other token the app offers to shield on a network works the same way: allowlist that token's contract on the same network.

## Create the policy rules

Open **Policies** in the Fireblocks Console. You'll add rules to four policy types: **dApp connection**, **Typed message** (under the three-dot menu), **Approve**, and **Contract call**. Scope every rule to your initiators and the vault account so it doesn't open anything up for other users or vaults.

> [!NOTE]
>
> The spend approval is the only request that can wait for your approvers. On the Approve, shielding, and account setup rules, **Request approval** only works if an approver answers while the initiator is still in the app. Otherwise the app reports the step as failed.

For each rule:

1. Select the policy type and choose **Edit policy**.
2. Choose **Add rule**, or open an existing rule's **three-dot menu > Edit**.
3. Enter a descriptive **Rule name** and fill in the fields from that rule's table below. For Contract call rules, follow [Select contract call methods](#select-contract-call-methods) to choose the destination and functions.
4. Choose **Add rule** for a new rule or **Save rule** when editing one, then check where the rule sits in the list (see [Rule order](#rule-order)).
5. Choose **Publish policy**. A saved rule does nothing until the policy is published and any publication approval is done.

**Policies > Overview** shows which policy types are active and any publication requests still pending.

### dApp connection

| Field | Setting |
| - | - |
| Initiator | Your initiators |
| Source | The vault account |
| dApp | The Privacy Boost dApp entry |
| Action | **Allow** |

Allowing the connection doesn't let the app sign anything. Each request still has to match one of the rules below.

### Typed message

| Field | Setting |
| - | - |
| Initiator | Your initiators |
| Source | The vault account |
| Blockchain type | **EVM**, with any platform. Privacy Boost isn't one of the named platforms, so don't pick another protocol in its place. |
| Action | **Allow** |

This rule covers three messages. None of them moves funds, and Fireblocks can't tell them apart, so they all share this one rule:

* The sign-in message lets the app read the account's balance and history.
* The key export message releases the account's viewing and nullifying keys to the app, which it needs to read the balance and build transactions. These keys can't spend anything on their own: every spend still needs an approval from the vault account. The app asks for this message the first time it needs the keys after it loads, which is the first shield or spend, or when it submits a spend that was approved while it was closed. Each one has a new nonce, so Fireblocks signs it fresh every time.
* The vault backup message is part of first-time setup. "Vault" here is Privacy Boost's own key vault, not your Fireblocks vault. The app asks for it twice and checks that the two signatures match, because the account's backup key is derived from the signature. Fireblocks' [signature caching](https://fireblocks.readme.io/reference/caching-signatures), on by default for WalletConnect, returns the same signature the second time, so the repeat can come back without a new approval.

Keep this rule on **Allow**. The app asks for these messages on most visits.

### Approve

| Field | Setting |
| - | - |
| Initiator | Your initiators |
| Source | The vault account |
| Asset | Each token you'll shield, and WETH if you'll shield ETH |
| Maximum | Your largest single shield |
| Action | **Allow** or **Request approval** |

The app approves the pool for exactly the amount being shielded, and skips the approval when the existing allowance already covers it. Include WETH if you'll shield ETH: an ETH shield wraps first and approves second, so without WETH in this rule the shield stops after the ETH has already been wrapped. If your Console lets the Approve rule match the spender, set it to the PrivacyBoost pool.

### Select contract call methods

Select the approved contract destination before choosing its methods:

1. In the **Destination** picker, open **Whitelisted > Contract** and select the checkbox for the named contract wallet you created above. Select the specific wallet, leaving **Any whitelist address** and the whole **Contract** category unselected.
2. Set the address restriction below the picker to **Whitelisted addresses**. This restriction is separate from selecting the named destination.
3. Open **Contract call method**. Fireblocks groups the decoded functions under the wallet name and network asset, such as `ETH-OPT` for Optimism.
4. Search for the function name and select its checkbox. For the pool's shielding rule, select `requestDeposit` and check that its selector is `0x9848bf45`. Use the method rows below for the other rules.

The selectors in the earlier table help identify the function entries. Choose a decoded function from the list; typing in this field searches the available methods.

Fireblocks decodes calls using the contract's verified ABI on the relevant block explorer. If the list is empty or a required function is missing, follow the [troubleshooting checks](#troubleshooting) before saving the rule. See Fireblocks' [instructions for specific contract call methods](https://support.fireblocks.io/hc/en-us/articles/29216898855964-Policy-rules-for-specific-contract-call-methods).

### Contract call: account setup

| Field | Setting |
| - | - |
| Initiator | Your initiators |
| Source | The vault account |
| Destination | **Whitelisted addresses**: AuthRegistry |
| Contract call method | `createAccount` |
| Action | **Allow** or **Request approval** |

`createAccount` runs once per chain and doesn't move funds. Put this rule above the spend approval rule, because both match AuthRegistry.

Use a separate setup rule only when you can select `createAccount` from the AuthRegistry entry's decoded methods. A setup rule matching all AuthRegistry methods would also match spend approvals. If those methods aren't available after the troubleshooting checks, use the spend approval rule for both calls, with the payment approval requirements. If setup fails, reject the request in Fireblocks if it's still pending, and connect again.

### Contract call: shielding

| Field | Setting |
| - | - |
| Initiator | Your initiators |
| Source | The vault account |
| Destination | **Whitelisted addresses**: the PrivacyBoost pool, and WETH if used |
| Contract call method | Select `requestDeposit` from the pool entry and `deposit` from the WETH entry if used |
| Action | **Allow** or **Request approval** |

If the app reports that a shield failed, check Fireblocks before starting it again. A step can still go through in Fireblocks after the app reports the failure, so reject any Privacy Boost request that's still pending there. A wrap or token approval that already went through stays done.

### Contract call: spend approval

| Field | Setting |
| - | - |
| Initiator | Your initiators |
| Source | The vault account |
| Destination | **Whitelisted addresses**: AuthRegistry |
| Contract call method | Select `approveSpendBatch` from the AuthRegistry entry's decoded methods |
| Action | **Request approval**, with your payment approver set and threshold |

This is the rule that authorizes payments. Every send, unshield, Earn action, and swap goes through it, whatever its size, so set the approvers and threshold you'd want on your largest outgoing payment. The threshold counts approvals: "1 of 2 users" means either user can approve on their own. Also decide whether initiators can approve their own payments, and pick the **Designated signer**.

The app doesn't have to stay open while approvers decide. If the approval confirms while the app is closed, the app submits the spend the next time it's opened.

### Rule order

Fireblocks applies the first rule that matches a request. Put the Privacy Boost rules above any broader rule that would catch the same requests, keep the account setup rule above the spend approval rule, and leave the default block rule last. Fireblocks' [policy setup guide](https://fireblocks.readme.io/docs/set-transaction-authorization-policy) covers ordering in more detail.

## Workspace settings

Check these under **gear icon > Settings > General**:

| Setting | Recommended |
| - | - |
| **'Approve' transaction amount cap** | At or above your largest shield. Token approvals over the cap fail even when the Approve rule allows them. |
| **One-time address transactions** | Can stay disallowed, as long as every contract has an allowlist entry. |

## Connect the app

Connect over WalletConnect only. The app recognizes Fireblocks from the WalletConnect session. Through the Fireblocks browser extension it sees an ordinary browser wallet and creates a standard account, which can't be switched to approval-only later.

Once the policies are published, an initiator connects the vault account:

1. In [Privacy Boost](https://app.privacyboost.io), choose **Connect wallet**, check the network shown under the wallet list, then choose **WalletConnect**.
2. Choose Fireblocks in the WalletConnect window, or paste the connection URI into Fireblocks. In the Fireblocks mobile app, use **Scan** or **Settings > Connect DeFi App**.
3. In Fireblocks, select the vault account, network, and fee level.
4. Before approving the sign-in message, check that the app shows **Approval-only with Fireblocks**. If it doesn't, reject the request and reconnect over WalletConnect.
5. Approve the sign-in message, save the recovery phrase the app shows, then approve the vault backup message and the `createAccount` transaction.

The recovery phrase lets whoever has it read the account's balance and history. It can't move funds, since every spend still needs an approval from the vault account. Keep it with your other sensitive treasury records and limit who can see it.

An approval-only session uses one network at a time. Fireblocks lists it under **Connections > Web3 > Connected dApps**. For pairing details, see Fireblocks' [WalletConnect integration](https://support.fireblocks.io/hc/en-us/articles/5403817784732-WalletConnect-integration) article.

## Check the configuration

Run these with small amounts in a Testnet workspace before production. Each transaction's details in Fireblocks show which rule matched. Use ETH for the shield tests on a testnet: OP Sepolia has no stablecoin registered with Privacy Boost, and the USDC registered on Base Sepolia isn't Circle's test USDC.

| Test | Expected result |
| - | - |
| Connect and sign in | The dApp connection and Typed message rules match, and the app shows the vault account's address. |
| First-time setup | `createAccount` matches the setup rule (or the spend approval rule) and confirms. |
| Shield a token | The token approval and `requestDeposit` match their rules, and the private balance updates. |
| Send a small amount | The approval goes to the payment approvers with the expected threshold, and the send settles after it confirms. |
| Reject a spend approval | Nothing is spent, and the private balance is unchanged. |
| Initiate from a user outside the rules | The request is blocked. |
| Sign in from another browser | The same account and balance appear. |
| Shield or send after reloading the app | The key export message matches the Typed message rule, then the shield or send continues. |

## Troubleshooting

| Symptom | What to check |
| - | - |
| The app doesn't show **Approval-only with Fireblocks** during sign-in | The connection didn't come through WalletConnect, or wasn't recognized as Fireblocks. Disconnect and reconnect over WalletConnect. |
| Fireblocks receives an EIP-712 request from Privacy Boost | The app connected the vault account as a standard account. Reject it, disconnect, and reconnect over WalletConnect. |
| Sign-in fails | The Typed message rule's initiator and source, and any signing approval it requires. |
| Setup says the wallet returned a different signature each time | The two vault backup signatures didn't match. Ask Fireblocks support about signature caching for the connection. |
| **Add ETH to finish setup**, or Fireblocks returns `Session settlement failed` | The vault account needs ETH on this network to pay for `createAccount`. |
| `BLOCKED_BY_POLICY` | The operation type and matched rule number in the transaction details, then the rule's initiator, source, destination, and position. |
| A spend approval doesn't reach the payment approvers | An earlier rule matching AuthRegistry with a different action. |
| The token approval succeeds, but the shield fails | The shielding Contract call rule, the vault account's ETH balance, and whether `requestDeposit` is still pending in Fireblocks. |
| An ETH shield wraps, then fails at the token approval | WETH in the Approve rule's assets. |
| The token approval is over the permitted amount | The Approve rule's maximum and **Settings > General > 'Approve' transaction amount cap**. |
| A new allowlist entry still fails | **Settings > General > Address whitelist suspension** and the entry's approval state. |
| Contract call method shows **Nothing to display** | Confirm the wallet is type **Contract**, contains an approved address on the correct network, and is selected through **Destination > Whitelisted > Contract**. A dApp URL entry alone doesn't populate contract methods. |
| The contract is selected, but a required function is missing | Check that the contract has a verified ABI on that network's block explorer. If the ABI is verified and the function is still missing, contact Fireblocks Support. |
| `INSUFFICIENT_FUNDS_FOR_FEE` | ETH on the exact network, including the Fireblocks fee reserve. |
| The request fails while approvers are still reviewing it | Only the spend approval can wait for approvers. Reject the pending request in Fireblocks, then try again with an approver ready or the rule on **Allow**. |
| An approval confirmed, but the spend hasn't settled | The app submits approved spends while it's open. Open it and check the spend under **Fireblocks approvals**. |
| Wrong or zero address, or the asset isn't supported | Mainnet versus Testnet workspace, and the network-specific asset. |

Fireblocks' [substatus reference](https://fireblocks.readme.io/reference/sub-statuses) explains each substatus.

When contacting Privacy Boost support, include the failing step, workspace type, network, Fireblocks transaction ID and substatus, and the matched rule number. Never share API secrets, signatures, private keys, or recovery phrases.

## SDK integrations

An application built on the Privacy Boost SDK uses the same Fireblocks configuration, with these differences:

* Allowlist your application's origin instead of `app.privacyboost.io`.
* Create the SDK with `approvalOnly: true`. The SDK doesn't detect Fireblocks, so your application sets the mode. Approval-only mode needs the SDK's wallet login, not a `tokenProvider`. See [Authentication](https://docs.privacyboost.io/sdk/concepts/authentication.md#approval-only-eoa-multichain-authentication).
* The example below sends `approveSpendBatch`, like the app. If your integration also sends `approveSpend(uint256,uint256,uint64)` (what `buildApproveSpendTransaction` builds) or `revokeSpendApprovalBatch(uint256,uint256)`, add them to the AuthRegistry rule.
* Your WalletConnect session needs `personal_sign`, `eth_signTypedData_v4`, and `eth_sendTransaction` on the selected chain. The SDK's WalletConnect adapter requests all three.
* If you send requests through the Fireblocks API instead of WalletConnect, scope the rules to the API user, and keep the API credentials on your server.

Your application also takes over what the app does around each spend: build the plan, show the verified details to approvers, send the approval from the vault account, and submit the plan once the approval is indexed.

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

const approvalExpiry = String(Math.floor(Date.now() / 1000) + 72 * 60 * 60);
const plan = await sdk.vault.buildSendApprovalPlan({
  tokenAddress,
  amount: 1_000_000n,
  to: recipientPrivacyAddress,
  approvalExpiry,
});

// Throws unless the plan's details match its commitment. Show
// plan.owner.recipient, amount, fee, and commitment to the approvers.
await sdk.vault.verifyApprovalOwnerPackage(plan.owner);

const { authRegistryAddress } = await sdk.getServerInfo();
const approval = buildApproveSpendBatchTransaction(
  authRegistryAddress!,
  plan.owner.accountId,
  plan.owner.expiry,
  [plan.owner],
);
await walletClient.sendTransaction({
  account: walletClient.account!,
  chain: walletClient.chain,
  to: approval.to,
  data: approval.data,
  value: 0n,
});

// Later, once the approval has confirmed and been indexed:
const status = await sdk.vault.getApprovalStatus(plan.owner.commitment);
if (status.status === 'active') {
  await sdk.vault.submitPrebuiltSendApprovalPlan(plan.privatePlan);
}
```

Don't block a user flow on the Fireblocks approval. `sdk.vault.reconcilePendingApprovals()` submits every plan whose approval is active and prunes expired ones; run it at startup and on an interval while plans are pending.


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