⚠️ TESTNET ONLY — DO NOT USE REAL FUNDS

This software runs on Arbitrum Sepolia testnet. Use a dedicated test wallet with no mainnet assets. Never use private keys that hold real funds. The staking, rewards, and inference mechanics are real on testnet but have no mainnet value.

@abhieren/blindference-agent

Confidential AI inference SDK for Node.js — submit encrypted prompts to a decentralized quorum of verified nodes.

🆕 First time here? Read WHY.md to understand why this package exists, what problems it solves, and how it compares to OpenAI API vs local LLMs.

TL;DR: Your prompt is encrypted with AES-256-GCM before leaving your machine, split into FHE-encrypted key halves, sent to 3 independent verified nodes that must cryptographically agree on the exact same output, and only then is the result decrypted locally. No plaintext ever touches a server.

Blindference Agent enables developers to build agents that send prompts through end-to-end encryption (AES-256-GCM + Fhenix CoFHE), execute across a leader-verifier quorum for integrity, and receive decrypted results locally. No plaintext leaves your machine.

🔗 Live Services:

• ICL API: icl.blindference.xyz
• Payment Service: payment.blindference.xyz
• Dashboard: www.blindference.xyz

Table of Contents

1. What It Does
2. Architecture
3. Prerequisites
4. Installation
5. 🚀 5-Minute Quickstart
6. CLI Reference
7. SDK API
8. REST Server
9. Configuration
10. Python Interop
11. Troubleshooting
12. Links

What It Does

The Agent SDK provides a complete end-to-end confidential inference pipeline:

• Encrypts your prompt with AES-256-GCM before it leaves your machine
• Splits the encryption key into FHE-encrypted halves via Fhenix CoFHE
• Submits the encrypted job to the Payment Service with on-chain key storage
• Dispatches to a quorum of 3 verified nodes (1 Leader + 2 Verifiers)
• Verifies all nodes cryptographically agree on the same output hash
• Decrypts the result locally using CoFHE threshold decryption
• Returns plaintext answer only after quorum consensus is reached

Key Features:

• CLI for quick inference: blindference-agent infer --prompt "Hello"
• SDK class for programmatic use: new BlindferenceAgent(config)
• REST server for language-agnostic integration
• Multi-gateway IPFS fallback for reliable content retrieval
• Auto-polling for job completion with configurable timeouts

Architecture

View interactive versions:

• Mermaid (GitHub native)
• Excalidraw (importable) — open at excalidraw.com
• ASCII fallback

11-Step Data Flow:

1. User submits prompt via Agent SDK CLI
2. Agent AES-encrypts prompt, CoFHE-encrypts key halves
3. Agent submits job to Payment Service
4. Payment Service creates job, ICL selects quorum (1 Leader + 2 Verifiers)
5. ICL dispatches to verified nodes
6. Nodes decrypt prompt, run inference (Groq/Gemini/vLLM), upload result to IPFS
7. Nodes commit result hash on-chain
8. ICL verifies quorum consensus (2+ confirms = accepted)
9. Payment Service marks job COMPLETED
10. Agent polls status, decrypts output key via CoFHE
11. Agent AES-decrypts final result, returns plaintext to user

API Endpoints Used:

• POST /v1/jobs/submit — Submit encrypted inference job
• GET /v1/jobs/{jobId} — Poll job status
• GET /v1/balance/{address} — Check credit balance
• POST /v1/credits/purchase-package — Buy credit package
• GET /v1/inference/quorum-preview — Preview quorum
• POST /v1/inference/upload-prompt — Upload encrypted prompt

Prerequisites

• Node.js 18+ — check with node --version
• npm 9+ — check with npm --version
• A MetaMask wallet with Arbitrum Sepolia testnet
• Testnet ETH on Arbitrum Sepolia (for gas)
• Testnet BLIND tokens — get from the Blindference Faucet
• cUSDC credits — purchase with BLIND via CLI

Quick Check

