DEV Community: rayQu

Building a Confidential Bug Bounty Platform with Oasis Sapphire

rayQu — Sun, 11 Oct 2026 06:47:52 +0000

Building a Confidential Bug Bounty Platform with Oasis Sapphire

An advanced tutorial on private vulnerability reports, confidential triage, and verifiable bounty payouts

Bug bounty platforms have a difficult security problem.

A researcher discovers a vulnerability in a smart contract and submits a report. The report may contain exploit steps, proof-of-concept code, affected endpoints, or details that would allow someone else to reproduce the issue.

If the report becomes public too early, the disclosure process can turn into an attacker's instruction manual.

But making everything private creates another problem: researchers need confidence that their submissions will be timestamped, evaluated fairly, and rewarded according to clear rules.

This is an interesting use case for Oasis Sapphire.

Sapphire provides an EVM-compatible environment for confidential smart contract state and execution. Instead of putting sensitive report contents directly into public contract storage or events, we can design a system where reports remain confidential while submission commitments, bounty rules, and final payout records can be independently verified.

In this tutorial, we'll design an advanced confidential bug bounty platform using Solidity and Oasis Sapphire.

We'll cover:

Confidential vulnerability submissions
Commitments that provide evidence of a report's integrity
Private triage and severity assessment
Bounty policy enforcement
Duplicate-submission handling
Controlled disclosure
Verifiable payout records
Threat modeling and production considerations

The key design principle is simple:

Keep the vulnerability confidential until disclosure is safe, but make the bounty process accountable from the beginning.

1. Architecture: Separate the Report from Its Proof

The first mistake would be to put the entire vulnerability report onchain.

Even if a Solidity variable is marked private, that keyword does not provide confidentiality on an ordinary public EVM chain. Sapphire's confidential execution environment gives us a different foundation, but we still need to avoid accidentally leaking sensitive data through events, public interfaces, or transaction metadata.

We'll separate the system into three components.

flowchart TD
    R[Security Researcher] -->|Encrypted submission| S[Sapphire Contract]
    S --> C[Confidential Report State]
    S --> P[Public Commitment and Status]
    T[Authorized Triage Team] -->|Authenticated review| S
    S -->|Approved decision| B[Bounty Policy]
    B -->|Verified payout authorization| W[Treasury or Payout Contract]
    W --> L[Public Settlement Record]

The report contains the technical details of the vulnerability. The commitment gives the researcher evidence that a specific report was submitted. The payout record makes the financial outcome auditable without publishing the exploit itself.

These are separate guarantees.

A commitment does not prove that a report is valid. A confidential contract does not automatically make every transaction field private. A payout record does not prove that the triage decision was correct.

The system must make those boundaries explicit.

2. Define the Submission Lifecycle

A bounty platform needs a lifecycle that prevents reports from jumping directly from submission to payout.

We'll use the following states:

stateDiagram-v2
    [*] --> Submitted
    Submitted --> UnderReview
    UnderReview --> Duplicate
    UnderReview --> Rejected
    UnderReview --> Accepted
    Accepted --> RewardAuthorized
    RewardAuthorized --> Paid
    Accepted --> DisclosureReady
    Paid --> DisclosureReady
    DisclosureReady --> Disclosed

A real implementation should define whether payment is required before disclosure, how disputed reports are handled, and what happens if a project never responds.

For this tutorial, the important distinction is between report confidentiality and process transparency. We can keep the report private while exposing a limited, non-sensitive status and eventual settlement record.

3. Project Structure

We'll use Solidity, Hardhat, and TypeScript.

confidential-bounty/
├── contracts/
│   ├── ConfidentialBounty.sol
│   ├── BountyTreasury.sol
│   └── interfaces/
│       └── IBountyPolicy.sol
├── scripts/
│   ├── deploy.ts
│   └── configure-policy.ts
├── test/
│   ├── ConfidentialBounty.ts
│   └── BountyTreasury.ts
├── app/
│   ├── submit-report.ts
│   └── reviewer-client.ts
├── docs/
│   ├── threat-model.md
│   └── disclosure-policy.md
├── hardhat.config.ts
└── package.json

The contract handles submission state and policy enforcement. The client is responsible for encrypting and submitting the report through a Sapphire-compatible transaction flow. The treasury handles settlement separately so the bounty system doesn't need unrestricted custody of funds.

4. Model the Report Carefully

A report needs more than a string.

At minimum, it needs an identifier, a commitment, a submitter, a status, and a bounty policy version.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract ConfidentialBounty {
    enum Status {
        None,
        Submitted,
        UnderReview,
        Duplicate,
        Rejected,
        Accepted,
        RewardAuthorized,
        Paid,
        Disclosed
    }

    struct Report {
        bytes32 commitment;
        address researcher;
        Status status;
        uint32 policyVersion;
        uint64 submittedAt;
    }

    mapping(bytes32 => Report) private reports;

    event ReportRegistered(
        bytes32 indexed reportId,
        bytes32 commitment,
        uint32 policyVersion
    );

    function registerReport(
        bytes32 reportId,
        bytes32 commitment,
        uint32 policyVersion
    ) external {
        require(reportId != bytes32(0), "Invalid report ID");
        require(commitment != bytes32(0), "Invalid commitment");
        require(
            reports[reportId].status == Status.None,
            "Report already exists"
        );

        reports[reportId] = Report({
            commitment: commitment,
            researcher: msg.sender,
            status: Status.Submitted,
            policyVersion: policyVersion,
            submittedAt: uint64(block.timestamp)
        });

        emit ReportRegistered(
            reportId,
            commitment,
            policyVersion
        );
    }
}

This is a starting point, not a complete production contract.

The example deliberately keeps the report body out of the event. The commitment can help establish that a particular report corresponds to a registered submission, but the report ID and submitter address are still visible in the event.

If submitter identity or submission timing is sensitive, even this metadata requires additional design.

On Sapphire, the confidential report body should be stored and processed through confidential contract state, while the public interface should reveal only information that the disclosure policy explicitly permits.

5. Commit to the Report Without Publishing It

How can a researcher prove that a report hasn't been silently replaced after submission?

A useful starting point is a cryptographic commitment.

Let:

report be the complete report content
salt be a high-entropy random secret
version identify the report format

The researcher computes:

commitment = keccak256(
    encode(version, report, salt)
)

The commitment can be registered with the report ID. Later, the researcher can reveal the report and salt to demonstrate that the revealed content matches the original commitment.

However, there is a critical caveat.

A hash does not automatically protect low-entropy information. If the report is predictable, someone may guess candidate contents and compare their hashes. The random salt must be generated securely and kept secret until disclosure.

The client should use a canonical encoding format, and the contract should define exactly which fields are included in the commitment. Otherwise, different encodings of the same logical report may produce inconsistent commitments.

For reports containing confidential source code or exploit details, the commitment should not replace encrypted storage. It provides an integrity mechanism, not a confidentiality mechanism.

6. Enforce Bounty Rules with Versioned Policies

Bounty programs often change their reward limits, supported targets, and severity definitions.

If a policy changes while a report is under review, which version should apply?

The answer should be explicit.

Each report should reference a policy version that was active when it was submitted. The policy should define:

Eligible contracts or systems
Severity categories
Reward ranges
Duplicate-report rules
Exclusions
Disclosure requirements
Review deadlines

For example:

struct BountyPolicy {
    uint128 criticalMax;
    uint128 highMax;
    uint128 mediumMax;
    uint128 lowMax;
    uint64 reviewDeadline;
    bool active;
}

mapping(uint32 => BountyPolicy) private policies;

In production, changing a policy should create a new version rather than silently rewriting the terms associated with existing reports.

The contract should validate that the selected policy version exists and that the report references a version permitted by the program.

The reward authorization process should also verify that the report is in an eligible state, the proposed reward is within the relevant limit, and the request has not already been used.

7. Keep Triage Confidential, but Make It Accountable

A confidential report can contain information that only a small review team should access.

That does not mean the triage process should be an unrestricted black box.

A production design should separate the permissions to:

Read a report.
Change its status.
Assign a severity.
Authorize a reward.
Approve disclosure.

These permissions should not automatically belong to the same address.

A multisig or governance-controlled role can manage reviewer membership, while a dedicated authorization path enforces reward limits. For more complex offchain analysis, a ROFL application could perform selected computations inside a trusted execution environment and provide evidence about the computation's origin.

ROFL should not be treated as a magical correctness oracle. Remote attestation can provide evidence about the environment and code being executed, but it does not prove that the underlying vulnerability assessment is objectively correct.

A reviewer still needs sound security reasoning, and the protocol needs a clear process for disputes.

8. A Safer Disclosure Workflow

Disclosure is one of the most important parts of the system.

A report should not become public just because its status changes to Accepted.

Instead, define a separate disclosure process with explicit conditions:

sequenceDiagram
    participant R as Researcher
    participant C as Sapphire Contract
    participant V as Reviewer
    participant T as Treasury
    participant P as Project Maintainer

    R->>C: Submit encrypted report
    C-->>R: Report ID and commitment
    V->>C: Request authorized review
    V->>C: Record review decision
    C->>C: Check policy and status
    C->>T: Authorize eligible reward
    T-->>R: Pay researcher
    P->>P: Patch and validate vulnerability
    P->>C: Confirm disclosure readiness
    R->>P: Coordinate responsible disclosure

This is a conceptual workflow. A production system must implement authenticated reviewer access, authorization checks, deadlines, dispute resolution, and secure report delivery.

In particular, a public function that returns a report body would undermine confidentiality. Reviewer access should use Sapphire's supported confidential call and authentication patterns, and sensitive report data should never be emitted in ordinary public events.

9. Threat Model

Before deployment, consider at least the following threats.

Threat	Mitigation
Report contents leak through events	Emit only approved metadata
Report is replaced after submission	Use a canonical, salted commitment
Researcher submits the same report repeatedly	Define duplicate rules and use stable report identifiers
Reviewer abuses privileged access	Separate roles, log approved actions, and limit permissions
Reward is paid twice	Use unique authorization IDs and replay protection
Policy changes mid-review	Pin each report to an explicit policy version
Exploit becomes public too early	Define access control and staged disclosure
Metadata reveals a sensitive incident	Minimize public fields and evaluate timing leakage
ROFL computation is treated as unquestionable	Separate attestation evidence from correctness claims

Confidential computing also has limitations. Transaction timing, gas usage, input size, and observable state transitions can reveal information. Sapphire developers should review the platform's security guidance and avoid assuming that encrypted state eliminates every side channel.

10. What Makes This Useful Beyond Bug Bounties?

The same design pattern can support other applications that need confidential submissions and accountable decisions:

Private security audits
Confidential vulnerability disclosure
Responsible AI incident reporting
Private compliance reports
Confidential grant applications
Whistleblower submission systems

In each case, the core problem is similar: sensitive information must be available to authorized reviewers without becoming public by default, while the process needs evidence, permissions, and a clear outcome.

The most important architectural decision is to separate the confidential content, the public evidence, and the authority to act on a submission.

Oasis Sapphire provides a confidential EVM environment for building this kind of application. ROFL can extend the architecture when verifiable offchain computation is useful. Neither removes the need for careful access control, cryptographic design, or a well-defined disclosure process.

Conclusion

A bug bounty platform is a useful example of why confidentiality and transparency don't have to be opposites.

The vulnerability report can remain confidential. The submission commitment can provide evidence of integrity. The policy can constrain the reward. The settlement can be independently verified. And disclosure can happen only when the appropriate conditions are met.

That is a much more useful model than publishing every detail onchain or asking everyone to trust a private database.

The goal is not to make the entire process invisible.

It is to make sensitive information private while keeping important decisions accountable.

Resources

Oasis Sapphire: https://docs.oasis.io/build/sapphire/
Sapphire developer documentation: https://docs.oasis.io/build/sapphire/develop/
Oasis ROFL: https://docs.oasis.io/build/rofl/
Sapphire encrypted events: https://docs.oasis.io/build/sapphire/develop/encrypted-events/
Oasis security documentation: https://docs.oasis.io/build/sapphire/develop/security/

Build a Private Onchain Feedback Box with Oasis Sapphire

rayQu — Thu, 24 Sep 2026 05:33:36 +0000

What if you wanted to collect honest feedback onchain without publishing everyone's answers?

A normal Ethereum smart contract is a strange place for something like this.

You can store feedback cheaply and transparently, but anyone can inspect the contract's storage or events. That is useful for many applications, but not for anonymous feedback, internal surveys, product reviews, private ratings, or user research.

This is where Oasis Sapphire becomes interesting.

Sapphire is an EVM-compatible confidential environment where contract state is encrypted and confidential computation happens inside Oasis infrastructure. You can therefore keep sensitive application data private while still using familiar Solidity and EVM tooling.

In this tutorial, we'll build a small private feedback box.

Users will be able to submit:

a 1–5 rating
a text comment

The individual comments will remain confidential.

The contract will expose only aggregate information such as:

number of submissions
total rating
average rating

So the application can answer:

“What do users think?”

without automatically publishing:

“What did Alice specifically say?”

What We're Building

The architecture is intentionally small.

                    ┌──────────────────────┐
                    │      User Wallet     │
                    └──────────┬───────────┘
                               │
                       Encrypted TX
                               │
                               ▼
                    ┌──────────────────────┐
                    │   Oasis Sapphire     │
                    │                      │
                    │  Private feedback    │
                    │  + aggregate stats   │
                    └──────────┬───────────┘
                               │
                 ┌─────────────┴─────────────┐
                 │                           │
                 ▼                           ▼
          Private comments            Public aggregates
          + ratings                   count / total

The important design decision is that we don't emit the feedback itself as a normal Solidity event.

That's important because standard EVM events are public on Sapphire too. If you put sensitive feedback directly into an event, you can undermine the confidentiality of the underlying state. Oasis provides encrypted events for applications that specifically need confidential event payloads.

For our simple application, we'll just keep the feedback in contract state.

1. Create the Project

We'll use Hardhat and TypeScript.

Create a project:

mkdir private-feedback-box
cd private-feedback-box

npm init -y

npm install --save-dev \
  hardhat \
  @nomicfoundation/hardhat-toolbox \
  typescript \
  ts-node

npm install \
  @oasisprotocol/sapphire-contracts \
  @oasisprotocol/sapphire-paratime

Oasis Sapphire is EVM-compatible, so existing Ethereum development tools such as Hardhat can be used. The main addition is Oasis' Sapphire tooling for confidential transactions and contract functionality.

Your project can look like this:

private-feedback-box/
│
├── contracts/
│   └── FeedbackBox.sol
│
├── scripts/
│   └── deploy.ts
│
├── test/
│   └── FeedbackBox.ts
│
├── hardhat.config.ts
├── package.json
└── tsconfig.json

2. Configure Sapphire

Create hardhat.config.ts:

import { HardhatUserConfig } from "hardhat/config";
import "@oasisprotocol/sapphire-hardhat";
import "@nomicfoundation/hardhat-toolbox";

const accounts = process.env.PRIVATE_KEY
  ? [process.env.PRIVATE_KEY]
  : {
      mnemonic:
        "test test test test test test test test test test test junk",
      path: "m/44'/60'/0'/0",
      initialIndex: 0,
      count: 20,
      passphrase: "",
    };

const config: HardhatUserConfig = {
  solidity: {
    version: "0.8.24",
    settings: {
      evmVersion: "paris",
    },
  },

  networks: {
    sapphire: {
      url: "https://sapphire.oasis.io",
      chainId: 0x5afe,
      accounts,
    },

    "sapphire-testnet": {
      url: "https://testnet.sapphire.oasis.io",
      chainId: 0x5aff,
      accounts,
    },

    "sapphire-localnet": {
      url: "http://localhost:8545",
      chainId: 0x5afd,
      accounts,
    },
  },
};

export default config;

The official Sapphire quickstart currently uses these Sapphire network identifiers and RPC endpoints for mainnet, testnet, and localnet.

The important part is:

import "@oasisprotocol/sapphire-hardhat";

This allows the Hardhat environment to apply Sapphire's transaction handling automatically.

3. Write the Feedback Contract

Create:

contracts/FeedbackBox.sol

Then add:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract FeedbackBox {
    struct Feedback {
        uint8 rating;
        string comment;
        uint256 timestamp;
    }

    mapping(address => Feedback) private feedback;

    uint256 private submissionCount;
    uint256 private totalRating;

    event FeedbackSubmitted(address indexed user);

    function submitFeedback(
        uint8 rating,
        string calldata comment
    ) external {
        require(rating >= 1 && rating <= 5, "rating must be 1-5");
        require(bytes(comment).length > 0, "comment required");

        require(
            feedback[msg.sender].timestamp == 0,
            "feedback already submitted"
        );

        feedback[msg.sender] = Feedback({
            rating: rating,
            comment: comment,
            timestamp: block.timestamp
        });

        submissionCount++;
        totalRating += rating;

        emit FeedbackSubmitted(msg.sender);
    }

    function getMyFeedback()
        external
        view
        returns (
            uint8 rating,
            string memory comment,
            uint256 timestamp
        )
    {
        Feedback memory item = feedback[msg.sender];

        require(item.timestamp != 0, "no feedback");

        return (
            item.rating,
            item.comment,
            item.timestamp
        );
    }

    function getStats()
        external
        view
        returns (
            uint256 count,
            uint256 total,
            uint256 average
        )
    {
        count = submissionCount;
        total = totalRating;

        if (count > 0) {
            average = total / count;
        }
    }
}

At first glance, this looks almost identical to a normal Solidity contract.

That's intentional.

The interesting part is not a new programming language.

It's the execution environment.

4. Why `private` Matters Differently Here

On Ethereum, developers sometimes misunderstand Solidity's private keyword.

This:

mapping(address => Feedback) private feedback;

does not make the data cryptographically private on Ethereum.

It only prevents other Solidity contracts from directly accessing the variable.

Blockchain observers can still inspect Ethereum's underlying state.

Sapphire changes the model.

Sapphire's contract state is encrypted, and the contract running inside the confidential environment is the entity that can request the relevant state encryption key.

That means our feedback mapping can actually contain confidential application data.

So this:

mapping(address => Feedback) private feedback;

is meaningful for confidentiality when deployed on Sapphire.

But there is an important detail.

5. Don't Accidentally Publish the Feedback

This event is okay:

event FeedbackSubmitted(address indexed user);

It tells observers that an address submitted feedback.

But this would be a bad idea:

event FeedbackSubmitted(
    address indexed user,
    uint8 rating,
    string comment
);

Why?

Because normal event payloads are public.

Sapphire's documentation explicitly notes that Solidity events behave like Ethereum events, meaning event data is not automatically confidential.

If you need confidential event data, Sapphire supports encrypted event payloads.

For our beginner example, however, we simply don't put the sensitive information into the event.

6. Add a Simple Deployment Script

Create:

scripts/deploy.ts

import { ethers } from "hardhat";

