Developer Guide

npm install @human.tech/clean.sdk

import { HumanTechBridge, ACTIVE_DEPLOYMENT_ID, getDeployment } from '@human.tech/clean.sdk'
 
const bridge = new HumanTechBridge({
  l1RpcUrl: process.env.L1_RPC_URL, // required; your own endpoint. Keep keys server-side.
  deployment: ACTIVE_DEPLOYMENT_ID, // optional, defaults to the active deployment
  domain: window.location.origin,   // optional in the browser, required in Node.js
  apiUrl: 'https://shield.human.tech', // optional, this is the default
  // l2NodeUrl: '...'               // optional, overrides the deployment default
})

const { token, userId, user } = await bridge.authenticate({
  l1Address: '0x...',              // Ethereum address
  l2Address: '0x...',              // Aztec address
  domain: window.location.host,
  uri: window.location.origin,
  chainId: l1ChainId,              // from getDeployment(ACTIVE_DEPLOYMENT_ID).network.l1ChainId
  signMessage: (msg) => wallet.signMessage(msg),
  // optional: nonce, l1LoginMethod, l1WalletProvider, l2LoginMethod, l2WalletProvider
})
 
// Persist the JWT, then restore it on the next page load:
bridge.setAuthToken(token)
 
// Non-throwing session check. Call on startup to detect a stale JWT:
const session = await bridge.verifySession()
if (!session.valid) {
  // session.reason: 'no_token' | 'token_expired' | 'user_not_found' | 'network_error'
}

import type { WalletAdapterInterface } from '@human.tech/clean.sdk'
 
const walletAdapter: WalletAdapterInterface = {
  // L2 TokenBridge address this adapter acts on
  bridgeAddress: '0x...',
 
  // Run an L2 contract call; return the resulting tx hash
  async executeCall(contractAddress, method, args, options) {
    const txHash = await myAztecWallet.call(contractAddress, method, args, options)
    return { txHash }
  },
 
  // Private L2 -> L1 exit
  async executeWithdrawToL1Private(l1Address, amount, nonce, cleanHands, passport, l2Address) {
    const { txHash, l2BlockNumber } = await myAztecWallet.withdrawPrivate(/* ... */)
    return { txHash, l2BlockNumber }
  },
 
  // Public L2 -> L1 exit (same signature as the private variant)
  async executeWithdrawToL1Public(l1Address, amount, nonce, cleanHands, passport, l2Address) {
    const { txHash, l2BlockNumber } = await myAztecWallet.withdrawPublic(/* ... */)
    return { txHash, l2BlockNumber }
  },
 
  // Optional: register the bridged token with the wallet's PXE after claiming
  async registerToken(tokenAddress) { /* ... */ },
}

const result = await bridge.bridgeL1ToL2({
  token: 'USDC',          // symbol or L1 contract address
  amount: '100.00',       // human-readable amount
  l1Address: '0x...',
  l2Address: '0x...',
  isPrivate: true,        // private (shielded) or public claim on L2
  fuel: {
    enabled: true,
    amount: '5',          // token amount (native decimals) to swap into FeeJuice
    fuelType: 'private',  // 'public' | 'private'; must be 'private' in private mode
    slippageBps: 300,     // optional, default 300 (3%)
  },
  // fuelQuote is optional. Omit it and the SDK builds the V4 quote internally
  sendTransaction: (tx) => wallet.sendTransaction(tx),
  walletAdapter: aztecWalletAdapter, // implements WalletAdapterInterface (see "Wallet Adapter")
  signMessage: (msg) => wallet.signMessage(msg),
  signTypedData: (addr, json) => wallet.signTypedData(addr, JSON.parse(json)), // Permit2
  onEvent: (event) => console.log(event.type, event),
})
// result: { operationId, l1TxHash, l2TxHash, l1TxUrl, l2TxUrl }

const result = await bridge.withdrawL2ToL1({
  token: 'cUSDC',         // L2 symbol or L2 contract address
  amount: '50.00',
  l1Address: '0x...',     // L1 recipient
  l2Address: '0x...',
  isPrivate: true,
  sendTransaction: (tx) => wallet.sendTransaction(tx),
  walletAdapter: aztecWalletAdapter,
  signMessage: (msg) => wallet.signMessage(msg),
  onEvent: (event) => console.log(event.type, event),
})

// Full status: binding, attester config
const status = await bridge.getAttestationStatus()
 
// Lightweight pre-checks. No nonce consumed
const poch = await bridge.checkPochEligibility()
if (!poch.eligible) {
  const passport = await bridge.checkPassportEligibility()
  // passport.eligible, passport.score, passport.maxAmount
}

const ops = await bridge.getOperations()
const op = await bridge.getOperation(operationId) // fetch a single operation by ID
 
const result = await bridge.resume(operationId, {
  signMessage: (msg) => wallet.signMessage(msg),
  sendTransaction: (tx) => wallet.sendTransaction(tx), // needed for L2->L1 resume
  walletAdapter: aztecWalletAdapter,                   // needed for L1->L2 resume
  l1Address: '0x...',                                  // optional hint
  l2Address: '0x...',                                  // optional hint
  onEvent: (event) => console.log(event.type, event),
})

const quote = await bridge.getFuelQuote({
  token: 'USDC',      // symbol or L1 contract address
  fuelAmount: '5',    // token amount in NATIVE decimals (not USD)
  slippageBps: 300,   // optional, default 300 (3%)
})
// quote: { expectedOutput, minOutput, poolKeys, zeroForOnes }

import { BridgeApiError } from '@human.tech/clean.sdk'
 
try {
  await bridge.bridgeL1ToL2(params)
} catch (err) {
  if (err instanceof BridgeApiError) {
    console.error(err.friendlyMessage) // human-readable
    console.error(err.status)          // HTTP status code
    console.error(err.parsedBody)      // parsed JSON body, or null
  }
}