Fireblocks Setup
This page is for the Fireblocks admin connecting a vault account to the Privacy Boost app. 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.
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.
- 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 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 URLhttps://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:
- Choose Whitelisted addresses > Add > Whitelisted address wallet.
- Set the type to Contract, enter a descriptive name such as
PrivacyBoost pool OP Mainnet, and choose Create wallet. - Open the wallet and choose Add address. Creating the wallet alone leaves it empty.
- 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.
- Paste the contract address for that network and choose Add address.
- If the entry shows Pending approval, have the configured workspace approvers approve the address request in Fireblocks before using it in a policy.
Contract addresses
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:
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.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.
- Select the policy type and choose Edit policy.
- Choose Add rule, or open an existing rule’s three-dot menu > Edit.
- 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 to choose the destination and functions.
- 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).
- Choose Publish policy. A saved rule does nothing until the policy is published and any publication approval is done.
dApp connection
Allowing the connection doesn’t let the app sign anything. Each request still has to match one of the rules below.
Typed message
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, on by default for WalletConnect, returns the same signature the second time, so the repeat can come back without a new approval.
Approve
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:- 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.
- Set the address restriction below the picker to Whitelisted addresses. This restriction is separate from selecting the named destination.
- Open Contract call method. Fireblocks groups the decoded functions under the wallet name and network asset, such as
ETH-OPTfor Optimism. - Search for the function name and select its checkbox. For the pool’s shielding rule, select
requestDepositand check that its selector is0x9848bf45. Use the method rows below for the other rules.
Contract call: account setup
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
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
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 covers ordering in more detail.Workspace settings
Check these under gear icon > Settings > General: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:- In Privacy Boost, choose Connect wallet, check the network shown under the wallet list, then choose WalletConnect.
- 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.
- In Fireblocks, select the vault account, network, and fee level.
- 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.
- Approve the sign-in message, save the recovery phrase the app shows, then approve the vault backup message and the
createAccounttransaction.
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.Troubleshooting
Fireblocks’ substatus reference 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 atokenProvider. See Authentication. - The example below sends
approveSpendBatch, like the app. If your integration also sendsapproveSpend(uint256,uint256,uint64)(whatbuildApproveSpendTransactionbuilds) orrevokeSpendApprovalBatch(uint256,uint256), add them to the AuthRegistry rule. - Your WalletConnect session needs
personal_sign,eth_signTypedData_v4, andeth_sendTransactionon 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.
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.