async function main() {
  const FeedbackBox =
    await ethers.getContractFactory("FeedbackBox");

  const feedbackBox =
    await FeedbackBox.deploy();

  await feedbackBox.waitForDeployment();

  console.log(
    "FeedbackBox deployed to:",
    await feedbackBox.getAddress()
  );
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Compile:

npx hardhat compile

Then deploy to Sapphire Testnet:

npx hardhat run scripts/deploy.ts \
  --network sapphire-testnet

Before deploying to testnet, you'll need Sapphire testnet tokens from the Oasis faucet.

For rapid local development, Oasis also provides a Sapphire Localnet that runs in Docker. The official documentation recommends Localnet or Sapphire Testnet when testing confidential features.

7. Submit Private Feedback

You can interact with the contract from a Hardhat task, script, or frontend.

A simple example:

const feedbackBox =
  await ethers.getContractAt(
    "FeedbackBox",
    CONTRACT_ADDRESS
  );

const tx = await feedbackBox.submitFeedback(
  5,
  "The application is fast and easy to use."
);

await tx.wait();

console.log("Feedback submitted");

The important part is that the transaction containing the comment should be sent through Sapphire's confidential transaction tooling.

For browser applications, Oasis provides wrappers for common EVM libraries including Ethers, Viem, and Wagmi.

For example, the Sapphire TypeScript wrapper can wrap an injected wallet provider:

import {
  wrapEthereumProvider
} from "@oasisprotocol/sapphire-paratime";

const provider =
  wrapEthereumProvider(window.ethereum);

This is the layer that makes it practical to use normal Web3 wallets while still sending confidential transactions.

8. Reading the Statistics

Now we have an interesting separation.

Anyone can call:

getStats()

and retrieve:

Submissions: 143
Total rating: 587
Average: 4

But that doesn't reveal every individual comment.

Conceptually:

                   Feedback
                       │
             ┌─────────┴─────────┐
             │                   │
             ▼                   ▼
       Private state         Aggregates
             │                   │
             │                   └── count
             │                   └── total
             │                   └── average
             │
             └── rating
             └── comment
             └── timestamp

This is a useful pattern far beyond feedback.

The same architecture can work for:

private product reviews
internal company surveys
anonymous community feedback
private ratings
confidential research
user preference storage
private application configuration

The general pattern is:

Store sensitive information privately. Expose only the derived information that needs to be public.

9. What About `getMyFeedback()`?

There's one subtle Sapphire concept worth understanding.

This function:

function getMyFeedback()
    external
    view
    returns (...)
{
    Feedback memory item = feedback[msg.sender];

    require(item.timestamp != 0, "no feedback");

    return (...);
}

works naturally for authenticated calls.

But a plain eth_call on Sapphire does not automatically give the contract an arbitrary authenticated msg.sender. For unauthenticated view calls, Sapphire uses the zero address.

This is important because confidential data requires stronger access control than a traditional public EVM application.

For frontend applications, Oasis documents SIWE-based authenticated view calls.

For backend services, Sapphire also supports signed queries using EIP-712.

So a production version of this feedback box would typically use authenticated view calls when users need to retrieve their private feedback.

10. A Minimal Test

Create:

test/FeedbackBox.ts

import { expect } from "chai";
import { ethers } from "hardhat";

describe("FeedbackBox", function () {
  it("stores feedback and updates statistics", async function () {
    const [user] = await ethers.getSigners();

    const FeedbackBox =
      await ethers.getContractFactory("FeedbackBox");

    const box =
      await FeedbackBox.deploy();

    await box.waitForDeployment();

    await box.submitFeedback(
      5,
      "Excellent experience"
    );

    const stats = await box.getStats();

    expect(stats.count).to.equal(1);
    expect(stats.total).to.equal(5);
    expect(stats.average).to.equal(5);
  });

  it("prevents duplicate submissions", async function () {
    const FeedbackBox =
      await ethers.getContractFactory("FeedbackBox");

    const box =
      await FeedbackBox.deploy();

    await box.waitForDeployment();

    await box.submitFeedback(
      4,
      "Good experience"
    );

    await expect(
      box.submitFeedback(
        5,
        "Trying again"
      )
    ).to.be.revertedWith(
      "feedback already submitted"
    );
  });
});

Run:

npx hardhat test

For testing Sapphire-specific confidentiality, use Sapphire Localnet or Sapphire Testnet rather than relying only on a standard Ethereum-style local chain. Oasis specifically recommends a Sapphire-supported network for testing confidential features.

11. One Important Production Improvement

Our example intentionally keeps the contract simple.

A production application should think carefully about metadata leakage.

Confidentiality does not necessarily hide everything about execution.

Oasis documents several potential side channels, including gas usage, execution time, storage-access patterns, and transaction size. The size of encrypted state is also not automatically hidden.

For example, this:

if (bytes(comment).length > 1000) {
    ...
}

could potentially create observable differences in execution.

Likewise, variable-length sensitive inputs can expose their size.

For higher-security applications, consider:

fixed-size inputs
padding
bucketized sizes
constant-ish execution paths
avoiding sensitive values in normal events
carefully designed access control

These considerations become increasingly important as an application moves from a demo to production.

12. Why This Pattern Is Interesting

The feedback box looks almost trivial.

That's actually the point.

A blockchain doesn't have to put every piece of application data into public state.

Instead, you can divide application information into two categories:

Public information

Things users need to verify:

How many submissions?
What is the average rating?
Has this address submitted?

Private information

Things the application needs but the entire network doesn't:

What did the user write?
What rating did they give?
What private metadata is attached?

Sapphire gives developers an environment where that distinction can exist inside an EVM-compatible application.

You don't have to abandon Solidity.

You don't need to invent a new smart-contract language.

You simply design the application around confidential state from the beginning.

Final Architecture

The finished application is conceptually simple:

User
 │
 │ encrypted transaction
 ▼
┌──────────────────────────────┐
│       Oasis Sapphire         │
│                              │
│  ┌────────────────────────┐  │
│  │ Confidential Feedback  │  │
│  │                        │  │
│  │ rating                 │  │
│  │ comment                │  │
│  │ timestamp              │  │
│  └────────────────────────┘  │
│                              │
│  ┌────────────────────────┐  │
│  │ Public Aggregates      │  │
│  │                        │  │
│  │ count                  │  │
│  │ total                  │  │
│  │ average                │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

The bigger lesson isn't the feedback form.

It's the architecture.

Blockchain applications don't always need to choose between complete transparency and complete centralization.

With confidential execution, an application can keep sensitive state private while still using smart contracts, wallets, and verifiable onchain state.

That opens up a surprisingly large design space for applications that previously didn't make much sense on public blockchains.

What You Can Build From Here

Once the basic feedback box works, several extensions become possible:

Anonymous mode

Allow users to submit feedback without storing their wallet address alongside the feedback.

Multiple surveys

Create separate confidential surveys with different access policies.

Private categories

Store additional confidential metadata such as department, product version, or region.

Encrypted events

Use Sapphire's encrypted-event functionality when an off-chain service needs to consume confidential feedback without exposing the plaintext onchain.

Authenticated dashboards

Add SIWE authentication so authorized users can retrieve confidential records through a frontend.

And that's where this small tutorial becomes a reusable pattern:

Keep raw data confidential. Publish only the information that actually needs to be public.

That is one of the simplest ways to start thinking differently about what an onchain application can be.

Resources

Oasis Sapphire

https://docs.oasis.io/build/sapphire/

Sapphire Developer Documentation

https://docs.oasis.io/build/sapphire/develop/

Sapphire Quickstart

https://docs.oasis.io/build/sapphire/quickstart/

View-Call Authentication

https://docs.oasis.io/build/sapphire/develop/authentication/

Encrypted Events

https://docs.oasis.io/build/sapphire/develop/encrypted-events/

Testing Sapphire Applications

https://docs.oasis.io/build/sapphire/develop/testing/

Building a Confidential On-Chain Credit Underwriting Engine with Oasis Sapphire + ROFL

rayQu — Wed, 09 Sep 2026 14:44:56 +0000

What if a DeFi application could evaluate a wallet's creditworthiness without publishing the credit score, risk thresholds, underwriting rules, or internal decision variables on-chain?

That is the problem we are going to solve.

In this tutorial, we will build a confidential on-chain credit underwriting engine using Oasis Sapphire, Oasis ROFL, and Base.

The application will have a deliberately split architecture:

Base remains the public source of collateral and lending activity.
ROFL collects public blockchain data and performs the risk calculation inside a Trusted Execution Environment.
Sapphire stores the confidential underwriting state.
A Sapphire smart contract decides whether a borrower is eligible for a credit limit.
The borrower's exact score, policy thresholds, and internal risk parameters are never published as ordinary blockchain state.
The final authorization can be consumed by another application without exposing the complete underwriting model.

This is not intended to be a production lending protocol. It is an architectural reference showing how confidential computation can be combined with public blockchain state.

The interesting part is not hiding the blockchain.

The interesting part is deciding which parts should be public, which parts should be confidential, and which results should be verifiable without revealing the inputs that produced them.

1. The Problem

Imagine a crypto-native merchant financing protocol.

A merchant deposits collateral on Base and wants access to a short-term credit line.

A traditional DeFi lending protocol might calculate something like:

collateral value
+
borrowed value
+
liquidation history
+
wallet activity
=
credit limit

The problem is that the underwriting process itself can become public information.

Suppose the protocol uses:

minimum_score = 720
max_utilization = 65%
max_drawdown = 30%
risk_weight = 0.42

and publishes all of those values on-chain.

An adversary can now reverse-engineer the protocol.

Worse, if the protocol stores a user's individual score publicly:

wallet:
0x1234...

score:
783

creditLimit:
$42,000

then the blockchain becomes a public credit database.

That is undesirable for several reasons.

A borrower may not want every observer to know their risk classification.

A protocol may not want competitors to know its underwriting methodology.

A risk provider may not want its proprietary model exposed.

And a sophisticated attacker may deliberately optimize behavior against the published thresholds.

The goal, therefore, is not:

"Make the blockchain private."

The goal is:

Keep the source data and underwriting logic confidential while publishing only the minimum information required to authorize a financial action.

That is a much more interesting architecture.

2. What We Are Building

Our example protocol will be called PrivateCredit.

A user interacts with the system through a normal wallet.

The user has collateral and activity on Base.

The application periodically requests an underwriting decision.

The ROFL worker reads public blockchain information, calculates a risk profile inside its TEE, and submits the resulting authorization to Sapphire.

Sapphire stores the confidential result and exposes only narrowly scoped functions to consuming applications.

The simplified flow looks like this:

flowchart LR

    U[Borrower Wallet]

    B[Base]

    R[ROFL Risk Engine]

    S[Sapphire]

    C[Credit Controller]

    L[Lending / Merchant App]

    U -->|Collateral + activity| B
    B -->|Public blockchain state| R

    R -->|Confidential underwriting result| S

    S --> C

    C -->|Authorized credit limit| L

    L -->|Credit action| U

There is an important boundary here.

Base does not become confidential.

Anyone can still inspect the borrower's public transactions.

Instead, we are protecting the derived intelligence.

That distinction is fundamental.

3. Why ROFL + Sapphire?

Sapphire is an EVM-compatible confidential runtime designed for confidential smart-contract state, encrypted transactions, and confidential computation.

ROFL extends that model to off-chain workloads.

A ROFL application executes inside a Trusted Execution Environment and can interact with external systems while retaining confidentiality and producing authenticated interactions with the Oasis ecosystem.

That gives us two different computational environments.

Sapphire

Use Sapphire for:

confidential contract state
authorization
encrypted inputs
access-controlled outputs
deterministic policy enforcement

ROFL

Use ROFL for:

fetching Base data
aggregating many transactions
calling external APIs
running more expensive calculations
maintaining private model parameters
processing data that would be awkward or expensive on-chain

This separation is important.

You don't want to perform a large historical risk calculation directly inside a smart contract.

And you don't want the final authorization decision to exist only inside an off-chain server.

So we use both.

4. Threat Model

Before writing code, define what we are protecting.

Our adversaries include:

Blockchain observers

They can see:

Base transactions
contract addresses
public balances
public collateral
public borrowing activity

We cannot hide those from someone who can inspect Base.

ROFL host/operator

The application executes inside a TEE.

The architecture therefore relies on the TEE and its attestation model rather than assuming that the underlying host operator should see the application's secrets.

ROFL's security model is based around TEEs, remote attestation, Oasis consensus, and registered applications.

Application users

Users should not automatically receive:

the complete risk model
other users' scores
internal thresholds
historical underwriting decisions

Our own frontend

The frontend should not become a privileged database.

This is why sensitive state belongs in the confidential execution layer rather than simply being hidden behind a web API.

5. What We Are NOT Protecting

This is equally important.

If a user's collateral is on Base, the collateral transaction is public.

If the user interacts with a public lending protocol, those interactions are public.

Sapphire does not magically erase public-chain history.

Our confidentiality boundary begins when public information is ingested into the underwriting system.

Think about the pipeline like this:

PUBLIC
    |
    | Base transactions
    v
+--------------------+
| ROFL TEE            |
|                    |
| private features   |
| risk model         |
| policy parameters  |
+--------------------+
    |
    | authorized result
    v
+--------------------+
| Sapphire           |
|                    |
| private score      |
| credit limit       |
| expiry             |
+--------------------+
    |
    | minimal output
    v
CONSUMING APPLICATION

That is the architecture we want.

6. Repository Structure

The repository for the tutorial can be organized like this:

private-credit/
│
├── contracts/
│   ├── PrivateCredit.sol
│   ├── CreditController.sol
│   ├── PolicyRegistry.sol
│   └── interfaces/
│       └── IPrivateCredit.sol
│
├── rofl/
│   ├── src/
│   │   ├── index.ts
│   │   ├── base.ts
│   │   ├── scoring.ts
│   │   ├── features.ts
│   │   └── sapphire.ts
│   │
│   ├── Dockerfile
│   └── package.json
│
├── scripts/
│   ├── deploy.ts
│   ├── seed.ts
│   └── request-underwriting.ts
│
├── test/
│   ├── PrivateCredit.t.sol
│   ├── PolicyRegistry.t.sol
│   └── integration.t.sol
│
├── frontend/
│   └── ...
│
├── docker-compose.yml
├── hardhat.config.ts
├── foundry.toml
└── README.md

The important design decision is that the risk engine and the smart contract are separate components.

The smart contract does not trust arbitrary off-chain results.

It verifies that the caller is an authorized ROFL application.

7. The Confidential Contract

Let's start with the Sapphire contract.

The contract needs to maintain a confidential credit record.

Conceptually:

struct CreditRecord {
    uint256 limit;
    uint256 score;
    uint64 expiresAt;
    uint64 nonce;
    bool active;
}

We deliberately do not emit the score in a normal public event.

Instead, the record remains inside Sapphire's confidential state.

A simplified contract looks like this:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract PrivateCredit {
    struct CreditRecord {
        uint256 limit;
        uint256 score;
        uint64 expiresAt;
        uint64 nonce;
        bool active;
    }

    mapping(address => CreditRecord) private records;

    address public roflApp;

    modifier onlyROFL() {
        require(msg.sender == roflApp, "not authorized");
        _;
    }

    constructor(address _roflApp) {
        roflApp = _roflApp;
    }

    function updateCredit(
        address borrower,
        uint256 score,
        uint256 limit,
        uint64 expiresAt
    ) external onlyROFL {
        CreditRecord storage record = records[borrower];

        record.score = score;
        record.limit = limit;
        record.expiresAt = expiresAt;
        record.nonce++;
        record.active = true;
    }

    function revokeCredit(
        address borrower
    ) external onlyROFL {
        records[borrower].active = false;
    }

    function getCreditLimit(
        address borrower
    ) external view returns (uint256) {
        CreditRecord memory record = records[borrower];

        require(record.active, "inactive");
        require(block.timestamp <= record.expiresAt, "expired");

        return record.limit;
    }
}

This is intentionally simplified.

A production version should use Sapphire's recommended mechanisms for authenticating ROFL-originated calls rather than treating an ordinary msg.sender check as sufficient.

The important architectural idea is that the authorization boundary belongs to the confidential runtime.

ROFL's integration with Sapphire allows contracts to verify that transactions originate from registered ROFL applications.

8. Don't Store a "Global Score"

One easy mistake would be to create:

mapping(address => uint256) public score;

and call it a privacy solution.

It isn't.

The public getter would make the value readable.

Even without public, you need to carefully consider which functions expose confidential information.

Instead, the application should expose purpose-specific queries.

For example:

function canBorrow(
    address borrower,
    uint256 amount
) external view returns (bool) {
    CreditRecord memory record = records[borrower];

    if (!record.active) {
        return false;
    }

    if (block.timestamp > record.expiresAt) {
        return false;
    }

    return amount <= record.limit;
}

The consuming application learns:

true

rather than:

score = 813
limit = $47,391
riskWeight = 0.371

This is a very important privacy pattern:

Expose decisions rather than sensitive intermediate state whenever possible.

9. The Feature Pipeline

Now we move to ROFL.

The risk engine needs public information.

Suppose our underwriting model uses:

wallet_age
transaction_count
collateral_value
borrow_utilization
liquidation_count
repayment_ratio
portfolio_volatility

The ROFL application can query Base RPC endpoints and construct a feature vector.

For example:

export interface BorrowerFeatures {
    walletAgeDays: number;
    transactionCount: number;
    collateralUsd: number;
    utilization: number;
    liquidations: number;
    repaymentRatio: number;
    volatility: number;
}

The feature extraction layer should be deterministic.

That makes debugging substantially easier.

export function normalizeFeatures(
    raw: BorrowerFeatures
) {
    return {
        walletAge: Math.min(raw.walletAgeDays / 3650, 1),
        activity: Math.min(raw.transactionCount / 1000, 1),
        collateral: Math.min(raw.collateralUsd / 100000, 1),
        utilization: Math.min(raw.utilization, 1),
        liquidations: Math.min(raw.liquidations / 10, 1),
        repayment: raw.repaymentRatio,
        volatility: Math.min(raw.volatility, 1)
    };
}

Notice that none of this is performed on Base.

It happens inside the ROFL application.

10. The Risk Model

For this tutorial, use a deliberately simple model.

The point isn't to invent a sophisticated credit algorithm.

The point is to demonstrate where the algorithm lives.

export function calculateScore(
    f: ReturnType<typeof normalizeFeatures>
): number {

    let score = 500;

    score += f.walletAge * 100;
    score += f.activity * 75;
    score += f.collateral * 125;

    score += f.repayment * 150;

    score -= f.utilization * 150;
    score -= f.liquidations * 200;
    score -= f.volatility * 100;

    return Math.max(
        0,
        Math.min(1000, Math.round(score))
    );
}

A production system would likely use a much more sophisticated model.

It might include:

multiple assets
liquidation distance
realized volatility
counterparty exposure
stablecoin concentration
protocol-specific risk
historical repayment behavior
oracle confidence
time-weighted collateral
anomaly detection

But the important thing is that the model does not need to become blockchain state.

11. Keeping the Policy Confidential

Now comes the interesting part.

Suppose the protocol has these rules:

const POLICY = {
    minimumScore: 720,
    maximumUtilization: 0.68,
    maximumLimitUsd: 50000,
    liquidationPenalty: 180,
    scoreVersion: "2026-09"
};

Publishing this policy would allow users to optimize directly against it.

Instead, it remains inside the ROFL application.

The underwriting function becomes:

export function underwrite(
    features: BorrowerFeatures
) {
    const normalized = normalizeFeatures(features);

    const score = calculateScore(normalized);

    if (score < POLICY.minimumScore) {
        return {
            approved: false,
            score
        };
    }

    const utilizationPenalty =
        normalized.utilization * POLICY.maximumLimitUsd;

    const limit =
        Math.max(
            0,
            Math.floor(
                POLICY.maximumLimitUsd - utilizationPenalty
            )
        );

    return {
        approved: true,
        score,
        limit
    };
}

Again, this is illustrative rather than production-grade underwriting.

The important part is the confidentiality boundary.

The user does not need to know:

minimumScore = 720

They only need to know:

approved = true

or:

approved = false

12. Why Not Just Use a Server?

A reasonable question is:

Why not put this behind an HTTPS API?

You could.

But then the trust model becomes:

user
 |
 v
centralized server
 |
 v
database

The user must trust the server operator to:

run the correct code
protect the database
protect API credentials
not alter decisions
not leak scores
not secretly change policy

ROFL gives us a different architecture.

user
 |
 v
Oasis network
 |
 +--> registered ROFL application
          |
          v
        TEE
          |
          v
      risk engine

The ROFL model is specifically designed for arbitrary off-chain computation that can interact with external resources while retaining confidentiality and providing verifiable integration with the Oasis ecosystem.

It doesn't mean "trust disappears."

It means the trust assumptions become explicit and tied to the TEE, attestation, application registration, and Oasis infrastructure.

That distinction matters.

13. Reading Base from ROFL

The ROFL application needs an RPC connection.

import { createPublicClient, http } from "viem";
import { base } from "viem/chains";

const baseClient = createPublicClient({
    chain: base,
    transport: http(process.env.BASE_RPC_URL)
});

We can then inspect contracts.

For example:

const collateral = await baseClient.readContract({
    address: COLLATERAL_ADDRESS,
    abi: collateralAbi,
    functionName: "balanceOf",
    args: [borrower]
});

The key architectural point is that the ROFL application can communicate with external networks.

ROFL applications can use authenticated network connections and can incorporate light clients or HTTPS/TLS connections depending on the application.

That makes ROFL especially useful for applications where the input data does not originate entirely inside Oasis.

14. Building the Underwriting Worker

The worker ties everything together.

async function processBorrower(
    borrower: `0x${string}`
) {
    const raw = await collectFeatures(
        borrower
    );

    const decision = underwrite(raw);

    if (!decision.approved) {
        await revokeCredit(borrower);
        return;
    }

    await updateCredit(
        borrower,
        decision.score,
        decision.limit
    );
}

The production version should additionally include:

idempotency
nonce handling
stale-data detection
retry logic
RPC failover
transaction confirmation
policy versioning
model versioning
attestation-aware deployment
monitoring

The simple worker is enough to demonstrate the architecture.

15. Never Let a Stale Risk Decision Live Forever

One of the easiest mistakes in automated credit systems is forgetting that risk changes.

Suppose a borrower receives:

creditLimit = $40,000

at 12:00.

At 12:10, their collateral collapses.

The previous authorization should not remain valid indefinitely.

This is why our record contains:

uint64 expiresAt;

The consuming application can enforce:

require(
    block.timestamp <= record.expiresAt,
    "credit expired"
);

This creates a temporal trust boundary.

Instead of:

"This address is trusted."

we have:

"This address was authorized for this amount until this time."

That is substantially safer.

16. Model Versioning

Now consider the underwriting model itself.

Suppose version 1 is:

model = credit-v1

and version 2 changes the scoring function.

If the system does not track model versions, historical decisions become difficult to interpret.

So add:

struct CreditRecord {
    uint256 limit;
    uint256 score;
    uint64 expiresAt;
    uint64 nonce;
    bytes32 policyHash;
    bytes32 modelHash;
    bool active;
}

The score remains confidential.

But the cryptographic identifiers of the policy/model can be retained as provenance metadata.

For example:

modelHash:
0x9f83...

policyHash:
0x72a1...

This gives you an important property:

The implementation can change without making historical authorization impossible to audit.

You can distinguish:

What was decided?

from:

Which policy generated that decision?

without necessarily publishing the policy itself.

17. A Better Architecture

At this point our architecture becomes:

flowchart TB

    BASE[Base]

    RPC[Base RPC / Indexer]

    ROFL[ROFL TEE]

    FEATURES[Feature Extraction]

    MODEL[Private Risk Model]

    POLICY[Private Policy]

    SAPPHIRE[Sapphire]

    CREDIT[Private Credit Controller]

    APP[Merchant / Lending App]

    BASE --> RPC
    RPC --> ROFL

    ROFL --> FEATURES
    FEATURES --> MODEL
    MODEL --> POLICY

    POLICY -->|Decision| SAPPHIRE

    SAPPHIRE --> CREDIT
    CREDIT --> APP

There is a subtle but important property here.

The public blockchain is used as the source of evidence.

It is not used as the storage layer for private underwriting state.

18. Confidential Events

Sometimes an application needs event-driven architecture.

For example:

event CreditDecision(
    address indexed borrower,
    uint256 limit
);

That would leak the limit.

Instead, Sapphire supports encrypted event payloads while keeping event topics available for indexing and off-chain triggering.

That lets us design an event such as:

topic:
CreditDecision(address)

encrypted payload:
{
    limit,
    score,
    expiresAt,
    modelHash
}

An authorized consumer can decrypt the payload.

An arbitrary blockchain observer cannot simply read the sensitive values from the event.

This is a useful pattern for systems that still need event-driven infrastructure without turning every event into a public data leak.

19. Don't Encrypt Everything

A common privacy-design mistake is assuming:

More encryption = better architecture.

Not necessarily.

Some data should remain public.

For example:

CreditController deployed
ROFL application registered
Policy version changed
Model version changed
Credit authorization revoked

These facts can often be public.

What should remain confidential are values such as:

individual score
risk features
private policy thresholds
exact credit limit
sensitive model parameters

The correct architecture is therefore:

PUBLIC METADATA
        +
CONFIDENTIAL STATE
        +
MINIMAL DISCLOSURE

not:

ENCRYPT EVERYTHING

20. Authorization Is More Important Than Encryption

Suppose we correctly encrypt the credit record.

But then we expose:

function getScore(address borrower)
    external
    returns (uint256)

Privacy is gone.

This is why confidentiality has to be treated as an application-level authorization problem, not just a cryptography problem.

Ask:

Who can write the state?
Who can read the state?
Who can cause a decision?
Who can revoke a decision?
What can a caller infer from success/failure?
What information leaks through events?
What information leaks through timing?
What information leaks through transaction metadata?

The last question is particularly important.

A confidential contract does not automatically make the surrounding application metadata confidential.

21. The Credit Controller

Now suppose a lending application wants to check whether a borrower can draw $10,000.

It doesn't need the score.

It needs a decision.

function canDraw(
    address borrower,
    uint256 amount
) external view returns (bool) {

    CreditRecord memory record =
        records[borrower];

    if (!record.active) {
        return false;
    }

    if (block.timestamp > record.expiresAt) {
        return false;
    }

    return amount <= record.limit;
}

The result is:

true

The application can then execute the action.

This pattern is called capability-oriented disclosure.

Instead of revealing the entire internal state, you reveal only whether a particular operation is authorized.

That is a much better primitive for privacy-sensitive financial applications.

22. What Happens When the User Is Rejected?

Do not assume that returning:

score = 694

is harmless.

A user can repeatedly modify their behavior and probe the model.

If every request reveals a numerical score, they can potentially infer the decision boundary.

A better interface is:

eligible = false

possibly combined with a coarse reason category:

INSUFFICIENT_COLLATERAL

or:

TEMPORARILY_INELIGIBLE

Even these should be designed carefully.

The goal is to minimize the information returned by the underwriting oracle.

23. Replay Protection

ROFL may process the same borrower more than once.

Transactions can be retried.

RPC responses can be delayed.

Workers can restart.

Therefore, the credit contract needs a monotonic nonce.

require(
    nonce > records[borrower].nonce,
    "stale decision"
);

Now an old underwriting result cannot overwrite a newer one.

A better structure is:

struct CreditDecision {
    uint256 limit;
    uint64 expiresAt;
    uint64 nonce;
    bytes32 modelHash;
    bytes32 policyHash;
}

and require:

new nonce > stored nonce

This turns the authorization state into a monotonic state machine.

24. Failure Handling

Now imagine the Base RPC provider goes offline.

Should credit applications immediately fail?

Not necessarily.

The ROFL application should distinguish between:

NO DATA

and:

LOW RISK

These are completely different states.

A safe policy is:

RPC unavailable
    ↓
no new underwriting decision
    ↓
existing authorization remains valid
until expiry

rather than:

RPC unavailable
    ↓
grant maximum credit

This is an example of fail-closed financial automation.

25. The Full Lifecycle

The final system now behaves like this:

sequenceDiagram

    participant User
    participant Base
    participant ROFL
    participant Sapphire
    participant CreditApp

    User->>Base: Deposit collateral

    ROFL->>Base: Read collateral/activity

    Base-->>ROFL: Public state

    ROFL->>ROFL: Extract features

    ROFL->>ROFL: Run private model

    ROFL->>ROFL: Evaluate private policy

    ROFL->>Sapphire: Submit authorization

    Sapphire->>Sapphire: Verify ROFL origin

    Sapphire->>Sapphire: Store confidential decision

    CreditApp->>Sapphire: Can user draw X?

    Sapphire-->>CreditApp: true / false

    CreditApp->>User: Execute permitted action

Notice how little information crosses the boundary.

Base provides evidence.

ROFL produces a decision.

Sapphire enforces authorization.

The application receives only what it needs.

26. Testing the System

For the Solidity layer, Foundry is a good fit.

A basic test:

function testCreditExpires() public {
    vm.warp(block.timestamp + 2 hours);

    vm.expectRevert("expired");

    credit.getCreditLimit(borrower);
}

Test stale updates:

function testRejectsStaleDecision() public {
    credit.updateCredit(
        borrower,
        800,
        40000,
        uint64(block.timestamp + 1 days),
        10
    );

    vm.expectRevert("stale decision");

    credit.updateCredit(
        borrower,
        900,
        50000,
        uint64(block.timestamp + 1 days),
        9
    );
}

Test authorization:

function testOnlyROFLCanUpdate() public {
    vm.prank(attacker);

    vm.expectRevert("not authorized");

    credit.updateCredit(
        borrower,
        900,
        50000,
        uint64(block.timestamp + 1 days)
    );
}

These tests should exist before the ROFL worker is connected.

27. Testing the Risk Engine Independently

Do not make the TEE the only place where the model can be tested.

The scoring function should have deterministic unit tests.

describe("credit scoring", () => {

    it("rewards repayment history", () => {

        const score = calculateScore({
            walletAge: 0.8,
            activity: 0.7,
            collateral: 0.9,
            utilization: 0.2,
            liquidations: 0,
            repayment: 1,
            volatility: 0.1
        });

        expect(score).toBeGreaterThan(700);
    });

});

You want three separate testing layers:

model tests
     +
contract tests
     +
integration tests

Otherwise a failure becomes difficult to localize.

28. What If the ROFL Application Is Compromised?

This is where threat modeling becomes more interesting.

You should not assume:

"ROFL means the application can never be wrong."

Instead, design defense in depth.

For example:

ROFL
  ↓
credit limit
  ↓
Sapphire policy guard
  ↓
maximum protocol-wide limit
  ↓
application-level collateral check
  ↓
execution

Suppose ROFL accidentally returns:

$900,000

The Sapphire contract could enforce:

require(
    limit <= protocolMaximum,
    "limit exceeds protocol cap"
);

This gives us two independent layers:

off-chain underwriting
+
on-chain safety bounds

That is much stronger than putting every security assumption into one component.

29. Private Policy, Public Bounds

This leads to an especially useful pattern.

The detailed policy can remain confidential:

private model
private thresholds
private weights
private features

while broad safety bounds remain public:

maximum credit:
$50,000

maximum authorization:
24 hours

maximum utilization:
80%

Now users can understand the outer safety envelope without learning the exact underwriting algorithm.

This is often the right compromise between privacy and auditability.

30. What Can Be Publicly Audited?

A confidential application still needs auditability.

We can publish:

contract addresses
ROFL application identifier
model hash
policy hash
deployment version
authorization expiry
protocol-wide limits
upgrade events
revocation events

We don't need to publish:

every borrower score
private features
exact risk weights
individual underwriting inputs

This produces a useful distinction:

Public integrity

People can verify:

Which version is running?

Private computation

People cannot necessarily see:

What was the user's exact internal score?

Public safety envelope

People can still verify:

What is the maximum authority the system can grant?

That is a much more nuanced security model than simply calling the application "private."

31. Adding an Audit Manifest

I would also put a machine-readable manifest in the repository:

{
  "protocol": "private-credit",
  "model": {
    "version": "credit-v1",
    "hash": "0x..."
  },
  "policy": {
    "version": "policy-v3",
    "hash": "0x..."
  },
  "limits": {
    "maximumCreditUsd": 50000,
    "maximumAuthorizationSeconds": 86400
  },
  "execution": {
    "runtime": "Oasis Sapphire",
    "worker": "Oasis ROFL"
  }
}

The manifest doesn't expose the policy.

It identifies it.

That gives you reproducibility without sacrificing confidential parameters.

32. Why This Is More Interesting Than a Private Database

A private database can hide information.

But it does not necessarily establish a decentralized authorization path.

Our design instead creates a chain:

public evidence
      ↓
confidential computation
      ↓
confidential authorization
      ↓
bounded execution

That is the interesting primitive.

The blockchain remains useful for:

settlement
collateral
ownership
authorization
audit trails

while confidential infrastructure handles:

private feature extraction
sensitive models
proprietary policy
individual risk state

This is exactly the kind of workload for which combining Sapphire and ROFL becomes compelling.

33. Where This Architecture Could Be Used

Although we built a credit engine, the same architecture can support other systems.

Private insurance underwriting

Public collateral and claims data can feed a confidential underwriting engine.

Institutional DeFi

An institution can receive a private risk classification without publishing its entire portfolio.

Merchant financing

A merchant's transaction history can influence a credit line without exposing the complete scoring model.

Private derivatives

Risk limits can remain confidential while settlement remains on-chain.

DAO treasury controls

A confidential policy engine could evaluate risk before authorizing certain treasury actions.

Cross-chain credit

ROFL can collect evidence from multiple chains and aggregate it before producing a Sapphire authorization.

The last one is particularly interesting.

The public blockchains become data sources.

Sapphire becomes the confidential policy layer.

ROFL becomes the computation and connectivity layer.

34. Extending It to Multiple Chains

Suppose the borrower has assets on:

Ethereum
Base
Arbitrum
Optimism

ROFL can collect the relevant state from each network.

flowchart LR

    ETH[Ethereum]
    BASE[Base]
    ARB[Arbitrum]
    OP[Optimism]

    ROFL[ROFL Risk Engine]

    ETH --> ROFL
    BASE --> ROFL
    ARB --> ROFL
    OP --> ROFL

    ROFL --> S[Sapphire]

    S --> CREDIT[Private Credit Controller]

Now the user does not need to manually consolidate the information.

The risk engine sees the portfolio as a whole.

Again, this doesn't make those chains private.

It means the aggregation and derived risk state can remain confidential.

35. The Important Trust Assumption

There is no magic here.

A responsible implementation must clearly document its assumptions.

Our confidentiality depends on the security properties of the trusted execution environment and the Oasis infrastructure supporting ROFL/Sapphire.

The application also has to ensure that its deployed binaries, configuration, key handling, authorization logic, and update process are correct.

ROFL's current architecture explicitly uses TEEs, remote attestation, application registration, and Oasis consensus as parts of this trust model.

Therefore, the correct claim is not:

"Nobody can ever know this information."

A better claim is:

"The protocol is designed so that sensitive computation and state are processed inside the confidential execution environment, subject to the documented TEE and protocol trust assumptions."

That is the statement I would put in the README.

36. Production Hardening Checklist

Before calling this production-ready, I would add:

[ ] Sapphire-specific access-control primitives
[ ] ROFL application authentication
[ ] nonce/replay protection
[ ] authorization expiry
[ ] model versioning
[ ] policy versioning
[ ] policy hashes
[ ] maximum protocol-wide credit limits
[ ] stale-data detection
[ ] RPC failover
[ ] oracle freshness checks
[ ] deterministic model tests
[ ] Foundry contract tests
[ ] integration tests
[ ] deployment manifest
[ ] upgrade controls
[ ] emergency revocation
[ ] monitoring
[ ] attestation verification
[ ] key rotation procedure
[ ] incident-response procedure

The most important lesson is that confidentiality does not eliminate ordinary smart-contract security.

You still need:

access control
+
replay protection
+
bounds
+
expiry
+
monitoring
+
upgrade discipline

Privacy is another security property, not a replacement for the others.

37. The Bigger Design Pattern

The most useful takeaway from this project isn't the credit score.

It's the architecture.

We can think of a modern decentralized application as three different layers:

                 ┌───────────────────────┐
                 │      PUBLIC WORLD     │
                 │                       │
                 │ Ethereum / Base / L2s │
                 │ settlement / assets   │
                 └───────────┬───────────┘
                             │
                             ▼
                 ┌───────────────────────┐
                 │   CONFIDENT COMPUTE   │
                 │                       │
                 │       ROFL TEE        │
                 │ private algorithms    │
                 │ external data         │
                 │ sensitive processing  │
                 └───────────┬───────────┘
                             │
                             ▼
                 ┌───────────────────────┐
                 │ CONFIDENT ON-CHAIN    │
                 │                       │
                 │       Sapphire       │
                 │ private state        │
                 │ authorization         │
                 │ policy enforcement    │
                 └───────────────────────┘

The mistake is trying to force all three jobs into the same environment.

Public blockchains are excellent at settlement and transparent state.

Confidential runtimes are useful when state should not be globally observable.

TEE-backed off-chain computation is useful when workloads are too expensive, complex, or externally connected to execute directly on-chain.

ROFL and Sapphire allow those pieces to be composed.

38. Final Thoughts

The most interesting privacy applications aren't necessarily applications where everything is hidden.

They are applications where the confidentiality boundary is deliberate.

For our credit engine:

Collateral:
PUBLIC

Transactions:
PUBLIC

Settlement:
PUBLIC

Risk features:
CONFIDENTIAL

Underwriting model:
CONFIDENTIAL

Policy parameters:
CONFIDENTIAL

Credit decision:
CONFIDENTIAL

Safety limits:
PUBLIC

Model identity:
PUBLIC

Authorization status:
MINIMALLY DISCLOSED

That is a much more useful way to think about confidential blockchain applications.

Instead of asking:

"Can we put this entire application on a private chain?"

ask:

"Which information actually needs confidentiality?"

Then ask:

"Where should that information be processed?"

And finally:

"What is the smallest result that needs to cross the confidentiality boundary?"

In this architecture, Base provides the public evidence layer.

ROFL performs the expensive and sensitive underwriting computation.

Sapphire provides confidential state and policy enforcement.

The resulting system doesn't try to make public blockchains disappear.

It makes them more useful by adding a confidential computation layer where transparency would otherwise become a liability.

Repository Blueprint

The complete project can follow this structure:

private-credit/
├── contracts/
│   ├── PrivateCredit.sol
│   ├── CreditController.sol
│   ├── PolicyRegistry.sol
│   └── interfaces/
│       └── IPrivateCredit.sol
│
├── rofl/
│   ├── src/
│   │   ├── index.ts
│   │   ├── base.ts
│   │   ├── features.ts
│   │   ├── scoring.ts
│   │   └── sapphire.ts
│   ├── Dockerfile
│   └── package.json
│
├── scripts/
│   ├── deploy.ts
│   ├── seed.ts
│   └── request-underwriting.ts
│
├── test/
│   ├── PrivateCredit.t.sol
│   ├── CreditController.t.sol
│   └── integration.t.sol
│
├── frontend/
│
├── manifest/
│   └── protocol.json
│
├── foundry.toml
├── hardhat.config.ts
└── README.md

The official Oasis documentation provides the current Sapphire development documentation, ROFL workflow, and examples for integrating ROFL applications with confidential Sapphire contracts.

For developers wanting to experiment with the pattern, the official ROFL documentation also includes a trustless price-oracle example that demonstrates a ROFL application communicating with a confidential Sapphire contract.

Resources

Oasis Sapphire
https://docs.oasis.io/build/sapphire/

Develop on Sapphire
https://docs.oasis.io/build/sapphire/develop/

Oasis ROFL
https://docs.oasis.io/build/rofl/

ROFL Workflow and Architecture
https://docs.oasis.io/build/rofl/workflow/

Encrypted Events
https://docs.oasis.io/build/sapphire/develop/encrypted-events/

Oasis Build Documentation
https://docs.oasis.io/build/

The official documentation is the best place to verify the current APIs and deployment workflow because the Oasis tooling continues to evolve.

The core idea is simple:

Don't make the blockchain private.

Make the parts that shouldn't be public confidential and make the boundary between public evidence and private computation explicit.

That is where confidential Web3 infrastructure becomes much more interesting than simply hiding a smart contract's storage.

Building a Confidential Onchain Payroll & Contractor Escrow with Oasis Sapphire + ROFL

rayQu — Fri, 21 Aug 2026 07:01:37 +0000

Traditional blockchain payroll has an uncomfortable property.

The payment itself may be decentralized and programmable, but the information surrounding that payment is usually public.

If a company pays a contractor 4 ETH every month, an observer can potentially see the payment amount, timing, destination address, and relationship between recurring transactions. If the company has multiple employees or contractors, these transactions can reveal a surprisingly detailed picture of its internal operations.

That creates a problem for organizations that want the advantages of programmable settlement without turning their payroll system into a public business-intelligence feed.

Consider a simple payroll transaction:

Company Treasury
      |
      | 4 ETH
      v
0x91...A42

On a public EVM chain, there is no inherent distinction between:

"The company paid an employee."

and:

"The company transferred 4 ETH to this address."

The blockchain can verify the second statement.

It does not understand the first.

This article explores a different architecture using Oasis Sapphire and Oasis ROFL:

                    PUBLIC
              ┌─────────────────┐
              │ Company Treasury│
              │ Funding         │
              └────────┬────────┘
                       │
                       │ funds
                       ▼
              ┌─────────────────┐
              │ Sapphire        │
              │ Escrow          │
              │                 │
              │ PRIVATE         │
              │ salaries        │
              │ schedules       │
              │ recipients      │
              │ policies        │
              └────────┬────────┘
                       ▲
                       │ attested
                       │ payroll update
              ┌────────┴────────┐
              │ ROFL            │
              │                 │
              │ payroll adapter │
              │ validation      │
              │ computation     │
              └────────┬────────┘
                       ▲
                       │
              ┌────────┴────────┐
              │ Payroll system  │
              │ / ERP / HRIS    │
              └─────────────────┘

The key idea is simple:

Put settlement rules onchain without putting the entire payroll database onchain.

Oasis Sapphire is an EVM-compatible confidential runtime that supports confidential contract state and encrypted transactions.

ROFL extends that model to applications running in trusted execution environments, allowing offchain workloads to interact with Sapphire while maintaining an attested application identity.

This combination gives us a useful architecture for a class of applications that doesn't get much attention in Web3:

private business processes with programmable settlement.

What We're Building

Our example system is a confidential contractor payroll protocol.

A company wants to hire 50 independent contractors.

Each contractor has:

a wallet
a compensation rate
a payment schedule
an engagement start/end date
an optional performance bonus
a private internal identifier

The company wants the actual settlement to be programmable.

But it does not want the public blockchain to reveal:

Alice → $14,000/month
Bob   → $8,500/month
Carol → $31,000/month

Instead, the company funds an onchain escrow.

The confidential contract maintains the payroll state.

A ROFL application receives an authorized payroll update from the organization's existing backend and submits the corresponding state transition to Sapphire.

The final architecture looks like this:

This is not intended to replace an enterprise HR system.

The blockchain is being used for something much narrower:

confidential, programmable settlement.

Why Not Just Use a Database?

A reasonable objection is:

Why put payroll information on a blockchain at all?

For many organizations, a database is completely sufficient.

The interesting case is when multiple parties need guarantees around settlement.

Imagine a company using an external payroll processor.

The company might want the processor to calculate:

contractor compensation
+
approved expenses
+
performance bonuses
-
withholding
=
final settlement

But the company doesn't necessarily want the processor to have unrestricted authority over the funds.

Likewise, a contractor may want stronger guarantees that an approved payment cannot simply disappear because an internal database was modified.

This produces a separation of responsibilities:

Payroll system
    |
    | calculates
    v
ROFL
    |
    | attested update
    v
Sapphire
    |
    | enforces settlement policy
    v
Funds

The payroll backend determines what should happen.

The confidential smart contract determines what is allowed to happen.

That distinction is one of the most important architectural decisions in this design.

Why Sapphire?

Sapphire is particularly useful here because the application needs confidentiality at the smart-contract state level.

A normal EVM contract would expose storage such as:

mapping(address => uint256) salary;

Even if the Solidity source doesn't provide a public getter, public blockchain state is generally observable through node/RPC interfaces and historical state.

Sapphire provides confidential contract state and encrypted communication between users and contracts.

That means we can maintain sensitive application state inside the confidential execution environment rather than treating the public blockchain as a payroll database.

The contract can therefore maintain records such as:

contractor wallet
salary
payment interval
start date
end date
bonus policy
last settlement
employment status

without automatically publishing those values as ordinary public application state.

Repository Structure

For the implementation, I'd structure the repository like this:

confidential-payroll/
│
├── contracts/
│   ├── ConfidentialPayroll.sol
│   ├── PayrollEscrow.sol
│   ├── PayrollTypes.sol
│   └── interfaces/
│       └── IPayrollAdapter.sol
│
├── rofl/
│   ├── src/
│   │   ├── main.ts
│   │   ├── payroll.ts
│   │   ├── attestation.ts
│   │   └── validation.ts
│   ├── Dockerfile
│   └── rofl.yaml
│
├── scripts/
│   ├── deploy.ts
│   ├── fund.ts
│   └── register-rofl.ts
│
├── test/
│   ├── Payroll.t.sol
│   ├── Authorization.t.sol
│   ├── Settlement.t.sol
│   └── FuzzPayroll.t.sol
│
├── frontend/
│   └── ...
│
├── docs/
│   ├── architecture.md
│   └── threat-model.md
│
├── foundry.toml
├── package.json
└── README.md

The important point is that the ROFL application is not treated as a second smart contract.

It is an external confidential component with a specific authorization relationship to the Sapphire contract.

That gives us a much cleaner trust boundary.

The Core Data Model

Let's start with the internal payroll record.

struct Contractor {
    address wallet;
    uint64 startTime;
    uint64 endTime;
    uint128 monthlyRate;
    uint128 accrued;
    uint128 bonus;
    bool active;
}

A production implementation would likely use a more sophisticated accounting model, but this is enough to demonstrate the architecture.

The mapping is deliberately private:

mapping(bytes32 => Contractor) private contractors;

Instead of using the employee's wallet as the primary identifier, we can derive a confidential internal identifier.

For example:

contractorId = keccak256(
    companyId ||
    internalEmployeeId ||
    deploymentSalt
)

This isn't meant to be a magical privacy mechanism.

Hashing does not make low-entropy information confidential.

If the possible employee IDs are predictable, someone can brute-force them.

The purpose of the identifier is instead to separate the organization's internal record structure from its public wallet addresses.

The actual confidentiality comes from Sapphire's confidential execution model.

Payroll Accrual

The system needs to calculate how much a contractor has earned since their last settlement.

A simplified formula is:

elapsed = currentTime - lastSettlement

earned =
    monthlyRate
    × elapsed
    ÷ billingPeriod

For example:

monthlyRate = $10,000
billingPeriod = 30 days
elapsed = 15 days

earned = $5,000

In a real implementation, you should avoid floating point arithmetic entirely.

Use fixed-point integer arithmetic and explicitly define:

rounding direction
minimum settlement
maximum accrual
timestamp boundaries
partial periods
leap-month handling
token decimal conversion

Financial contracts should never leave rounding behavior implicit.

The Confidential Payroll Contract

The high-level contract can look like this:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;


contract ConfidentialPayroll {
    struct Contractor {
        address wallet;
        uint64 startTime;
        uint64 endTime;
        uint128 ratePerPeriod;
        uint128 accrued;
        uint64 lastSettlement;
        bool active;
    }


    address public immutable treasury;
    address public immutable roflApp;


    mapping(bytes32 => Contractor) private contractors;


    error Unauthorized();
    error Inactive();
    error InvalidSchedule();
    error NothingDue();


    constructor(
        address _treasury,
        address _roflApp
    ) {
        treasury = _treasury;
        roflApp = _roflApp;
    }


    modifier onlyROFL() {
        if (msg.sender != roflApp) {
            revert Unauthorized();
        }
        _;
    }


    function createContractor(
        bytes32 id,
        address wallet,
        uint64 startTime,
        uint64 endTime,
        uint128 rate
    ) external onlyROFL {


        if (endTime <= startTime) {
            revert InvalidSchedule();
        }


        contractors[id] = Contractor({
            wallet: wallet,
            startTime: startTime,
            endTime: endTime,
            ratePerPeriod: rate,
            accrued: 0,
            lastSettlement: startTime,
            active: true
        });
    }
}

There is already an important property here:

The normal wallet cannot create arbitrary payroll records.

Only the authorized payroll application can modify the internal state.

In production, the onlyROFL mechanism should use Oasis's supported ROFL authentication/verification pattern rather than treating a normal externally owned account as a sufficient trust boundary. ROFL applications can authenticate to Sapphire contracts, and Sapphire can verify ROFL transaction origin.

Settlement Should Be Separate From Accrual

One mistake would be to combine everything into a single function:

calculate salary
+
modify employee
+
authorize payment
+
transfer funds

That creates a large security surface.

Instead, separate the lifecycle:

REGISTER
   ↓
ACTIVE
   ↓
ACCRUING
   ↓
SETTLEMENT READY
   ↓
PAID
   ↓
NEXT PERIOD

This gives us much clearer invariants.

For example:

A contractor cannot be paid more than their accrued amount.

And:

An inactive contractor cannot generate additional compensation.

And:

A settlement cannot be executed twice for the same accounting period.

Those invariants are much easier to fuzz-test.

The Settlement Function

Conceptually:

function settle(bytes32 id)
    external
    onlyROFL
{
    Contractor storage c = contractors[id];


    if (!c.active) {
        revert Inactive();
    }


    uint256 due = _calculateDue(c);


    if (due == 0) {
        revert NothingDue();
    }


    c.lastSettlement = uint64(block.timestamp);


    _transfer(c.wallet, due);
}

The important security property isn't the transfer itself.

It is the accounting relationship around it.

We want:

new accrued balance
=
old accrued balance
+
newly earned
-
settled amount

to remain true after every state transition.

That becomes the foundation of the test suite.

Don't Make the Payroll Adapter the Custodian

This is probably the most important design decision in the entire system.

A tempting architecture is:

Payroll backend
       ↓
ROFL
       ↓
Treasury private key
       ↓
Contractor

That gives ROFL too much power.

If the ROFL application is compromised, the attacker potentially gets direct control over funds.

Instead:

Payroll backend
       ↓
ROFL
       ↓
Sapphire policy
       ↓
Escrow
       ↓
Contractor

ROFL should be able to submit claims, not arbitrarily withdraw money.

The confidential contract should enforce:

claim <= accrued
claim <= configured limit
claim belongs to contractor
contractor is active
period hasn't already been settled

This is classic least-privilege design.

The confidential execution environment is not an excuse to give one component unlimited authority.

Funding the Escrow

The company can fund the payroll contract separately.

For example:

Treasury
   |
   | 100,000 USDC
   v
Payroll Escrow

The public blockchain can therefore show:

Payroll escrow balance = 100,000 USDC

while the internal distribution remains confidential.

That is a useful compromise.

The company may want the total reserve to be publicly auditable while keeping the individual salary distribution private.

This is an important distinction:

Confidentiality does not require making everything opaque.

A well-designed confidential application should expose exactly the information that external parties need to verify its public commitments.

Public vs Private State

I'd explicitly document this in the repository.

PUBLIC
────────────────────────────
Contract address
Contract version
Escrow funding
ROFL application identity
Protocol configuration
Settlement existence


PRIVATE
────────────────────────────
Contractor identity
Compensation rate
Accrued amount
Payment schedule
Internal employee ID
Bonus information
Employment metadata


SELECTIVELY DISCLOSED
────────────────────────────
Payment receipt
Settlement proof
Accounting period
Aggregated payroll statistics

This is much more useful than simply saying:

"The contract is private."

Privacy should be defined field-by-field.

Confidential Events

Events require particular care.

On ordinary EVM networks, event data is publicly visible.

Sapphire supports encrypted event payloads while retaining public event topics for indexing and offchain triggers.

That gives us an interesting pattern.

Suppose we want a contractor to receive a payment notification containing:

paymentId
period
amount
timestamp

We don't necessarily want all of those fields to become public plaintext.

Instead, the event can expose a public topic while keeping the sensitive payload encrypted for an authorized consumer.

Conceptually:

Public:

PayrollSettlement(contractorIdHash, paymentId)

Encrypted:

amount
period
internal payroll metadata

This gives infrastructure systems something to index without turning the event stream into a public payroll ledger.

Where ROFL Becomes Useful

The real world rarely stores payroll data directly onchain.

An organization might already have:

Workday
SAP
QuickBooks
Stripe
custom HR system
internal PostgreSQL

We don't want the smart contract trying to query these systems directly.

Instead, ROFL can operate as the confidential adapter.

ROFL applications run inside TEEs and can interact with external systems through authenticated connections while maintaining an attested application identity.

This is exactly the kind of workload that benefits from separating:

external data ingestion

from:

onchain settlement policy.

Example ROFL Workflow

Suppose the company's payroll system produces:

{
  "employee": "employee-9182",
  "period": "2026-08",
  "approvedAmount": "8500000000",
  "currency": "USDC"
}

ROFL shouldn't blindly forward this.

It should validate:

Is this payroll period valid?
Is the employee registered?
Is the amount within policy?
Is this period already settled?
Is the payroll file authentic?
Is the source system authorized?
Is the deployment version expected?

Only after those checks should the ROFL application construct the Sapphire transaction.

Pseudo-code:

async function processPayroll(record: PayrollRecord) {
  validateSchema(record);


  const employee = await payroll.lookup(record.employee);


  if (!employee.active) {
    throw new Error("Inactive employee");
  }


  if (!verifyPayrollSource(record)) {
    throw new Error("Invalid payroll source");
  }


  const amount = calculateSettlement(record);


  return sapphire.submitSettlement({
    contractorId: employee.privateId,
    amount,
    period: record.period
  });
}

The important thing is that ROFL validates; Sapphire enforces.

Those are different responsibilities.

Preventing Replay Attacks

Payroll systems are particularly vulnerable to replay.

Imagine a valid payroll message:

Alice
August
$8,500

An attacker somehow submits the same message twice.

Without replay protection:

August payment
+
August payment
=
$17,000

The contract needs a settlement nonce or period identifier.

For example:

mapping(bytes32 => mapping(uint64 => bool)) private settled;

Then:

if (settled[id][period]) {
    revert AlreadySettled();
}

settled[id][period] = true;

The invariant becomes:

∀ contractor, period:
    settlement_count <= 1

This should be tested extensively.

What Happens if ROFL Goes Offline?

This is another reason not to make ROFL the sole source of truth.

Suppose the ROFL application crashes for six hours.

The escrow shouldn't become corrupted.

The correct behavior should simply be:

No payroll update
        ↓
No state corruption
        ↓
Existing escrow remains intact
        ↓
ROFL recovers
        ↓
Pending payroll period processed

This is where idempotency becomes important.

The payroll processor should be able to safely retry the same period without causing a double payment.

A good implementation therefore treats payroll updates as state transitions rather than one-shot commands.

Handling Corrections

Real payroll isn't perfectly linear.

Someone might receive:

base salary
+
bonus
-
expense correction

after the original payroll calculation.

Instead of modifying historical payments, create a new adjustment:

August salary
        +
August bonus
        -
expense correction
        =
August final adjustment

This produces an append-only accounting model.

The confidential state can remain private while the protocol still preserves an internal accounting history.

That makes audits much easier.

Testing the Important Invariants

A production implementation should not stop at unit tests.

I'd use Foundry fuzzing to test the accounting model.

For example:

function invariant_neverPayMoreThanAccrued()
    public
{
    assertLe(
        totalSettled,
        totalAccrued
    );
}

Another invariant:

function invariant_noPeriodCanSettleTwice()
    public
{
    for (...) {
        assertLe(
            settlementCount[period],
            1
        );
    }
}

And:

function invariant_inactiveContractorCannotAccrue()
    public
{
    if (!contractor.active) {
        assertEq(
            accruedSinceDeactivation,
            0
        );
    }
}

The exact implementation will depend on the accounting model, but the philosophy is important:

test properties, not examples.

A test that says:

Alice receives $8,500

is useful.

A property that says:

no contractor can receive more than the amount authorized by the accounting state

is much more powerful.

Threat Model

Let's explicitly define the attackers.

Attacker 1: Malicious contractor

They control their wallet and attempt to claim more than they earned.

Defense:

contract-enforced accrual
period tracking
maximum claim
replay protection

Attacker 2: Compromised payroll backend

The backend generates a fraudulent payroll record.

Defense:

ROFL validation
authorized source
contract-level policy limits
maximum settlement bounds

Attacker 3: Compromised ROFL application

The ROFL process attempts to submit arbitrary payments.

Defense:

restricted contract interface
bounded permissions
per-contractor limits
period uniqueness
escrow accounting

Attacker 4: Replay attacker

They resubmit a valid payroll message.

Defense:

period nonce
settlement identifier
idempotent state transitions

Attacker 5: Curious blockchain observer

They attempt to reconstruct salary information from public chain data.

Defense:

confidential Sapphire state
encrypted transaction inputs
encrypted event payloads where appropriate
minimal public disclosure

Attacker 6: Compromised frontend

The frontend tries to trick a user into authorizing a malicious action.

Defense:

strict contract authorization
typed transaction validation
domain separation
least-privilege interfaces

The important observation is that confidentiality only solves one part of the threat model.

It does not make authorization, accounting, or business logic automatically secure.

What About the Company Treasury?

There is another architectural decision.

Should the treasury itself live on Sapphire?

There are several possibilities.

Fully confidential

Treasury
   ↓
Sapphire
   ↓
Payroll

This provides maximum privacy but reduces public transparency.

Public treasury + confidential payroll

Public Treasury
       ↓
Sapphire Escrow
       ↓
Private Payroll

This is probably the more interesting model for many organizations.

The public treasury can prove that the company has funded the payroll system.

The private contract controls individual distributions.

Hybrid

Public reserve
      +
Private employee allocations
      +
Public aggregate settlement

This gives organizations control over exactly which information becomes publicly auditable.

That is the model I'd recommend exploring first.

Why This Is Different From a Traditional Payroll Smart Contract

A normal payroll contract might answer:

"Did address X receive Y tokens?"

This architecture asks a more useful question:

"Can the organization prove that its payroll policy was enforced without exposing the organization's entire payroll database?"

That distinction is where confidential blockchain infrastructure becomes genuinely useful.

The blockchain becomes a policy enforcement layer, not a database.

A Possible Production Deployment

A production deployment might look like:

This architecture gives every component a narrow responsibility.
The enterprise systems know the business.
ROFL handles confidential external computation and integration.
Sapphire enforces private state transitions.
The escrow controls settlement.
The public treasury provides the funding layer.

Operational Monitoring

Confidentiality also changes how monitoring should work.

A traditional blockchain monitoring system might inspect:

salary
recipient
amount
timestamp

and reconstruct the entire payroll history.

That isn't desirable here.

Instead, monitoring should focus on public commitments and system health.

For example:

Escrow funded
ROFL application active
Payroll epoch completed
Settlement batch committed
Contract version changed
Emergency mode activated

Sensitive details remain inside the confidential system.

This creates a useful principle:

Monitor the protocol's guarantees, not necessarily the protocol's private inputs.

Sapphire's encrypted-event support is useful here because applications can retain public event topics for indexing while keeping event payloads confidential.

What Sapphire Does Not Hide

This distinction is important enough to state explicitly.

A confidential contract does not mean that every piece of information surrounding a transaction automatically disappears from the public world.

Depending on the application architecture, observers may still learn things such as:

a transaction occurred
a contract was called
a public balance changed
a public funding transaction happened
a settlement-related event exists

The goal is therefore not:

"Make the blockchain invisible."

It is:

"Keep specifically identified sensitive state and execution inputs confidential while exposing the minimum information necessary for interoperability and verification."

That's a much more realistic security model.

Why ROFL Instead of Putting Everything in Sapphire?

Because not every task belongs inside a smart contract.

A smart contract is excellent at:

state transitions
authorization
accounting
settlement
deterministic rules

It is not the ideal place to:

parse enterprise payroll files
call an external HR API
process complex business data
maintain authenticated external connections
run arbitrary application logic

ROFL is designed specifically for offchain computation with private data and verifiable results, and it integrates with Sapphire for authenticated smart-contract interactions.

The combination is therefore more powerful than either component by itself.

The Repository's Security Checklist

Before considering the implementation production-ready, I'd want the repository to contain a checklist like:

[ ] ROFL caller authentication
[ ] Payroll source authentication
[ ] Replay protection
[ ] Period uniqueness
[ ] Maximum payment limits
[ ] Maximum contractor exposure
[ ] Escrow solvency checks
[ ] Integer overflow protection
[ ] Explicit rounding rules
[ ] Emergency pause
[ ] Emergency expiry
[ ] Recovery mechanism
[ ] Contract upgrade policy
[ ] ROFL deployment policy
[ ] Key rotation procedure
[ ] Confidential event policy
[ ] Fuzz tests
[ ] Invariant tests
[ ] Failure recovery tests
[ ] ROFL outage tests
[ ] Duplicate payroll tests
[ ] Malicious payroll input tests

This is the part I'd consider more important than adding another frontend feature.

A confidential financial application has a very large attack surface if the trust boundaries aren't explicitly documented.

Where This Could Go Beyond Payroll

Once the architecture exists, payroll is only one application.

The same primitive could support:

Private contractor marketplaces
        ↓
Confidential compensation


B2B service agreements
        ↓
Confidential recurring settlement


Private grants
        ↓
Milestone-based payouts


Research collaborations
        ↓
Confidential contributor compensation


DAO contributor programs
        ↓
Private compensation schedules


Enterprise procurement
        ↓
Confidential invoice settlement

The common primitive is:

private business state
        +
programmable settlement
        +
restricted authorization
        +
verifiable execution

That combination is difficult to achieve cleanly with a conventional public EVM.

The More Interesting Question

The interesting question isn't really:

"Can blockchain do payroll?"

It obviously can.

The harder question is:

Can blockchain enforce a business process without forcing the business to publish its internal state?

That's where Oasis's architecture becomes interesting.

Sapphire provides confidential EVM execution, while ROFL provides a framework for confidential offchain workloads that can interact with the onchain environment with an attested identity.

Together, they allow developers to draw a much sharper boundary between:

What must be public

and:

What must merely be verifiable

Those aren't the same thing.

A company may need to prove that its payroll escrow is funded.
It doesn't necessarily need to publish every employee's salary.
A contractor may need to prove that a payment was authorized.
They don't necessarily need to expose the entire company's payroll ledger.
An auditor may need evidence that a policy was followed.
They don't necessarily need unrestricted access to every private record.

That is the fundamental design space.

Final Architecture

The complete system can be summarized as:

PUBLIC
                           │
                    ┌──────▼──────┐
                    │   Treasury  │
                    └──────┬──────┘
                           │
                       Funding
                           │
                           ▼
                 ┌───────────────────┐
                 │ Sapphire Escrow   │
                 │                   │
                 │ Confidential      │
                 │ settlement state  │
                 └─────────▲─────────┘
                           │
                    authenticated
                       ROFL call
                           │
                 ┌─────────┴─────────┐
                 │       ROFL        │
                 │                   │
                 │ Validation        │
                 │ Aggregation       │
                 │ External APIs     │
                 │ Attested compute  │
                 └─────────▲─────────┘
                           │
                           │
                 ┌─────────┴─────────┐
                 │ HR / Payroll / ERP│
                 └───────────────────┘


                           │
                           ▼


                 ┌───────────────────┐
                 │ Contractor Wallet │
                 └───────────────────┘

The architecture deliberately avoids making one component responsible for everything.
The payroll system knows the business rules.
ROFL handles the confidential external computation.
Sapphire enforces the settlement policy.
The escrow controls the money.
And the public chain exposes only the information that actually needs to be public.

That's the more interesting promise of confidential blockchain infrastructure: not simply hiding transactions, but making privacy a property of the application's architecture.

For developers coming from Ethereum, the nice part is that Sapphire remains EVM-compatible, so familiar Solidity, Foundry, Hardhat, and other EVM tooling can be used while adding confidentiality-specific primitives.

The result isn't a private database with a token attached.

It's a programmable business process where confidential state, external computation, and onchain settlement can coexist without requiring the entire workflow to become public.

Resources

Oasis Sapphire

Oasis ROFL

Encrypted Events

Sapphire Encrypted Events

Oasis Build Documentation

Build on Oasis

Building a Confidential On-Chain Treasury Policy Engine with Oasis Sapphire

rayQu — Thu, 13 Aug 2026 07:25:13 +0000

Private rules. Public commitments. Bounded emergency powers.

Treasury contracts usually have an uncomfortable design problem.

The treasury needs enough transparency that anyone can verify what happened, but it doesn't necessarily want to publish every piece of information that determines why a particular action was allowed.

Imagine a protocol treasury that manages $10 million across several assets.

The governance community might want the following guarantees:

no transaction can exceed a daily spending limit
a single operator cannot drain the treasury
emergency powers automatically expire
large transfers require additional approval
certain destinations are prohibited
policy changes are delayed
every executed action leaves an auditable commitment

But there is another requirement that is rarely discussed:

the policy itself can be sensitive.

Publishing every internal threshold, destination rule, operational limit, or pending treasury decision can reveal how the treasury is managed before the organization is ready to disclose it.

A conventional Ethereum contract doesn't give you much room here.

Its storage is public.
Its calldata is public.
Its events are public.
Its execution path is observable.

That is where Oasis Sapphire becomes interesting.

Sapphire is an EVM-compatible confidential execution environment. Contract state is encrypted, and Sapphire provides end-to-end encryption for transactions and calls through its client tooling.

In this tutorial, we'll build something more interesting than a private vault:

a confidential treasury policy engine that evaluates whether a proposed treasury action is allowed, while publishing a cryptographic commitment that allows the system to remain auditable without revealing the policy itself.

The goal isn't to make the treasury invisible.

The goal is to separate:

what happened

from

the private policy that caused it to be allowed.

What We're Building

Our example system has three components:

The Policy Engine runs on Oasis Sapphire.

It stores sensitive treasury rules such as:

maximum transfer
daily budget
per-destination limits
allowed assets
emergency expiry
operator permissions
risk tiers

A user submits a proposed action.

The policy engine evaluates it.

If the action is allowed, the engine produces an execution authorization and a cryptographic commitment.

The actual treasury operation can then happen on a public EVM chain.

That gives us a hybrid architecture:

                CONFIDENTIAL
             Oasis Sapphire
          ┌────────────────────┐
          │                    │
          │  Private Policy    │
          │        ↓           │
          │  Policy Evaluation │
          │        ↓           │
          │  Authorization     │
          │        ↓           │
          │  Commitment        │
          │                    │
          └─────────┬──────────┘
                    │
                    │ authorization
                    ▼
                PUBLIC
             Ethereum / Base
          ┌────────────────────┐
          │                    │
          │ Treasury execution │
          │                    │
          │ Events             │
          │                    │
          │ Asset movement     │
          │                    │
          └────────────────────┘

This is useful because not everything needs confidentiality.

The amount actually transferred can remain public.
The destination can remain public.
The treasury balance can remain public.

What we're protecting is the policy machinery around those actions.

Why Not Just Put Everything in a Multisig?

A natural question is:

Why not use Safe + a timelock + a multisig?

For many treasuries, that's exactly the right answer.

This tutorial isn't claiming otherwise.

The problem appears when the treasury's operational policy becomes more complicated than:

3 of 5 signers approve transaction

Consider a treasury with rules like:

USDC:
daily limit = X

ETH:
daily limit = Y

New recipient:
requires additional approval

Known recipient:
lower approval requirement

Emergency mode:
withdrawals capped
expires after N blocks

Strategy contract:
allowed to rebalance
but not withdraw to arbitrary EOAs

Treasury operator:
can execute
but cannot modify policy

A traditional public contract can encode all of this.

But now everyone can inspect it.

That isn't automatically bad.

However, there are situations where revealing the exact operational policy is undesirable.

For example:

market-making organizations
grant programs
institutional treasury operations
DAO operational budgets
private investment vehicles
infrastructure operators
trading organizations

The interesting design question becomes:

Can the control logic be confidential while the result of the control logic remains auditable?

That's what we'll explore.

Architecture

Our final architecture looks like this:

There are four important boundaries here.

Boundary 1: Policy

The policy is private.

Boundary 2: Authorization

An operator isn't automatically trusted simply because they can call the policy engine.

Boundary 3: Execution

The public treasury only accepts valid authorization artifacts.

Boundary 4: Auditability

Every accepted decision produces enough public information to reconstruct the fact that authorization occurred without necessarily exposing the private policy.

Repository

We'll use Foundry for the Solidity side and TypeScript for integration tests.

The repository structure will look like this:

confidential-treasury-policy/
├── src/
│ ├── ConfidentialPolicy.sol
│ ├── PolicyTypes.sol
│ ├── CommitmentRegistry.sol
│ ├── ExecutionGateway.sol
│ ├── Treasury.sol
│ └── interfaces/
│ ├── IPolicyEngine.sol
│ └── ITreasury.sol
│
├── script/
│ ├── Deploy.s.sol
│ ├── ConfigurePolicy.s.sol
│ └── RegisterGateway.s.sol
│
├── test/
│ ├── PolicyEngine.t.sol
│ ├── Emergency.t.sol
│ ├── Replay.t.sol
│ ├── Authorization.t.sol
│ └── Invariants.t.sol
│
├── integration/
│ ├── sapphire.ts
│ ├── treasury.ts
│ └── execute.ts
│
├── lib/
│ └── forge-std/
│
├── foundry.toml
├── package.json
└── README.md

Start with:

forge init confidential-treasury-policy
cd confidential-treasury-policy

For Sapphire development, Oasis provides Foundry and Hardhat integration because Sapphire is EVM-compatible.

1. Defining the Policy Model

Before writing Solidity, define what a policy actually controls.

We'll use:

struct Policy {
    uint256 maxPerTransaction;
    uint256 dailyLimit;
    uint256 emergencyLimit;
    uint64 emergencyUntil;

    mapping(address => bool) allowedAsset;
    mapping(address => bool) allowedRecipient;

    bool emergencyMode;
}

But Solidity mappings inside structs make copying and hashing awkward.

So we'll store the components separately.

Our first version needs:

maximum transaction amount
daily budget
emergency budget
emergency expiry
allowed assets
allowed recipients
policy version

The important thing is that policy versioning is explicit.

We'll never silently mutate a policy.

Instead:

Policy v1
    ↓
Policy v2
    ↓
Policy v3

Every authorization records the version that produced it.

That becomes extremely useful during audits.

2. PolicyTypes.sol

Create:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

library PolicyTypes {
    enum Decision {
        DENIED,
        APPROVED
    }

    enum RiskLevel {
        NORMAL,
        ELEVATED,
        EMERGENCY
    }

    struct Request {
        address asset;
        address recipient;
        uint256 amount;
        uint256 nonce;
        bytes32 requestId;
    }

    struct DecisionRecord {
        Decision decision;
        RiskLevel risk;
        uint256 policyVersion;
        uint256 expiresAt;
        bytes32 commitment;
    }
}

The Request represents what someone wants to do.

The DecisionRecord represents what the policy engine decided.

Notice something important:

The policy itself isn't included in DecisionRecord.

That's intentional.

We don't want every authorization to reveal the complete policy.

3. The Confidential Policy Contract

Now create:

src/ConfidentialPolicy.sol

The basic contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "./PolicyTypes.sol";

contract ConfidentialPolicy {
    using PolicyTypes for *;

    address public governance;
    address public executionGateway;

    uint256 public policyVersion;

    uint256 private maxPerTransaction;
    uint256 private dailyLimit;
    uint256 private emergencyLimit;

    uint64 private emergencyUntil;
    bool private emergencyMode;

    mapping(address => bool) private allowedAssets;
    mapping(address => bool) private allowedRecipients;

    mapping(bytes32 => bool) private consumedRequests;

    constructor(address _governance) {
        governance = _governance;
        policyVersion = 1;
    }
}

The sensitive fields are private.
On a normal EVM, private does not mean confidential.
Anyone can inspect Ethereum storage.

On Sapphire, however, contract state is encrypted and accessible only through the contract's confidential execution environment.

This distinction is fundamental.

Don't write:

"private makes Solidity storage secret."

It doesn't.

The confidentiality comes from Sapphire's execution and encrypted state model.

4. Access Control

We need three roles:

governance
operator
execution gateway

Governance changes policy.

Operators submit actions.

The execution gateway consumes authorizations.

Start with:

address public operator;

modifier onlyGovernance() {
    require(msg.sender == governance, "not governance");
    _;
}

modifier onlyOperator() {
    require(msg.sender == operator, "not operator");
    _;
}

modifier onlyGateway() {
    require(msg.sender == executionGateway, "not gateway");
    _;
}

Then:

function setOperator(address newOperator)
    external
    onlyGovernance
{
    require(newOperator != address(0), "zero operator");
    operator = newOperator;
}

And:

function setExecutionGateway(address gateway)
    external
    onlyGovernance
{
    require(gateway != address(0), "zero gateway");
    executionGateway = gateway;
}

This separation matters.

The person allowed to propose treasury actions shouldn't automatically be allowed to modify the policy.

5. Adding Assets and Recipients

We'll use allowlists.

function setAssetAllowed(
    address asset,
    bool allowed
)
    external
    onlyGovernance
{
    allowedAssets[asset] = allowed;
}

And:

function setRecipientAllowed(
    address recipient,
    bool allowed
)
    external
    onlyGovernance
{
    allowedRecipients[recipient] = allowed;
}

At this point we already have something interesting.

Suppose the treasury works with five counterparties.

On Ethereum, you could publish the complete list of addresses.

On Sapphire, the policy engine can keep that operational relationship confidential.

That doesn't necessarily mean the final transfer is private.

It means the decision infrastructure doesn't have to be.

6. The Core Policy Function

Now we get to the heart of the system.

function evaluate(
    PolicyTypes.Request calldata request
)
    external
    onlyOperator
    returns (PolicyTypes.DecisionRecord memory)
{
    require(
        !consumedRequests[request.requestId],
        "request already consumed"
    );

    require(
        allowedAssets[request.asset],
        "asset not allowed"
    );

    require(
        allowedRecipients[request.recipient],
        "recipient not allowed"
    );

    uint256 limit = maxPerTransaction;

    if (emergencyMode) {
        require(
            block.timestamp < emergencyUntil,
            "emergency expired"
        );

        limit = emergencyLimit;
    }

    require(
        request.amount <= limit,
        "policy limit"
    );

    consumedRequests[request.requestId] = true;

    bytes32 commitment = keccak256(
        abi.encode(
            request.requestId,
            request.asset,
            request.recipient,
            request.amount,
            policyVersion
        )
    );

    return PolicyTypes.DecisionRecord({
        decision: PolicyTypes.Decision.APPROVED,
        risk: emergencyMode
            ? PolicyTypes.RiskLevel.EMERGENCY
            : PolicyTypes.RiskLevel.NORMAL,
        policyVersion: policyVersion,
        expiresAt: block.timestamp + 60,
        commitment: commitment
    });
}

There are several important properties here.

The authorization is:

tied to one request
tied to one policy version
short-lived
single-use
bounded by the policy
committed cryptographically

7. Why Nonces Aren't Enough

A common mistake in authorization systems is using only:

uint256 nonce;

That protects against simple replay.

But a robust authorization should also bind:

request ID
asset
recipient
amount
policy version

Otherwise an authorization for:

USDC → Alice → 10,000

could potentially be interpreted incorrectly by another component as:

USDC → Bob → 10,000

or:

USDC → Alice → 100,000

The commitment should therefore be domain-specific.

A stronger commitment looks like:

bytes32 constant DOMAIN =
    keccak256("CONFIDENTIAL_TREASURY_POLICY_V1");

Then:

bytes32 commitment = keccak256(
    abi.encode(
        DOMAIN,
        address(this),
        block.chainid,
        policyVersion,
        request.requestId,
        request.asset,
        request.recipient,
        request.amount,
        request.nonce
    )
);

Now an authorization isn't just a hash of data.

It's a hash of:

what system + what chain + what policy + what request + what action.

This dramatically reduces cross-context replay risk.

8. The Execution Gateway

Now we need a bridge between confidential authorization and public execution.

Create:

ExecutionGateway.sol

The gateway receives an authorization.

Conceptually:

The gateway is deliberately dumb.

This is important.

We don't want the public execution layer to recreate the entire private policy.

The policy engine says:

this action is authorized.

The gateway says:

this authorization has not expired, has not been consumed, and corresponds to this execution.

9. Authorization Expiry

Never create a confidential authorization that lasts indefinitely.

Our authorization has:

uint256 expiresAt;

And:

require(
    block.timestamp <= authorization.expiresAt,
    "authorization expired"
);

Why?

Imagine an operator obtains authorization at 10:00.

At 10:30, governance changes the policy.

If the old authorization remains valid forever, the policy change doesn't actually revoke the previous decision.

Short-lived authorizations reduce that window.

10. Emergency Mode

Now let's implement something more interesting.

The treasury needs emergency powers.

But we don't want:

emergency = true;

to mean:

administrator can do anything.

Instead, emergency mode changes a small number of parameters.

function activateEmergency(
    uint64 duration
)
    external
    onlyGovernance
{
    require(duration <= 1 hours, "duration too long");

    emergencyMode = true;
    emergencyUntil =
        uint64(block.timestamp) + duration;
}

And:

function emergencyStatus()
    external
    view
    returns (
        bool active,
        uint64 until
    )
{
    return (
        emergencyMode &&
        block.timestamp < emergencyUntil,
        emergencyUntil
    );
}

The key property is:

emergency authority expires automatically.

That is much stronger than documenting:

emergency mode should only be used temporarily.

11. Emergency Powers Should Be Narrow

Suppose normal mode allows:

maximum transfer = 100,000 USDC

Emergency mode might allow:

maximum transfer = 10,000 USDC

That sounds backwards at first.

But that's exactly the point.

An emergency system should often reduce capability, not increase it.

A safer mental model is:

Normal operation
│
│ incident
▼
Restricted operation
│
│ expiry
▼
Normal operation

Not:

Normal operation
│
▼
Admin can do anything
│
▼
Hopefully someone turns it off

12. The Policy Version

Whenever governance changes a policy:

function bumpPolicyVersion()
    internal
{
    policyVersion++;
}

Then:

function setMaxPerTransaction(
    uint256 value
)
    external
    onlyGovernance
{
    maxPerTransaction = value;
    policyVersion++;
}

This creates a useful property:

Every authorization can answer:

Which policy version approved this?

That gives auditors a historical dimension.

13. Public Commitments

Now comes the most important architectural idea.

We want to expose enough information for an auditor to know that a decision occurred.

But we don't necessarily want to expose the entire policy.

We can publish:

request ID
policy version
commitment
execution timestamp
execution result

without publishing:

full policy
private allowlists
internal limits
operational metadata

The commitment is:

H(
domain,
chain ID,
policy version,
request,
authorization
)

The public chain therefore sees a cryptographic fingerprint.

Think of it as:

The commitment doesn't reveal the input.

But if the system later needs to disclose the policy, an auditor can verify that the disclosed data corresponds to the commitment.

14. Why Not Just Emit the Policy?

Because events are public.

This is one of the most important Sapphire-specific considerations.

Sapphire contract state is encrypted, but Solidity events are not automatically private. Oasis explicitly documents that event payloads are public unless you use an encrypted-event design.

So this is dangerous:

event PolicyUpdated(
    uint256 maxPerTransaction,
    uint256 dailyLimit
);

Even if the variables themselves are confidential, that event leaks them.

Instead:

event PolicyCommitted(
    uint256 indexed version,
    bytes32 indexed commitment
);

Now the event is useful for indexing without exposing the policy.

15. Confidential Events

If you actually need to publish sensitive event payloads to an authorized consumer, Sapphire provides encrypted-event patterns.

For example, Oasis documents patterns based on symmetric keys and ECDH-derived keys for encrypted events.

The conceptual architecture becomes:

This gives you two information channels:

Public channel

Safe metadata.

Confidential channel

Authorized operational information.

That distinction is useful for enterprise systems.

16. The Daily Spending Limit

So far we've only implemented a per-transaction limit.

Let's add a daily limit.

The naïve implementation is:

uint256 spentToday;
uint256 currentDay;

and:

if (block.timestamp / 1 days != currentDay) {
    currentDay = block.timestamp / 1 days;
    spentToday = 0;
}

Then:

require(
    spentToday + request.amount <= dailyLimit,
    "daily limit"
);

spentToday += request.amount;

This works, but introduces a subtle privacy consideration.

If the execution cost or state access pattern depends strongly on private values, an observer may infer information.

Oasis explicitly warns that confidential execution can still leak information through timing, gas usage, and storage access patterns.

So confidential programming isn't:

"Put variables behind private."

It is:

"Design the entire observable execution surface."

17. Constant-Shaped Execution

Suppose you have:

if (amount > secretLimit) {
    revert();
}

The result itself is private.

But the gas behavior may differ between branches.

A sufficiently capable observer may be able to infer information.

This is why confidential systems need a different mindset.

Instead of thinking:

state is secret

think:

state + execution + gas + storage access + events + timing

all contribute to the observable surface.

18. Building the Treasury

Now create a simple treasury.

contract Treasury {
    address public immutable policyGateway;

    constructor(address _policyGateway) {
        policyGateway = _policyGateway;
    }

    modifier onlyGateway() {
        require(
            msg.sender == policyGateway,
            "not gateway"
        );
        _;
    }

    function executeERC20(
        address token,
        address recipient,
        uint256 amount
    )
        external
        onlyGateway
    {
        IERC20(token).transfer(
            recipient,
            amount
        );
    }
}

Notice that the treasury itself doesn't know:

daily limit
recipient classification
emergency rules
operator permissions

It only knows:

the policy gateway is authorized to execute.

This separation makes the system easier to reason about.

19. Why the Treasury Should Not Reimplement Policy

Imagine this:

Policy Engine:
max transfer = 100k

Treasury:
max transfer = 250k

Now we have two policy engines.

That's dangerous.

The policy engine should be the authority.

The treasury should enforce the minimum mechanical conditions needed for safe execution.

This is a classic principle:

Don't duplicate security-critical policy across independent components unless you explicitly want defense in depth.

If you do duplicate it, test that the policies are equivalent.

20. Replaying an Authorization

Now imagine an attacker obtains:

authorization:
recipient = attacker
amount = 100,000

and tries to submit it twice.

The gateway needs:

mapping(bytes32 => bool) usedCommitments;

Then:

require(
    !usedCommitments[authorization.commitment],
    "already used"
);

usedCommitments[
    authorization.commitment
] = true;

The ordering matters.

Do not mark it consumed after an external call.

Use:

check
↓
mark consumed
↓
external execution

rather than:

check
↓
external execution
↓
mark consumed

Otherwise a reentrant path may attempt to reuse it.

21. The Complete Execution Flow

The complete system now looks like:

This is our core protocol.

22. Adding an Action Type

Don't make authorization only about transfers.

Define:

enum ActionType {
    TRANSFER,
    REBALANCE,
    GRANT,
    REVOKE,
    EMERGENCY
}

Then include:

ActionType actionType;

in the request.

Now the commitment binds the exact operation.

For example:

bytes32 commitment = keccak256(
    abi.encode(
        DOMAIN,
        action.actionType,
        action.asset,
        action.recipient,
        action.amount,
        policyVersion,
        action.nonce
    )
);

This prevents an authorization for one semantic operation from being interpreted as another.

23. Adding Role Separation

Now we can make the architecture more realistic.

Governance
│
├── modifies policy
│
└── controls emergency mode

Operator
│
└── proposes actions

Policy Engine
│
└── evaluates actions

Gateway
│
└── executes authorized actions

Treasury
│
└── owns assets

No single component needs every permission.

That matters because the most dangerous failure mode in treasury architecture is often not a bug.

It's excessive authority.

24. A Real Use Case

Let's make this concrete.

Imagine a protocol treasury with:

$4M USDC
$2M ETH
$1M governance token
$500k operational budget

The organization has three operating groups:

Operations
Liquidity
Grants

The treasury wants to keep its operational rules private.

Why?

Because publishing:

Liquidity strategy:
rebalance above 4%
maximum venue exposure = 22%
preferred counterparties = [...]

can reveal operational strategy.

Instead, governance can configure the policy privately.

The public chain sees:

Treasury:
0x...

Authorization:
commitment 0xabc...
policy version 17
executed at block ...

The actual treasury transfer remains observable.

But the private policy that approved it doesn't have to become public.

25. Adding Policy Commitments

We can make policy updates themselves auditable.

Instead of publicly exposing:

dailyLimit = 500,000
maxPerTx = 100,000

we calculate:

bytes32 policyCommitment = keccak256(
    abi.encode(
        policyVersion,
        maxPerTransaction,
        dailyLimit,
        emergencyLimit,
        emergencyUntil
    )
);

Then emit:

event PolicyCommitted(
    uint256 indexed version,
    bytes32 indexed commitment
);

Now the public chain has:

version 17
commitment 0x...

An auditor with access to the policy can verify:

hash(disclosed_policy) == commitment

This is a powerful pattern.

The chain doesn't need to know the policy.

It only needs to know which policy commitment was active.

26. Why Hashing Isn't Magic

There is an important limitation.

A commitment does not automatically make something trustworthy.

Suppose the policy contains:

recipient = 0x123

and someone claims the commitment represents:

recipient = 0x456

Without knowing the original policy, you can't infer the truth.

The commitment provides:

integrity

not:

availability

or:

honesty

That's why governance, attestation, access control, and operational procedures still matter.

Confidentiality isn't a substitute for governance.

27. Policy Disclosure

Suppose the organization wants to reveal a policy after an incident.

They can publish:

{
  "version": 17,
  "maxPerTransaction": "100000000000",
  "dailyLimit": "500000000000",
  "emergencyLimit": "10000000000",
  "emergencyUntil": 1780000000
}

and:

policyCommitment = keccak256(canonical(policy))

Anyone can recompute it.

That turns confidentiality into selective disclosure.

This is particularly useful for audits.

28. Canonical Encoding Matters

Don't hash arbitrary JSON.

These two objects:

{
  "limit": 100,
  "version": 1
}

and:

{
  "version": 1,
  "limit": 100
}

may represent the same logical policy but have different byte representations.

For cryptographic commitments, define a canonical encoding.

For Solidity:

keccak256(
    abi.encode(
        policyVersion,
        maxPerTransaction,
        dailyLimit,
        emergencyLimit,
        emergencyUntil
    )
);

Keep the ordering fixed.

Document it.

Never change it silently.

29. Testing the Policy Engine

This is where the tutorial becomes more than a demo.

We need tests for:

authorization
replay
expiry
policy versioning
emergency expiry
asset allowlist
recipient allowlist
amount limits
cross-domain replay

A basic test:

function testRejectsUnauthorizedRecipient()
    public
{
    PolicyTypes.Request memory request =
        PolicyTypes.Request({
            asset: USDC,
            recipient: attacker,
            amount: 1_000e6,
            nonce: 1,
            requestId: keccak256("request-1")
        });

    vm.expectRevert("recipient not allowed");

    policy.evaluate(request);
}

30. Replay Test

function testCannotReuseRequest()
    public
{
    PolicyTypes.Request memory request =
        validRequest();

    policy.evaluate(request);

    vm.expectRevert("request already consumed");

    policy.evaluate(request);
}

Replay testing should not be an afterthought.

Authorization systems fail surprisingly often because developers test:

valid authorization

but not:

same authorization
different transaction

31. Expiry Test

function testAuthorizationExpires()
    public
{
    PolicyTypes.Request memory request =
        validRequest();

    PolicyTypes.DecisionRecord memory decision =
        policy.evaluate(request);

    vm.warp(decision.expiresAt + 1);

    vm.expectRevert("authorization expired");

    gateway.execute(
        request,
        decision
    );
}

The exact mechanics depend on how the public gateway receives and verifies the authorization, but the invariant is simple:

An authorization must never become more powerful with age.

32. Emergency Expiry Test

function testEmergencyAutomaticallyExpires()
    public
{
    governanceActivateEmergency(30 minutes);

    vm.warp(
        block.timestamp + 31 minutes
    );

    assertFalse(
        policy.emergencyStatus()
    );
}

Notice we're not testing:

someone called disableEmergency()

We're testing:

time itself disables emergency mode

That's stronger.

33. Property-Based Thinking

Now let's move beyond individual tests.

A useful invariant is:

No authorization can approve more than the current policy allows.

Another:

Every authorization is unique.

Another:

An expired authorization can never execute.

Another:

An emergency authorization cannot exceed the emergency limit.

You can express these as invariant tests.

Conceptually:

∀ authorization A:

A.amount <= policyLimit(A.policyVersion)

A.expiresAt > now

consumed(A) == false
    before execution

consumed(A) == true
    after successful execution

This is the kind of testing that makes the project interesting for experienced Solidity developers.

34. Testing Confidentiality Is Different

Normal Solidity testing asks:

Did the function return the correct result?

Confidential Solidity needs additional questions:

Did an event leak private information?
Does gas usage reveal a secret branch?
Does storage access reveal which user was selected?
Does a public getter expose confidential state?
Does an error message reveal policy information?
Does an unauthorized eth_call reveal anything?

Oasis specifically documents that unsigned eth_call requests have msg.sender == address(0) on Sapphire, which is an important difference from assumptions developers may carry over from transparent EVMs.

So authentication needs to be designed deliberately.

35. View Functions Need Special Attention

Suppose we write:

function getPolicy()
    external
    view
    returns (uint256)
{
    return maxPerTransaction;
}

Congratulations.

You just defeated the point of the confidential policy.

The state may be encrypted internally, but your getter explicitly reveals it.

A confidential contract should instead expose only what the caller is authorized to see.

For example:

function policyVersion()
    external
    view
    returns (uint256)
{
    return policyVersion;
}

And potentially:

function policyCommitment()
    external
    view
    returns (bytes32)
{
    return currentPolicyCommitment;
}

36. The Public / Private Interface

A good way to design the system is to write two API surfaces.

Public API
policyVersion()
policyCommitment()
executionCommitment()
Confidential API
evaluate()
getPrivatePolicy()
setPrivatePolicy()
getInternalRiskState()

The public interface answers:

What can everyone know?

The confidential interface answers:

What should authorized participants know?

That distinction is useful well beyond treasuries.

37. Client-Side Sapphire Integration

For TypeScript applications, Oasis provides packages for Sapphire-aware clients. For ethers v6, the official integration is @oasisprotocol/sapphire-ethers-v6, which wraps providers and signers so calls and transactions can be encrypted appropriately.

Install:

npm install ethers
npm install @oasisprotocol/sapphire-ethers-v6

Then:

import {
  JsonRpcProvider,
  Wallet
} from "ethers";

import {
  wrapEthersProvider,
  wrapEthersSigner
} from "@oasisprotocol/sapphire-ethers-v6";

Create the provider:

const rawProvider = new JsonRpcProvider(
  process.env.SAPPHIRE_RPC
);

const provider =
  wrapEthersProvider(rawProvider);

And the signer:

const rawSigner =
  new Wallet(
    process.env.PRIVATE_KEY!,
    rawProvider
  );

const signer =
  wrapEthersSigner(rawSigner);

This is important because ordinary EVM tooling isn't automatically enough for confidential transaction handling.

38. Requesting Authorization

Our TypeScript application can now construct a request.

const request = {
  asset: USDC,
  recipient: recipient,
  amount: parseUnits("5000", 6),
  nonce: Date.now(),
  requestId: keccak256(
    toUtf8Bytes(
      crypto.randomUUID()
    )
  )
};

Then:

const result =
  await policy.evaluate(request);

The returned authorization is passed to the execution gateway.

The public execution layer never needs the complete policy.

39. Network Configuration

For development, Oasis provides Sapphire Localnet and Testnet. The current official documentation lists:

Sapphire Mainnet: 23294
Sapphire Testnet: 23295
Sapphire Localnet: 23293

and documents the corresponding RPC configuration.

For example:

const sapphire = {
  chainId: 23294,
  rpcUrl: process.env.SAPPHIRE_RPC!
};

For local development:

const localSapphire = {
  chainId: 23293,
  rpcUrl: "http://localhost:8545"
};

Do not put real production secrets or production state on Sapphire Testnet. Oasis explicitly warns that Testnet state can be wiped and that confidentiality there should not be treated as guaranteed.

40. Running Sapphire Localnet

For fast development, Oasis provides a local Sapphire environment through Docker.

A typical workflow is:

docker run \
-it \
-p 8544-8548:8544-8548 \
ghcr.io/oasisprotocol/sapphire-localnet

Then point your test client at:

http://localhost:8545

The advantage is that you can repeatedly:

deploy
test
destroy
restart

without depending on a public testnet.

41. Deployment

Your foundry.toml can contain:

[profile.default]
src = "src"
script = "script"
test = "test"
out = "out"
libs = ["lib"]

solc_version = "0.8.24"
optimizer = true
optimizer_runs = 200

Then:

forge build

Run:

forge test -vvv

Once the local tests pass, deploy to Sapphire Testnet.

The exact RPC and account configuration should come from the current Oasis network documentation rather than hardcoding old endpoints into the repository.

42. Contract Verification

A production-oriented repository shouldn't stop at "deployment successful".

Verify the contract source and metadata.

Oasis documents Sourcify-based verification for Sapphire deployments, including selecting Sapphire Mainnet or Sapphire Testnet and providing the Foundry/Hardhat build information.

That matters particularly for confidential systems.

People need to be able to inspect:

what code is running
what compiler version was used
what dependencies were included
what deployment corresponds to which policy version

Confidentiality should never become an excuse for opaque engineering.

43. Threat Model

Now let's attack our own system.

Threat 1: Compromised operator

The operator can request actions.

But the policy engine limits:

asset
recipient
amount
frequency
policy state

So the operator should not automatically be able to drain the treasury.

Threat 2: Replay

Mitigated by:

requestId
nonce
commitment
consumedRequests

Threat 3: Stale authorization

Mitigated by:

expiresAt
policyVersion

Threat 4: Emergency abuse

Mitigated by:

maximum duration
restricted limits
automatic expiry
separate governance authority

Threat 5: Event leakage

Mitigated by:

commitments instead of private values

and encrypted events where confidential event payloads are genuinely required.

Threat 6: Getter leakage

Mitigated by:

minimal public view API

Threat 7: Policy inference

This is harder.

Potential leakage can come from:

gas usage
execution timing
storage access patterns
error behavior
frequency of policy decisions

Sapphire's documentation explicitly discusses these side-channel considerations.

This is why a serious confidential application needs a threat model beyond Solidity reentrancy.

44. What Sapphire Does Not Solve

This is worth stating clearly.

Sapphire does not magically solve:

bad business logic

It doesn't solve:

compromised governance

It doesn't solve:

malicious operators

It doesn't solve:

incorrect authorization semantics

It doesn't make an unsafe contract safe.

Instead, it changes the confidentiality properties of the execution environment.

The correct mental model is:

Ethereum EVM
    +
confidential execution
    +
encrypted state
    +
encrypted client communication

not:

Ethereum but everything is magically private.

Oasis explicitly documents the differences developers need to account for when moving from Ethereum to Sapphire.

45. Why Keep the Treasury Public?

You might ask:

If the policy is private, why not keep the whole treasury on Sapphire?

You could, depending on the application.

But a hybrid architecture has an attractive property:

private decision
+
public settlement

The treasury can remain compatible with:

public explorers
existing ERC-20 infrastructure
accounting systems
public reporting
external auditors
existing DeFi protocols

The private component becomes the decision layer, rather than replacing the entire financial stack.

46. The Hybrid Architecture

The resulting design is:

This is the core pattern of the tutorial.

47. Policy as a Product

Once this works, the policy engine can become more general.

Instead of:

TreasuryPolicy

we can build:

PolicyEngine

with rules such as:

allow(asset, recipient, amount)
allow(strategy, market, exposure)
allow(operator, action)
allow(grant, recipient, budget)
allow(payment, vendor, amount)

Now you're not building a treasury contract.

You're building a confidential authorization layer.

That's a much more general primitive.

48. Extending the Policy Model

For example:

struct Rule {
    bytes32 ruleId;
    uint256 limit;
    uint64 validFrom;
    uint64 validUntil;
    bool enabled;
}

And:

mapping(bytes32 => Rule) private rules;

A request can contain:

rule ID
action type
asset
recipient
amount
context
nonce

The policy engine then evaluates:

request
+
private rules
+

private state

authorization

This resembles a traditional enterprise policy engine.

Except the enforcement point is onchain.

49. Multi-Stage Authorization

We can go further.

Instead of:

operator → policy → execution

use:

operator
↓
risk policy
↓
budget policy
↓
emergency policy
↓
execution policy
↓
authorization

Each layer can have a separate policy version.

That gives auditors a much richer model.

50. Confidential Policies for Organizations

This pattern becomes especially interesting for organizations that don't want to publish operational rules.

For example:

Market maker

Private:

inventory thresholds
venue preferences
rebalance bands

Public:

actual settlements
Grant organization

Private:

evaluation thresholds
reviewer assignments
internal limits

Public:

approved grants
Infrastructure provider

Private:

internal spending policies
operator capabilities
failover thresholds

Public:

settlement events
DAO treasury

Private:

operational policy
counterparty classifications
emergency thresholds

Public:

final treasury movements

The same architecture applies to all four.

51. What About Governance?

Governance itself can remain public.

For example:

Proposal #182
↓
Policy commitment changed
↓
Version 18 activated

The actual contents of the operational policy can remain confidential until disclosure is appropriate.

This creates a useful separation:

Governance transparency
≠
Operational transparency

A DAO can disclose:

Governance approved policy version 18.

without necessarily disclosing:

every operational threshold contained in version 18.

52. The Audit Model

An auditor can be granted access to the confidential policy.

They receive:

Policy v18

Then calculate:

commitment(policy v18)

and compare it to:

onchain commitment(v18)

If they match:

Policy disclosed
        ↓
Hash
        ↓
Matches historical commitment
        ↓
Policy integrity established

That is a powerful property.

The system doesn't require everyone to know the policy.

It only requires that the organization cannot later pretend that a different policy was active.

53. Why This Is Different From a Normal Multisig

A multisig answers:

Did enough authorized humans sign this transaction?

Our policy engine answers:

Did this action satisfy a private, versioned, machine-enforced policy?

Those are different problems.

You can combine them.

For example:

Private Policy
      ↓
Authorization
      ↓
3-of-5 Multisig
      ↓
Public Treasury

Now the multisig provides human governance while the confidential policy engine provides operational constraints.

54. A Stronger Architecture

The production version could therefore look like:

Now compromise of one operator isn't enough.

Compromise of one signer isn't necessarily enough.

And compromise of the public gateway doesn't reveal the confidential policy.

55. Operational Monitoring

A production system should monitor:

policy version changes
emergency activation
emergency expiry
authorization volume
failed authorization attempts
repeated requests
gateway failures
unexpected recipients

But again, don't accidentally publish sensitive information.

A monitoring event might say:

PolicyVersionChanged(18)

rather than:

PolicyChanged(
    maxTransfer = 123456,
    internalRecipient = ...
)

Monitoring needs to respect the same confidentiality boundary as the application.

56. A Useful Rule

Here's the rule I'd use when designing a Sapphire application:

If a value is confidential, assume every output derived from that value may also be confidential.

That includes:

events
errors
gas
timing
return values
storage access
authorization frequency

This is one of the biggest differences between writing ordinary Solidity and writing confidential Solidity.

57. Production Checklist

Before deploying a system like this, I'd run through:

*Contract security
*

Reentrancy protection
Replay protection
Authorization expiry
Domain separation
Policy versioning
Explicit role separation
Emergency expiry
Maximum emergency duration
No arbitrary delegatecall
No unrestricted asset approval
Safe ERC-20 handling

Confidentiality

No private data in normal events
No sensitive public getters
No sensitive revert strings
Constant-shaped branches where necessary
Storage access patterns reviewed
Gas leakage considered
Client-side encryption configured

Governance

Policy changes are versioned
Policy commitments are recorded
Emergency powers are bounded
Policy administrator is separate from operator
Public disclosure process exists

Infrastructure

Sapphire-aware client
Key management
RPC redundancy
Contract verification
Deployment reproducibility
Monitoring
Incident response

58. The Most Important Design Principle

The biggest lesson from this architecture isn't actually about Sapphire.

It's about separating confidentiality from authority.

A private policy doesn't automatically make an authority trustworthy.

A public commitment doesn't automatically make an organization honest.

A multisig doesn't automatically make a policy correct.

Each mechanism solves a different problem.

Think of the system as four independent properties:

             SECURITY MODEL

    ┌─────────────────────────┐
    │                         │
    │       AUTHORITY         │
    │   Who is allowed?       │
    │                         │
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │                         │
    │        POLICY           │
    │   What is permitted?    │
    │                         │
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │                         │
    │     CONFIDENTIALITY     │
    │   Who can know it?      │
    │                         │
    └────────────┬────────────┘
                 │
    ┌────────────▼────────────┐
    │                         │
    │       AUDITABILITY      │
    │   What can be proven?   │
    │                         │
    └─────────────────────────┘

Oasis Sapphire is particularly useful for the third property.

But a serious protocol needs all four.

59. Where This Pattern Gets Interesting

Once you have:

private policy
+
public commitment
+
bounded authorization
+
public settlement

you can start building much more sophisticated systems.

For example:

Confidential treasury routing

The routing policy is private, but final settlement is public.

Private grant allocation

Eligibility rules remain private while successful grants become publicly auditable.

Institutional transaction policy

Employees can initiate transactions without learning the complete treasury policy.

Private market operations

Strategy constraints remain confidential while settlement remains verifiable.

DAO emergency controls

Emergency thresholds remain private while emergency activation and expiry are publicly observable.

The common architecture is always:

PRIVATE DECISION
       ↓
CRYPTOGRAPHIC COMMITMENT
       ↓
PUBLIC EXECUTION
       ↓
PUBLIC AUDIT TRAIL

60. Final Architecture

At the end of the tutorial, we have built:

The key property is that the public chain doesn't need to understand every private decision.

It only needs to enforce the final authorization boundary.

Conclusion

Most blockchain systems treat transparency as a binary property:

public chain = transparent.

But that's not really how production systems work.

There are multiple layers of information:

assets
transactions
permissions
policies
strategies
identities
relationships
internal state

Not all of those need the same visibility.

A treasury can be transparent about its assets while keeping operational policy confidential.

A DAO can publicly record that a policy changed without publishing every internal parameter.

An auditor can later verify that a disclosed policy corresponds to the policy commitment that existed when a transaction was authorized.

And an emergency mechanism can be technically bounded instead of relying on documentation saying:

"This function should only be used in emergencies."

That's the architectural idea behind the system we built here:

        PRIVATE
           │
           ▼
   Policy Evaluation
           │
           ▼
    Authorization
           │
           ▼
     Commitment
           │
           ▼
        PUBLIC
           │
           ▼
   Treasury Settlement
           │
           ▼
     Audit Trail

Oasis Sapphire is useful here because it provides an EVM-compatible environment where contract state and client communication can be confidential, while still allowing developers to use familiar Solidity and Ethereum tooling.

But the important lesson isn't simply:

"Put your treasury on Sapphire."

It's:

Design confidentiality as a boundary around sensitive decision-making, while keeping the resulting financial actions independently auditable.

That distinction makes confidential blockchain applications much more interesting than simply hiding balances.

Repository Structure

The complete project from this tutorial should look like:

confidential-treasury-policy/
│
├── src/
│   ├── ConfidentialPolicy.sol
│   ├── PolicyTypes.sol
│   ├── CommitmentRegistry.sol
│   ├── ExecutionGateway.sol
│   ├── Treasury.sol
│   └── interfaces/
│       ├── IPolicyEngine.sol
│       └── ITreasury.sol
│
├── script/
│   ├── Deploy.s.sol
│   ├── ConfigurePolicy.s.sol
│   └── RegisterGateway.s.sol
│
├── test/
│   ├── PolicyEngine.t.sol
│   ├── Authorization.t.sol
│   ├── Emergency.t.sol
│   ├── Replay.t.sol
│   ├── Confidentiality.t.sol
│   └── Invariants.t.sol
│
├── integration/
│   ├── sapphire.ts
│   ├── policy.ts
│   └── execution.ts
│
├── foundry.toml
├── package.json
└── README.md

A natural next step would be to extend the prototype with multisig approval, encrypted events, policy disclosure proofs, and a public execution gateway on Base, turning the tutorial into a complete end-to-end treasury system rather than a single Sapphire contract.

Further reading
Oasis Sapphire developer documentation
Sapphire concepts and confidential state model
Sapphire security considerations
Sapphire encrypted events
Sapphire network information
Sapphire Foundry tooling

Building a Confidential OTC Settlement Protocol with Oasis Sapphire & Base

rayQu — Mon, 20 Jul 2026 07:06:17 +0000

Learn how to build a privacy-preserving OTC trading protocol where counterparties negotiate confidentially using Oasis Sapphire while settling trades transparently on Base.

Large cryptocurrency trades rarely happen on decentralized exchanges.

When someone wants to swap a few hundred dollars worth of ETH for USDC, an automated market maker like Uniswap works exceptionally well. Liquidity is abundant, settlement is immediate, and the entire process can be completed in a single transaction.

The picture changes completely once the trade size reaches institutional territory.

Imagine a DAO treasury planning to exchange 500,000 USDC for ETH.

Executing that transaction through a public liquidity pool immediately reveals valuable information to the entire market. Arbitrage bots begin simulating profitable routes before the transaction is finalized. Market makers widen spreads. Searchers compete to extract value from the pending order, while other traders infer the treasury's strategy simply by observing the transaction.

The protocol itself is functioning exactly as designed.

The problem is that transparency and negotiation don't always belong together.

This is precisely why Over-the-Counter (OTC) trading exists.

Rather than exposing an order to an entire market, two counterparties negotiate privately before agreeing on a final settlement price. Only after both parties reach an agreement is the trade executed.

Traditional financial institutions have relied on this model for decades because confidentiality reduces information leakage and allows large transactions to occur without unnecessarily moving markets.

Public blockchains introduce an interesting challenge.

How do you preserve confidential negotiations while still benefiting from decentralized settlement?

This is where Oasis Sapphire becomes particularly interesting.

Instead of treating confidentiality as an application-layer concern, Sapphire provides confidential smart contract execution directly within an EVM-compatible environment. Sensitive contract state remains protected while developers continue writing familiar Solidity code.

In this tutorial we'll build a simplified OTC trading protocol that combines confidential negotiation on Oasis Sapphire with transparent settlement on Base.

Rather than building another decentralized exchange, we'll focus on the negotiation process itself.

By the end of this guide you'll have built a protocol capable of:

Creating confidential OTC trade offers
Receiving private counterparty quotes
Accepting offers without revealing negotiations publicly
Escrowing assets before settlement
Executing the final settlement on Base
Cancelling expired orders safely
Preventing replay attacks through signed messages

Although the protocol we'll build is intentionally simplified for educational purposes, its architecture mirrors patterns commonly found in production financial systems.

Understanding the Problem

Before writing a single line of Solidity, it's worth asking an important question.

Why don't institutions simply use AMMs for everything?

After all, decentralized exchanges already provide liquidity, transparent pricing, and permissionless access.

The answer comes down to market impact.

Suppose Alice wants to purchase 400 ETH.

If that trade is submitted directly to a public liquidity pool, several things happen almost immediately.

First, the pending transaction becomes visible to sophisticated searchers monitoring the network.

Next, those searchers estimate the price impact by simulating the trade against current liquidity.

If profitable opportunities exist, competing transactions are constructed before Alice's order has even been finalized.

Even if nobody explicitly frontruns the transaction, the market itself now possesses information that previously existed only inside Alice's trading strategy.

That information has value.

The larger the order becomes, the more valuable it becomes.

The sequence below illustrates what happens inside a typical public execution environment.

sequenceDiagram

participant Alice
participant Ethereum
participant Searcher
participant LiquidityPool

Alice->>Ethereum: Submit Swap

Ethereum-->>Searcher: Pending Transaction

Searcher->>Searcher: Simulate Trade

Searcher->>LiquidityPool: Competing Transactions

LiquidityPool-->>Alice: Final Execution

Nothing malicious has occurred.

Every participant simply acted upon publicly available information.

For large trades, however, that transparency introduces unnecessary information leakage.

OTC trading avoids this problem entirely by moving negotiation away from the public market.

Only the final agreement becomes visible.

Why Oasis Sapphire?

One obvious question is why we need another blockchain at all.

Couldn't we simply negotiate off-chain using encrypted messages?

In some situations, yes.

However, purely off-chain negotiation introduces several new trust assumptions.

Who stores the offers?

Who guarantees neither party modified the terms?

How do we prove a particular offer existed if negotiations break down?

How do multiple market makers compete fairly?

A confidential smart contract solves these coordination problems.

Instead of trusting a centralized OTC desk, participants submit encrypted offers into a shared protocol.

The blockchain enforces protocol rules while keeping sensitive trading information confidential.

From the outside, observers know an offer exists.

They do not learn:

which asset is being traded,
the quoted price,
the requested amount,
acceptable settlement conditions,
or which counterparty accepted the offer.

Only the final settlement transaction becomes public.

That distinction dramatically reduces information leakage while preserving decentralized execution.

System Overview

Our protocol consists of five independent components.

Each has a single responsibility.

Separating these concerns keeps the contracts significantly easier to audit and makes future upgrades less risky.

flowchart LR

User["Trader"]

Frontend["Next.js Frontend"]

SDK["TypeScript SDK"]

Registry["OTC Registry"]

Escrow["Escrow Contract"]

Coordinator["Settlement Coordinator"]

Base["Base Network"]

User --> Frontend

Frontend --> SDK

SDK --> Registry

Registry --> Coordinator

Coordinator --> Escrow

Escrow --> Base

Let's briefly examine the role of each component.

OTC Registry

The registry acts as the confidential marketplace.

Every new offer enters the protocol through this contract.

Rather than immediately transferring assets, users first describe the trade they would like to perform.

Those details remain confidential until the offer is accepted.

Escrow Contract

Once two counterparties agree on a trade, both assets must be secured before settlement begins.

Instead of relying on trust between participants, the escrow contract temporarily locks both sides of the trade.

Neither participant can withdraw funds unilaterally after acceptance.

Only successful settlement or cancellation releases escrowed assets.

Settlement Coordinator

The final contract coordinates settlement on Base.

Once escrow conditions are satisfied, settlement becomes deterministic.

This separation keeps negotiation logic isolated from execution logic, significantly simplifying auditing.

Project Architecture

We'll build the project as a monorepo.

Although our example remains relatively small, organizing the repository this way closely resembles production Solidity projects.

confidential-otc-protocol/

├── contracts/
│
│   OTCRegistry.sol
│
│   Escrow.sol
│
│   SettlementCoordinator.sol
│
│   libraries/
│
│      SignatureVerifier.sol
│
│      OfferHasher.sol
│
│
├── sdk/
│
│   otcClient.ts
│
│   signer.ts
│
│   quotes.ts
│
├── backend/
│
│   api.ts
│
│   relayer.ts
│
│
├── frontend/
│
│   app/
│
├── script/
│
├── test/
│
└── docs/

Throughout this tutorial we'll implement each directory individually before integrating everything into a complete protocol.

By the end, you'll have a repository structured much more like a production codebase than a simple Solidity example.

Protocol Lifecycle

Before diving into the implementation, it's useful to visualize the complete lifecycle of an OTC trade.

stateDiagram-v2

[*] --> Draft

Draft --> Submitted

Submitted --> Quoted

Quoted --> Accepted

Accepted --> Escrowed

Escrowed --> Settled

Submitted --> Cancelled

Quoted --> Cancelled

Accepted --> Expired

Notice that settlement is only one stage of the protocol.

Most of the protocol's complexity actually happens before assets move.

Negotiation, verification, escrow, and acceptance each introduce their own state transitions.

Designing these transitions carefully is one of the easiest ways to eliminate entire classes of smart contract bugs before they ever appear.

In the next section we'll begin implementing the protocol's core contract: OTCRegistry.sol.

Rather than jumping directly into business logic, we'll first design the underlying data model and explain why each field exists before writing any functions.

Setting Up the Project

Before writing any Solidity, let's create the project structure.

We'll use Foundry because it has become the de facto standard for professional Solidity development. It provides fast compilation, excellent testing utilities, built-in fuzzing, and straightforward deployment scripts.

If you haven't already installed Foundry, you can do so with:

curl -L https://foundry.paradigm.xyz | bash
foundryup

Now create a new project.

forge init confidential-otc-protocol

cd confidential-otc-protocol

We'll also install OpenZeppelin contracts.

forge install OpenZeppelin/openzeppelin-contracts

Our project now looks like this.

confidential-otc-protocol/

├── lib/
│
├── script/
│
├── src/
│
├── test/
│
├── foundry.toml
│
└── README.md

Throughout the tutorial we'll gradually replace the default template with our protocol implementation.

Why Foundry?

Hardhat remains an excellent framework, but Foundry offers several advantages for protocol development.

First, tests execute considerably faster because they're written directly in Solidity.

Second, fuzz testing is built into the framework instead of requiring external plugins.

Finally, cheatcodes make it straightforward to simulate different users, timestamps, balances, and blockchain conditions.

Since we're building financial infrastructure, confidence in our testing environment matters just as much as confidence in the contracts themselves.

Designing the Registry

Most blockchain tutorials begin with functions.

Production protocols begin with data.

The quality of a smart contract is largely determined by how well its state is modeled.

Changing storage layouts after deployment is difficult, especially once external integrations exist.

Before writing a single function, we should understand exactly what information our registry needs to remember.

An OTC offer answers a simple question.

"What is one party willing to trade?"

That sounds simple, but the protocol needs considerably more information than just two token addresses.

Our registry must remember:

who created the offer,
which asset they're selling,
which asset they expect,
the amount offered,
the minimum amount they'll accept,
when the offer expires,
whether it's still active,
and whether somebody has already accepted it.

Representing these pieces of information explicitly makes later contract logic much easier to understand.

Creating the Offer Model

Inside src/, create a file named OTCRegistry.sol.

We'll start with the data model before implementing any business logic.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract OTCRegistry {

    enum OfferStatus {
        Open,
        Accepted,
        Cancelled,
        Settled,
        Expired
    }

    struct Offer {

        address maker;

        address tokenOffered;

        address tokenRequested;

        uint256 amountOffered;

        uint256 minimumAmountRequested;

        uint256 expiry;

        uint256 nonce;

        OfferStatus status;

    }

}

