Skip to main content

Text Encryption

Learn how to encrypt and decrypt text payloads using the CIFER blackbox API.

Overview​

The blackbox.payload namespace provides functions for encrypting and decrypting short messages (< 16KB). For larger data, see the File Encryption guide.

Encrypt​

import { blackbox } from 'cifer-sdk';

const encrypted = await blackbox.payload.encryptPayload({
  chainId: 752025,
  secretId: 123n,
  plaintext: 'My secret message',
  signer,
  readClient: sdk.readClient,
  blackboxUrl: sdk.blackboxUrl,
  outputFormat: 'hex', // or 'base64'
});

console.log('CIFER envelope:', encrypted.cifer);
console.log('Encrypted message:', encrypted.encryptedMessage);

Decrypt​

Only the secret owner (or delegate) can decrypt:

const decrypted = await blackbox.payload.decryptPayload({
  chainId: 752025,
  secretId: 123n,
  encryptedMessage: encrypted.encryptedMessage,
  cifer: encrypted.cifer,
  signer,
  readClient: sdk.readClient,
  blackboxUrl: sdk.blackboxUrl,
  inputFormat: 'hex', // or 'base64'
});

console.log('Decrypted:', decrypted.decryptedMessage);

Output Formats​

FormatUse Case
hexOn-chain storage, JSON APIs
base64Web APIs, compact storage

Error Handling​

import {
  BlackboxError,
  EncryptionError,
  DecryptionError,
  BlockStaleError,
  SecretNotReadyError,
  isBlockStaleError,
  isCiferError,
} from 'cifer-sdk';

try {
  await blackbox.payload.encryptPayload({ ... });
} catch (error) {
  if (isBlockStaleError(error)) {
    // SDK already retried - this indicates a persistent issue
    console.log('Stale block error after retries');
  } else if (error instanceof SecretNotReadyError) {
    console.log('Secret is still syncing');
  } else if (error instanceof EncryptionError) {
    console.log('Encryption failed:', error.message);
  } else if (error instanceof BlackboxError) {
    console.log('Blackbox error:', error.message, error.statusCode);
  }
  
  // All SDK errors include cause for error chaining
  if (isCiferError(error) && error.cause) {
    console.log('Underlying error:', error.cause);
  }
}
Debug Logging

The SDK doesn't log by default. To see progress messages, pass a logger when creating the SDK:

const sdk = await createCiferSdk({
  blackboxUrl: 'https://cifer-blackbox.ternoa.dev:3010',
  logger: console.log,
});

See Debugging & Logging for more details.

Best Practices​

Choose the Right Method​

Data SizeMethod
< 16 KBpayload.encryptPayload (this guide)
> 16 KBfiles.encryptFile

Handle Block Freshness​

The SDK automatically retries on stale block errors, but you should:

  • Use reliable RPC endpoints
  • Minimize time between signing and API calls
  • Consider retry logic for persistent failures

Next Steps​