node --version   # >= 18.0.0
npm --version    # >= 9.0.0

Installation

Global Install (Recommended)

npm install -g @abhieren/blindference-agent

This installs the blindference-agent CLI globally.

Per-Project Install

npm install @abhieren/blindference-agent

Import in your code:

import { BlindferenceAgent } from '@abhieren/blindference-agent'

🚀 5-Minute Quickstart

1. Set Up Environment

Create .env in your working directory:

cat > .env << 'EOF'
BLF_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
BLF_PAYMENT_URL=https://payment.blindference.xyz
BLF_ICL_URL=https://icl.blindference.xyz
BLF_RPC_URL=https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY
BLF_COFHE_URL=https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY
EOF

⚠️ Get a free Alchemy key at dashboard.alchemy.com The default URLs won't work without a real RPC endpoint.

2. Check Your Balance

blindference-agent balance

3. Buy Credits (if needed)

blindference-agent buy-package --id starter

Packages:

• starter — 10 calls
• pro — 100 calls
• enterprise — 1000 calls

4. Run Inference

blindference-agent infer --prompt "What is the capital of France?"

Expected output:

Initializing CoFHE...
Encrypting prompt...
Submitting to Payment Service...
Job submitted: abc-123
Polling for completion (this may take 1-3 minutes)...
Job COMPLETED

Result:
Paris

5. Start REST Server (Optional)

blindference-agent start --port 3000

Now you can call the API from any language:

curl -X POST http://localhost:3000/infer \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is 2+2?"}'

CLI Reference

blindference-agent infer

Run a single confidential inference job.