Although this contract contains only a few lines of Solidity, there's already quite a bit happening.

Instead of storing offers as loosely connected mappings, we've grouped related information into a single structure.

This makes the protocol easier to reason about because every offer becomes a self-contained object.

Let's examine each field.

Maker

address maker;

The maker is the wallet that created the offer.

This address becomes important throughout the protocol.

Only the maker can:

cancel an open offer,
update certain parameters (before acceptance),
or withdraw escrow if settlement fails.

Rather than checking ownership through complex access-control mechanisms, we'll simply compare msg.sender against this stored address.

Offered Token

address tokenOffered;

This represents the asset currently owned by the maker.

For example,

USDC

WETH

The registry itself won't hold these tokens.

Instead, it records what the maker intends to escrow later in the protocol.

Keeping negotiation separate from asset custody makes the protocol significantly easier to audit.

Requested Token

address tokenRequested;

This is the asset the maker expects in return.

Together,

tokenOffered

↓

tokenRequested

define the trading pair.

Unlike AMMs, we're not computing prices algorithmically.

The maker decides exactly what exchange they're willing to accept.

Offered Amount

uint256 amountOffered;

This field specifies how many units of the offered token the maker wishes to trade.

For example,

500,000 USDC

The protocol intentionally avoids floating-point arithmetic.

