@zkclaw/credentials 1.0.0 → 1.0.1

package/src/noir-lib/src/rlp/mod.nr

@@ -0,0 +1,128 @@
+use dep::std::wrapping_sub;
+
+pub global RLP_DATA_TYPE_STRING = 0;
+pub global RLP_DATA_TYPE_LIST = 1;
+
+pub struct RlpFragment {
+    pub offset: u32,
+    pub length: u32,
+    pub data_type: u32,
+}
+
+pub unconstrained fn decode_rlp_list_fragments<let NODE_LEN: u32, let MAX_FIELDS: u32>(
+    rlp_header: RlpFragment,
+    node: [u8; NODE_LEN],
+) -> BoundedVec<RlpFragment, MAX_FIELDS> {
+    let node_len = rlp_header.length + rlp_header.offset;
+    let mut rlp_list = BoundedVec::new();
+    let mut curr_offset = rlp_header.offset;
+    for _ in 0..MAX_FIELDS {
+        if (curr_offset < node_len) {
+            let field_prefix = node[curr_offset];
+
+            let field_offset = if field_prefix < 0x80 { 0 } else { 1 };
+            let field_length = if field_prefix < 0x80 {
+                1
+            } else {
+                wrapping_sub(field_prefix as u32, 0x80)
+            };
+
+            rlp_list.push(
+                RlpFragment {
+                    offset: curr_offset + field_offset,
+                    length: field_length,
+                    data_type: RLP_DATA_TYPE_STRING,
+                },
+            );
+
+            curr_offset += field_length + field_offset;
+        }
+    }
+
+    rlp_list
+}
+
+pub unconstrained fn decode_rlp_header<let NODE_LEN: u32>(node: [u8; NODE_LEN]) -> RlpFragment {
+    let (prefix, data) = node.as_slice().pop_front();
+
+    if (prefix < 0x80) {
+        // 1 byte
+        RlpFragment { offset: 0 as u32, length: 1 as u32, data_type: RLP_DATA_TYPE_STRING }
+    } else if (prefix < 0xb8) {
+        // 0-55 byte string
+        RlpFragment {
+            offset: 1,
+            length: wrapping_sub(prefix, 0x80) as u32,
+            data_type: RLP_DATA_TYPE_STRING,
+        }
+    } else if (prefix < 0xc0) {
+        // > 55 byte string
+        RlpFragment {
+            offset: wrapping_sub(1 + prefix, 0xb7) as u32,
+            length: extract_payload_len(data, wrapping_sub(prefix, 0xb7) as u32),
+            data_type: RLP_DATA_TYPE_STRING,
+        }
+    } else if (prefix < 0xf8) {
+        // 0-55 byte array
+        RlpFragment {
+            offset: 1,
+            length: wrapping_sub(prefix, 0xc0) as u32,
+            data_type: RLP_DATA_TYPE_LIST,
+        }
+    } else {
+        // > 55 byte array
+        RlpFragment {
+            offset: wrapping_sub(1 + prefix, 0xf7) as u32,
+            length: extract_payload_len(data, wrapping_sub(prefix, 0xf7) as u32),
+            data_type: RLP_DATA_TYPE_LIST,
+        }
+    }
+}
+
+fn extract_payload_len(data: [u8], len: u32) -> u32 {
+    let data_len = data.len();
+    let mut node_len = 0;
+    for i in 0..2 {
+        if (i < len & i < data_len) {
+            node_len = data[i] as u32 + node_len * 256;
+        }
+    }
+
+    node_len
+}
+
+pub fn encode_rlp_string<let N: u32>(data: [u8; N]) -> [u8; N] {
+    let length = data.len();
+    let mut result = [0; N];
+
+    // Find first non-zero byte using for loop
+    let mut start_idx = 0;
+    for i in 0..N {
+        if (start_idx == 0) & (data[i] != 0) {
+            start_idx = i;
+        }
+    }
+
+    // If all zeros, return single zero byte
+    if (start_idx == 0) & (data[0] == 0) {
+        result[0] = 0x80;
+        result
+    }
+
+    let actual_length = length - start_idx;
+
+    if (actual_length == 1) & (data[start_idx] < 0x80) {
+        // Single byte < 0x80
+        result[0] = data[start_idx];
+    } else {
+        // 0-55 bytes string
+        result[0] = (0x80 + actual_length) as u8;
+        for i in 0..N {
+            if i < actual_length {
+                result[i + 1] = data[start_idx + i];
+            }
+        }
+    }
+
+    result
+}

