fhestate-sdk

v0.2.1

Published

15 days ago

FHESTATE TypeScript SDK — FHE encryption and Solana coordinator integration for devnet

Downloads

256

0High
0Medium
0Low

fhestate

fhe solana tfhe privacy homomorphic fhestate

🛡️ FHESTATE SDK

FHE + CONFIDENTIAL AI AGENTS ON SOLANA

"Encrypt at the edge. Compute on ciphertext. Settle on Solana."

Official TypeScript SDK — browser TFHE encryption, confidential agent steps, and Solana devnet settlement.

Quick Start • Confidential Agents • Architecture • Verified Txs • API • Docs • Rust SDK • Website

| | | | --- | --- | | Package | fhestate-sdk v0.2.0 | | Runtime | Node 18+ · Browser (TFHE WASM) | | Chain | Solana devnet | | Tagline | Private Intelligence. Public Settlement. |

📑 Table of contents

🌟 Overview

FHESTATE is the privacy layer for autonomous AI agents on Solana — built on Fully Homomorphic Encryption (FHE) so agents can compute, coordinate, and settle on encrypted state without exposing prompts, memory, strategies, or intent.

This npm package (fhestate-sdk) is how you integrate that stack in TypeScript: TFHE-rs in the browser, SPL Memo / coordinator transactions on devnet, and confidential agent orchestration (Sentinel, Auditor, Coordinator missions).

What makes FHESTATE unique?

| | | | --- | --- | | 🔒 Real FHE | TFHE-rs WASM — not hashing alone. Homomorphic ops via fhestate-rs + fhe-node. | | 🤖 Agent-native | Blind agent steps, hash-linked encrypted memory, devnet proof on Solscan. | | ⛓️ Solana settlement | local:// memo commitments or coordinator PDAs — verifiable without plaintext on-chain. | | 🧩 TS + Rust parity | Instruction bytes, PDA seeds, and layouts match the Rust coordinator program. | | 📦 One npm install | fhestate-sdk, fhestate-sdk/browser, fhestate-sdk/agents. |

The concept: private intelligence, public settlement

Unlike ZK (prove a statement about data), FHE lets the runtime compute on ciphertext — the server never needs plaintext for the core blind step.