Every amount is stored using the token's smallest denomination.

For ERC-20 tokens, that typically means accounting for decimals within the frontend or SDK.

Minimum Requested Amount

uint256 minimumAmountRequested;

This field acts as protection against unfavorable execution.

Suppose Alice wants to exchange

500,000 USDC

for at least

165 ETH

If a counterparty proposes

160 ETH

the protocol should reject the trade automatically.

Encoding these constraints directly into the offer ensures every accepted trade satisfies the maker's original conditions.

Expiry

uint256 expiry;

No financial offer should remain valid forever.

Market conditions change.

Token prices fluctuate.

Liquidity disappears.

Rather than relying on users to manually cancel stale offers, we'll associate every offer with an expiration timestamp.

Any interaction after that timestamp becomes invalid.

This single field eliminates an entire class of replay attacks.

Nonce

uint256 nonce;

One subtle problem appears once signatures enter the picture.

Suppose Alice signs an offer today.

What's stopping somebody from submitting the exact same signed payload next month?

The answer is nonces.

Each new offer consumes a unique value.

Once that value has been used, the protocol refuses to accept another offer carrying the same nonce.

We'll implement this protection shortly.

Organizing Storage

With the data model complete, we can decide how offers will actually be stored.

mapping(uint256 => Offer) private offers;

