flows

cifer-sdk API Reference v0.3.1

---

cifer-sdk API Reference / flows

flows

High-level orchestrated flows for common operations.

Remarks

Flows combine multiple primitives into complete operations and support two modes:

• Plan mode: Returns a plan with steps that would be executed
• Execute mode: Executes the flow using provided callbacks

Interfaces

CreateSecretResult

Defined in: flows/create-secret.ts:27

Result of createSecretAndWaitReady flow

Properties

secretId

secretId: bigint

Defined in: flows/create-secret.ts:29

The new secret ID

state

state: SecretState

Defined in: flows/create-secret.ts:31

The final secret state

---

RetrieveAndDecryptParams

Defined in: flows/decrypt-from-logs.ts:24

Parameters for retrieve-and-decrypt flow

Properties

secretId

secretId: bigint

Defined in: flows/decrypt-from-logs.ts:26

Secret ID used for encryption

dataId

dataId: `0x${string}`

Defined in: flows/decrypt-from-logs.ts:28

Data ID to retrieve

commitmentContract

commitmentContract: `0x${string}`

Defined in: flows/decrypt-from-logs.ts:30

Contract address where the commitment is stored

storedAtBlock?

optional storedAtBlock: number

Defined in: flows/decrypt-from-logs.ts:32

Block number where the data was stored (optional - fetched if not provided)

skipIntegrityCheck?

optional skipIntegrityCheck: boolean

Defined in: flows/decrypt-from-logs.ts:34

Skip integrity verification (default: false)

---

RetrieveAndDecryptResult

Defined in: flows/decrypt-from-logs.ts:40

Result of retrieveFromLogsThenDecrypt flow

Properties

decryptedMessage

decryptedMessage: string

Defined in: flows/decrypt-from-logs.ts:42

The decrypted plaintext

secretId

secretId: bigint

Defined in: flows/decrypt-from-logs.ts:44

The secret ID used

storedAtBlock

storedAtBlock: number

Defined in: flows/decrypt-from-logs.ts:46

Block where the commitment was stored

---

EncryptThenCommitParams

Defined in: flows/encrypt-commit.ts:24

Parameters for encrypt-then-commit flow

Properties

secretId

secretId: bigint

Defined in: flows/encrypt-commit.ts:26

Secret ID to use for encryption

plaintext

plaintext: string

Defined in: flows/encrypt-commit.ts:28

The plaintext to encrypt

key

key: `0x${string}`

Defined in: flows/encrypt-commit.ts:30

Key for the commitment (bytes32)

commitmentContract

commitmentContract: `0x${string}`

Defined in: flows/encrypt-commit.ts:32

Contract address for storing the commitment

storeFunction?

optional storeFunction: AbiFunction

Defined in: flows/encrypt-commit.ts:34

Store function ABI (optional - uses default if not provided)

---

EncryptThenCommitResult

Defined in: flows/encrypt-commit.ts:40

Result of encryptThenPrepareCommitTx flow

Properties

cifer

cifer: `0x${string}`

Defined in: flows/encrypt-commit.ts:42

The CIFER envelope

encryptedMessage

encryptedMessage: `0x${string}`

Defined in: flows/encrypt-commit.ts:44

The encrypted message

txIntent

txIntent: TxIntentWithMeta

Defined in: flows/encrypt-commit.ts:46

The prepared transaction intent

---

EncryptFileFlowParams

Defined in: flows/file-jobs.ts:25

Parameters for file encryption flow

Properties

secretId

secretId: bigint

Defined in: flows/file-jobs.ts:27

Secret ID to use for encryption

file

file: Blob | File

Defined in: flows/file-jobs.ts:29

The file to encrypt

---

EncryptFileFlowResult

Defined in: flows/file-jobs.ts:35

Result of file encryption flow

Properties

jobId

jobId: string

Defined in: flows/file-jobs.ts:37

The job ID

job

job: JobInfo

Defined in: flows/file-jobs.ts:39

Final job status

encryptedFile

encryptedFile: Blob

Defined in: flows/file-jobs.ts:41

The encrypted file blob

---

DecryptFileFlowParams

Defined in: flows/file-jobs.ts:181

Parameters for file decryption flow

Properties

secretId

secretId: bigint

Defined in: flows/file-jobs.ts:183

Secret ID used for encryption

file

file: Blob | File

Defined in: flows/file-jobs.ts:185

The encrypted .cifer file

---

DecryptFileFlowResult

Defined in: flows/file-jobs.ts:191

Result of file decryption flow

Properties

jobId

jobId: string

Defined in: flows/file-jobs.ts:193

The job ID

job

job: JobInfo

Defined in: flows/file-jobs.ts:195

Final job status

decryptedFile

decryptedFile: Blob

Defined in: flows/file-jobs.ts:197

The decrypted file blob

---

DecryptExistingFileFlowParams

Defined in: flows/file-jobs.ts:341

Parameters for decrypting from an existing encrypt job

Properties

secretId

secretId: bigint

Defined in: flows/file-jobs.ts:343

