React Hooks

function usePrivora(options: UsePrivoraOptions): UsePrivoraResult

interface UsePrivoraOptions {
  /** The Privora sequencer RPC URL */
  rpcUrl: string;
  /** Custom message for deriving encryption keys */
  signatureMessage?: string;
}

interface UsePrivoraResult {
  /** The connected Privora instance */
  privora: Privora | null;
  /** The user's crypto instance for local encryption/decryption */
  userCrypto: UserCrypto | null;
  /** The user's derived keypair */
  userKeypair: Keypair | null;
  /** Whether Privora is fully initialized */
  isInitialized: boolean;
  /** Whether initialization is in progress */
  isInitializing: boolean;
  /** Any error that occurred during initialization */
  error: string | null;
  /** Initialize Privora with a wallet signature */
  initialize: (signMessage: SignMessageFn) => Promise<void>;
  /** Reset the Privora state */
  reset: () => void;
}

const { privora, isInitialized, initialize } = usePrivora({
  rpcUrl: 'http://localhost:8899',
});

useEffect(() => {
  if (signMessage && !isInitialized) {
    initialize(signMessage);
  }
}, [signMessage, isInitialized]);

function useEncrypt(
  privora: Privora | null,
  userCrypto: UserCrypto | null
): UseEncryptResult

interface UseEncryptResult {
  /** Whether encryption is in progress */
  isEncrypting: boolean;
  /** Whether submission to sequencer is in progress */
  isSubmitting: boolean;
  /** Any error that occurred */
  error: string | null;

  /** Encrypt a value with FHE and user recovery */
  encrypt: <T extends EncryptedType>(
    value: number,
    type: T
  ) => Promise<EncryptedWithRecovery<T> | null>;

  /** Encrypt and submit a value to the sequencer */
  encryptAndSubmit: <T extends EncryptedType>(
    value: number,
    type: T
  ) => Promise<SubmitResult | null>;

  /** Submit already-encrypted data to the sequencer */
  submit: <T extends EncryptedType>(
    encrypted: Encrypted<T>
  ) => Promise<string | null>;

  /** Clear any error state */
  clearError: () => void;
}

interface EncryptedWithRecovery<T extends EncryptedType> {
  /** The FHE encrypted data */
  encrypted: Encrypted<T>;
  /** Base64-encoded user-encrypted value for local recovery */
  userCiphertext: string;
  /** Base64-encoded nonce used for user encryption */
  userNonce: string;
}

interface SubmitResult {
  /** The hash of the submitted FHE data */
  hash: string;
  /** The user-encrypted ciphertext (base64) */
  userCiphertext: string;
  /** The nonce used for user encryption (base64) */
  userNonce: string;
}

const { encryptAndSubmit, isEncrypting, error } = useEncrypt(privora, userCrypto);

const handleSubmit = async (value: number) => {
  const result = await encryptAndSubmit(value, 'u8');
  if (result) {
    console.log('Hash:', result.hash);
    // Store for later decryption
    saveRecoveryData(result.userCiphertext, result.userNonce);
  }
};

function useDecryptReveal(
  field: EncryptedField | null,
  userCrypto: UserCrypto | null
): UseDecryptRevealResult

interface EncryptedField {
  /** Base64-encoded user-encrypted ciphertext */
  ciphertext: string;
  /** Base64-encoded nonce */
  nonce: string;
  /** The data type of the encrypted value */
  dataType: EncryptedType;
}

type UseDecryptRevealResult = [
  RevealState,
  {
    /** Decrypt and reveal the value */
    reveal: () => Promise<void>;
    /** Hide the revealed value */
    hide: () => void;
    /** Toggle between revealed and hidden */
    toggle: () => Promise<void>;
  }
];

interface RevealState {
  /** Whether the value has been revealed */
  revealed: boolean;
  /** The decrypted value (null if not revealed) */
  value: number | bigint | null;
  /** Whether decryption is in progress */
  isDecrypting: boolean;
  /** Any error that occurred during decryption */
  error: string | null;
}

const priceField = {
  ciphertext: order.userCiphertext,
  nonce: order.userNonce,
  dataType: 'u8' as const,
};

const [state, { reveal, hide, toggle }] = useDecryptReveal(priceField, userCrypto);

return (
  <div>
    <span>{state.revealed ? state.value : '****'}</span>
    <button onClick={toggle}>
      {state.revealed ? 'Hide' : 'Reveal'}
    </button>
  </div>
);

function useDecryptRevealMultiple<K extends string>(
  fields: Record<K, EncryptedField | null>,
  userCrypto: UserCrypto | null
): Record<K, RevealState & Actions> & {
  revealAll: () => Promise<void>;
  hideAll: () => void;
}

const fields = {
  price: { ciphertext: '...', nonce: '...', dataType: 'u8' as const },
  quantity: { ciphertext: '...', nonce: '...', dataType: 'u8' as const },
};

const { price, quantity, revealAll, hideAll } = useDecryptRevealMultiple(
  fields,
  userCrypto
);

// Access individual field state
console.log(price.revealed, price.value);

// Reveal/hide individual fields
await price.reveal();
price.hide();

// Reveal/hide all at once
await revealAll();
hideAll();