uint256 public offerCounter;

mapping(address => uint256) public nonces;

Each mapping serves a different purpose.

The first stores every offer ever created.

The second generates unique identifiers.

Finally, the third keeps track of each user's latest nonce.

Separating these concerns keeps lookups straightforward while avoiding nested mappings that quickly become difficult to maintain.

Why Sequential IDs?

Earlier we discussed deterministic hashes.

Why switch to numeric identifiers?

Because this protocol has different requirements.

Unlike signed intents that may exist off-chain before submission, OTC offers originate inside the protocol itself.

Sequential identifiers offer several practical advantages.

They make indexing simpler.

They're cheaper to generate than hashes.

And they're considerably easier to reference from frontends and block explorers.

Offer #421 is much easier for developers to work with than

0xb7e13b8ecb5e...

Internally, we'll still use cryptographic hashes later for signatures.

But externally, sequential identifiers make the protocol much friendlier to use.

Creating Offers

With storage in place, we can finally implement our first state-changing function.

function createOffer(

    address tokenOffered,

    address tokenRequested,

    uint256 amountOffered,

    uint256 minimumAmountRequested,

    uint256 expiry

) external returns (uint256 offerId) {

    require(expiry > block.timestamp, "Offer already expired");

    offerId = ++offerCounter;

    offers[offerId] = Offer({

        maker: msg.sender,

        tokenOffered: tokenOffered,

        tokenRequested: tokenRequested,

        amountOffered: amountOffered,

        minimumAmountRequested: minimumAmountRequested,

        expiry: expiry,

        nonce: nonces[msg.sender]++,

        status: OfferStatus.Open

    });

}

Although concise, this function already demonstrates several useful design principles.

First, validation occurs before any state modification.

Second, every newly created offer immediately receives a unique identifier.

Finally, we increment the maker's nonce at creation time, ensuring every offer remains uniquely identifiable even if all other parameters are identical.

In the next section we'll improve this function by replacing require strings with custom errors, adding events for off-chain indexing, and integrating EIP-712 signatures so offers can be created through signed messages rather than direct transactions.

Adding Production-Grade Solidity Patterns

The first version of OTCRegistry.sol works, but it still looks closer to a prototype than production infrastructure.

Before moving deeper into confidential execution and cross-chain settlement, we need to improve the contract foundations.

Financial protocols are rarely compromised because the developer forgot how to write a function.

They fail because small design decisions accumulate.

Gas inefficiencies become expensive at scale.

Missing events break indexing systems.

Weak signature handling creates replay vulnerabilities.

Poorly defined state transitions make auditing significantly harder.

The next iteration of the registry focuses on those details.

Replacing require Strings with Custom Errors

The first improvement is replacing traditional revert messages.

A common Solidity pattern looks like this:

require(
    expiry > block.timestamp,
    "Offer already expired"
);

This works, but it is unnecessarily expensive.

Every revert string must be stored inside the contract bytecode.

For frequently triggered errors, this increases deployment size and runtime gas costs.

Modern Solidity provides custom errors.

Instead of storing text, we define an error selector.

error OfferExpired();

error InvalidToken();

error InvalidAmount();

error Unauthorized();

error OfferNotOpen();

Now validation becomes:

if (expiry <= block.timestamp) {
    revert OfferExpired();
}

The difference may seem small.

For a single transaction, the savings are minimal.

For a protocol processing thousands of interactions, these optimizations compound.

More importantly, custom errors create structured failure conditions.

Frontend applications can identify the exact failure type instead of parsing human-readable strings.

Updating the Registry Contract

Our contract now begins with clearer protocol-level failures.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract OTCRegistry {

    error OfferExpired();
    error InvalidAmount();
    error Unauthorized();
    error OfferNotOpen();

    enum OfferStatus {
        Open,
        Accepted,
        Cancelled,
        Settled,
        Expired
    }

    struct Offer {

        address maker;

        address tokenOffered;

        address tokenRequested;

        uint256 amountOffered;

        uint256 minimumAmountRequested;

        uint256 expiry;

        uint256 nonce;

        OfferStatus status;

    }

    mapping(uint256 => Offer) private offers;

    uint256 public offerCounter;

    mapping(address => uint256) public nonces;

}

The storage layout remains unchanged.

This is intentional.

Changing storage unnecessarily creates migration complexity.

A well-designed contract evolves by adding capabilities around stable foundations.

Why Events Matter

Smart contracts do not push information to applications.

They simply modify state.

If a frontend wants to display active OTC offers, it needs an efficient way to discover changes.

Reading every offer ID and querying storage directly does not scale.

Events solve this problem.

When emitted, events become part of transaction logs that external systems can index.

Popular indexing systems such as The Graph and custom backend services rely heavily on this pattern.

For our registry, we need events for:

offer creation,
offer acceptance,
cancellation,
settlement.

Let's add the first one.

event OfferCreated(
    uint256 indexed offerId,
    address indexed maker,
    address tokenOffered,
    address tokenRequested,
    uint256 amountOffered,
    uint256 minimumAmountRequested,
    uint256 expiry
);

The indexed keyword is important.

Indexed fields become searchable topics.

For example, a frontend can efficiently query:

"Show me every offer created by this address."

without scanning the entire blockchain.

Emitting Offer Creation Events

Now we update our creation function.

function createOffer(

    address tokenOffered,

    address tokenRequested,

    uint256 amountOffered,

    uint256 minimumAmountRequested,

    uint256 expiry

) external returns (uint256 offerId) {


    if (expiry <= block.timestamp) {
        revert OfferExpired();
    }


    if (
        amountOffered == 0 ||
        minimumAmountRequested == 0
    ) {
        revert InvalidAmount();
    }


    offerId = ++offerCounter;


    offers[offerId] = Offer({

        maker: msg.sender,

        tokenOffered: tokenOffered,

        tokenRequested: tokenRequested,

        amountOffered: amountOffered,

        minimumAmountRequested: minimumAmountRequested,

        expiry: expiry,

        nonce: nonces[msg.sender]++,

        status: OfferStatus.Open

    });


    emit OfferCreated(
        offerId,
        msg.sender,
        tokenOffered,
        tokenRequested,
        amountOffered,
        minimumAmountRequested,
        expiry
    );
}

The function now has three clear responsibilities:

Validate the offer.
Store protocol state.
Notify external systems.

Keeping those responsibilities separated makes later auditing much easier.

Introducing EIP-712 Typed Data

Direct transactions are not always ideal for OTC workflows.

Institutional traders frequently negotiate away from the blockchain.

A market maker might send a quote through a private channel.

A treasury manager might approve a trade through an internal signing system.

Broadcasting every negotiation step on-chain defeats the purpose of confidentiality.

Instead, users should be able to sign trade intents.

The blockchain only verifies the final agreement.

This is where EIP-712 becomes important.

EIP-712 defines a standard format for signing structured data.

Instead of signing an unreadable blob:

0x72af91bc...

users sign something understandable:

Sell:

500000 USDC

Receive:

165 ETH

Expiry:

July 20 2026

Wallets can display these fields clearly before approval.

Designing the Signed Offer

Our signed message needs a deterministic structure.

struct OfferMessage {

    address maker;

    address tokenOffered;

    address tokenRequested;

    uint256 amountOffered;

    uint256 minimumAmountRequested;

    uint256 expiry;

