Decrypt to View

Use decryptForView to reveal a confidential (encrypted) value locally in your app so you can display it in the UI. Unlike decryptForTx, this flow does not return an onchain-verifiable signature, and it is not meant to be published onchain.

Flow

Read the encrypted handle (ctHash) from your contract.
Ensure you have an ACP that authorizes decryption of that value.
Call decryptForView(ctHash, utype).execute() to get the plaintext.

decryptForView always decrypts using an ACP (there is no .withoutACP() mode). If your protocol intends for the plaintext to become publicly visible onchain, use decryptForTx instead.

Prerequisites

Create and connect a client.
Know the encrypted handle (ctHash) and the encrypted type (utype).
Have a ACP available for the connected chainId + account.

Getting ctHash: In most apps, ctHash comes from reading a stored encrypted value, an event arg, or a return value from a view call.

Providing utype: utype must match the ciphertext’s underlying FHE type. The SDK uses it to convert the decrypted bigint into a convenient JS type.Supported utypes:

FheTypes.Bool to returns a boolean
FheTypes.Uint160 (address) to returns a checksummed 0x... string
FheTypes.Uint8 | Uint16 | Uint32 | Uint64 | Uint128 to returns a bigint

ACP setup

If you don’t have an ACP yet, create one once after connecting:

await client.connect(publicClient, walletClient);

// Creates an ACP if needed, stores it, and selects it as the active ACP.
await client.acp.getOrCreateSelfACP();

Decrypt for UI

Choose the pattern that matches how your app manages ACPs:

await client.connect(publicClient, walletClient);
await client.acp.getOrCreateSelfACP();

const plaintext = await client
  .decryptForView(ctHash, FheTypes.Uint32)
  .execute();

const acp = await client.acp.getOrCreateSelfACP();

const plaintext = await client
  .decryptForView(ctHash, FheTypes.Uint64)
  .withACP(acp)
  .execute();

const plaintext = await client
  .decryptForView(ctHash, FheTypes.Uint8)
  .withACP(acpHash)
  .execute();

What `decryptForView` returns

Running .execute() resolves to a scalar JS value:

Integer utypes (Uint8, Uint16, Uint32, Uint64, Uint128): a bigint
FheTypes.Bool: a boolean
FheTypes.Uint160 (address): a checksummed 0x... address string

Builder API

`.execute()` (required, call last)

Runs the decryption and returns a UI-friendly scalar value.

`.withACP(...)` (optional)

Select which ACP to use:

.withACP(): uses the active ACP
.withACP(acpHash): fetches a stored ACP by hash
.withACP(acp): uses the provided ACP object

If you don’t call .withACP(...), the active ACP is used by default.

`.setAccount(address)` (optional)

Overrides the account used to resolve the active/stored ACP.

`.setChainId(chainId)` (optional)

Overrides the chain used to resolve the Teecryptor URL and ACPs.

`.onPoll(callback)` (optional)

Register a callback that fires once per poll attempt while decryptForView waits for Teecryptor to return the sealed plaintext. Useful for surfacing decrypt progress in a UI.

const plaintext = await client
  .decryptForView(ctHash, FheTypes.Uint64)
  .onPoll(({ operation, requestId, attemptIndex, elapsedMs, intervalMs, timeoutMs }) => {
    console.log(`[${operation}] attempt ${attemptIndex} after ${elapsedMs}ms (next in ${intervalMs}ms, budget ${timeoutMs}ms)`);
  })
  .execute();

The callback receives:

Field	Type	Description
`operation`	`'decrypt' \| 'sealoutput'`	Which decryption flow is polling. For `decryptForView` this is `'sealoutput'`.
`requestId`	`string`	The Teecryptor request id. May be the empty string during submit-time retries, see `.set404RetryTimeout(...)` below.
`attemptIndex`	`number`	Zero-based poll attempt counter.
`elapsedMs`	`number`	Time since the first submit attempt.
`intervalMs`	`number`	Delay until the next poll.
`timeoutMs`	`number`	Overall budget shared by submit-retries and status-polling.

`.set404RetryTimeout(timeoutMs)` (optional)

Configures how long decryptForView keeps retrying when Teecryptor’s submit endpoint responds with 404 Not Found before a requestId is available. This typically happens on slower backends where the ciphertext isn’t visible yet at submit time. Defaults to 10_000 ms.

const plaintext = await client
  .decryptForView(ctHash, FheTypes.Uint32)
  .set404RetryTimeout(20_000) // give a slower backend more time
  .execute();

Pass 0 to disable submit-time retries (404 becomes a hard failure). Submit retries share the same overall timeout budget as status polling.

Common UI patterns

import { formatUnits } from 'viem';

const decimals = 6;
const display = formatUnits(amount, decimals);

const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
const asNumber = amount <= MAX_SAFE ? Number(amount) : undefined;

const statusLabel = decryptedIsAllowed ? 'Allowed' : 'Not allowed';
const shortOwner = `${decryptedOwner.slice(0, 6)}…${decryptedOwner.slice(-4)}`;

Common pitfalls

Missing ACP: decryptForView will fail if there is no active ACP for the current chainId + account.
Wrong utype: you must pass the correct FHE type for the ciphertext.
Wrong chain/account: ACPs are scoped to chainId + account. If the user switches wallets or networks, create/select the correct ACP.

Introduction

Quick Start

Guides

Hardhat Plugin

Hardhat 3 Plugin

Foundry Plugin

Examples

Reference

Flow

Prerequisites

ACP setup

Decrypt for UI

What `decryptForView` returns

Builder API

`.execute()` (required, call last)

`.withACP(...)` (optional)

`.setAccount(address)` (optional)

`.setChainId(chainId)` (optional)

`.onPoll(callback)` (optional)

`.set404RetryTimeout(timeoutMs)` (optional)

Common UI patterns

Common pitfalls

​Flow

​Prerequisites

​ACP setup

​Decrypt for UI

​What decryptForView returns

​Builder API

​.execute() (required, call last)

​.withACP(...) (optional)

​.setAccount(address) (optional)

​.setChainId(chainId) (optional)

​.onPoll(callback) (optional)

​.set404RetryTimeout(timeoutMs) (optional)

​Common UI patterns

​Common pitfalls

Flow

Prerequisites

ACP setup

Decrypt for UI

What `decryptForView` returns

Builder API

`.execute()` (required, call last)

`.withACP(...)` (optional)

`.setAccount(address)` (optional)

`.setChainId(chainId)` (optional)

`.onPoll(callback)` (optional)

`.set404RetryTimeout(timeoutMs)` (optional)

Common UI patterns

Common pitfalls