package/src/utils/circuit.ts

@@ -0,0 +1,74 @@
+import type { CompiledCircuit, Noir } from '@noir-lang/noir_js'
+import type { UltraHonkBackend, BarretenbergVerifier, ProofData } from '@aztec/bb.js'
+
+type ProverModules = {
+  Noir: typeof Noir
+  UltraHonkBackend: typeof UltraHonkBackend
+}
+
+type VerifierModules = {
+  BarretenbergVerifier: typeof BarretenbergVerifier
+}
+
+export abstract class Circuit {
+  private proverPromise: Promise<ProverModules> | null = null
+  private verifierPromise: Promise<VerifierModules> | null = null
+
+  private circuit: CompiledCircuit
+  private vkey: Uint8Array
+
+  constructor(circuit: unknown, vkey: unknown) {
+    this.circuit = circuit as CompiledCircuit
+    // Convert vkey from JSON array to Uint8Array if needed
+    this.vkey = Array.isArray(vkey) ? new Uint8Array(vkey) : (vkey as Uint8Array)
+  }
+
+  async initProver(): Promise<ProverModules> {
+    if (!this.proverPromise) {
+      this.proverPromise = (async () => {
+        const [{ Noir }, { UltraHonkBackend }] = await Promise.all([
+          import('@noir-lang/noir_js'),
+          import('@aztec/bb.js'),
+        ])
+        return {
+          Noir,
+          UltraHonkBackend,
+        }
+      })()
+    }
+    return this.proverPromise
+  }
+
+  async initVerifier(): Promise<VerifierModules> {
+    if (!this.verifierPromise) {
+      this.verifierPromise = (async () => {
+        const { BarretenbergVerifier } = await import('@aztec/bb.js')
+        return { BarretenbergVerifier }
+      })()
+    }
+    return this.verifierPromise
+  }
+
+  async verify(proofData: ProofData) {
+    const { BarretenbergVerifier } = await this.initVerifier()
+
+    const verifier = new BarretenbergVerifier({ crsPath: process.env.TEMP_DIR })
+    const result = await verifier.verifyUltraHonkProof(proofData, this.vkey)
+
+    return result
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async generate(input: any) {
+    const { Noir, UltraHonkBackend } = await this.initProver()
+
+    const backend = new UltraHonkBackend(this.circuit.bytecode)
+    const noir = new Noir(this.circuit)
+
+    const { witness } = await noir.execute(input)
+
+    return await backend.generateProof(witness)
+  }
+
+  abstract parseData(publicInputs: string[]): unknown
+}

package/src/utils/index.ts

@@ -0,0 +1,59 @@
+import { recoverPublicKey } from 'viem'
+
+export async function getPublicKey(signature: `0x${string}`, messageHash: `0x${string}`) {
+  const pubKey = await recoverPublicKey({
+    hash: messageHash,
+    signature,
+  })
+  const pubKeyX = pubKey.slice(4, 68)
+  const pubKeyY = pubKey.slice(68)
+
+  return { pubKeyX, pubKeyY }
+}
+
+export function formatArray(
+  arr: string[],
+  formatFn: (item: string) => string[],
+  { length = 7, pad = 'end' }: { length?: number; pad?: 'start' | 'end' } = {}
+) {
+  const result: string[][] = []
+  for (const item of arr) {
+    result.push(formatFn(item))
+  }
+
+  while (result.length < length) {
+    if (pad === 'start') {
+      result.unshift(formatFn('0x00'))
+    } else {
+      result.push(formatFn('0x00'))
+    }
+  }
+
+  return result
+}
+
+export function formatHexArray(
+  hex: string,
+  {
+    chunkSize = 2,
+    length = 32,
+    pad = 'left',
+  }: { chunkSize?: number; length?: number; pad?: 'left' | 'right' } = {}
+) {
+  const str = hex.replace('0x', '')
+
+  const arr: string[] = []
+  for (let i = 0; i < str.length; i += chunkSize) {
+    arr.push(`0x${str.slice(i, i + chunkSize)}`)
+  }
+
+  while (arr.length < length) {
+    if (pad === 'left') {
+      arr.unshift('0x00')
+    } else {
+      arr.push('0x00')
+    }
+  }
+
+  return arr.slice(0, length)
+}

package/src/verifier.test.ts

@@ -0,0 +1,163 @@
+import { describe, test, expect } from 'bun:test'
+import { hashMessage } from 'viem'
+import {
+  AnonBalanceVerifier,
+  getVerifier,
+  ANON_TOKEN,
+  BALANCE_THRESHOLDS,
+} from './verifier'
+
+describe('AnonBalanceVerifier - Unit Tests', () => {
+  test('should export correct token configuration', () => {
+    // $ZKCLAW token on Base chain
+    expect(ANON_TOKEN.address).toBe('0x000000000000000000000000000000000000dead')
+    expect(ANON_TOKEN.chainId).toBe(8453) // Base
+    expect(ANON_TOKEN.balanceSlot).toBe(0)
+    expect(ANON_TOKEN.decimals).toBe(18)
+  })
+
+  test('should export correct balance thresholds', () => {
+    // 5,000 tokens with 18 decimals
+    expect(BALANCE_THRESHOLDS.POST).toBe(BigInt('5000000000000000000000'))
+    // 2,000,000 tokens with 18 decimals
+    expect(BALANCE_THRESHOLDS.PROMOTE).toBe(BigInt('2000000000000000000000000'))
+  })
+
+  test('should return singleton verifier instance', () => {
+    const verifier1 = getVerifier()
+    const verifier2 = getVerifier()
+    expect(verifier1).toBe(verifier2)
+  })
+
+  test('canPost returns correct values', () => {
+    const verifier = new AnonBalanceVerifier()
+
+    // Below threshold
+    expect(verifier.canPost(BigInt('4999000000000000000000'))).toBe(false)
+
+    // At threshold
+    expect(verifier.canPost(BigInt('5000000000000000000000'))).toBe(true)
+
+    // Above threshold
+    expect(verifier.canPost(BigInt('10000000000000000000000'))).toBe(true)
+  })
+
+  test('canPromote returns correct values', () => {
+    const verifier = new AnonBalanceVerifier()
+
+    // Below threshold
+    expect(verifier.canPromote(BigInt('1999999000000000000000000'))).toBe(false)
+
+    // At threshold
+    expect(verifier.canPromote(BigInt('2000000000000000000000000'))).toBe(true)
+
+    // Above threshold
+    expect(verifier.canPromote(BigInt('3000000000000000000000000'))).toBe(true)
+  })
+})
+
+describe('AnonBalanceVerifier - Network Tests', () => {
+  test('buildInput fetches storage proof from Base', async () => {
+    const verifier = new AnonBalanceVerifier()
+
+    // Use an address that holds some $ANON (found via on-chain lookup)
+    const testAddress = '0x0000000000000000000000000000000000000001'
+    const result = await verifier.buildInput(testAddress, BigInt(0))
+
+    expect(result.input.chainId).toBe('0x2105') // 8453 in hex
+    expect(result.input.tokenAddress).toBe(ANON_TOKEN.address)
+    expect(result.input.storageHash).toBeDefined()
+    expect(result.input.storageHash).toMatch(/^0x[a-fA-F0-9]{64}$/)
+    expect(result.input.storageProof).toBeDefined()
+    expect(result.input.storageProof.length).toBeGreaterThan(0)
+    expect(result.message).toBeDefined()
+
+    // Verify the proof structure
+    const proof = result.input.storageProof[0]
+    expect(proof.proof.length).toBeGreaterThan(0)
+    console.log('Storage proof depth:', proof.proof.length)
+    console.log('Storage value:', proof.value.toString())
+  }, 30000)
+})
+
+describe('AnonBalanceVerifier - Proof Tests', () => {
+  // These tests require a valid signature from a wallet that holds $ANON
+  // To run: set TEST_SIGNATURE and TEST_ADDRESS environment variables
+  // The signature should be over the message 'test' (using hashMessage('test'))
+  //
+  // NOTE: The old test address 0xe4dd432fe405891ab0118760e3116e371188a1eb
+  // no longer holds $ANON tokens. You need to provide credentials from
+  // a wallet that currently holds tokens.
+
+  const testSignature = process.env.TEST_SIGNATURE
+  const testAddress = process.env.TEST_ADDRESS
+
+  const shouldRunProofTests = testSignature && testAddress
+
+  test.skipIf(!shouldRunProofTests)('generates and verifies proof end-to-end', async () => {
+    const verifier = new AnonBalanceVerifier()
+
+    // Build input with storage proof from chain
+    // Note: We use a fixed message 'test' to match the pre-generated signature
+    const { input } = await verifier.buildInput(testAddress!, BigInt(1))
+
+    // Check if the address actually has a balance
+    const storageValue = input.storageProof[0].value
+    if (storageValue === BigInt(0)) {
+      console.log('⚠️  Test address has 0 balance - skipping proof generation')
+      console.log('    To run this test, provide TEST_ADDRESS with $ANON tokens')
+      return
+    }
+
+    console.log('Balance:', storageValue.toString())
+    console.log('Generating proof...')
+    console.time('generateProof')
+
+    // Generate proof using the test signature (signed over 'test' message)
+    const proof = await verifier.generateProof({
+      ...input,
+      signature: testSignature!,
+      messageHash: hashMessage('test'),
+    })
+
+    console.timeEnd('generateProof')
+
+    expect(proof.proof).toBeDefined()
+    expect(proof.proof.length).toBeGreaterThan(0)
+    expect(proof.publicInputs).toBeDefined()
+
+    console.log('Verifying proof...')
+    console.time('verifyProof')
+
+    // Verify the proof
+    const verified = await verifier.verifyProof(proof)
+
+    console.timeEnd('verifyProof')
+
+    expect(verified).toBe(true)
+
+    // Parse and validate the public data
+    const data = verifier.parseData(proof.publicInputs)
+    expect(data.chainId).toBe(ANON_TOKEN.chainId)
+
+    console.log('Proof verified! Data:', data)
+  }, 300000)
+
+  // If no test credentials, just log instructions
+  test.skipIf(shouldRunProofTests)('instructions for running proof tests', () => {
+    console.log(`
+To run proof generation tests, you need a wallet that holds $ANON tokens.
+
+1. Get the message to sign:
+   const verifier = new AnonBalanceVerifier()
+   const { message } = await verifier.buildInput(YOUR_ADDRESS, BigInt(1))
+
+2. Sign the message with your wallet (e.g., using ethers or viem)
+
+3. Run tests with environment variables:
+   TEST_ADDRESS=0x... TEST_SIGNATURE=0x... bun test
+
+Note: The signature must be from the wallet at TEST_ADDRESS which must hold $ANON tokens.
+    `)
+  })
+})

package/src/verifier.ts

@@ -0,0 +1,227 @@
+import {
+  type GetProofReturnType,
+  keccak256,
+  concat,
+  toHex,
+  pad,
+  createPublicClient,
+  http,
+  type PublicClient,
+} from 'viem'
+import { base } from 'viem/chains'
+
+// Use premium RPC if available, fallback to public
+const BASE_RPC_URL = process.env.BASE_RPC_URL || 'https://mainnet.base.org'
+import { formatArray, formatHexArray, getPublicKey } from './utils'
+import { Circuit } from './utils/circuit'
+import circuit from './circuit/target/anon_balance.json'
+import vkey from './circuit/target/vkey.json'
+
+// $ZKCLAW token on Base (hardcoded for SDK bundle compatibility)
+export const ZKCLAW_TOKEN = {
+  address: '0x8849386BCd0fA6B8fF484A4aAd9c374B2F7c4B07' as `0x${string}`,
+  chainId: 8453,
+  balanceSlot: 0, // Standard ERC20 balance slot
+  decimals: 18,
+}
+
+// Legacy alias for compatibility
+export const ANON_TOKEN = ZKCLAW_TOKEN
+
+// Balance thresholds (hardcoded for SDK bundle compatibility)
+export const BALANCE_THRESHOLDS = {
+  POST: BigInt('50000') * BigInt(10 ** 18),     // 50K tokens
+  PROMOTE: BigInt('20000000') * BigInt(10 ** 18), // 20M tokens
+}
+
+export type ProofData = {
+  proof: number[]
+  publicInputs: string[]
+}
+
+export type CredentialData = {
+  balance: string
+  chainId: number
+  blockNumber: string
+  tokenAddress: string
+  balanceSlot: string
+  storageHash: string
+}
+
+export type BuildInputResult = {
+  input: {
+    storageHash: string
+    storageProof: GetProofReturnType['storageProof']
+    chainId: string
+    blockNumber: string
+    tokenAddress: string
+    balanceSlot: string
+    verifiedBalance: string
+  }
+  message: string
+}
+
+export type GenerateProofInput = BuildInputResult['input'] & {
+  signature: string
+  messageHash: string
+}
+
+export class AnonBalanceVerifier extends Circuit {
+  private client: PublicClient
+
+  constructor() {
+    super(circuit, vkey)
+    this.client = createPublicClient({
+      chain: base,
+      transport: http(BASE_RPC_URL),
+    }) as PublicClient
+  }
+
+  /**
+   * Build the input data needed for proof generation.
+   * This fetches the current storage proof from the blockchain.
+   *
+   * @param address - The wallet address to prove balance for
+   * @param verifiedBalance - The balance threshold to prove (e.g., 5000 tokens)
+   */
+  async buildInput(address: string, verifiedBalance: bigint): Promise<BuildInputResult> {
+    const balanceSlotHex = pad(toHex(ZKCLAW_TOKEN.balanceSlot))
+    const storageKey = keccak256(concat([pad(address as `0x${string}`), balanceSlotHex]))
+
+    const block = await this.client.getBlock()
+    const ethProof = await this.client.getProof({
+      address: ZKCLAW_TOKEN.address,
+      storageKeys: [storageKey],
+      blockNumber: block.number,
+    })
+
+    const input = {
+      storageHash: ethProof.storageHash,
+      storageProof: ethProof.storageProof,
+      chainId: `0x${ZKCLAW_TOKEN.chainId.toString(16)}`,
+      blockNumber: `0x${block.number.toString(16)}`,
+      tokenAddress: ZKCLAW_TOKEN.address,
+      balanceSlot: balanceSlotHex,
+      verifiedBalance: `0x${verifiedBalance.toString(16)}`,
+    }
+
+    // Message to sign (excludes storageProof for brevity)
+    const message = JSON.stringify({ ...input, storageProof: undefined })
+
+    return { input, message }
+  }
+
+  /**
+   * Generate a ZK proof of token balance.
+   *
+   * @param args - Input data including signature and storage proof
+   */
+  async generateProof(args: GenerateProofInput): Promise<ProofData> {
+    const { pubKeyX, pubKeyY } = await getPublicKey(
+      args.signature as `0x${string}`,
+      args.messageHash as `0x${string}`
+    )
+
+    const storageProof = args.storageProof[0]
+    const nodes = storageProof.proof.slice(0, storageProof.proof.length - 1)
+    const leaf = storageProof.proof[storageProof.proof.length - 1]
+
+    const input = {
+      signature: formatHexArray(args.signature, { length: 64 }),
+      message_hash: formatHexArray(args.messageHash),
+      pub_key_x: formatHexArray(pubKeyX),
+      pub_key_y: formatHexArray(pubKeyY),
+      storage_hash: formatHexArray(args.storageHash),
+      storage_nodes: formatArray(
+        nodes,
+        (node) => formatHexArray(node, { length: 1080, pad: 'right' }),
+        { length: 5 }
+      ),
+      storage_leaf: formatHexArray(leaf, { length: 120, pad: 'right' }),
+      storage_depth: storageProof.proof.length,
+      storage_value: `0x${storageProof.value.toString(16)}`,
+      chain_id: args.chainId,
+      block_number: args.blockNumber,
+      token_address: args.tokenAddress,
+      balance_slot: args.balanceSlot,
+      verified_balance: args.verifiedBalance,
+    }
+
+    const proof = await super.generate(input)
+
+    return {
+      proof: Array.from(proof.proof),
+      publicInputs: proof.publicInputs,
+    }
+  }
+
+  /**
+   * Verify a ZK proof.
+   */
+  async verifyProof(proof: ProofData): Promise<boolean> {
+    return super.verify({
+      proof: new Uint8Array(proof.proof),
+      publicInputs: proof.publicInputs,
+    })
+  }
+
+  /**
+   * Parse the public inputs from a proof into readable data.
+   */
+  parseData(publicInputs: string[]): CredentialData {
+    const balance = BigInt(publicInputs[0]).toString()
+    const chainId = Number(BigInt(publicInputs[1]).toString())
+    const blockNumber = BigInt(publicInputs[2]).toString()
+    const tokenAddress = `0x${publicInputs[3].slice(-40)}`
+    const balanceSlot = BigInt(publicInputs[4]).toString()
+    const storageHash = `0x${publicInputs
+      .slice(5, 5 + 32)
+      .map((b) => BigInt(b).toString(16).padStart(2, '0'))
+      .join('')}`
+
+    return {
+      balance,
+      chainId,
+      blockNumber,
+      tokenAddress,
+      balanceSlot,
+      storageHash,
+    }
+  }
+
+  /**
+   * Check if the proven balance meets the POST threshold.
+   */
+  canPost(balance: bigint): boolean {
+    return balance >= BALANCE_THRESHOLDS.POST
+  }
+
+  /**
+   * Check if the proven balance meets the PROMOTE threshold.
+   */
+  canPromote(balance: bigint): boolean {
+    return balance >= BALANCE_THRESHOLDS.PROMOTE
+  }
+
+  /**
+   * Get balance tier from proof data.
+   */
+  getBalanceTier(proofData: ProofData): 'none' | 'post' | 'promote' {
+    const data = this.parseData(proofData.publicInputs)
+    const balance = BigInt(data.balance)
+
+    if (this.canPromote(balance)) return 'promote'
+    if (this.canPost(balance)) return 'post'
+    return 'none'
+  }
+}
+
+// Singleton instance
+let verifierInstance: AnonBalanceVerifier | null = null
+
+export function getVerifier(): AnonBalanceVerifier {
+  if (!verifierInstance) {
+    verifierInstance = new AnonBalanceVerifier()
+  }
+  return verifierInstance
+}