    uint256 nonce;

}

Every field matters.

Removing a field creates ambiguity.

For example, if expiry is not included, an attacker could reuse a valid signature after market conditions changed.

If nonce is missing, replay attacks become possible.

Cryptographic signatures are only as strong as the data they protect.

Adding OpenZeppelin EIP712

Rather than implementing hashing manually, we'll use OpenZeppelin's audited implementation.

import {
    EIP712
} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";


import {
    ECDSA
} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";

Our contract now inherits:

contract OTCRegistry is EIP712 {

}

The constructor initializes the signing domain.

constructor()
    EIP712(
        "Confidential OTC Protocol",
        "1"
    )
{}

The domain separates signatures from other applications.

A signature created for our OTC protocol cannot accidentally be reused inside another application with different rules.

Hashing the Offer

EIP-712 requires two stages.

First, we hash the structured message.

Then we hash that result with the domain separator.

The final digest is what gets signed.

bytes32 private constant OFFER_TYPEHASH =
keccak256(
    "OfferMessage(address maker,address tokenOffered,address tokenRequested,uint256 amountOffered,uint256 minimumAmountRequested,uint256 expiry,uint256 nonce)"
);

The type hash describes the exact structure.

Any modification changes the resulting hash.

This prevents attackers from altering individual fields without invalidating the signature.

Why This Matters for Confidential OTC

At this point, we have an important architectural improvement.

The negotiation process no longer requires every participant to submit transactions.

A trader can:

Create an offer locally.
Sign it.
Share it privately.
Receive counterparty acceptance.
Submit only the final agreed trade.

This changes the privacy model dramatically.

The blockchain no longer observes every negotiation step.

It only verifies the final commitment.

This pattern is common in modern trading infrastructure.

The chain becomes a settlement layer rather than a communication layer.

Connecting This Back to Oasis Sapphire

This is where Oasis Sapphire becomes useful.

Sapphire allows the negotiation layer itself to become confidential while remaining EVM-compatible.

Instead of exposing signed offers and quotes publicly, sensitive state can remain inside confidential contract execution.

The architecture becomes:

flowchart LR

TraderA --> Sapphire

TraderB --> Sapphire

Sapphire --> SignedSettlement

SignedSettlement --> Base

Base --> FinalSettlement

Sapphire handles the private coordination.

Base provides transparent final settlement.

Neither chain is replacing the other.

Each handles the part it is best suited for.

Next Section

The registry now has:

structured storage,
custom errors,
event indexing,
typed signatures,
replay protection foundations.

The next step is implementing the acceptance flow.

We will build:

counterparty quote submission,
signature verification,
offer acceptance,
escrow state transitions,
settlement preparation,
and the bridge between confidential negotiation and public Base settlement.

Building the Acceptance Flow

The registry can now create offers and verify signed trade intents. However, an OTC protocol is not complete when an offer exists.

An offer represents only one side of the agreement.

The critical moment happens when another participant decides:

"I accept these terms, and I am willing to proceed toward settlement."

This transition is where many financial protocols become complicated.

A naive implementation might look like this:

function acceptOffer(uint256 offerId)
    external
{
    offers[offerId].status = OfferStatus.Accepted;
}

This appears simple, but it introduces several problems.

Who is accepting?

Can anyone accept?

Was the offer already cancelled?

Has the offer expired?

Did the counterparty actually provide the requested asset?

Can the same offer be accepted twice?

In financial infrastructure, changing a single enum value is not the operation. The operation is a state transition with strict conditions.

Our goal is to make every transition explicit.

Designing the Acceptance Lifecycle

Before writing code, let's define what acceptance actually means.

The lifecycle currently looks like:

Open
 |
 |
 v
Accepted
 |
 |
 v
Escrowed
 |
 |
 v
Settled

There are also failure paths:

Open
 |
 +----> Cancelled
 |
 +----> Expired

The important observation is that acceptance is not settlement.

This distinction matters.

A counterparty agreeing to trade does not mean assets have moved.

The protocol must first verify:

The offer still exists.
The offer is still open.
The acceptance satisfies the original conditions.
Both parties can proceed to escrow.
Settlement can happen deterministically later.

Separating these phases prevents a common class of bugs where negotiation state and asset movement become tightly coupled.

Reading Offers Safely

Before adding acceptance logic, we need a way for external applications to inspect offers.

Currently:

mapping(uint256 => Offer) private offers;

The storage is private.

This is intentional.

In a confidential environment, exposing raw storage defeats the purpose of keeping negotiation details protected.

However, applications still need controlled access.

We can create a view function.

function getOffer(uint256 offerId)
    external
    view
    returns (Offer memory)
{
    return offers[offerId];
}

This works for a public chain.

However, because our final architecture uses Oasis Sapphire for confidential negotiation, this function becomes an important design decision.

On Sapphire, the contract can expose information selectively.

The difference is subtle but important:

A public Ethereum contract assumes:

"Everything is visible unless encrypted externally."

A confidential execution environment assumes:

"The contract decides what information leaves the private state."

The same Solidity pattern behaves differently depending on where it executes.

Validating State Transitions

Let's add a helper function.

function _requireOpenOffer(
    Offer storage offer
)
    internal
    view
{
    if (offer.status != OfferStatus.Open) {
        revert OfferNotOpen();
    }

    if (block.timestamp > offer.expiry) {
        revert OfferExpired();
    }
}

This function centralizes the rules for an active offer.

Why not repeat these checks everywhere?

Because duplicated state validation creates drift.

Imagine one function checks expiry:

block.timestamp >= expiry

while another checks:

block.timestamp > expiry

That one-character difference creates inconsistent behavior.

Financial protocols should have one definition of validity.

Accepting an Offer

Now we can implement the acceptance transition.

function acceptOffer(
    uint256 offerId
)
    external
{
    Offer storage offer = offers[offerId];

    _requireOpenOffer(offer);

    offer.status = OfferStatus.Accepted;
}

The function is intentionally simple.

The complexity comes from the guarantees around it.

Before changing state, the contract proves:

the offer exists,
the offer is active,
the offer has not expired.

Only then does the transition occur.

But Who Can Accept?

This is the first major design decision.

There are several possible models.

Open Acceptance

Anyone can accept an offer.

Example:

Alice creates:

Sell:
500,000 USDC

Receive:
165 ETH

Any participant can accept.

Advantages:

simple,
permissionless,
similar to public exchange orders.

Disadvantages:

poor fit for institutional OTC,
no counterparty negotiation,
creates competition around acceptance.

Whitelisted Counterparties

The maker specifies who can accept.

Example:

Maker:
DAO Treasury

Allowed Counterparty:
Market Maker X

Advantages:

closer to institutional OTC,
predictable counterparties.

Disadvantages:

requires identity management.

Signed Acceptance

The most flexible approach is requiring both sides to sign the agreement.

The final transaction contains:

Maker Signature

+

Counterparty Signature

The contract verifies both signatures before allowing settlement.

This is the approach we will move toward.

Adding Counterparty Information

Our current Offer struct only knows the maker.

For bilateral OTC trading, we need another participant.

Update the structure:

struct Offer {

    address maker;

    address taker;

    address tokenOffered;

    address tokenRequested;

    uint256 amountOffered;

    uint256 minimumAmountRequested;

    uint256 expiry;

    uint256 nonce;

    OfferStatus status;

}

The new field:

address taker;

represents the counterparty who accepted the trade.

Before acceptance:

maker = Alice

taker = address(0)

After acceptance:

maker = Alice

taker = Bob

This gives the protocol an explicit record of both parties.

Updating Acceptance

Now acceptance records the counterparty.

function acceptOffer(
    uint256 offerId
)
    external
{
    Offer storage offer = offers[offerId];

    _requireOpenOffer(offer);

    offer.taker = msg.sender;

    offer.status = OfferStatus.Accepted;

    emit OfferAccepted(
        offerId,
        msg.sender
    );
}

The state transition is now clearer.

Before:

Open

maker:
Alice

taker:
none

After:

Accepted

maker:
Alice

taker:
Bob

The contract now knows exactly who negotiated the trade.

Adding Acceptance Events

Just like offer creation, acceptance needs an event.

event OfferAccepted(
    uint256 indexed offerId,
    address indexed taker
);

This allows external systems to react.

For example:

A backend service can listen for:

OfferAccepted

and automatically begin escrow preparation.

A frontend can update:

Status:
Accepted
Waiting for escrow

Events become the communication layer between blockchain state and applications.

Preventing Double Acceptance

Consider this sequence:

Transaction 1:
Bob accepts offer #10

Transaction 2:
Charlie accepts offer #10

Only one should succeed.

Our _requireOpenOffer check already prevents this.

After Bob's transaction:

offer.status = OfferStatus.Accepted;

The second transaction sees:

OfferStatus.Accepted

and reverts.

This is why explicit state machines are powerful.

The contract does not need complicated logic.

The state itself prevents invalid actions.

Why This Matters for Confidential OTC

At first glance, acceptance looks like a simple update.

It is not.

Acceptance is the point where private negotiation becomes a binding agreement.

In traditional OTC markets, this moment happens after:

price discovery,
counterparty verification,
risk checks,
legal confirmation.

On-chain, the smart contract replaces much of that coordination.

The contract becomes the neutral agreement layer.

With Sapphire, this process can remain confidential:

Trader A
   |
   |
Private Offer
   |
   v

Oasis Sapphire

   |
   |
Accepted Agreement
   |
   v

Base Settlement

The public chain does not need to observe every negotiation step.

It only needs proof that settlement conditions were satisfied.

Preparing for Escrow

Acceptance alone is still not enough.

A malicious counterparty could accept an offer and then disappear.

Example:

Alice:

Locks:
500,000 USDC

Bob:

Accepts trade

Then Bob never provides ETH.

The protocol must solve this problem.

The next stage introduces escrow.

We will build:

ERC-20 token transfers,
secure custody,
allowance handling,
escrow state tracking,
settlement authorization,
withdrawal rules,
failure recovery.

This is where the protocol starts becoming an actual OTC settlement system rather than a negotiation registry.

Building the Escrow Layer

The acceptance flow gives us something important.

We now have agreement.

But agreement is not settlement.

This distinction is fundamental in financial protocols.

A traditional OTC desk does not send millions of dollars simply because two traders verbally agree on a price. There is usually a custody layer, a clearing process, or a settlement mechanism that guarantees both parties perform.

Smart contracts need the same separation.

The registry answers:

"Who agreed to trade?"

The escrow contract answers:

"Are the assets actually secured?"

Only after both questions have a valid answer should settlement begin.

Why Escrow Exists

Consider a simple failure scenario.

Alice creates an offer:

Sell:
500,000 USDC

Receive:
165 ETH

Bob accepts.

The registry now contains:

status = Accepted;

But nothing forces Bob to provide ETH.

The protocol has created an agreement without enforcement.

This is the difference between:

Negotiation Layer

and:

Settlement Layer

The escrow contract connects them.

Separating Escrow From the Registry

A common beginner design is putting everything into one contract.

Something like:

contract OTCProtocol {

    createOffer()

    acceptOffer()

    deposit()

    settle()

    cancel()

}

This looks convenient.

However, it creates several problems.

The contract now handles:

offer management,
token custody,
settlement,
permissions,
refunds.

Every additional responsibility increases audit complexity.

Instead, we separate concerns.

Our architecture becomes:

                 OTCRegistry

              "What was agreed?"
                    |
                    |
                    v

                  Escrow

              "Are assets locked?"
                    |
                    |
                    v

        SettlementCoordinator

              "Execute final trade"

Each contract has one job.

Creating Escrow.sol

Inside:

src/Escrow.sol

we create our custody contract.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {
    IERC20
} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";


contract Escrow {

}

The first dependency is ERC-20 support.

The escrow contract does not care whether the token is USDC, WETH, or another asset.

It only needs the standard interface.

Modeling Escrow Positions

An escrow position represents one side of a trade.

We need to store:

who deposited,
which token,
how much,
which offer it belongs to,
current state.

Let's define it.

contract Escrow {

    enum EscrowStatus {
        Pending,
        Deposited,
        Released,
        Refunded
    }


    struct Deposit {

        address depositor;

        address token;

        uint256 amount;

        uint256 offerId;

        EscrowStatus status;

    }

}

The structure is intentionally small.

Escrow contracts should avoid unnecessary state.

Every stored variable creates another invariant that must remain correct forever.

Tracking Deposits

Now we need storage.

mapping(uint256 => Deposit) public deposits;

uint256 public depositCounter;

Each deposit receives an identifier.

Example:

Deposit #42

Offer:
#100

Depositor:
Alice

Token:
USDC

Amount:
500000

This identifier becomes useful during settlement.

Depositing Assets

Now we can implement the first important function.

function deposit(
    uint256 offerId,
    address token,
    uint256 amount
)
    external
    returns (uint256 depositId)
{

    require(
        amount > 0,
        "Invalid amount"
    );


    IERC20(token).transferFrom(
        msg.sender,
        address(this),
        amount
    );


    depositId = ++depositCounter;


    deposits[depositId] = Deposit({

        depositor: msg.sender,

        token: token,

        amount: amount,

        offerId: offerId,

        status: EscrowStatus.Deposited

    });

}

The flow is:

User approves the escrow contract.
Escrow pulls tokens using transferFrom.
A deposit record is created.
The protocol now knows assets are secured.

Why Approval Comes First

ERC-20 tokens do not allow arbitrary contracts to move funds.

The user must first approve spending.

The sequence is:

User Wallet

approve()

      |

      v

Escrow Contract

transferFrom()

      |

      v

Escrow Balance

This is standard ERC-20 behavior.

For production systems, frontends usually combine these steps into a single user experience.

The user sees:

"Deposit 500,000 USDC"

rather than manually performing approval and transfer operations.

Safe Transfer Handling

The previous example uses:

IERC20(token).transferFrom()

However, production contracts should handle tokens that do not properly return boolean values.

OpenZeppelin provides:

SafeERC20

Let's update the contract.

import {
    SafeERC20
} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";


contract Escrow {

    using SafeERC20 for IERC20;

}

Now deposits become:

IERC20(token).safeTransferFrom(
    msg.sender,
    address(this),
    amount
);

This protects against non-standard ERC-20 implementations.

Adding Events

Like the registry, escrow needs events.

event Deposited(
    uint256 indexed depositId,
    uint256 indexed offerId,
    address indexed depositor,
    address token,
    uint256 amount
);

Then after creating the deposit:

emit Deposited(
    depositId,
    offerId,
    msg.sender,
    token,
    amount
);

External systems can now monitor escrow activity.

For example:

Offer Accepted

        |

        v

Waiting for Deposits

        |

        v

Both Sides Funded

        |

        v

Settlement Ready

The Escrow Invariant

The most important property of this contract is:

Escrowed funds
=
Funds controlled by protocol rules

Users should never be able to bypass the settlement process.

After depositing:

Alice
 |
 | 500,000 USDC
 v

Escrow Contract

Alice cannot simply withdraw.

Bob cannot withdraw.

The only valid paths are:

Successful Settlement

or

Authorized Refund

This is the core security property.

Connecting Escrow to Acceptance

Right now the escrow contract does not know whether an offer was actually accepted.

That is intentional.

Remember our separation of responsibilities.

The registry knows:

Offer #100

Maker:
Alice

Taker:
Bob

Status:
Accepted

The escrow knows:

Deposit #55

Offer:
#100

Amount:
500,000 USDC

Status:
Deposited

The settlement coordinator will connect these pieces.

Introducing the Settlement Coordinator

The final architecture becomes:

                 Sapphire

              OTCRegistry

        Negotiation + Agreement


                    |

                    v


                  Escrow

          Asset Security Layer


                    |

                    v


        SettlementCoordinator

             Cross-chain Execution


                    |

                    v


                  Base

          Public Settlement

The coordinator becomes the bridge between confidential negotiation and public execution.

Why This Architecture Fits Sapphire + Base

This separation lets each network do what it does best.

Sapphire handles:

private offers,
confidential quotes,
negotiation state.

Escrow handles:

asset custody,
enforcement.

Base handles:

transparent settlement,
final ownership changes.

The protocol does not attempt to make one chain solve every problem.

Instead, it assigns responsibilities.

Next Section

The escrow layer now provides:

ERC-20 custody,
deposit tracking,
safe token transfers,
event indexing,
clear ownership boundaries.

The next part will implement the final settlement path.

We will cover:

SettlementCoordinator.sol
cross-chain settlement design
proving escrow conditions
releasing funds safely
Base integration patterns
replay protection across chains
handling failures and cancellations

This is where the complete OTC protocol architecture comes together.

Building the Settlement Coordinator

At this point, the protocol has three important capabilities.

The registry can create and accept agreements.
The escrow contract can lock assets.

What remains is the most important operation:

Moving from a private agreement into final settlement.

This is where the architecture becomes interesting.

The protocol intentionally separates:

Private negotiation

        |

        v

Verified agreement

        |

        v

Public settlement

The negotiation does not happen on Base.

The final ownership transfer does.

Why Settlement Should Be Separate

A common mistake is allowing the escrow contract to directly perform settlement.

Something like:

function settle()
external
{
    transferTokens();
}

This couples custody and execution.

The escrow contract now needs to understand:

who receives funds,
which chain settlement happens on,
whether signatures are valid,
whether external messages are trusted.

That creates unnecessary complexity.

Instead, escrow only answers:

"Are the required assets secured?"

The settlement coordinator answers:

"Should the trade execute?"

Creating SettlementCoordinator.sol

Inside:

src/SettlementCoordinator.sol

we create:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;


contract SettlementCoordinator {

}

The coordinator will eventually communicate with:

OTCRegistry

        |

        |

Escrow

        |

        |

Base Settlement Layer

Defining Settlement State

A settlement has its own lifecycle.

It is different from an offer lifecycle.

The offer lifecycle:

Open

 |

 v

Accepted

 |

 v

Escrowed

 |

 v

Settled

The settlement lifecycle:

Created

 |

 v

Verified

 |

 v

Executed

 |

 v

Completed

Let's model this.

enum SettlementStatus {

    Pending,

    Ready,

    Executed,

    Failed

}

This prevents ambiguous states.

Settlement Records

The coordinator needs to know:

which offer is being settled,
which escrow positions are involved,
who receives what,
whether execution happened.

Create the structure:

struct Settlement {

    uint256 offerId;

    uint256 makerDeposit;

    uint256 takerDeposit;

    address maker;

    address taker;

    SettlementStatus status;

}

A settlement is not an offer.

An offer describes intention.

A settlement describes execution.

Keeping those separate avoids mixing negotiation state with financial state.

Storing Settlements

mapping(uint256 => Settlement)
public settlements;


uint256 public settlementCounter;

Example:

Settlement #7

Offer:
#421


Maker:
Alice


Taker:
Bob


Maker Deposit:
USDC


Taker Deposit:
ETH


Status:
Ready

Creating a Settlement

Once both sides have escrowed funds, we create a settlement.

function createSettlement(
    uint256 offerId,
    uint256 makerDeposit,
    uint256 takerDeposit,
    address maker,
    address taker
)
external
returns(uint256 settlementId)
{

    settlementId = ++settlementCounter;


    settlements[settlementId] =
        Settlement({

            offerId: offerId,

            makerDeposit: makerDeposit,

            takerDeposit: takerDeposit,

            maker: maker,

            taker: taker,

            status: SettlementStatus.Pending

        });

}

This function does not move funds.

That is intentional.

Settlement creation is a coordination step.

Verifying Escrow Conditions

Before execution, we need proof that both sides funded the trade.

The coordinator should never trust user input.

A malicious user could attempt:

makerDeposit = fakeDepositId

The coordinator must verify directly with escrow.

The pattern becomes:

Escrow

"Is deposit X valid?"

        |

        v

SettlementCoordinator

"Proceed or reject"

Escrow Interface

Instead of importing the entire escrow contract, define a small interface.

interface IEscrow {

    function getDeposit(
        uint256 depositId
    )
    external
    view
    returns(
        address depositor,
        address token,
        uint256 amount,
        uint256 offerId,
        uint8 status
    );

}

The coordinator only knows what it needs.

This reduces coupling.

Making Settlement Ready

Now we can verify both deposits.

function markReady(
    uint256 settlementId
)
external
{

    Settlement storage settlement =
        settlements[settlementId];


    require(
        settlement.status ==
        SettlementStatus.Pending,
        "Invalid state"
    );


    settlement.status =
        SettlementStatus.Ready;

}

In production, this function would perform full escrow validation.

The simplified version demonstrates the state machine.

Executing Settlement

Execution is where assets finally move.

The coordinator instructs escrow:

Release maker asset

        +

Release taker asset

The important rule:

Both sides execute atomically.

Either:

Alice receives ETH

Bob receives USDC

or:

Nothing happens

Partial settlement is dangerous.

Atomic Settlement Pattern

A bad implementation:

releaseAliceFunds();

releaseBobFunds();

If the second operation fails:

Alice receives funds

Bob receives nothing

A production system requires transactional atomicity.

The better pattern:

function settle(
    uint256 settlementId
)
external
{

    Settlement storage settlement =
        settlements[settlementId];


    require(
        settlement.status ==
        SettlementStatus.Ready,
        "Not ready"
    );


    // execute both transfers


    settlement.status =
        SettlementStatus.Executed;

}

Because Solidity transactions revert entirely on failure, the operation is atomic.

Cross-Chain Settlement Design

Now we reach the interesting architectural question.

How does Sapphire communicate with Base?

The answer is not:

"Move the whole application to Base."

The answer is:

Create a settlement message.

The flow becomes:

Sapphire

Private Trade Agreement

        |

        v

Settlement Message

        |

        v

Base

Public Execution

The settlement message contains only what is necessary.

For example:

struct SettlementMessage {

    bytes32 tradeId;

    address receiver;

    address token;

    uint256 amount;

    uint256 nonce;

}

Notice what is missing.

No negotiation history.

No quotes.

No private strategy.

Only the information required for final execution.

Why This Matters

The privacy boundary becomes very clear.

Before settlement:

Confidential

After settlement:

Public

This mirrors traditional finance.

A hedge fund may privately negotiate a block trade.

But once settlement occurs, ownership changes become visible.

The blockchain is not replacing OTC markets.

It is improving the settlement layer.

Adding Replay Protection

Cross-chain systems introduce another risk.

A valid settlement message could potentially be submitted twice.

Example:

Message:

Pay Alice 500 ETH

Executed once.

Then replayed.

Executed again.

This is why every settlement message needs uniqueness.

The simplest mechanism:

mapping(bytes32 => bool)
processedMessages;

Before execution:

require(
    !processedMessages[id],
    "Already executed"
);

After:

processedMessages[id] = true;

One small mapping prevents catastrophic duplication.

Current Architecture

We now have:

                 Oasis Sapphire


          Confidential Negotiation


                    |

                    v


              Settlement Message


                    |

                    v


                   Base


          Transparent Final Settlement

Each layer has a clear responsibility.

Integrating Oasis Sapphire Confidential Execution

The settlement architecture is now complete.

However, we have not yet fully answered the original question:

How do we actually make OTC negotiation confidential?

So far, we have built a conventional Solidity protocol:

offers,
signatures,
escrow,
settlement coordination.

Those components work on any EVM-compatible chain.

The reason Oasis Sapphire is interesting is that it changes the privacy model of the application.

Instead of asking:

"How do we encrypt everything before putting it on-chain?"

we can ask:

"Which parts of the application should execute privately?"

That distinction is extremely important.

Public Blockchains and Information Leakage

On a traditional EVM chain, contract state is transparent.

If a contract stores:

struct Offer {

    address maker;

    address tokenOffered;

    uint256 amount;

    uint256 price;

}

then anyone can eventually inspect:

who created the offer,
what asset they want,
how much they are trading,
the conditions.

Even if the frontend hides this information, the blockchain does not.

For OTC trading, that is a problem.

The negotiation itself is valuable information.

What Sapphire Changes

Oasis Sapphire provides confidential EVM execution.

The developer experience remains familiar:

pragma solidity ^0.8.24;

contract OTCRegistry {

}

but execution happens inside a confidential environment.

Sensitive state can remain protected while the contract continues using Solidity patterns.

The important architectural shift is:

Before Sapphire:

User

 |
 |
Encrypted Data

 |
 |
Public Smart Contract

 |
 |
Everyone Observes State

After Sapphire:

User

 |
 |
Confidential Contract Execution

 |
 |
Protected State

 |
 |
Only Authorized Outputs Revealed

Moving the Registry to Sapphire

The OTC Registry is the natural candidate for Sapphire.

Why?

Because the registry contains negotiation information.

The escrow and final settlement layer do not need the same privacy guarantees.

A better architecture becomes:

                 Oasis Sapphire


          OTCRegistry

     Private Offers + Quotes


                 |

                 |

          Settlement Proof


                 |

                 |

                  Base


          Final Asset Settlement

The registry becomes the private negotiation engine.

Confidential Offer Storage

Previously we stored:

mapping(uint256 => Offer)
private offers;

On a public chain, private storage is only private by convention.

On Sapphire, confidential state is enforced by the execution environment.

This means the contract can safely maintain information such as:

struct PrivateOffer {

    address maker;

    address requestedCounterparty;

    uint256 amount;

    uint256 price;

    bytes encryptedTerms;

}

without exposing every field publicly.

Private Quotes

Institutional OTC trading rarely happens with a single offer.

Usually the process looks like:

Trader:

"I want to sell 10 million USDC."

Market makers:

"Here are three quotes."

Trader:

"I accept quote #2."

A public blockchain would reveal every quote.

That creates unnecessary information leakage.

Sapphire allows this flow:

Trader

 |
 |
Private Request

 |
 |
Sapphire Contract

 |
 |
Market Makers Submit Quotes

 |
 |
Trader Accepts Best Quote

Only the final agreement needs to leave the confidential environment.

What Sapphire Does Not Hide

It is important not to overstate confidentiality.

Sapphire does not magically make everything invisible.

The final settlement on Base is public.

Observers can see:

settlement transactions,
transferred assets,
destination addresses,
execution timing.

The privacy boundary is:

Negotiation

Private


Settlement

Public

This is exactly the same separation used in traditional OTC markets.

Confidential Signatures

Our earlier EIP-712 flow becomes even more useful here.

Instead of broadcasting every signed message:

Offer Created

Quote Received

Counter Offer

Revised Quote

the application can keep those interactions confidential.

Only the final signed commitment becomes relevant.

The protocol effectively changes from:

Every negotiation step is public

to:

Only the final agreement is verifiable

Sapphire Design Principles

When building confidential contracts, the same engineering principles still apply.

Privacy does not replace good architecture.

We still need:

explicit state machines,
replay protection,
authorization checks,
safe token handling,
deterministic settlement.

Confidential execution protects information.

It does not protect incorrect logic.

Building the SDK and Production Workflow

The smart contracts are complete.

Now we need users to interact with them.

A professional protocol rarely exposes raw contract calls directly.

Instead, applications use an SDK layer.

Our repository already contains:

sdk/

    otcClient.ts

    signer.ts

    quotes.ts

This layer handles:

wallet connections,
typed messages,
signatures,
contract calls,
settlement tracking.

Creating the SDK Client

Example:

class OTCClient {

    constructor(
        private registryContract,
        private signer
    ) {}


    async createOffer(params) {

        return this.registryContract
            .createOffer(
                params.tokenOffered,
                params.tokenRequested,
                params.amount,
                params.minimum,
                params.expiry
            );

    }

}

The frontend should not know Solidity details.

It should think in business operations:

createOffer()

acceptOffer()

deposit()

settle()

Signing Offers

The SDK also handles EIP-712.

Example:

const signature =
await signer.signTypedData(
    domain,
    types,
    offer
);

The user sees:

Sell:

500,000 USDC

Receive:

165 ETH

Expires:

Tomorrow

not:

0x83ab29ff....

Readable signatures reduce user mistakes.

Frontend Flow

A complete user journey looks like:

Trader Opens App

        |

Creates OTC Request

        |

Signs Private Intent

        |

Market Makers Submit Quotes

        |

Trader Accepts Quote

        |

Assets Escrowed

        |

Settlement Message Created

        |

Base Transaction Executed

        |

Trade Complete

Testing the Protocol

Financial protocols require more than happy-path testing.

We should test:

invalid signatures,
expired offers,
double acceptance,
failed deposits,
replayed settlement messages,
unauthorized withdrawals.

Example Foundry Test

function testCannotAcceptExpiredOffer()
    public
{

    vm.warp(block.timestamp + 2 days);


    vm.expectRevert(
        OfferExpired.selector
    );


    registry.acceptOffer(
        offerId
    );

}

The goal is not simply proving success.

The goal is proving invalid behavior is impossible.

Fuzz Testing

OTC protocols have many numeric inputs:

amounts,
timestamps,
nonces,
token quantities.

Fuzz testing helps discover unexpected edge cases.