Secret ID used for the original encryption

encryptJobId

encryptJobId: string

Defined in: flows/file-jobs.ts:345

Job ID of the completed encrypt job

---

FlowStep

Defined in: flows/types.ts:24

A single step in a flow

Properties

id

id: string

Defined in: flows/types.ts:26

Step identifier

description

description: string

Defined in: flows/types.ts:28

Human-readable description

type

type: "transaction" | "api_call" | "poll" | "read" | "compute"

Defined in: flows/types.ts:30

Step type

status

status: StepStatus

Defined in: flows/types.ts:32

Current status

txIntent?

optional txIntent: TxIntent

Defined in: flows/types.ts:34

Transaction intent (for transaction steps)

result?

optional result: unknown

Defined in: flows/types.ts:36

Result data (after completion)

error?

optional error: Error

Defined in: flows/types.ts:38

Error (if failed)

---

FlowPlan

Defined in: flows/types.ts:44

Flow plan returned in plan mode

Properties

name

name: string

Defined in: flows/types.ts:46

Flow name

description

description: string

Defined in: flows/types.ts:48

Human-readable description

steps

steps: FlowStep[]

Defined in: flows/types.ts:50

Ordered list of steps

estimatedDurationMs?

optional estimatedDurationMs: number

Defined in: flows/types.ts:52

Estimated total duration (if known)

---

PollingStrategy

Defined in: flows/types.ts:58

Polling strategy configuration

Properties

intervalMs

intervalMs: number

Defined in: flows/types.ts:60

Interval between polls in milliseconds

maxAttempts

maxAttempts: number

Defined in: flows/types.ts:62

Maximum number of polling attempts

backoffMultiplier?

optional backoffMultiplier: number

Defined in: flows/types.ts:64

Backoff multiplier (default: 1 = no backoff)

maxIntervalMs?

optional maxIntervalMs: number

Defined in: flows/types.ts:66

Maximum interval (for exponential backoff)

---

FlowContext

Defined in: flows/types.ts:81

Flow context with all dependencies and callbacks

Properties

signer

signer: SignerAdapter

Defined in: flows/types.ts:83

Signer for authentication

readClient

readClient: ReadClient

Defined in: flows/types.ts:85

Read client for blockchain queries

blackboxUrl

blackboxUrl: string

Defined in: flows/types.ts:87

Blackbox URL

chainId

chainId: number

Defined in: flows/types.ts:89

Chain ID

controllerAddress?

optional controllerAddress: `0x${string}`

Defined in: flows/types.ts:91

SecretsController address (optional - can be resolved from discovery)

txExecutor?

optional txExecutor: TxExecutor

Defined in: flows/types.ts:101

Transaction executor callback

Apps provide this to execute transaction intents. The SDK doesn't handle gas estimation or nonce management.

pollingStrategy?

optional pollingStrategy: PollingStrategy

Defined in: flows/types.ts:106

Polling strategy for operations that require waiting

logger()?

optional logger: (message) => void

Defined in: flows/types.ts:111

Logger for progress updates

Parameters

message

string

Returns

void

abortSignal?

optional abortSignal: AbortSignal

Defined in: flows/types.ts:116

Abort signal for cancellation

fetch()?

optional fetch: (input, init?) => Promise<Response>

Defined in: flows/types.ts:121

Custom fetch implementation

MDN Reference

Parameters

input

RequestInfo | URL

init?

RequestInit

Returns

Promise<Response>

---

FlowOptions

Defined in: flows/types.ts:127

Options for flow execution

Properties

mode?

optional mode: FlowMode

Defined in: flows/types.ts:133

Execution mode

• 'plan': Return a plan without executing
• 'execute': Execute the flow (requires txExecutor)

onStepProgress()?

optional onStepProgress: (step) => void

Defined in: flows/types.ts:138

Callback for step progress updates

Parameters

step

FlowStep

Returns

void

---

FlowResult

Defined in: flows/types.ts:144

Flow execution result

Type Parameters

T

T

Properties

success

success: boolean

Defined in: flows/types.ts:146

Whether the flow completed successfully

plan

plan: FlowPlan

Defined in: flows/types.ts:148

The flow plan (steps that were/would be executed)

data?

optional data: T

Defined in: flows/types.ts:150

Result data (if successful)

error?

optional error: Error

Defined in: flows/types.ts:152

Error (if failed)

receipts?

optional receipts: TransactionReceipt[]

Defined in: flows/types.ts:154

Transaction receipts (for flows that submit transactions)

Type Aliases

FlowMode

FlowMode = "plan" | "execute"

Defined in: flows/types.ts:14

Flow execution mode

---

StepStatus

StepStatus = "pending" | "in_progress" | "completed" | "failed" | "skipped"

Defined in: flows/types.ts:19

Flow step status

Variables

DEFAULT_POLLING_STRATEGY

const DEFAULT_POLLING_STRATEGY: PollingStrategy

Defined in: flows/types.ts:72

Default polling strategy

Functions

createSecretAndWaitReady()

