# ShadowLine Complete AI Agent & Developer Reference (`llms-full.txt`)

> Comprehensive technical specification, contract ABIs, REST API documentation, and code integration guide for autonomous AI agents and web3 developers building on ShadowLine.

---

## 1. Protocol Architecture & Overview
ShadowLine is a decentralized asset shielding protocol built on Zama's Fully Homomorphic Encryption Virtual Machine (fhEVM). It acts as a confidential wrapper layer for ERC-20 tokens, adhering to the ERC-7984 confidential token standard.

### Why Autonomous AI Agents Need ShadowLine
Autonomous AI agents executing DeFi trading strategies, payroll, or DAO treasury management face severe MEV (Maximal Extractable Value) exploitation and strategy front-running when holding public ERC-20 tokens. By shielding tokens into ERC-7984 confidential wrappers (`cTokens`), an AI agent can:
1. Hold encrypted treasury balances on-chain.
2. Execute confidential peer-to-peer transfers without revealing transaction amounts to blockchain observers or MEV searchers.
3. Decrypt holdings locally inside trusted memory using EIP-712 read-only permits.

---

## 2. REST API Reference

ShadowLine provides a wallet-free, public HTTP REST API for discovering verified ERC-20 ↔ ERC-7984 wrapper pairs.

### Endpoint: `GET /api/registry`
Queries the on-chain `WrappersRegistry` contract and returns all registered token pairs.

#### Query Parameters:
- `chain` (optional): `"sepolia"` (default) or `"mainnet"`.

#### Example Request:
```bash
curl -s "https://shadow-line.vercel.app/api/registry?chain=sepolia"
```

#### Response JSON Schema:
```json
{
  "pairs": [
    {
      "tokenAddress": "0x9b5Cd13b8eFbB58Dc25A05CF411D8056058aDFfF",
      "confidentialTokenAddress": "0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639",
      "symbol": "USDC",
      "confidentialSymbol": "cUSDC",
      "name": "USD Coin",
      "decimals": 6,
      "wrapperDecimals": 6,
      "isValid": true,
      "source": "registry"
    }
  ],
  "total": 1,
  "chain": "sepolia",
  "registryAddress": "0x2f0750Bbb0A246059d80e94c454586a7F27a128e",
  "timestamp": 1751740000000,
  "source": "on-chain"
}
```

---

## 3. Decimal Scaling Rules (CRITICAL FOR AGENTS)
When building automated transactions, agents must adhere to strict decimal scaling:
- **Shield (Deposit):** The input amount MUST be formatted using the **underlying ERC-20 token's decimals** (e.g., 6 for USDC, 18 for WETH/ZAMA).
- **Unshield (Withdraw) & Confidential Transfers:** The input amount MUST be formatted using the **wrapper's fixed 6-decimal scale (`euint64`)**, regardless of what decimals the underlying ERC-20 uses.
- **Why?** Zama's fhEVM represents encrypted token balances as 64-bit unsigned homomorphic integers (`euint64`). To prevent overflow and maintain uniform computation costs across all assets, all ERC-7984 wrappers normalize balances to 6 decimal places.

---

## 4. Smart Contract ABIs for AI Agents

### WrappersRegistry Contract
- **Sepolia Address:** `0x2f0750Bbb0A246059d80e94c454586a7F27a128e`
- **Mainnet Address:** `0xeb5015fF021DB115aCe010f23F55C2591059bBA0`

```json
[
  {
    "name": "getTokenConfidentialTokenPairsLength",
    "type": "function",
    "stateMutability": "view",
    "inputs": [],
    "outputs": [{ "name": "", "type": "uint256" }]
  },
  {
    "name": "getTokenConfidentialTokenPairsSlice",
    "type": "function",
    "stateMutability": "view",
    "inputs": [
      { "name": "fromIndex", "type": "uint256" },
      { "name": "toIndex", "type": "uint256" }
    ],
    "outputs": [
      {
        "type": "tuple[]",
        "components": [
          { "name": "tokenAddress", "type": "address" },
          { "name": "confidentialTokenAddress", "type": "address" },
          { "name": "isValid", "type": "bool" }
        ]
      }
    ]
  }
]
```

### ERC-7984 Confidential Wrapper Contract (`cToken`)
> **WARNING FOR AI AGENTS:** Do NOT call `transfer` or `unwrap` using raw plaintext numbers or padded hex strings in Viem/Ethers! In FHEVM, confidential transfers and unshielding require client-side WASM encryption (`euint64`) and FHE input proof generation. Always use `ShadowlineAgentHarness` or `@zama-fhe/sdk` to execute these methods.

```json
[
  {
    "name": "wrap",
    "type": "function",
    "stateMutability": "nonpayable",
    "inputs": [
      { "name": "to", "type": "address" },
      { "name": "amount", "type": "uint256" }
    ],
    "outputs": [{ "name": "", "type": "bytes32" }]
  },
  {
    "name": "confidentialBalanceOf",
    "type": "function",
    "stateMutability": "view",
    "inputs": [{ "name": "account", "type": "address" }],
    "outputs": [{ "name": "", "type": "bytes32" }]
  }
]
```

---

## 5. Autonomous Agent Integration Code (Headless Node.js Harness)

To enable true autonomous execution without a browser, ShadowLine provides a headless execution harness (`ShadowlineAgentHarness`) in `@shadowline/agent-tools` (`src/lib/agent-harness.ts`). It wraps `@zama-fhe/sdk` in Node worker pool mode (`node()`) and handles EIP-712 permit signing, KMS decryption, and FHE client-side encryption automatically.

```typescript
import { ShadowlineAgentHarness } from '@/lib/agent-harness';

// 1. Initialize Headless Agent Harness
const agent = new ShadowlineAgentHarness({
  privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
  relayerApiKey: process.env.ZAMA_RELAYER_API_KEY || 'YOUR_API_KEY',
});

await agent.init();

// 2. Discover Verified Pairs
const pairs = await agent.getPairs();
const usdcPair = pairs.find(p => p.symbol === 'USDC') || pairs[0];

// 3. Shield (Wrap) ERC-20 -> ERC-7984
// NOTE: Shielding amount MUST use underlying ERC-20 decimals (e.g. 6 for USDC)
const shieldHash = await agent.shield(usdcPair.confidentialTokenAddress, '10.5');
console.log('Shielded in tx:', shieldHash);

// 4. Check Confidential Balance
// Automatically generates EIP-712 permit, queries Zama KMS, and decrypts in WASM
const balance = await agent.getConfidentialBalance(usdcPair.confidentialTokenAddress);
console.log('Decrypted Confidential Balance:', balance);

// 5. Confidential Transfer
// Automatically encrypts amount into an FHE euint64 handle and generates FHE input proof
// NOTE: Transfer amount MUST use fixed 6 decimals scale!
const transferHash = await agent.transfer(usdcPair.confidentialTokenAddress, '0xRecipientAddress', '5.0');
console.log('Confidential transfer tx:', transferHash);

// 6. Unshield (Unwrap) ERC-7984 -> ERC-20
// NOTE: Unshield amount MUST use fixed 6 decimals scale!
const unshieldHash = await agent.unshield(usdcPair.confidentialTokenAddress, '5.0');
console.log('Unshield requested in tx:', unshieldHash);
```