Example:

function testAmounts(
    uint256 amount
)
public
{

    vm.assume(amount > 0);


    createOffer(amount);

}

The framework automatically explores many values.

Security Checklist

Before deploying a protocol handling valuable assets:

Access Control

Verify:

only makers cancel offers,
only accepted counterparties settle,
only authorized coordinators release escrow.

Replay Protection

Verify:

signatures cannot be reused,
settlement messages cannot execute twice,
nonces increment correctly.

State Transitions

Verify:

Invalid:

Open → Settled

Valid:

Open
 |
Accepted
 |
Escrowed
 |
Settled

Token Safety

Use:

SafeERC20,
allowance checks,
zero address validation.

Failure Recovery

Every financial protocol needs failure paths.

Examples:

expired offers,
abandoned settlements,
cancelled negotiations.

A protocol is not defined only by successful trades.

It is defined by how safely it handles failure.

Final Architecture

The completed system looks like this:

                    Trader A


                       |

                       |

              Oasis Sapphire


        Confidential OTC Registry

        - Private Offers

        - Private Quotes

        - Signed Agreements


                       |

                       |

              Settlement Message


                       |

                       |

                    Base


        Public Settlement Layer

        - Asset Transfer

        - Final Ownership


                       |

                       |

                    Trader B

Conclusion

Large trades require different infrastructure from ordinary swaps.

Automated market makers are excellent for transparent liquidity.

They are not designed for confidential institutional negotiation.

An OTC protocol needs a different approach.

The architecture we built separates the problem into three layers:

Confidential Negotiation

Handled by Oasis Sapphire.

This protects sensitive trading information while preserving smart contract coordination.

Asset Security

Handled through escrow.

This ensures both parties commit funds before execution.

Public Settlement

Handled by Base.

This provides transparent final ownership transfer.

The result is not a replacement for decentralized exchanges.

It is a complementary system designed for a different class of trading.

Large financial transactions require both privacy and trust minimization.

Confidential execution provides the privacy.

Smart contracts provide the enforcement.

Public settlement provides the transparency.

Together, they create a practical foundation for the next generation of decentralized OTC trading systems.

Building a Confidential Cross-Chain Identity Protocol with Oasis Sapphire, ENS & Base

rayQu — Thu, 16 Jul 2026 07:15:44 +0000

The biggest paradox in Web3 identity is that while we demand privacy in the real world, our on-chain infrastructure defaults to absolute transparency. If you attach a KYC credential, credit score, or real name to your ENS domain, it is immediately indexable by anyone.

But what if you could store your sensitive Personally Identifiable Information (PII) inside a secure enclave, and only expose cryptographic proofs of that data to smart contracts on other chains?

In this advanced tutorial, we are building a Confidential Cross-Chain Identity Layer. We will use Oasis Sapphire (the first confidential EVM) as our secure vault, Base (Ethereum L2) as our execution environment, and the Oasis Privacy Layer (OPL) via Celer IM to bridge the two.

The Real-World Use Case: Compliant DeFi on Base

Imagine a DeFi lending protocol on Base that requires users to be non-US citizens and over 18 to access leverage.

The Problem: Storing "Country" and "Date of Birth" directly on Base violates privacy and data protection laws (like GDPR).
The Solution: The user mints an ENS name (alice.base.eth) on Base. They store their private KYC data in a smart contract on Oasis Sapphire. When the Base DeFi protocol queries the ENS resolver, the resolver triggers a cross-chain message via OPL to Sapphire. Sapphire computes the logic inside a Trusted Execution Environment (TEE), checking if age > 18 && country != US, and returns a simple true or false back to Base.

No PII is ever leaked, the public RPCs see nothing but ciphertext, and the DeFi protocol remains fully compliant.

Architecture & Interaction Flow

We will utilize EIP-3668 (CCIP-Read) for off-chain data resolution and Celer Inter-Chain Messaging (IM) for state synchronization between Base and Sapphire.

sequenceDiagram
    participant User
    participant DeFi as Base DeFi Protocol
    participant Resolver as Base ENS Resolver
    participant Relayer as Celer IM / OPL
    participant Sapphire as Oasis Sapphire (TEE)

    User->>Sapphire: 1. Encrypt & Store KYC (Age, Country)
    Note over Sapphire: State is encrypted end-to-end
    User->>DeFi: 2. Request Undercollateralized Loan
    DeFi->>Resolver: 3. Verify compliance for `alice.base.eth`
    Resolver->>Relayer: 4. Dispatch Cross-Chain Request
    Relayer->>Sapphire: 5. Execute query inside TEE
    Sapphire-->>Sapphire: 6. Decrypt -> Check logic -> Re-encrypt
    Sapphire->>Relayer: 7. Emit boolean compliance proof
    Relayer->>Resolver: 8. CCIP-Read Callback with Proof
    Resolver-->>DeFi: 9. Returns `true` (Compliant)
    DeFi-->>User: 10. Loan Approved

Repository Structure

For this advanced stack, we will use a monorepo built with Hardhat/Foundry to manage multi-chain deployments.

cross-chain-identity/
├── contracts/
│   ├── base/
│   │   ├── ENSIdentityResolver.sol     # Custom ENS Resolver on Base
│   │   └── IDeFiProtocol.sol           # Mock DeFi contract
│   ├── sapphire/
│   │   ├── ConfidentialVault.sol       # TEE-encrypted storage contract
│   │   └── VerificationEngine.sol      # Logic computation 
│   └── interfaces/
│       ├── ICelerMessageBus.sol        # Celer IM interface
│       └── IOasisPrivacyLayer.sol
├── scripts/
│   ├── deploy-base.js
│   ├── deploy-sapphire.js
│   └── bridge-setup.js
├── hardhat.config.js                   # Configured for Base & Sapphire networks
└── package.json

Step-by-Step Implementation

Step 1: The Confidential Vault on Oasis Sapphire
Oasis Sapphire is EVM-compatible but runs inside secure enclaves. State variables are encrypted by default. We will write ConfidentialVault.sol to store user data securely.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@oasisprotocol/sapphire-contracts/contracts/Sapphire.sol";

contract ConfidentialVault {
    // This state is encrypted inside the Sapphire TEE
    struct IdentityRecord {
        uint256 dateOfBirth;
        string countryCode;
        bool isVerified;
    }

    mapping(address => IdentityRecord) private privateIdentities;

    // Address of the Celer Message Bus on Sapphire
    address public messageBus;

    constructor(address _messageBus) {
        messageBus = _messageBus;
    }

    /**
     * @dev User updates their private data. Transactions are end-to-end encrypted.
     */
    function updateIdentity(uint256 _dob, string calldata _countryCode) external {
        privateIdentities[msg.sender] = IdentityRecord({
            dateOfBirth: _dob,
            countryCode: _countryCode,
            isVerified: true
        });
    }

    /**
     * @dev Executed via cross-chain message from Base.
     * Computes compliance without revealing raw data.
     */
    function verifyComplianceCrossChain(address _user, address _baseCallbackContract) external {
        require(msg.sender == messageBus, "Only Relayer");

        IdentityRecord memory record = privateIdentities[_user];

        // Confidential computation: Is over 18 and not US?
        bool isCompliant = false;
        if (record.isVerified) {
            uint256 age = (block.timestamp - record.dateOfBirth) / 31556926; // Approx years
            if (age >= 18 && keccak256(bytes(record.countryCode)) != keccak256(bytes("US"))) {
                isCompliant = true;
            }
        }

        // Construct payload to send back to Base
        bytes memory message = abi.encode(_user, isCompliant);

        // Send via Celer IM (Oasis Privacy Layer) back to Base
        // (Pseudocode for Celer IM integration)
        ICelerMessageBus(messageBus).sendMessage(
            _baseCallbackContract,
            8453, // Base Mainnet Chain ID
            message
        );
    }
}

Note: Because Sapphire encrypts calldata, an observer on block explorers will only see gibberish bytes, completely protecting the user's DoB and Country.

Step 2: The Cross-Chain ENS Resolver on Base
On Base, our custom ENS Resolver implements executeWithCCIPRead to pause execution, request data from Sapphire, and resume via a callback once Celer IM delivers the result.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import "@ensdomains/ens-contracts/contracts/resolvers/PublicResolver.sol";

contract ENSIdentityResolver {
    address public messageBus;
    address public sapphireVaultAddress;

    mapping(address => bool) public complianceCache;

    error OffchainLookup(address sender, string[] urls, bytes callData, bytes4 callbackFunction, bytes extraData);

    constructor(address _messageBus, address _sapphireVaultAddress) {
        messageBus = _messageBus;
        sapphireVaultAddress = _sapphireVaultAddress;
    }

    /**
     * @dev Standard check called by DeFi protocols on Base.
     */
    function isUserCompliant(address _user) external view returns (bool) {
        // If not in cache, trigger CCIP-Read / Cross-chain flow
        if (!complianceCache[_user]) {
            string[] memory urls = new string[](1);
            urls[0] = "[https://our-relayer-gateway.io/verify/](https://our-relayer-gateway.io/verify/){sender}/{data}";

            revert OffchainLookup(
                address(this),
                urls,
                abi.encodePacked(_user),
                this.celfCallback.selector,
                abi.encode(_user)
            );
        }
        return complianceCache[_user];
    }

    /**
     * @dev Callback executed by Celer Executor once Sapphire computes the result.
     */
    function executeMessage(
        address _srcContract,
        uint64 _srcChainId,
        bytes calldata _message,
        address _executor
    ) external payable returns (uint256) {
        require(msg.sender == messageBus, "Only Celer Message Bus");
        require(_srcChainId == 23294, "Only Sapphire Mainnet"); // Sapphire Chain ID
        require(_srcContract == sapphireVaultAddress, "Invalid source contract");

        (address user, bool isCompliant) = abi.decode(_message, (address, bool));

        // Cache the confidential state on Base
        complianceCache[user] = isCompliant;

        return 1;
    }
}

Step 3: Hardhat Deployment & Orchestration
To deploy this, your hardhat.config.js needs RPC endpoints for both networks. Oasis Sapphire provides standard Web3 RPC endpoints, making the developer experience seamless.

module.exports = {
  solidity: "0.8.19",
  networks: {
    base: {
      url: "[https://mainnet.base.org](https://mainnet.base.org)",
      accounts: [process.env.PRIVATE_KEY]
    },
    sapphire: {
      url: "[https://sapphire.oasis.io](https://sapphire.oasis.io)",
      chainId: 23294,
      accounts: [process.env.PRIVATE_KEY]
    }
  }
};

When integrating the frontend, use the @oasisprotocol/sapphire-paratime wrapper for Ethers.js. This automatically encrypts your transactions on the client side before sending them to the Sapphire network.

import { ethers } from "ethers";
import * as sapphire from "@oasisprotocol/sapphire-paratime";

// Wrap your standard signer to enable end-to-end encryption
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = sapphire.wrap(provider.getSigner());

// Now call the vault; the calldata will be automatically encrypted!
const vaultContract = new ethers.Contract(VAULT_ADDR, VAULT_ABI, signer);
await vaultContract.updateIdentity(946684800, "UK");

Step 4: Building the CCIP-Read Off-Chain Gateway (Node.js)
When the Base contract reverts with OffchainLookup, the user's wallet (or the dApp frontend) will automatically send an HTTP GET request to the URL specified in the revert. We need an Express server to catch this, trigger the Celer IM message to Sapphire, and manage the asynchronous state.

// server.js (Gateway)
const express = require('express');
const { ethers } = require('ethers');

const app = express();
app.use(express.json());

app.get('/verify/:sender/:data', async (req, res) => {
    const { sender, data } = req.params;

    try {
        // Decode the user address from the original call data
        const decodedUser = ethers.utils.defaultAbiCoder.decode(['address'], data)[0];

        // 1. Trigger the cross-chain message on the Relayer/Sapphire side
        // In a production environment, this triggers a relayer bot to pay gas on Sapphire
        await dispatchToSapphire(decodedUser);

        // 2. We return a pending state or an acknowledgment 
        // Note: Because Celer IM is asynchronous, the Base contract will receive 
        // the actual boolean value from the Celer Executor in a subsequent block.
        res.status(200).json({
            status: "pending_cross_chain_execution",
            message: "Celer IM dispatched to Oasis Sapphire. Await callback on Base."
        });

    } catch (error) {
        res.status(500).json({ error: error.message });
    }
});

app.listen(3000, () => console.log('CCIP-Read Gateway running on port 3000'));

Step 5: Gas Abstraction (Zero-Gas UX on Sapphire)
A major UX hurdle in cross-chain architectures is forcing the user to hold the native gas token (ROSE) on Oasis Sapphire just to update their identity.

To solve this, we can implement the Oasis Gas Station Network (GSN) or a custom Paymaster. Because Sapphire supports EIP-4337 (Account Abstraction) and standard meta-transactions, you can set up a Gas Relayer. The user signs an EIP-712 message containing their encrypted KYC data, and your backend submits it to Sapphire, paying the ROSE gas fee on their behalf. The user only ever needs ETH on Base.

Step 6: Security & Threat Model
When dealing with cross-chain PII, the threat model extends beyond standard smart contract bugs:

State Desyncs: If a user updates their age on Sapphire but the Base cache isn't refreshed, the Base DeFi protocol might operate on stale data. Always implement a Time-to-Live (TTL) or an expiration timestamp on the complianceCache mapping on Base.
Replay Attacks: Ensure the Celer IM callback (executeMessage) strictly verifies _srcChainId and _srcContract. If an attacker can spoof the message origin, they can arbitrarily set their complianceCache to true on Base.
TEE Side-Channels: While Sapphire's Secure Enclaves (Intel SGX) protect data in use, developers must ensure they do not leak data via access patterns. Avoid writing logic that significantly changes gas consumption based on the value of a private variable.

Conclusion

By combining ENS on Base with the Oasis Privacy Layer, we've built a robust architecture that solves Web3's biggest compliance hurdle. Smart contracts on L2s can now leverage confidential logic, request attestations, and maintain composability without doxxing their users.

The future of Web3 identity isn't fully transparent, nor is it siloed in isolated private chains. The future is modular, cross-chain, and selectively private.

If you found this advanced tutorial helpful, leave a comment below or check out the Oasis Privacy Layer Documentation to dive deeper into confidential smart contracts!

Building a Confidential Data Clean Room on Oasis Sapphire: Privacy-Preserving Analytics Across Organizations

rayQu — Sat, 13 Jun 2026 17:27:40 +0000

One of the biggest unsolved problems in data engineering is collaboration between organizations that do not trust each other enough to share raw data.

Consider the following scenarios:

Two crypto exchanges want to identify overlapping fraudulent wallets.
Multiple banks want to detect coordinated money laundering activity.
Healthcare providers want to compare patient cohorts for research.
Marketing companies want to measure customer overlap.
Cybersecurity firms want to identify shared threat actors.

In all of these cases, the organizations would benefit from collaboration.

The problem is that they cannot expose their underlying datasets.

Traditional solutions usually involve:

Trusted third parties
Secure legal agreements
Data escrow providers
Multi-party computation frameworks
Internal clean room infrastructure

These solutions are expensive, operationally complex, and often difficult to audit.

This is where Oasis Sapphire, once again (:p), becomes interesting.

Instead of sharing raw data, organizations can:

Encrypt datasets locally
Submit encrypted data to Sapphire
Execute confidential computations
Receive aggregated results
Never expose the underlying records

In this tutorial we will build a complete confidential data clean room that allows multiple organizations to compare datasets without revealing them. I will also answer any comments/dms I'm going to get as soon as possible!

We will cover:

Architecture design
Confidential smart contracts
Dataset encryption
Secure submissions
Set intersection algorithms
Similarity metrics
Differential privacy
Attestation concepts
Production deployment considerations

By the end, you will have a system capable of performing privacy-preserving analytics across organizations.

The Problem

Suppose Exchange A maintains a list of suspicious wallets:

0x111...
0x222...
0x333...
0x444...

Exchange B maintains its own list:

0x333...
0x444...
0x555...
0x666...

Both exchanges want to know:

How many suspicious wallets do we have in common?

A traditional approach would require both exchanges to reveal their full datasets.

This creates multiple risks:

Customer privacy violations
Regulatory concerns
Competitive intelligence leakage
Data retention obligations

The clean room model allows the question to be answered without exposing the datasets themselves.

The final output becomes:

{
  "overlap": 2
}

Nothing else is revealed.

High-Level Architecture
                Exchange A
                     |
                     |
            Encrypt Dataset
                     |
                     v

          +------------------+
          | Oasis Sapphire   |
          | Confidential     |
          | Data Clean Room  |
          +------------------+

                     ^
                     |
            Encrypt Dataset
                     |
                     |

                Exchange B

                     |
                     v

              Aggregated Result

               overlap = 2

The critical observation is that raw data never leaves the confidential execution boundary in plaintext.

Project Structure
sapphire-clean-room/

├── contracts/
│   ├── CleanRoom.sol
│   ├── SimilarityEngine.sol
│
├── scripts/
│   ├── deploy.ts
│
├── worker/
│   ├── encryptDataset.ts
│   ├── submitDataset.ts
│
├── api/
│   ├── server.ts
│
├── datasets/
│   ├── exchangeA.csv
│   ├── exchangeB.csv
│
├── test/
│   ├── cleanRoom.test.ts
│
└── hardhat.config.ts

Understanding Data Clean Rooms

A data clean room is a controlled environment where:

Data providers submit information
Computations occur
Raw data remains hidden
Only approved outputs leave the environment

Traditionally, cloud providers offer clean room services.

The challenge is trust.

Organizations must trust:

Infrastructure operators
Database administrators
Cloud providers

Sapphire introduces a different trust model.

The computation occurs inside confidential execution environments backed by Trusted Execution Environments (TEEs).

This means computation is isolated from the host system itself.

Step 1: Dataset Registration Contract

We begin by allowing organizations to register encrypted datasets.

pragma solidity ^0.8.20;

contract CleanRoom {

    struct Dataset {
        bytes encryptedData;
        address owner;
        uint256 submittedAt;
        bool active;
    }

    uint256 public datasetCount;

    mapping(uint256 => Dataset) public datasets;

    event DatasetSubmitted(
        uint256 indexed datasetId,
        address indexed owner
    );

    function submitDataset(
        bytes calldata encryptedData
    ) external {

        datasetCount++;

        datasets[datasetCount] = Dataset({
            encryptedData: encryptedData,
            owner: msg.sender,
            submittedAt: block.timestamp,
            active: true
        });

        emit DatasetSubmitted(
            datasetCount,
            msg.sender
        );
    }
}

This contract stores encrypted payloads only.
The blockchain never sees plaintext records.

Why Encryption Alone Is Not Enough

A common misconception is:

"Just encrypt the data and store it on-chain."

Encryption protects storage.

It does not solve computation.

Eventually somebody must decrypt and process the data.

The real challenge is:

How do we compute on sensitive information without exposing it?

That is where Sapphire enters the picture.

Step 2: Confidential Set Intersection

The most common clean room operation is set intersection.

We want:

A ∩ B without revealing A or B.

Inside Sapphire we can safely decrypt datasets and perform the operation.

pragma solidity ^0.8.20;

contract SimilarityEngine {

    function computeIntersection(
        address[] memory a,
        address[] memory b
    )
        public
        pure
        returns (uint256)
    {
        uint256 overlap;

        for (uint256 i = 0; i < a.length; i++) {

            for (uint256 j = 0; j < b.length; j++) {

                if (a[i] == b[j]) {
                    overlap++;
                }
            }
        }

        return overlap;
    }
}

This implementation is intentionally simple. We will optimize it later.

Why This Naive Approach Does Not Scale

Suppose:

Dataset A = 100,000 entries
Dataset B = 100,000 entries

Complexity becomes:

100,000 × 100,000 = 10 billion comparisons

This is not practical. We need better data structures.

Step 3: Hash-Based Intersection

Instead of nested loops we build lookup tables.

function computeIntersectionFast(
    bytes32[] memory a,
    bytes32[] memory b
)
    public
    pure
    returns (uint256)
{
    uint256 overlap;

    for (uint256 i = 0; i < a.length; i++) {

        for (uint256 j = 0; j < b.length; j++) {

            if (a[i] == b[j]) {
                overlap++;
            }
        }
    }

    return overlap;
}

In production, off-chain preprocessing should convert datasets into hashed representations.

Benefits include:

Smaller payloads
Better privacy
Faster matching
Similarity Metrics

Sometimes overlap counts are insufficient.

Organizations may want similarity scores.

A common metric is Jaccard Similarity.

The formula is:

Jaccard Similarity = Number of Shared Records / Total Unique Records

Interpretation:

0.0 = completely different
1.0 = identical datasets

Implementing Jaccard Similarity
function computeJaccard(
    uint256 intersection,
    uint256 unionSize
)
    public
    pure
    returns (uint256)
{
    return (intersection * 1e18) / unionSize;
}

Returning scaled values avoids floating-point arithmetic.

Step 4: Local Dataset Encryption

Before submission, organizations encrypt locally.

Example Node.js utility:

import crypto from "crypto";

const algorithm = "aes-256-gcm";

export function encryptDataset(
  plaintext: string,
  key: Buffer
) {

  const iv = crypto.randomBytes(16);

  const cipher =
    crypto.createCipheriv(
      algorithm,
      key,
      iv
    );

  let encrypted =
    cipher.update(
      plaintext,
      "utf8",
      "hex"
    );

  encrypted += cipher.final("hex");

  const tag =
    cipher.getAuthTag();

  return {
    iv: iv.toString("hex"),
    encrypted,
    tag: tag.toString("hex")
  };
}

Encryption occurs before data leaves the organization.

Step 5: Submission Worker

import { ethers } from "ethers";

async function submitDataset() {

  const contract =
    new ethers.Contract(
      CONTRACT_ADDRESS,
      ABI,
      signer
    );

  const encrypted =
    await encryptDataset(
      dataset,
      key
    );

  const tx =
    await contract.submitDataset(
      ethers.toUtf8Bytes(
        JSON.stringify(encrypted)
      )
    );

  await tx.wait();
}

This worker becomes the ingestion pipeline.

Differential Privacy Layer

Even aggregate results can leak information.

Example:

Dataset overlap: 1245

Repeated queries could allow reconstruction attacks.

To mitigate this, we can introduce controlled noise.

function addNoise(
    uint256 value,
    uint256 noise
)
    internal
    pure
    returns (uint256)
{
    return value + noise;
}

Result:

Actual overlap: 1245
Reported overlap: 1242

Privacy improves while preserving utility.

Multi-Party Data Clean Rooms

The real power appears when more than two organizations participate.

Exchange A
Exchange B
Exchange C
Exchange D

        |
        v

   Sapphire Clean Room

        |
        v

  Aggregated Analysis

Examples:

Shared fraud detection
Shared sanctions monitoring
Shared AML screening
Shared cybersecurity intelligence
Production Security Considerations
Dataset Poisoning

An attacker may submit fabricated data.

Mitigations:

Staking requirements
Dataset signatures
Reputation systems
Replay Attacks

An attacker may repeatedly submit old datasets.

Mitigations:

mapping(bytes32 => bool)
public processedHashes;

Reject duplicates.

Query Abuse

Attackers may repeatedly request computations.

Mitigations:

Rate limiting
Access control
Usage quotas
Membership Inference Attacks

An attacker may attempt to infer whether a specific record exists.

Mitigations:

Differential privacy
Minimum cohort sizes
Query restrictions
Future Extensions

This architecture can evolve into:

Confidential AML Network
Banks privately compare suspicious entities.
Cross-Exchange Fraud Detection
Exchanges identify shared attackers.
Healthcare Research Network
Hospitals compare patient cohorts without sharing records.
Privacy-Preserving Advertising Analytics
Companies measure audience overlap.
Confidential Supply Chain Intelligence
Manufacturers compare supplier data without exposing relationships.

Conclusion

Most blockchain applications focus on moving value.

Far fewer explore moving information safely.

Confidential data clean rooms represent a massive opportunity because they solve a real-world problem that organizations face every day:

How can we collaborate on data without exposing the data itself?

Oasis Sapphire provides a powerful foundation for this model by combining smart contracts with confidential execution.

Instead of choosing between privacy and computation, we can finally have both.

The result is a new class of applications where organizations can learn from each other without surrendering control of their most valuable asset: their data.

Building a Confidential Event-Driven Indexer on Oasis Sapphire (Beyond The Graph Pattern)

rayQu — Thu, 11 Jun 2026 07:18:56 +0000

Most blockchain indexing systems today assume a very simple model:

all blockchain data is public, and indexing is just a deterministic transformation of public events.

This assumption works well for analytics platforms like dashboards, DEX trackers, or portfolio tools.

However, it breaks down in real-world scenarios where:

event data is sensitive (wallet behavior, internal flows, private classifications)
indexing logic itself is proprietary (risk models, scoring systems, compliance logic)
or you need selective disclosure (some users can see more data than others)

In traditional architectures, you are forced to choose between:

transparency (but no privacy)
privacy (but no verifiability)

Oasis Sapphire introduces a third option:

execute indexing logic inside a confidential runtime (TEE-backed), while still using standard EVM interfaces.

This tutorial builds a confidential event-driven indexer, where:

raw blockchain events remain public
classification logic is hidden
only sanitized outputs are exposed externally

Think of it as:

“The Graph, but the mapping function is private and policy-controlled.”

Why This Is Architecturally Different

To understand why this matters, let's compare the standard indexing pipeline:

Traditional Indexing (The Graph-style)

Smart Contract -> Events -> Indexer -> Public Database -> API

Everything is:

deterministic
reproducible
fully observable

This is great for trustlessness, but it creates problems:

any adversary can reconstruct your analytics logic
wallet behavior is fully exposed
proprietary scoring models cannot exist

Confidential Indexing (Oasis Sapphire model)

Smart Contract -> Events
                     ↓
        Sapphire Confidential Runtime
                     ↓
          Private State Transformation
                     ↓
         Offchain Worker + Storage
                     ↓
            Sanitized Public API

Key difference:

The transformation function (indexing logic) is no longer public.

Real-World Use Case

We will build a confidential DeFi activity indexer that:

tracks swaps on a DEX
computes internal risk scores
classifies activity (low / medium / high risk)
hides wallet-level behavior
exposes only aggregated metrics

This is useful for:

institutional compliance dashboards
private DeFi analytics platforms
MEV-aware monitoring systems
regulated crypto infrastructure

Why Not Just Use Existing Indexers?

Existing solutions like The Graph or custom ETL pipelines have a fundamental limitation:

they cannot hide the transformation logic itself.

Even if you obfuscate the backend:

input events are public
transformations are reproducible
reverse-engineering is trivial

With Sapphire:

logic executes in a TEE (Trusted Execution Environment)
computation is not externally observable
only final outputs are revealed

Project Structure (Production-Grade)

confidential-indexer/
│
├── contracts/
│   ├── Dex.sol
│   ├── ConfidentialIndexer.sol
│   ├── interfaces/
│
├── worker/
│   ├── indexer.ts
│   ├── eventDecoder.ts
│   ├── riskEngine.ts
│   ├── db.ts
│
├── api/
│   ├── server.ts
│   ├── routes/
│
├── scripts/
│   ├── deploy.ts
│
├── test/
│   ├── indexer.test.ts
│
└── hardhat.config.ts

Step 1: Event Source Contract (DEX Simulation)

We start with a simple decentralized exchange emitting swap events.

This is intentionally minimal, the complexity happens in the indexing layer.

// contracts/Dex.sol
pragma solidity ^0.8.20;

contract Dex {

    event Swap(
        address indexed user,
        address indexed tokenIn,
        address indexed tokenOut,
        uint256 amount,
        uint256 timestamp
    );

    function swap(
        address tokenIn,
        address tokenOut,
        uint256 amount
    ) external {
        emit Swap(
            msg.sender,
            tokenIn,
            tokenOut,
            amount,
            block.timestamp
        );
    }
}

Key idea:

We deliberately include structured data so the indexer can apply richer classification logic.

Step 2: Confidential Indexer Contract (Sapphire Core Logic)

This is the core of the system.

Key properties:

runs inside Sapphire confidential runtime
decrypts event payloads
applies private scoring rules
stores encrypted internal state

// contracts/ConfidentialIndexer.sol
pragma solidity ^0.8.20;

import "@oasisprotocol/sapphire-contracts/contracts/Sapphire.sol";

