Quick Start for Contract Devs

This guide will help a developer to develop a smart contract that contains secure operations using the Bubble network.

Installation

Install the Bubble Solidity library:

npm install @sodalabs/bubble-core-contracts

Import it directly from node_modules — there is no copy step and no compiler remapping to configure:

import "@sodalabs/bubble-core-contracts/contracts/bubble/MpcCore.sol";
import "@sodalabs/bubble-core-contracts/contracts/bubble/DecryptionCaller.sol";

The library selects the Bubble host contracts for the chain you deploy to by block.chainid, so the same source compiles and deploys to every supported network without changes. See Contract addresses for the supported chains.

Writing a Private Smart Contract

1. Import and use the MpcCore.sol library: Import MpcCore.sol into every contract that handles encrypted values. It provides the MPC operations used for private computation, and routes each operation to the host contracts for your chain.

   Encrypted values are opaque handles. Store and pass these handles between operations. Do not try to read or convert their plaintext value in Solidity.

   See operations on encrypted types for supported types and operation signatures, and decryption for the controlled decryption flow.

2. Grant permissions on every new handle: A new handle is unusable until permission is granted — not even by the contract that created it. Call MpcCore.permitThis(handle) on any handle the contract stores or uses again.

   Grant a user access only for values that user is meant to see — a balance, a result they requested — with MpcCore.permit(handle, userAddress). Without it, Read an encrypted value returns user is not permitted to make this operation.

   Do not permit intermediate handles. A running subtotal or the result of a comparison needs permitThis alone; granting a user access to it widens the ACL permanently and can expose values the contract never meant to disclose.

3. Accept encrypted inputs: To keep a value off the calldata, the caller encrypts it client-side with Prepare private inputs and passes an itUint*. The contract turns it into a handle with MpcCore.validateCiphertext(it).

4. Read results off-chain: Encrypted results leave the chain through Read an encrypted value, which returns the value encrypted to the user's AES key.

Worked example

How to Transform Your Smart Contract into a Bubble Smart Contract walks a public contract through to a Bubble one, with before/after Solidity and a mini ERC-20.

For complete contracts, see bubble-app-contracts — wallet/contracts/PrivateERC20Contract256.sol is a full confidential ERC-20 with encrypted balances, transfers and allowances. Putting it together runs it end to end on a live network.