flowchart LR
  subgraph client["Browser / wallet"]
    ENC[TFHE encrypt intent]
    AG[Confidential agent step]
  end
  subgraph chain["Solana devnet"]
    MEMO[SPL Memo local://hash]
    PDA[StateContainer PDA]
  end
  ENC --> AG --> MEMO
  AG --> PDA

Architecture diagrams (shared with Rust repo): fhestate-rs assets/.

🎯 Use cases

Confidential AI agents — Sentinel, Auditor, Coordinator missions on encrypted intent (browser utility + this SDK).
Private voting & policy — homomorphic tallies without revealing individual ballots.
Sealed-bid flows — commit encrypted values, reveal only under policy.
Confidential trading & funds — strategies and treasury logic without plaintext on-chain.
Verifiable devnet demos — local:// memo commitments provable on Solscan.

What is FHESTATE? (protocol)

FHESTATE (Fully Homomorphic Encryption STATE) is a protocol design for confidential application state on Solana:

Users encrypt data locally with a client key (TFHE-rs).
The chain stores either a short commitment (local:// + SHA-256 of ciphertext) or the encrypted blob (coordinator mode).
A compute node (fhe-node in Rust) performs homomorphic operations on ciphertext using a server evaluation key, then updates on-chain state hashes / URIs.

Design principles:

| Principle | Meaning | | ---------------------------- | -------------------------------------------------------------------------------------------------- | | Encrypt at the edge | Plaintext should not be required on your backend for memo-mode dApps. | | Commit on-chain | Solana records that a defined ciphertext was submitted, without exposing the value in memo mode. | | Compute off-chain (FHE) | Solana validators do not run TFHE; fhe-node does. | | Rust + TypeScript parity | Instruction bytes, PDA seeds, and account layouts match fhestate-rs. |

What FHESTATE is not:

Not a privacy coin or mixer (wallet addresses and tx timing remain public).
Not anonymous relay or MPC threshold decryption in v0.2.0.
Not a substitute for a formal security audit on mainnet.

Token / community: The public site (fhestate.org) covers token and roadmap; this README focuses on technical SDK integration.

[!NOTE] FHESTATE is in devnet integrator beta (v0.2.0). TFHE-rs cryptography is production-grade; coordinate mainnet deployments with your own security review.

📦 What is this SDK?

fhestate-sdk is the npm package for application developers:

| You can | Module | | ------------------------------------------------------------------------ | ------------------------------------------ | | Bootstrap TFHE WASM and encrypt FheUint8/16/32, FheBool, FheString | fhestate-sdk/browser | | Run confidential agent steps + memo submit | fhestate-sdk/browser · fhestate-sdk/agents | | Persist client keys (browser / file path) | KeyManager | | Build Anchor coordinator instructions | fhestate-sdk/solana | | Sign and send real devnet transactions | FhestateClient, FhestateSolanaProvider | | One-call browser encrypt + memo tx | encryptAndSubmitMemo |

You cannot (in this package alone):

Deploy the coordinator program (use fhestate-rs).
Run homomorphic server compute (use fhe-node).
Generate server evaluation keys in browser (ServerKey throws by design).

🔗 Ecosystem

flowchart TB
  subgraph users["End users"]
    WEB[Web dApp / wallet]
  end
  subgraph npm_pkg["npm: fhestate-sdk"]
    SDK[TypeScript SDK\nencrypt + Solana client]
  end
  subgraph rust_pkg["fhestate-rs (Rust)"]
    CLI[fhe-cli\nencrypt, demo, doctor]
    PROOF[fhe_proof\nhomomorphic demo]
    NODE[fhe-node\nhomomorphic compute]
    PROG[coordinator program\nAnchor]
  end
  subgraph solana["Solana devnet"]
    MEMO[SPL Memo program]
    PDA[StateContainer PDA]
  end
  WEB --> SDK
  CLI --> SDK
  SDK -->|memo: local://hash| MEMO
  SDK -->|submit_input| PROG
  PROG --> PDA
  NODE --> PDA
  NODE --> PROG

| Component | Registry | Role | | ---------------------------- | ----------------------- | --------------------------------------------- | | fhestate-sdk (this repo) | npm | Browser FHE, Solana txs, instruction builders | | fhestate-rs | GitHub / crates.io | On-chain program, CLI, node, proofs | | fhestate-site | — | Marketing site + agent docs | | fhestate-app | — | Confidential agents utility UI |

🏗️ Architecture

Layer model

flowchart TB
  subgraph L4["Layer 4 — Application"]
    APP[Your dApp / API / script]
  end
  subgraph L3["Layer 3 — fhestate-sdk"]
    BT[browser-transactions]
    CL[FhestateClient]
    PR[FhestateSolanaProvider]
    CR[crypto: fheEngine, FheUint*, KeyManager]
    SL[solana: instructions, memo, PDA]
  end
  subgraph L2["Layer 2 — Dependencies"]
    TFHE[tfhe npm WASM]
    WEB3[@solana/web3.js]
  end
  subgraph L1["Layer 1 — Solana + operator"]
    CHAIN[Solana ledger]
    FNODE[fhe-node Rust]
  end
  APP --> BT
  APP --> CL
  BT --> CR
  BT --> CL
  CL --> PR
  PR --> SL
  CR --> TFHE
  PR --> WEB3
  SL --> CHAIN
  FNODE --> CHAIN

Memo-mode sequence (default devnet demo)

sequenceDiagram
  participant User
  participant SDK as fhestate-sdk/browser
  participant WASM as TFHE-rs WASM
  participant Wallet as Phantom / keypair
  participant RPC as Solana devnet
  participant Memo as SPL Memo

  User->>SDK: encryptAndSubmitMemo(1337)
  SDK->>WASM: FheUint32.encrypt(1337)
  WASM-->>SDK: ~263 KB ciphertext
  SDK->>SDK: SHA-256(ciphertext)
  SDK->>Wallet: sign transaction
  Wallet->>RPC: sendRawTransaction
  RPC->>Memo: data = local://<64 hex>
  RPC-->>User: signature + Solscan URL
  Note over Memo: Plaintext NOT on chain

Coordinator-mode sequence

sequenceDiagram
  participant App
  participant SDK as FhestateClient
  participant RPC as Solana devnet
  participant Prog as Coordinator program
  participant Node as fhe-node

  App->>SDK: ensureInitializedAndSubmit(ciphertext)
  SDK->>RPC: initialize_state (if needed)
  SDK->>RPC: submit_input(full ciphertext bytes)
  RPC->>Prog: store encrypted vec + op
  Node->>Prog: homomorphic update (later)

Source layout (published `dist/` mirrors `src/`)

fhestate-sdk/
├── src/
│   ├── index.ts                 # Main export
│   ├── browser.ts               # Browser public API
│   ├── browser-transactions.ts  # encryptAndSubmit*
│   ├── agents/                  # confidential agent runtime
│   ├── crypto/                  # engine, keys, primitives, lwe
│   └── solana/                  # client, provider, memo, programs, pda
├── dist/                        # ESM + .d.ts (npm tarball)
├── docs/                        # Technical guides + FAQ
└── tests/                       # Unit tests (not in tarball)

🔐 Privacy model — FHE vs SHA-256

Two steps — do not confuse them:

| Step | Technology | Input → Output | Purpose | | ----- | ----------------- | ------------------------------- | ---------------------------------- | | 1 | FHE (TFHE-rs) | 1337 → ~263 KB ciphertext | Secrecy of the value | | 2 | SHA-256 | ciphertext bytes → 64 hex chars | Commitment / short on-chain ID |

flowchart LR
  P[Plaintext] --> FHE[FHE encrypt]
  FHE --> CT[Ciphertext]
  CT --> H[SHA-256]
  H --> ON[On-chain: local://hash]
  CT --> LOC[Local cache only]

Memo mode: Only local://<hash> is written to the SPL Memo program. Coordinator mode: Full ciphertext bytes are in the instruction (still encrypted, but publicly visible as a blob).

Deep dive: docs/FHE-AND-PRIVACY.md.

📤 Package exports

| Import path | Use when | | ---------------------- | ----------------------------------------------------------------- | | fhestate-sdk | Node: Solana client, instruction builders, types (no browser FHE) | | fhestate-sdk/browser | Browser: FHE encrypt + wallet txs + agent helpers | | fhestate-sdk/agents | Agent runtime, hash-only memory, orchestration | | fhestate-sdk/crypto | Crypto-only re-exports | | fhestate-sdk/solana | Solana-only re-exports |

🚀 Quick start

Prerequisites

Node.js 18+
npm or pnpm
Funded Solana devnet wallet (for live tx scripts)
Optional: fhestate-rs for fhe-cli / fhe-node

Install

npm install fhestate-sdk

Browser — encrypt + devnet memo (one function)

import { encryptAndSubmitMemo } from "fhestate-sdk/browser";

await window.solana?.connect();
const { signature, explorerUrl, commitment, ciphertextBytes } =
  await encryptAndSubmitMemo(1337);

console.log({ signature, explorerUrl, commitment, ciphertextBytes });

Node — submit pre-encrypted bytes

import { readFileSync } from "node:fs";
import { Keypair } from "@solana/web3.js";
import { FhestateClient, keypairSigner } from "fhestate-sdk";

const wallet = Keypair.fromSecretKey(/* funded devnet key */);
const ciphertext = new Uint8Array(readFileSync("./ciphertext.bin"));
const client = new FhestateClient("https://api.devnet.solana.com");

const result = await client.ensureInitializedAndSubmit(
  keypairSigner(wallet),
  ciphertext,
  0,
);
console.log(result.explorerUrl);

Node — memo with hash only

const hash = "0331f74e7a41d2cf6123caaba191624f297f818f527d9eb94ccbfc54037ffbde";
await client.submitCommitmentHash(keypairSigner(wallet), hash);

More paths: docs/QUICKSTART.md.

🤖 Confidential FHE agents

Autonomous agents that operate on encrypted intent and hash-only memory, then anchor commitments on Solana devnet — Sentinel, Auditor, and Coordinator missions.

| Term | Meaning | | --- | --- | | Intent | User value encrypted as TFHE ciphertext (browser) | | Agent step | Blind transition: new stepHash from agent id + intent hash + chain | | Memory | Slots storing hashes only — no plaintext | | Commitment | On-chain SPL Memo local://<intentHash> |

Browser — encrypt, agent step, submit memo

import {
  runConfidentialAgentStep,
  encryptAgentStepAndSubmitMemo,
} from "fhestate-sdk/browser";

// Encrypt + one agent step (no wallet)
const run = await runConfidentialAgentStep(42);
console.log(run.intentHash, run.stepHash, run.memory);

// With Phantom — encrypt, step, submit memo
await window.solana?.connect();
const tx = await encryptAgentStepAndSubmitMemo(1337);
console.log(tx.explorerUrl);

Node — hash-only orchestration

import { AgentRuntime, runAgentStep } from "fhestate-sdk/agents";

const runtime = new AgentRuntime("my-agent");
const hash = "<64-char-hex-from-fhe-cli>";
await runtime.runStep(hash);
console.log(runtime.memory.list());

| Resource | Link | | --- | --- | | Agent guide | docs/FHE-AGENTS.md | | Live utility | app.fhestate.org | | Marketing / missions | fhestate.org/agents |

✅ Verified results — FHE proofs

The following results were captured from automated and manual verification on 2026-05-22 against this codebase (v0.2.0). Re-run locally with the commands in § Development.

1. Rust homomorphic proof (`fhe_proof demo`)

Command: cargo run --release --bin fhe_proof -- demo (in fhestate-rs)

| Field | Result | | ---------------- | ---------------------------------------------------- | | Plaintext | Solana Privacy Ops (18 characters) | | Operation | Homomorphic shift +1 per character on ciphertext | | Decrypted output | Tpmbob!Qsjwbdz!Pqt | | Status | VERIFIED SUCCESS |

This proves real FHE compute, not hashing alone: encrypt → homomorphic add → decrypt matches expected shift.

Sample per-character ciphertext commitments (SHA-256 of each char’s ciphertext) from the proof run:

| Char | SHA-256 (ciphertext) | | ---- | ------------------------------------------------------------------ | | S | ad5aa4e3ae1ecf5e77bc0630a1f29307732ebfd8a1c8572c38ff800717e58480 | | o | d440a24dedf3c3c7a3f3eebbd6f14d6bfddbdae401275d9199f646cdf9968c4a | | l | cdb51c6666ea7b31fb12767609cad9cb18a17bc4729e0e5be2fd091f8fd61e93 | | | 23282c19734cf98722b2dfdfcec3637e9ac9505a4d68190301e21976ee49a08f | | P | 4e2cf11442d3cc0d58f92c78d23a893d6df84a3c2a7cb463fc45d05c324e75ac | | … | (14 more characters in full demo output) |

2. Browser TFHE WASM (`FheUint32`)

Page: /test-sdk — Run Native WASM Encryption

| Metric | Value | | ------------------- | -------------------------------------------------------------------------- | | Method | TFHE-rs WASM FheUint32.encrypt(1337) | | Ciphertext size | 263,448 bytes | | Encrypt time | ~307 ms (hardware-dependent) | | SHA-256 commitment | ff02ec3e59f71cf78812ae235b5be6fa366c2b6be999fa253cf6522e83f44488 | | On-chain URI format | local://ff02ec3e59f71cf78812ae235b5be6fa366c2b6be999fa253cf6522e83f44488 |

3. Rust CLI encrypt (`fhe-cli encrypt --value 1337`)

| Metric | Value | | ----------- | -------------------------------------------------------------------------- | | Output file | e2e_ct.bin | | Bytes | 263,368 | | SHA-256 | 8554e340db5b79d48dbc14f820b182782d0984db9f6836efe6b83bfa47b3db98 | | Cache URI | local://8554e340db5b79d48dbc14f820b182782d0984db9f6836efe6b83bfa47b3db98 |

4. SDK hardcore verification (`npm run test:hardcore`)

Result: 8/8 PASS (representative run with devnet RPC up)

| # | Check | Status | | --- | ---------------------------------------- | ---------------------------- | | 1 | Package exports (solana + node storage) | PASS | | 2 | Node FHE guard (must fail before WASM) | PASS | | 3 | Node key file storage roundtrip | PASS | | 4 | Solana PDA + instruction feature | PASS | | 5 | Ciphertext SHA-256 commitment | PASS | | 6 | Solana devnet RPC (getSlot) | PASS (e.g. slot 464071407) | | 7 | Browser FHE site reachable (/test-sdk) | PASS | | 8 | Rust fhe_proof roundtrip | PASS when cargo available |

5. Unit tests (`npm run test:unit`)

50 tests across 12 suites in tests/unit/ (see tests/README.md):

| Suite | Tests | Coverage | | ----- | ----- | -------- | | coordinator | 5 | Program ID, PDA seeds, determinism | | instructions | 6 | Anchor discriminators, account wiring, payload encoding | | memo | 7 | local:// format, validation errors | | sha256 | 5 | NIST vector, determinism, large buffers | | state-container | 3 | Deserialize roundtrip | | runtime | 3 | Node FHE guard | | hash-chain | 3 | State transition verification | | storage-node | 5 | Key file I/O | | client | 3 | Explorer URL, RPC | | errors | 3 | Error types | | exports | 5 | package.json + dist layout | | server-key | 2 | Server key blocked in SDK |

6. Devnet RPC latency (reference)

10× getSlot samples (ms): 841, 439, 435, 437, 437, 1769, 4269, 1215, 396, 435
Average ~1067 ms — varies by network; not a SDK metric.

🌐 Verified devnet transactions

Confirmed Solana devnet transactions from E2E integration runs (2026-05-22).
Open links with ?cluster=devnet on Solscan.

Primary transaction index

| # | Source | Description | Signature | Explorer | | --- | ------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | 1 | fhe-cli demo | Encrypt 1337 → SPL Memo local://0331f74e... | 2Z72XRqjiq2S5QcZ3RSBq4HpnNpk3LWyRcpEra55VND7TEGQBZiFwEExXHzCFcRCKbfEv7pabUX2h8MEgew8wui7 | Solscan | | 2 | SDK test:live | submitMemoCommitment from TypeScript | 3XqK2eF3UHSM5gtbcJ8etfnD8KzEyAgH8vhvHmNkaQ4c5Xi22GfyrCGpNgZkEmi34wS7RZKLtXfHvk9Ei4tbzEzU | Solscan | | 3 | SDK test:live / CLI submit | Memo tx (CLI parser reported FAIL; tx confirmed) | 2Bug4MttPTrQeDibETR8hNdPjXDFstU2iQx9gG14JbExPkACvyTwVoEBMFMjZsHueZixEvx4MtPcMZ7mEifw3k8w | Solscan | | 4 | Site POST /api/increment | Server-signed memo (FHESTATE site API) | 5UxkvS9HezsJufjcFJwstYjD2WosqcDvMSzs8bXKJrFug8LU3rxwKftZJkmtLZ5KPifjGJRwYnhUbhV365goF671 | Solscan | | 5 | fhe-cli submit-file | Cached ciphertext → memo | 5jW9coj7SDeckyBCoNnjuP6GvsXq1xtmuSXYVULDgYTU8pJAUXck7HdCHhvYp9wYgx119q5DHtfSMddNBE5DAEB8 | Solscan | | 6 | Counter-spy use case (fhe-cli demo) | Memo flow demo | 4UvJT4y41BNvfCAGbjLkk7hqxX1hkYj8czw4HjFrgdKdYpGzbANTevDtQZj4MNZhG1WnTQ14ed1FcuFZvzceUkye | Solscan |

Commitments observed on-chain (memo field)

| Run | Plain value | Memo / URI commitment | | ---------------------- | --------------------- | -------------------------------------------------------------------------- | | fhe-cli demo | 1337 | local://0331f74e7a41d2cf6123caaba191624f297f818f527d9eb94ccbfc54037ffbde | | Site API increment | encrypted server-side | local://ff02ec3e59f71cf78812ae235b5be6fa366c2b6be999fa253cf6522e83f44488 | | fhe-cli encrypt only | 1337 | local://8554e340db5b79d48dbc14f820b182782d0984db9f6836efe6b83bfa47b3db98 |

How to verify yourself: Open any Solscan link → find the Memo instruction → confirm text starts with local:// and is 64 hex characters after the prefix. You should not see plaintext 1337 in the memo.

Test wallet (devnet only)

E2E runs used a funded devnet wallet:

| Field | Value | | ---------------------- | ---------------------------------------------- | | Address | 4QTdbQyGJ1mGGrViaZNHxsU6bbQfchnPob7VdkaTqwuc | | Balance (at test time) | ~0.0994 SOL | | RPC | https://api.devnet.solana.com |

Never use test wallet secrets on mainnet or commit them to git.

Additional reference transaction (earlier run)

| Source | Signature | Explorer | | ------------------------------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | SDK test:live (2026-05-22 earlier batch) | 5niVbVVrbj67CCLPyXzc6wpsDLrM45sMgZP6gsFYt4Z9WSJ54K7cKxpLk6Y9QXYXFL8HdvqrdsvDQ4i3bJwC9nk7 | Solscan | | fhe-cli demo (alternate run) | r8ohiE8QCmryWFzAgQuCH2KE872gfjowUVLNeRUbuZ5weaAVHAmosnK1E1Kn7pc6qmr7zfuv9mScQtRRGfngiJ5 | Solscan |

Site API response example (`POST /api/increment`)

{
  "success": true,
  "signature": "5UxkvS9HezsJufjcFJwstYjD2WosqcDvMSzs8bXKJrFug8LU3rxwKftZJkmtLZ5KPifjGJRwYnhUbhV365goF671",
  "onChain": true,
  "uri": "local://ff02ec3e59f71cf78812ae235b5be6fa366c2b6be999fa253cf6522e83f44488"
}

Response time in test: ~3706 ms (includes encrypt + RPC + confirm).

🧪 Test and verification matrix

| Command | What it validates | Needs devnet SOL? | | ------------------------ | ---------------------------------- | ---------------------------------- | | npm run test | Unit: PDAs, ix layout, memo format | No | | npm run test:solana | WASM + instruction script | No | | npm run test:hardcore | 8 integration checks + RPC | No | | npm run verify | build + test + test:solana | No | | npm run verify:all | verify + hardcore | No | | npm run test:live | FHE proof + memo txs | Yes (FHESTATE_WALLET_SECRET) | | npm run example:devnet | Example submit script | Yes | | fhe-cli doctor (Rust) | Keys, RPC, balance | Optional | | fhe-cli demo (Rust) | Full encrypt + memo tx | Yes |

E2E feature coverage (18/18 passed — full stack run)

| Category | Item | Result | | -------- | --------------------------------- | ------ | | FHE | Rust fhe_proof homomorphic demo | PASS | | FHE | Rust fhe-cli encrypt | PASS | | FHE | Browser /test-sdk reachable | PASS | | TX | fhe-cli demo memo | PASS | | TX | SDK test:live memo | PASS | | TX | Site API increment | PASS | | TX | fhe-cli submit-file | PASS | | TX | Wallet history listing | PASS | | Use case | local:// URI format | PASS | | Use case | Counter-spy memo flow | PASS | | SDK | Unit + instruction tests | PASS | | SDK | Hardcore 8/8 | PASS | | CLI | doctor / status | PASS | | CLI | cache show | PASS | | Latency | devnet RPC samples | logged |

📖 API overview

High-level browser API

import {
  fheEngine,
  KeyManager,
  FheUint32,
  encryptAndSubmitMemo,
  encryptAndSubmitCoordinator,
  FhestateClient,
  browserWalletSigner,
  keypairSigner,
} from "fhestate-sdk/browser";

High-level Node API

import {
  FhestateClient,
  FhestateSolanaProvider,
  keypairSigner,
  buildSubmitInputInstruction,
  buildInitializeStateInstruction,
  deriveStatePda,
  COORDINATOR_PROGRAM_ID,
} from "fhestate-sdk";

`FhestateClient` methods

| Method | Description | | ------------------------------------------------ | -------------------------------- | | submitCommitmentHash(signer, hashHex) | SPL Memo local:// tx | | submitEncrypted(signer, bytes, op?) | Coordinator submit_input | | ensureInitializedAndSubmit(signer, bytes, op?) | Init PDA if missing, then submit | | static devnetExplorerUrl(signature) | Solscan devnet URL |

`FhestateSolanaProvider` methods

| Method | Description | | ----------------------------------------- | ---------------------------- | | sendTransaction(signer, instructions[]) | Sign, send, confirm | | submitMemoCommitment(signer, hashHex) | Memo tx | | submitInput(signer, encryptedData, op?) | Coordinator submit | | initializeState(signer) | Create state PDA | | getStateContainer(pubkey) | Deserialize on-chain account | | isStateInitialized(pubkey) | Account exists? |

Crypto primitives

| Class | Encrypt range / notes | | ----------- | --------------------------------------- | | FheUint8 | 0..255 | | FheUint16 | 0..65535 | | FheUint32 | 0..4294967295 | | FheBool | true / false | | FheString | UTF-8 → array of FheUint8 ciphertexts |

`LweCiphertext`

| Method | Description | | ----------------------------- | ----------------------- | | bytes | Serialized TFHE payload | | hash() | SHA-256 hex commitment | | toBase64() / fromBase64() | Serialization helpers |

Full reference: docs/API-REFERENCE.md.

🛤️ Integration paths

flowchart TD
  START[Choose path] --> M{Memo or coordinator?}
  M -->|Memo| M1[Browser: encryptAndSubmitMemo]
  M -->|Memo| M2[CLI encrypt → Node submitCommitmentHash]
  M -->|Coordinator| C1[Deploy fhestate-rs program]
  C1 --> C2[Browser or Node: ensureInitializedAndSubmit]
  C2 --> C3[Run fhe-node for compute]

| Path | Deploy program? | Encrypt | Submit | | ------------------------- | --------------- | -------------------- | ------------------------------------------------- | | A — Memo | No | Browser or fhe-cli | submitCommitmentHash / encryptAndSubmitMemo | | B — Coordinator | Yes | Browser or fhe-cli | submitEncrypted / encryptAndSubmitCoordinator | | C — Instructions only | Your choice | External | You call sendTransaction with built ixs |

Guides: docs/QUICKSTART.md, docs/SOLANA-INTEGRATION.md, docs/BROWSER-INTEGRATION.md, docs/NODE-INTEGRATION.md.

⛓️ On-chain constants

| Name | Value | | ------------------------ | ---------------------------------------------- | | COORDINATOR_PROGRAM_ID | FHECord1111111111111111111111111111111111111 | | MEMO_PROGRAM_ID | MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr | | STATE_SEED | "state" | | Memo prefix | local:// | | Default RPC | https://api.devnet.solana.com |

`submit_input` instruction data layout

[ 8 bytes ] Anchor discriminator  38b89a5bad3f158a
[ 4 bytes ] u32 LE length of encrypted_data
[ N bytes ] encrypted_data
[ 1 byte  ] operation id

`initialize_state` discriminator

beabe0dbd948c7b0  (8 bytes)

🔧 Environment variables

| Variable | Purpose | | -------------------------- | ------------------------------------------------ | | FHESTATE_CLIENT_KEY_PATH | Override Node client key file | | FHESTATE_WALLET_SECRET | Base58 secret for test:live / example:devnet | | FHESTATE_RPC | Solana RPC URL | | FHESTATE_SKIP_RUST | Skip Rust checks in hardcore verify |

🏰 Security summary

| Topic | Guidance | | ---------------- | ----------------------------------------- | | Plaintext | Keep in browser; do not log in production | | Client key | Sensitive — localStorage / file path | | Server key | Only on fhe-node, not in browser bundle | | Memo mode | Preferred for smaller on-chain footprint | | Coordinator mode | Encrypted blob is public on-chain | | Devnet | Public test network — no real secrets | | Audit | Not mainnet-audited in v0.2.0 |

Full model: docs/SECURITY-MODEL.md.

❓ FAQ (overview)

Detailed answers live in docs/FAQ.md (protocol, FHE, Solana, keys, browser, Node, testing, errors, npm). Below is a structured index.

| Category | Topics covered in FAQ | | --------------------- | --------------------------------------------------------------- | | Protocol & vision | What FHESTATE is, FHE vs ZK, use cases, devnet vs mainnet | | Packages | fhestate-sdk vs fhestate-rs vs fhestate-site, registries | | FHE & SHA-256 | Step-by-step pipeline, ciphertext size, proofs, common mistakes | | Solana | Memo vs coordinator, program IDs, fees, failures, explorers | | Keys | Client vs server, storage paths, backup, loss scenarios | | Browser | Imports, Vite/Webpack, Phantom, COOP/COEP, bundle size | | Node & CLI | Why Node cannot FHE, fhe-cli workflow, env vars | | API | Which class to use, encryptAndSubmit*, custom signers | | Testing | All npm scripts, live tx reproduction, false FAIL notes | | Publishing | Tarball contents, version policy, prepublishOnly | | Troubleshooting | Error messages → fixes decision tree |

Most asked:

| Question | Answer | | ------------------------- | ------------------------------------------------------------------------------------------- | | Does SHA-256 replace FHE? | No. FHE encrypts the value; SHA-256 hashes the ciphertext for local:// memos. | | Can I encrypt in Node.js? | Not in plain Node — use fhestate-sdk/browser or fhe-cli, then submit from Node. | | Need a deployed program? | No for SPL Memo; yes for coordinator submit_input. | | npm package name? | fhestate-sdk only (Rust is fhestate-rs on crates.io). | | Where are real tx links? | § Verified devnet transactions in this README. |

→ Read the full FAQ →

📁 Repository structure

Production-grade open-source layout (npm ships dist/, docs/, README.md, LICENSE only):

fhestate-sdk/
├── .github/
│   ├── workflows/ci.yml          # Node 18/20/22 — build + unit tests
│   ├── ISSUE_TEMPLATE/           # Bug report, feature request
│   └── PULL_REQUEST_TEMPLATE.md
├── src/                          # TypeScript source
├── dist/                         # Build output (gitignored)
├── tests/
│   ├── unit/                     # 50+ unit tests — npm run test:unit
│   ├── helpers/fixtures.ts
│   └── README.md
├── scripts/                      # hardcore, live devnet, examples
├── docs/                         # Technical guides + FAQ
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── CHANGELOG.md
├── SECURITY.md
├── SUPPORT.md
├── LICENSE
└── README.md

| Root file | Purpose | |-----------|---------| | CONTRIBUTING.md | How to contribute, PR process, coding standards | | CODE_OF_CONDUCT.md | Community standards | | CHANGELOG.md | Version history | | SECURITY.md | Vulnerability reporting | | SUPPORT.md | Help channels |

📚 Full documentation

| Document | Description | | ---------------------------------------------------------- | ----------------------------- | | docs/README.md | Documentation index | | docs/FHE-AGENTS.md | Confidential FHE agents | | docs/QUICKSTART.md | Step-by-step devnet paths | | docs/ARCHITECTURE.md | Layers, sequences, source map | | docs/FHE-AND-PRIVACY.md | FHE vs SHA-256, keys, leakage | | docs/API-REFERENCE.md | Complete API | | docs/SOLANA-INTEGRATION.md | Programs, PDAs, txs | | docs/BROWSER-INTEGRATION.md | Vite, Phantom, React | | docs/NODE-INTEGRATION.md | Server + fhe-cli | | docs/SECURITY-MODEL.md | Threats and limits | | docs/DEVELOPMENT.md | Build, test, publish | | docs/FAQ.md | Frequently asked questions |

💻 Development

git clone https://github.com/FHESTATE/fhestate-sdk.git
cd fhestate-sdk
npm install
npm run build
npm run test:unit
npm run verify:all

Reproduce live devnet transactions

# Funded devnet wallet required
export FHESTATE_WALLET_SECRET=<base58_secret_key>
npm run test:live

Reproduce Rust FHE proof

cd ../fhestate-rs
cargo run --release --bin fhe_proof -- demo

Publish to npm

npm run verify:all
npm pack --dry-run
npm publish --access public

🤝 Contributing & community

| Resource | Link | |----------|------| | Contributing guide | CONTRIBUTING.md | | Code of conduct | CODE_OF_CONDUCT.md | | Security | SECURITY.md | | Support | SUPPORT.md | | Changelog | CHANGELOG.md | | Tests | tests/README.md |

We welcome issues, docs improvements, and test coverage PRs.

📜 License

MIT License — see LICENSE for full text.

🙏 Acknowledgments

| Contributor | Contribution | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Zama | TFHE-rs — the FHE engine behind tfhe npm and Rust crates | | Solana | High-performance L1 and SPL Memo / program model | | FHESTATE Rust team | fhestate-rs coordinator, fhe-cli, fhe-node, fhe_proof — parity with this SDK | | TypeScript / Node ecosystem | Tooling (tsx, @solana/web3.js) used in build and verification |

📞 Contact & Support

| Channel | Link | | --- | --- | | Website | fhestate.org | | Documentation | docs.fhestate.org | | npm | fhestate-sdk | | GitHub — SDK | FHESTATE/fhestate-sdk | | GitHub — Rust | FHESTATE/fhestate-rs | | Issues | Report bugs / request features | | Discussions | Community discussions | | X | @fhe_state |

FHESTATE — FHE and confidential AI agents on Solana

Private Intelligence. Public Settlement.