contract ConfidentialIndexer {

    struct SwapData {
        address user;
        address tokenIn;
        address tokenOut;
        uint256 amount;
        uint256 timestamp;
    }

    struct PoolState {
        uint256 riskScore;
        uint256 volume;
    }

    mapping(bytes32 => PoolState) private pools;

    event Indexed(bytes32 indexed poolId, uint256 riskScore, uint256 volume);

    function processSwap(bytes calldata encryptedSwap) external {

        // Step 1: decrypt inside TEE
        bytes memory decrypted = Sapphire.decrypt(encryptedSwap);

        SwapData memory data = abi.decode(decrypted, (SwapData));

        // Step 2: derive pool identifier
        bytes32 poolId = keccak256(
            abi.encodePacked(data.tokenIn, data.tokenOut)
        );

        // Step 3: update private state
        PoolState storage state = pools[poolId];

        state.volume += data.amount;

        uint256 risk = computeRisk(data, state);

        state.riskScore = risk;

        // Step 4: emit only sanitized output
        emit Indexed(poolId, state.riskScore, state.volume);
    }

    function computeRisk(
        SwapData memory data,
        PoolState memory state
    )
        internal
        pure
        returns (uint256)
    {
        uint256 score = 0;

        // Large trade heuristic
        if (data.amount > 1_000_000 ether) {
            score += 5;
        }

        // Volume spike heuristic
        if (state.volume > 10_000_000 ether) {
            score += 3;
        }

        return score;
    }
}

Why this is important:

The key innovation is:

the risk model is never observable externally

That means:

adversaries cannot game your scoring system
analytics logic is not reproducible
you can build proprietary indexers

Step 3: Event Worker (Offchain Index Aggregator)

This component listens to Sapphire outputs and stores them.

Unlike traditional indexers, it does NOT compute logic, only stores results.

// worker/indexer.ts
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);

const contract = new ethers.Contract(
  process.env.CONTRACT_ADDRESS,
  ABI,
  provider
);

contract.on("Indexed", async (poolId, riskScore, volume) => {

  console.log("Indexed update received");

  await db.upsert({
    poolId: poolId.toString(),
    riskScore: riskScore.toString(),
    volume: volume.toString(),
    updatedAt: Date.now()
  });
});

Step 4: Public API Layer (Sanitized Exposure)

This layer ensures no raw or sensitive data leaks.

// api/server.ts
import express from "express";
const app = express();

app.get("/pool/:id", async (req, res) => {

  const pool = await db.get(req.params.id);

  res.json({
    pool: req.params.id,
    riskScore: pool.riskScore,
    volume: pool.volume,

    // intentionally no user-level data exposed
    granularity: "aggregated"
  });
});

app.listen(3000);

Key Design Insight: Privacy Boundary Model

This architecture introduces a strict separation:

Layer	Visibility
Smart contract events	Public
Sapphire execution logic	Confidential
Risk model / heuristics	Hidden
Aggregated outputs	Public (sanitized)

Hard Engineering Problems (Important Section)

1. Determinism vs Confidential Execution

TEE environments must remain deterministic:

same input -> same output
but without revealing internal computation steps

2. Trust in Index Correctness

Because computation is hidden:

you rely on enclave guarantees
or multi-worker validation systems

3. Composability Limitations

Unlike The Graph:

results are not universally reproducible
external contracts cannot verify raw computation

4. State Replay Problem

Encrypted state introduces challenges:

historical recomputation is non-trivial
debugging requires replay tooling inside TEE

Why This Matters

This pattern enables a new category of systems:

private blockchain analytics
institutional DeFi infrastructure
MEV-resistant monitoring tools
compliance-aware data pipelines

It shifts the paradigm from:

“everything is transparent and verifiable”

to:

“computation is verifiable, but not necessarily observable”

Final Thoughts

Most blockchain infrastructure assumes transparency is always beneficial.

But in real systems, especially financial and institutional contexts:

privacy is required
analytics are proprietary
and data exposure is a liability

Oasis Sapphire enables a third design space:

verifiable execution with confidential logic

This indexer pattern is just one example of what becomes possible when indexing itself becomes programmable and private.

Building a Verifiable Multi-Chain AI Execution Layer with Oasis ROFL + Sapphire + TDX

rayQu — Thu, 21 May 2026 07:02:11 +0000

Most AI on blockchain applications today still rely heavily on trust.

The AI inference happens on centralized servers.
The wallet keys live in backend infrastructure.
Smart contracts trust APIs blindly.
And users have no way to verify what actually happened off-chain.

In this tutorial, we’ll build something far more advanced:

A verifiable confidential AI execution layer using:

Oasis Sapphire
ROFL (Runtime Offchain Logic)
Intel TDX Trusted Execution Environments
Remote Attestation
Enclave-managed wallet signing
Cross-chain transaction execution

This architecture enables:

Private AI inference
Verifiable off-chain execution
Secure enclave wallet management
Cross-chain automation
Trust-minimized AI agents

Without needing zkML or expensive zkVM proving systems.

What We’re Building

+---------------------------------------------------+
|                 User / dApp                       |
+--------------------+------------------------------+
                     |
                     v
+---------------------------------------------------+
|          Sapphire Smart Contract                  |
|---------------------------------------------------|
| - Stores trusted ROFL identities                  |
| - Verifies enclave signatures                     |
| - Accepts/verifies AI execution results           |
+--------------------+------------------------------+
                     ^
                     |
             Signed attested result
                     |
+---------------------------------------------------+
|          ROFL App Inside Intel TDX                |
|---------------------------------------------------|
| - Runs AI inference                               |
| - Calls APIs                                      |
| - Generates wallet keys internally                |
| - Signs responses                                 |
| - Performs remote attestation                     |
+--------------------+------------------------------+
                     |
                     v
         External APIs / Other Chains / LLMs

Why This Matters

Most AI agents today suffer from major trust issues.

| Problem                       | Why It Matters                    |
| ------------------------------------------------------------------|                                                              
| Centralized inference         | Outputs can be manipulated        |
| Backend wallet custody        | Keys can be stolen                |
| Hidden execution logic        | Impossible to audit               |
| Fake oracle data              | Contracts trust unverifiable APIs |
| Cross-chain trust assumptions | Bridges increase attack surface   |

ROFL changes this entirely.

Instead of trusting a backend server:

computation runs inside a Trusted Execution Environment
outputs are cryptographically signed
enclave identities are attested
smart contracts verify execution authenticity

This creates trustless off-chain compute.

Core Technologies

Sapphire

Sapphire is Oasis Network’s confidential EVM runtime.

Features:

encrypted calldata
encrypted state
confidential smart contract execution
Solidity/EVM compatibility

Unlike traditional EVM chains, node operators cannot inspect execution data.

ROFL (Runtime Offchain Logic)

ROFL allows developers to run arbitrary off-chain logic inside TEEs.

This means your application can:

call APIs
run AI models
sign transactions
manage secrets
execute autonomous workflows

while remaining cryptographically verifiable.

Intel TDX

Intel TDX provides confidential virtual machines with:

encrypted memory
hardware isolation
attestation support
strong execution guarantees

ROFL supports TDX-backed confidential compute environments.

Architecture Deep Dive

        User Prompt
              |
              v
+-----------------------------------+
|      Sapphire Smart Contract      |
+-----------------------------------+
              |
              v
+-----------------------------------+
|       ROFL TDX Enclave            |
|-----------------------------------|
| 1. Receives encrypted request     |
| 2. Runs AI inference              |
| 3. Generates signed result        |
| 4. Signs with enclave wallet      |
+-----------------------------------+
              |
              v
      Cross-chain execution
              |
              v
     Ethereum / Base / Arbitrum

Step 1: Install Oasis CLI

curl -sSL https://get.oasis.io | bash

Verify installation:

oasis --version

Step 2: Create a ROFL Application

mkdir ai-executor
cd ai-executor

oasis rofl init

This generates:

rofl.yaml

The manifest defines:

enclave configuration
TEE type
networking
policies
deployment settings

Step 3: Configure ROFL Manifest

Example advanced configuration:

name: ai-executor
version: 0.1.0

tee: tdx
kind: containers

resources:
  memory: 8192
  cpus: 4

network:
  paratime: sapphire

policy:
  quotes:
    pcs:
      tdx: {}

container:
  runtime: docker

Important Manifest Settings

| Field       |    Purpose                     |
| ------------|--------------------------------|                                
| tee         | TEE backend (SGX/TDX)          |
| kind        | Raw or containerized workloads |
| resources   | Enclave memory + CPU           |
| network     | Connected ParaTime             |
| policy      | Attestation requirements       |

Step 4: Build the Enclave

oasis rofl build

This generates an ORC bundle:

my-app.orc

The bundle includes:

enclave measurements
metadata
binaries
identity hashes

Step 5: Generate Wallet Keys Inside the Enclave

This is one of the most powerful features.

Traditional AI agents store keys:

in .env files
in cloud KMS systems
in backend infrastructure

Instead:

Wallet Key Generated INSIDE TEE
        ↓
Key Never Leaves Enclave
        ↓
Transactions Signed Securely

No backend custody required.

Example Rust Wallet Generation

use k256::ecdsa::SigningKey;
use rand_core::OsRng;

fn generate_wallet() -> SigningKey {
    SigningKey::random(&mut OsRng)
}

The private key only exists inside enclave memory.

Step 6: Run AI Inference Securely

Example inference service:

from transformers import pipeline

classifier = pipeline(
    "text-classification",
    model="distilbert-base-uncased"
)

result = classifier("Execute strategy?")
print(result)

Inside ROFL:

prompts remain confidential
inference is hidden from operators
outputs are signed by the enclave

Secure AI Execution Flow

User Prompt
    ↓
ROFL Enclave
    ↓
Private AI Inference
    ↓
Signed Output
    ↓
Sapphire Verification

Step 7: Remote Attestation

Attestation proves:

“This exact code executed inside genuine TDX hardware.”

Without attestation:

TEEs are just claims

With attestation:

contracts can verify enclave authenticity

Attestation Flow

ROFL App Starts
      ↓
TEE Generates Measurement
      ↓
Attestation Quote Produced
      ↓
Quote Registered On-Chain
      ↓
Sapphire Verifies Identity

Step 8: Register the ROFL App

Create the application:

oasis rofl create \
  --network testnet \
  --paratime sapphire

Deploy updates:

oasis rofl update

This stores:

enclave identities
measurements
execution policy
attestation configuration

on-chain.

Step 9: Smart Contract Verification

Now we create a Sapphire contract that verifies:

enclave identity
signatures
trusted execution

Solidity Verification Contract

pragma solidity ^0.8.20;

contract VerifiedAIExecutor {

    mapping(bytes32 => bool) public trustedEnclaves;

    function registerEnclave(bytes32 enclaveId) external {
        trustedEnclaves[enclaveId] = true;
    }

    function verifyExecution(
        bytes32 enclaveId,
        bytes calldata signature,
        bytes calldata result
    ) external view returns (bool) {

        require(trustedEnclaves[enclaveId], "Untrusted enclave");

        // Signature verification logic
        return true;
    }
}

Step 10: Cross-Chain Transaction Execution

This is where things become extremely powerful.

The enclave can:

manage Ethereum wallets
sign Base transactions
execute Arbitrum transactions
interact with multiple chains

without bridges.

Cross-Chain Execution Flow

AI Strategy Generated
        ↓
TEE Decides Action
        ↓
TEE Signs Transaction
        ↓
Broadcast To Ethereum RPC
        ↓
Result Returned To Sapphire

This enables:

autonomous trading systems
AI treasury management
confidential DAO executors
secure cross-chain agents

Step 11: Deterministic Execution Logging

AI outputs are often nondeterministic.

To improve auditability:

hash prompts
hash outputs
hash model versions

Example:

let hash = sha256(prompt + model_version + output);

Then store:

output hash
enclave ID
timestamp

on-chain.

Security Considerations

TEEs are powerful but not perfect.

Potential risks:

side-channel attacks
hardware trust assumptions
speculative execution vulnerabilities

Still, TEEs provide dramatically stronger guarantees than centralized servers.

Why This Architecture Is Important

Traditional AI systems rely on:

trusted cloud providers
centralized APIs
backend custody

ROFL + Sapphire introduces:

Traditional Backend	ROFL + Sapphire
Centralized inference	TEE-attested inference
Backend wallet storage	Enclave-managed keys
Hidden execution	Verifiable execution
API trust assumptions	Hardware-backed trust
Centralized orchestration	Permissionless infrastructure

Real-World Use Cases

Verifiable AI Trading Agents

The enclave:

runs private strategies
signs trades
proves execution authenticity

Confidential Healthcare AI

patient data remains private
inference occurs inside TEEs
outputs become auditable

Autonomous DAO Executors

AI agents:

propose governance actions
execute treasury operations
prove execution legitimacy

Multi-Chain AI Wallet Infrastructure

One enclave can securely control:

Ethereum
Base
Arbitrum
future ecosystems

without custodial bridges.

The Bigger Picture

ROFL introduces something Web3 desperately needs:

Trustless Off-Chain Compute

Not:

“another oracle”
“another AI chain”

But:

verifiable computation
confidential execution
autonomous infrastructure

This creates a new primitive between:

smart contracts
AI infrastructure
confidential computing
cross-chain orchestration

Final Thoughts

Most AI + blockchain systems today still require enormous trust assumptions.

With:

Sapphire
ROFL
TDX
attestation
enclave-managed wallets

developers can finally build systems where:

computation is private
outputs are verifiable
execution is cryptographically authenticated

This unlocks:

autonomous AI agents
confidential DeFi automation
verifiable off-chain compute
secure cross-chain execution
trusted AI infrastructure

And this is likely only the beginning of what confidential compute on Oasis can enable.

Resources

Building a Confidential AI RAG Agent on Oasis Sapphire + ROFL

rayQu — Tue, 12 May 2026 08:42:31 +0000

An advanced Oasis Network tutorial for developers who want to combine AI, confidential smart contracts, encrypted vector storage, and verifiable off-chain execution.

Introduction

Most AI applications today leak sensitive data somewhere in the pipeline.

Even if the frontend is secure, prompts, embeddings, retrieval context, API calls, or inference metadata are usually visible to:

Cloud providers
Backend operators
Database administrators
Analytics tools
Infrastructure vendors

This becomes a serious issue for:

Financial AI assistants
Healthcare copilots
Private enterprise knowledge bases
Identity systems
Reputation engines
On-chain AI agents

In this tutorial, we will build a Confidential Retrieval-Augmented Generation (RAG) Agent using:

Oasis Sapphire
ROFL (Runtime Off-chain Logic)
Encrypted storage
Smart contracts
Off-chain AI inference
Verifiable confidential execution

Instead of storing prompts or embeddings publicly, we will:

Encrypt user knowledge before storage
Perform confidential retrieval
Execute AI inference off-chain through ROFL
Return only approved outputs on-chain
Keep sensitive data hidden from everyone except the user

What We Are Building

We are building a confidential AI assistant where:

Users upload private documents
Documents are encrypted before storage
Embeddings are generated off-chain
Retrieval happens confidentially
AI inference runs through ROFL
Smart contracts manage permissions and integrity

The architecture combines:

Confidential EVM execution
Off-chain compute
AI pipelines
Privacy-preserving storage
Ethereum compatibility

Final Architecture

flowchart TD
    A[User Uploads Document] --> B[Frontend Encrypts Data]
    B --> C[IPFS / Arweave Storage]
    B --> D[Oasis Sapphire Contract]

    D --> E[ROFL Worker]
    E --> F[Embedding Model]
    F --> G[Encrypted Vector Store]

    H[User Query] --> I[Confidential Retrieval]
    I --> G

    G --> J[Relevant Context]
    J --> K[LLM Inference]
    K --> L[Signed Response]
    L --> D

    D --> M[Verified Output Returned]

Why Sapphire Matters

Traditional EVM chains expose:

Contract state
Function arguments
Internal logic
Metadata
User activity

Sapphire changes this model by introducing confidential smart contracts.

This allows developers to:

Encrypt application state
Generate secrets securely
Store confidential metadata
Protect AI prompts
Hide retrieval logic
Secure wallet-based identity systems

Unlike “privacy through frontend encryption,” Sapphire provides confidentiality at the runtime layer.

Why ROFL Matters

Large AI models cannot realistically run fully on-chain.

Inference requires:

GPUs
External APIs
Heavy compute
Vector databases
Long-running processes

ROFL enables:

Off-chain execution
Trusted compute
Verifiable outputs
Secure communication with Sapphire

Think of ROFL as a confidential execution bridge between:

Smart contracts
AI systems
External infrastructure

Tech Stack

Layer	Technology
Smart Contracts	Solidity + Sapphire
Off-chain Compute	ROFL
Storage	IPFS / Arweave
AI Embeddings	Sentence Transformers
Vector Search	ChromaDB / Qdrant
Frontend	Next.js
Wallet	RainbowKit + Wagmi
Encryption	AES-GCM
AI Inference	OpenAI / Local LLM

Step 1: Setting Up Sapphire

Create a new project:

mkdir confidential-rag-agent
cd confidential-rag-agent
npm init -y

Install dependencies:

npm install hardhat ethers dotenv

Initialize Hardhat:

npx hardhat

Add Sapphire configuration:

require('@oasisprotocol/sapphire-hardhat');

module.exports = {
  solidity: '0.8.20',
  networks: {
    sapphire: {
      url: 'https://testnet.sapphire.oasis.io',
      chainId: 23295,
      accounts: [process.env.PRIVATE_KEY]
    }
  }
}

Step 2: Creating the Confidential Contract

Our contract will:

Store encrypted metadata
Register AI responses
Verify ROFL signatures
Manage access permissions

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract ConfidentialRAG {

    struct Document {
        string cid;
        bytes encryptedKey;
        address owner;
    }

    mapping(uint256 => Document) public documents;

    uint256 public docCounter;

    event DocumentStored(uint256 indexed id, address owner);

    function storeDocument(
        string memory cid,
        bytes memory encryptedKey
    ) external {

        documents[docCounter] = Document({
            cid: cid,
            encryptedKey: encryptedKey,
            owner: msg.sender
        });

        emit DocumentStored(docCounter, msg.sender);

        docCounter++;
    }
}

Step 3: Encrypting User Data

Never upload raw user data directly.

Instead:

Generate a local encryption key
Encrypt the document client-side
Upload encrypted data to IPFS
Store only references on Sapphire

Architecture:

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant I as IPFS
    participant S as Sapphire

    U->>F: Upload document
    F->>F: Generate AES key
    F->>F: Encrypt document
    F->>I: Upload encrypted file
    I-->>F: CID
    F->>S: Store CID + encrypted key

Example encryption:

const encrypted = await encryptFile(file, secretKey)

Step 4: Generating Embeddings Through ROFL

We now process the encrypted content off-chain.

ROFL workers can:

Fetch encrypted files
Decrypt securely
Generate embeddings
Store vectors
Return signed proofs

ROFL Flow:

flowchart LR
    A[Sapphire Event] --> B[ROFL Worker]
    B --> C[Decrypt File]
    C --> D[Generate Embeddings]
    D --> E[Vector Database]
    E --> F[Signed Result]
    F --> G[Sapphire Contract]

Example Python embedding pipeline:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer('all-MiniLM-L6-v2')

embedding = model.encode(document_text)

Step 5: Confidential Retrieval

When a user asks a question:

Query embedding is generated
Similar vectors are retrieved
Relevant context is assembled
Context stays encrypted/private
LLM receives only authorized information

This prevents:

Prompt leakage
Public retrieval inspection
Competitor scraping
Metadata deanonymization

Step 6: AI Inference Layer

The inference engine can use:

OpenAI APIs
Local Llama models
Mistral
DeepSeek
Confidential GPU infrastructure

Prompt assembly example:

prompt = f"""
Context:
{retrieved_context}

Question:
{user_question}
"""

Step 7: Returning Verifiable Results

ROFL signs outputs before returning them.

The contract verifies:

Authorized worker
Valid signature
Fresh timestamp
Integrity proof

This creates a verifiable AI pipeline.

Security Design

Our architecture protects against:

Threat	Mitigation
Public prompt leakage	Sapphire confidentiality
Storage snooping	Client-side encryption
Vector DB exposure	Encrypted embeddings
Fake AI outputs	ROFL signatures
Metadata correlation	Confidential execution
Frontend compromise	Wallet authorization

Is this Architecture good?

Most Web3 AI projects today are not truly private.

They usually:

Store prompts publicly
Leak retrieval context
Expose embeddings
Depend entirely on centralized APIs

Oasis enables something different:

Confidential AI infrastructure.

That is a much bigger opportunity than simple “AI on blockchain” narratives. So yes, this is huge.

Improvements (!)

You can extend this architecture with:

Multi-Agent Systems

Use multiple ROFL workers for:

Retrieval
Ranking
Moderation
Inference
Verification

zkML Integration

Combine:

ROFL confidentiality
ZK proofs
Verifiable inference

Token-Gated Knowledge Access

Require NFT or token ownership before retrieval.

Cross-Chain Identity

Use confidential reputation scores across:

Ethereum
Base
Arbitrum
Solana

Potential Real-World Use Cases

Industry	Use Case
Healthcare	Private medical copilots
Finance	Confidential portfolio AI
Gaming	Hidden strategy agents
Enterprise	Secure internal knowledge AI
DAOs	Private governance research
Identity	Confidential trust scoring

Performance Considerations

AI systems are expensive.

Optimize:

Embedding caching
Batched retrieval
Async inference
Vector compression
Partial encryption
Event indexing

Avoid pushing unnecessary data on-chain.

The blockchain should coordinate trust, not store entire AI workloads.

Common Mistakes Developers Make

Storing Raw AI Data On-Chain

Never store:

Prompts
Embeddings
Conversations
User documents

Directly on public chains.

Treating Frontend Encryption as Enough

Frontend-only privacy still exposes backend operators.

Ignoring Metadata Privacy

Even transaction patterns can reveal sensitive information.

Production Architecture

flowchart TB
    subgraph User Layer
        A[Wallet User]
        B[Next.js Frontend]
    end

    subgraph Confidential Layer
        C[Sapphire Smart Contract]
        D[ROFL Workers]
    end

    subgraph AI Layer
        E[Embedding Models]
        F[LLM Inference]
        G[Vector Database]
    end

    subgraph Storage Layer
        H[IPFS]
        I[Arweave]
    end

    A --> B
    B --> C
    B --> H
    C --> D
    D --> E
    D --> F
    D --> G
    H --> D
    I --> D

Closingg Thoughts

The next generation of AI applications will not be won by the teams with the biggest models.

They will be won by the teams that solve:

Privacy
Data ownership
Confidential computation
Verifiable inference
User-controlled AI

Oasis Sapphire and ROFL provide a powerful foundation for building that future.

Instead of thinking about blockchain as "where data lives". think about it as a trust coordination layer for confidential AI systems.

That shift changes everything.

Useful Resources

Oasis Network

Ethereum / Smart Contract Development

Decentralized Storage

AI / Vector Databases

Frontend / Wallet Integration

Security / Cryptography

Building a Transparent Crypto Donation Ledger with Oasis Network (Beginner Tutorial)

rayQu — Mon, 20 Apr 2026 07:52:23 +0000

Crypto donations are great for transparency… until your donors open a block explorer and see a wall of hashes.

In this tutorial, we’ll build a simple, verifiable donation ledger using Oasis Network, a blockchain that lets you combine privacy + transparency using confidential smart contracts.

What we’re building

A minimal system where:

Donations are recorded on-chain
Expenses are recorded and linked to donations
Anyone can see totals and categories (public)
Sensitive details stay private but provable

Why Oasis?

With Oasis Sapphire (its confidential EVM):

You write Solidity like Ethereum
But contract state can be encrypted
You can expose only what matters (e.g. totals)

Docs: https://docs.oasis.io
Sapphire: https://oasis.net/sapphire

Step 1: Setup your environment

You can use Hardhat like a normal EVM chain:

mkdir oasis-ledger && cd oasis-ledger
npm init -y
npm install --save-dev hardhat
npx hardhat

Add Oasis Sapphire testnet config:

module.exports = {
  networks: {
    sapphire: {
      url: "https://testnet.sapphire.oasis.io",
      accounts: [PRIVATE_KEY]
    }
  },
  solidity: "0.8.20"
};

Step 2: Write the smart contract

Create DonationLedger.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract DonationLedger {

    struct Donation {
        address donor;
        uint amount;
    }

    struct Expense {
        uint amount;
        string category;
    }

    Donation[] public donations;
    Expense[] public expenses;

    uint public totalDonations;
    uint public totalSpent;

    function donate() external payable {
        donations.push(Donation(msg.sender, msg.value));
        totalDonations += msg.value;
    }

    function addExpense(uint _amount, string memory _category) external {
        expenses.push(Expense(_amount, _category));
        totalSpent += _amount;
    }

    function getBalance() public view returns (uint) {
        return totalDonations - totalSpent;
    }
}

This is intentionally simple:

Fully transparent totals
Expand later with private metadata (Oasis advantage)

Step 3: Deploy to Oasis Sapphire

Create a deploy script:

async function main() {
  const Ledger = await ethers.getContractFactory("DonationLedger");
  const ledger = await Ledger.deploy();

  await ledger.waitForDeployment();

  console.log("Deployed to:", await ledger.getAddress());
}

main();

Run:

npx hardhat run scripts/deploy.js --network sapphire

Step 4: Interact with the contract

Example (Hardhat console):

npx hardhat console --network sapphire

const ledger = await ethers.getContractAt("DonationLedger", "DEPLOYED_ADDRESS");

// donate
await ledger.donate({ value: ethers.parseEther("0.1") });

// add expense
await ledger.addExpense(ethers.parseEther("0.05"), "food");

// check totals
await ledger.totalDonations();
await ledger.totalSpent();

Step 5: Build a simple frontend (optional)

Even a basic UI can transform usability:

Show:
- Total donations
- Total spent
- Remaining balance
Add buttons:
- “Donate”
- “Add Expense” (admin)

You can use:

Next.js
ethers.js
wagmi

Step 6: Where Oasis shines (upgrade idea)

Right now everything is public.

With Oasis, you can:

Store private expense metadata (e.g. invoice hashes)
Keep donor notes confidential
Reveal only:
- totals
- categories
- proofs

This is done using confidential state inside Sapphire contracts.

Final result

Instead of showing donors this:

“Here’s our wallet, go check Etherscan”

You show them:

€100k raised
€40k spent on food
€20k spent on shelter

And every number is still verifiable on-chain

Takeaway

Using Oasis, you can build:

Transparent donation systems
Clean public dashboards
Private but provable accounting

All without leaving the EVM ecosystem.

DEV Community: rayQu

Building a Confidential Bug Bounty Platform with Oasis Sapphire

Building a Confidential Bug Bounty Platform with Oasis Sapphire

An advanced tutorial on private vulnerability reports, confidential triage, and verifiable bounty payouts

1. Architecture: Separate the Report from Its Proof

2. Define the Submission Lifecycle

3. Project Structure

4. Model the Report Carefully

5. Commit to the Report Without Publishing It

6. Enforce Bounty Rules with Versioned Policies

7. Keep Triage Confidential, but Make It Accountable

8. A Safer Disclosure Workflow

9. Threat Model

10. What Makes This Useful Beyond Bug Bounties?

Conclusion

Resources

Build a Private Onchain Feedback Box with Oasis Sapphire

What We're Building

1. Create the Project

2. Configure Sapphire

3. Write the Feedback Contract

4. Why private Matters Differently Here

5. Don't Accidentally Publish the Feedback

6. Add a Simple Deployment Script

7. Submit Private Feedback

8. Reading the Statistics

9. What About getMyFeedback()?

10. A Minimal Test

11. One Important Production Improvement

12. Why This Pattern Is Interesting

Public information

Private information

Final Architecture

What You Can Build From Here

Resources

Building a Confidential On-Chain Credit Underwriting Engine with Oasis Sapphire + ROFL

1. The Problem

2. What We Are Building

3. Why ROFL + Sapphire?

Sapphire

ROFL

4. Threat Model

Blockchain observers

ROFL host/operator

Application users

Our own frontend

5. What We Are NOT Protecting

6. Repository Structure

7. The Confidential Contract

8. Don't Store a "Global Score"

9. The Feature Pipeline

10. The Risk Model

11. Keeping the Policy Confidential

12. Why Not Just Use a Server?

13. Reading Base from ROFL

14. Building the Underwriting Worker

15. Never Let a Stale Risk Decision Live Forever

16. Model Versioning

17. A Better Architecture

18. Confidential Events

19. Don't Encrypt Everything

20. Authorization Is More Important Than Encryption

21. The Credit Controller

22. What Happens When the User Is Rejected?

23. Replay Protection

24. Failure Handling

25. The Full Lifecycle

26. Testing the System

27. Testing the Risk Engine Independently

28. What If the ROFL Application Is Compromised?

29. Private Policy, Public Bounds

30. What Can Be Publicly Audited?

Public integrity

Private computation

Public safety envelope

31. Adding an Audit Manifest

32. Why This Is More Interesting Than a Private Database

33. Where This Architecture Could Be Used

Private insurance underwriting

Institutional DeFi

4. Why `private` Matters Differently Here

9. What About `getMyFeedback()`?