blindference-agent infer --prompt "Your prompt here" [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --prompt | The prompt to send (required) | — | | --model | Model ID to use | groq:llama-3.3-70b-versatile | | --currency | Payment currency (BLIND or cUSDC) | BLIND | | --insurance | Enable insurance for this job | false | | --payment-service | Payment Service URL | https://payment.blindference.xyz | | --icl | ICL URL | https://icl.blindference.xyz | | --rpc-url | Arbitrum Sepolia RPC URL | from BLF_RPC_URL env | | --ipfs-gateway | IPFS download gateway | https://ipfs.io/ipfs |

Example:

blindference-agent infer \
  --prompt "Explain quantum computing in simple terms" \
  --model groq:llama-3.3-70b-versatile \
  --currency BLIND

blindference-agent balance

Check your credit balances.

blindference-agent balance [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --payment-service | Payment Service URL | https://payment.blindference.xyz |

Example output:

BLIND Balance: 1000.0000
cUSDC Balance: 50.0000
Credit Packages: starter (10 calls), pro (100 calls)

blindference-agent buy-package

Purchase a credit package.

blindference-agent buy-package --id <package-id> [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --id | Package ID: starter, pro, enterprise (required) | — | | --payment-service | Payment Service URL | https://payment.blindference.xyz | | --rpc-url | Arbitrum Sepolia RPC URL | from BLF_RPC_URL env |

Example:

blindference-agent buy-package --id starter

blindference-agent start

Start the local REST server.

blindference-agent start [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --port | Server port | 3000 | | --payment-service | Payment Service URL | https://payment.blindference.xyz | | --icl | ICL URL | https://icl.blindference.xyz | | --rpc-url | Arbitrum Sepolia RPC URL | from BLF_RPC_URL env | | --ipfs-gateway | IPFS download gateway | https://ipfs.io/ipfs |

Endpoints:

| Method | Path | Description | |--------|------|-------------| | GET | /health | Server health check | | GET | /balance | Get credit balance | | POST | /infer | Submit inference job |

Example:

blindference-agent start --port 3000

SDK API

BlindferenceAgent

The main SDK class for programmatic use.

Constructor

import { BlindferenceAgent } from '@abhieren/blindference-agent'

const agent = new BlindferenceAgent({
  privateKey: '0xYOUR_PRIVATE_KEY',
  paymentServiceUrl: 'https://payment.blindference.xyz',
  rpcUrl: 'https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY',
  // Optional:
  iclUrl: 'https://icl.blindference.xyz',
  ipfsGateway: 'https://ipfs.io/ipfs',
  chainId: 421614,
  promptKeyStoreAddress: '0x...',
  cofheConfig: { /* CoFHE SDK config */ }
})

Methods

| Method | Description | Returns | |--------|-------------|---------| | initCofhe() | Initialize CoFHE client | Promise<void> | | infer(options) | Run inference job | Promise<InferenceResult> | | getBalance(address?) | Get credit balance | Promise<CreditBalance> | | getPackages() | List available packages | Promise<CreditPackage[]> | | purchasePackage(packageId) | Buy credit package | Promise<PurchaseResult> |

infer() Options

interface InferOptions {
  prompt: string                    // The prompt to send (required)
  modelId?: string                 // Model ID (default: groq:llama-3.3-70b-versatile)
  currency?: 'BLIND' | 'cUSDC'      // Payment currency (default: BLIND)
  insurance?: boolean               // Enable insurance (default: false)
}

infer() Result

interface InferenceResult {
  jobId: string
  taskId: string
  status: 'COMPLETED' | 'FAILED' | 'REJECTED'
  output?: string                   // Decrypted plaintext (only if COMPLETED)
  outputCid?: string                // IPFS CID of encrypted output
  commitmentHash?: string          // On-chain commitment hash
}

Full Example

import { BlindferenceAgent } from '@abhieren/blindference-agent'

async function main() {
  const agent = new BlindferenceAgent({
    privateKey: process.env.BLF_PRIVATE_KEY!,
    paymentServiceUrl: 'https://payment.blindference.xyz',
    rpcUrl: process.env.BLF_RPC_URL!
  })

  await agent.initCofhe()

  const result = await agent.infer({
    prompt: 'What is the capital of France?',
    modelId: 'groq:llama-3.3-70b-versatile',
    currency: 'BLIND'
  })

  if (result.status === 'COMPLETED') {
    console.log('Answer:', result.output)
  } else {
    console.error('Job failed:', result.status)
  }
}

main().catch(console.error)

REST Server

The REST server wraps the SDK for language-agnostic integration.

Start the Server

blindference-agent start --port 3000

Endpoints

GET /health

Health check.

Response:

{ "status": "ok" }

GET /balance

Get credit balance.

Response:

{
  "blind": "1000.0000",
  "cusdc": "50.0000",
  "packages": ["starter", "pro"]
}

POST /infer

Submit an inference job.

Request:

{
  "prompt": "What is the capital of France?",
  "modelId": "groq:llama-3.3-70b-versatile",
  "currency": "BLIND",
  "insurance": false
}

Response:

{
  "jobId": "abc-123",
  "taskId": "task-456",
  "status": "PENDING"
}

GET /status/:jobId

Check job status.

Response:

{
  "jobId": "abc-123",
  "status": "COMPLETED",
  "output": "Paris",
  "outputCid": "Qm...",
  "commitmentHash": "0x..."
}

Python Client Example

import requests

# Start server first: blindference-agent start --port 3000

response = requests.post('http://localhost:3000/infer', json={
    'prompt': 'What is 2+2?'
})
result = response.json()
print(result['output'])  # "4"

Configuration

All configuration via environment variables prefixed with BLF_:

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | BLF_PRIVATE_KEY | ✅ | Your wallet private key (hex) | 0xabc123... | | BLF_PAYMENT_URL | ✅ | Payment Service URL | https://payment.blindference.xyz | | BLF_ICL_URL | ✅ | ICL API URL | https://icl.blindference.xyz | | BLF_RPC_URL | ✅ | Arbitrum Sepolia RPC | https://arb-sepolia.g.alchemy.com/v2/KEY | | BLF_COFHE_URL | | CoFHE RPC URL (defaults to BLF_RPC_URL) | Same as above | | BLF_CHAIN_ID | | Chain ID | 421614 | | BLF_IPFS_GATEWAY | | IPFS download gateway | https://ipfs.io/ipfs | | BLF_PINATA_JWT | | Pinata JWT for IPFS uploads | eyJ... | | BLF_PROMPT_KEY_STORE | | PromptKeyStore contract address | 0x... | | BLF_LOG_LEVEL | | Logging level | info | | BLF_MAX_POLL_ATTEMPTS | | Max polling attempts | 120 | | BLF_POLL_INTERVAL_MS | | Polling interval | 3000 | | BLF_GAS_MULTIPLIER | | Gas price multiplier | 1.2 | | BLF_CORS_ORIGINS | | CORS origins (for REST server) | * |

Create .env file:

cat > .env << 'EOF'
BLF_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
BLF_PAYMENT_URL=https://payment.blindference.xyz
BLF_ICL_URL=https://icl.blindference.xyz
BLF_RPC_URL=https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY
BLF_COFHE_URL=https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY
BLF_IPFS_GATEWAY=https://ipfs.io/ipfs
BLF_LOG_LEVEL=info
EOF

Python Interop

Subprocess

import subprocess
import json

result = subprocess.run(
    ['blindference-agent', 'infer', '--prompt', 'What is 2+2?', '--json'],
    capture_output=True, text=True
)
output = json.loads(result.stdout)
print(output['output'])  # "4"

HTTP Client

import requests

# Start server: blindference-agent start --port 3000

class BlindferenceClient:
    def __init__(self, base_url='http://localhost:3000'):
        self.base_url = base_url
    
    def infer(self, prompt, model_id='groq:llama-3.3-70b-versatile'):
        response = requests.post(f'{self.base_url}/infer', json={
            'prompt': prompt,
            'modelId': model_id
        })
        return response.json()

client = BlindferenceClient()
result = client.infer('What is the capital of France?')
print(result['output'])  # "Paris"

Troubleshooting

"Private key is required"

Create .env in your current directory:

cat > .env << 'EOF'
BLF_PRIVATE_KEY=0xYOUR_KEY
BLF_PAYMENT_URL=https://payment.blindference.xyz
EOF

"Payment Service URL is required"

Set the Payment Service URL:

export BLF_PAYMENT_URL=https://payment.blindference.xyz

"Insufficient credits"

1. Get BLIND from faucet
2. Purchase credits:

blindference-agent buy-package --id starter

CoFHE initialization hangs

ZK proof generation takes 10-30 seconds. Do not interrupt.

If it hangs indefinitely:

• Check your RPC URL is valid (not the default placeholder)
• Ensure you have testnet ETH for gas
• Try with debug logging: BLF_LOG_LEVEL=debug blindference-agent infer --prompt "test"

"Polling timed out"

The job may still be processing. Check the Payment Service dashboard:

curl https://payment.blindference.xyz/v1/jobs/YOUR_JOB_ID

Or check if quorum nodes are active:

curl https://icl.blindference.xyz/health

"IPFS download failed"

The multi-gateway fallback tries: ipfs.io → pinata.cloud → dweb.link

If all fail:

• Wait 30-60 seconds for IPFS propagation
• Check your BLF_IPFS_GATEWAY env var
• Verify the job actually completed (not FAILED)

"Invalid CoFHE RPC URL"

You must set a real Alchemy/Infura URL. The default is a placeholder:

export BLF_RPC_URL='https://arb-sepolia.g.alchemy.com/v2/YOUR_REAL_KEY'
export BLF_COFHE_URL='https://arb-sepolia.g.alchemy.com/v2/YOUR_REAL_KEY'

Debug Mode

BLF_LOG_LEVEL=debug blindference-agent infer --prompt "test"

Links

• NPM Package
• GitHub Repository
• Blindference Network
• Documentation
• Blindference Node — Run a compute node
• Payment Service
• ICL API

License

MIT — see LICENSE.