createSecretAndWaitReady(ctx, options?): Promise<FlowResult<CreateSecretResult>>

Defined in: flows/create-secret.ts:66

Create a new secret and wait until it's ready for use

This flow:

1. Reads the secret creation fee
2. Builds and executes the createSecret transaction
3. Extracts the secret ID from the receipt
4. Polls until isSyncing becomes false

Parameters

ctx

FlowContext

Flow context

options?

FlowOptions

Flow options

Returns

Promise<FlowResult<CreateSecretResult>>

Flow result with secret ID and state

Example

// Plan mode - see what will happen
const plan = await createSecretAndWaitReady(ctx, { mode: 'plan' });
console.log('Steps:', plan.plan.steps.map(s => s.description));

// Execute mode - actually create the secret
const result = await createSecretAndWaitReady({
  ...ctx,
  txExecutor: async (intent) => {
    const hash = await wallet.sendTransaction(intent);
    return { hash, waitReceipt: () => provider.waitForTransaction(hash) };
  },
}, { mode: 'execute' });

console.log('Secret ID:', result.data.secretId);
console.log('Public key CID:', result.data.state.publicKeyCid);

---

retrieveFromLogsThenDecrypt()

retrieveFromLogsThenDecrypt(ctx, params, options?): Promise<FlowResult<RetrieveAndDecryptResult>>

Defined in: flows/decrypt-from-logs.ts:76

Retrieve encrypted data from on-chain logs and decrypt it

This flow:

1. Fetches commitment metadata (if block not provided)
2. Retrieves cifer and encryptedMessage from event logs
3. Verifies data integrity (optional)
4. Decrypts the data using the blackbox

Parameters

ctx

FlowContext

Flow context

params

RetrieveAndDecryptParams

Retrieval and decryption parameters

options?

FlowOptions

Flow options

Returns

Promise<FlowResult<RetrieveAndDecryptResult>>

Flow result with decrypted message

Example

const result = await retrieveFromLogsThenDecrypt(ctx, {
  secretId: 123n,
  dataId: '0x...',
  commitmentContract: '0x...',
});

if (result.success) {
  console.log('Decrypted:', result.data.decryptedMessage);
}

---

encryptThenPrepareCommitTx()

encryptThenPrepareCommitTx(ctx, params, options?): Promise<FlowResult<EncryptThenCommitResult>>

Defined in: flows/encrypt-commit.ts:81

Encrypt data and prepare a transaction to store it on-chain

This flow:

1. Encrypts the plaintext using the blackbox
2. Validates the encrypted data sizes
3. Builds a transaction intent for storing the commitment

Note: This flow returns a transaction intent that you can execute with your own wallet/provider.

Parameters

ctx

FlowContext

Flow context

params

EncryptThenCommitParams

Encryption and commitment parameters

options?

FlowOptions

Flow options

Returns

Promise<FlowResult<EncryptThenCommitResult>>

Flow result with encrypted data and transaction intent

Example

const result = await encryptThenPrepareCommitTx(ctx, {
  secretId: 123n,
  plaintext: 'My secret data',
  key: keccak256('my-key'),
  commitmentContract: '0x...',
});

if (result.success) {
  // Execute the transaction
  const hash = await wallet.sendTransaction(result.data.txIntent);
  console.log('Commitment stored:', hash);
}

---

encryptFileJobFlow()

encryptFileJobFlow(ctx, params, options?): Promise<FlowResult<EncryptFileFlowResult>>

Defined in: flows/file-jobs.ts:57

Encrypt a file and download the result

This flow:

1. Uploads the file for encryption
2. Polls until the job completes
3. Downloads the encrypted result

Parameters

ctx

FlowContext

Flow context

params

EncryptFileFlowParams

Encryption parameters

options?

FlowOptions

Flow options

Returns

Promise<FlowResult<EncryptFileFlowResult>>

Flow result with encrypted file

---

decryptFileJobFlow()

decryptFileJobFlow(ctx, params, options?): Promise<FlowResult<DecryptFileFlowResult>>

Defined in: flows/file-jobs.ts:213

Decrypt a file and download the result

This flow:

1. Uploads the encrypted file for decryption
2. Polls until the job completes
3. Downloads the decrypted result (requires auth)

Parameters

ctx

FlowContext

Flow context

params

DecryptFileFlowParams

Decryption parameters

options?

FlowOptions

Flow options

Returns

Promise<FlowResult<DecryptFileFlowResult>>

Flow result with decrypted file

---

decryptExistingFileJobFlow()

decryptExistingFileJobFlow(ctx, params, options?): Promise<FlowResult<DecryptFileFlowResult>>

Defined in: flows/file-jobs.ts:356

Decrypt from an existing encrypt job and download the result

This flow:

1. Creates a decrypt job from the existing encrypt job
2. Polls until the job completes
3. Downloads the decrypted result (requires auth)

Parameters

ctx

FlowContext

params

DecryptExistingFileFlowParams

options?

FlowOptions

Returns

Promise<FlowResult<DecryptFileFlowResult>>