Add lit-bridge: permissionless cross-chain token bridge

lit-bridge/.env.example

@@ -0,0 +1,125 @@
+# ===========================================================================
+# REQUIRED for setup + deploy — fill these in before running the setup script
+# ===========================================================================
+
+# Your ACCOUNT-LEVEL (master) Lit API key — the one issued when you first
+# created the account, not a scoped usage key. Setup calls management endpoints
+# (create account/PKP, add_action, add_group) that reject scoped keys. Get it
+# from https://dashboard.chipotle.litprotocol.com.
+LIT_API_KEY=
+
+# EOA used to deploy BridgeConfigRegistry (on Base Sepolia) and BridgeToken on
+# BOTH Base Sepolia and Arbitrum Sepolia, and to wire bridge partners. Needs gas
+# on both chains — grab Sepolia ETH from a faucet and bridge a little to Arb
+# Sepolia. NEVER commit the filled-in .env (it's gitignored).
+DEPLOYER_PRIVATE_KEY=
+
+# Raw provider API keys (NOT full URLs). The action constructs the hostname for
+# each chain from a code-resident map and only the key is secret — so setup
+# encrypts JUST these against the bridge signing account and stores the
+# ciphertext in the registry. Each default chain ships with both, giving the
+# recommended quorum of 2 (a single lying RPC can't forge a mint).
+#   Alchemy:  https://dashboard.alchemy.com  (enable Base + Arb Sepolia)
+#   Infura:   https://developer.metamask.io   (enable Base + Arb Sepolia)
+ALCHEMY_API_KEY=
+INFURA_API_KEY=
+
+
+# ===========================================================================
+# Defaults — change only if you know why
+# ===========================================================================
+#
+# (The lit-bridge service itself is stateless — no database. All bridge state
+# lives on-chain: burns are BurnInitiated events, completions are usedBurnIds /
+# BridgeMint on the destination. The service just hosts the UI + a config
+# endpoint, so it needs no secrets to run.)
+
+LIT_API_BASE=https://api.chipotle.litprotocol.com
+
+# Chain where BridgeConfigRegistry lives (the control plane). Base Sepolia for
+# the demo; Base mainnet (8453) in production.
+REGISTRY_CHAIN_ID=84532
+
+# Broadcast RPCs used by forge to deploy + send txs. These do NOT need to be
+# keyed — the public endpoints work. The action's *verification* reads go
+# through the encrypted Alchemy/Infura keys above; these just broadcast.
+BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
+ARBITRUM_SEPOLIA_RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
+
+# Per-chain config written into the registry by setup. Quorum 2 = both the
+# Alchemy and Infura reads must agree. minConfirmations is floored in the action
+# code regardless, so lowering it below the floor has no effect.
+CHAIN_QUORUM=2
+MIN_CONFIRMATIONS=5
+
+# Bridge fee (option 1 — token skim). On mint, the destination token mints
+# (feeFlat + amount*feeBps/10000) to FEE_TREASURY and the remainder to the
+# recipient. Set FEE_TREASURY empty to default to the deployer. feeBps is capped
+# at 500 (5%) on-chain. The skimmed token accrues in the treasury; converting it
+# to gas to refill the oracle is a later, off-chain concern.
+FEE_TREASURY=
+FEE_FLAT=0
+FEE_BPS=10
+
+# Registry owner. Defaults to the deployer EOA for dev; set to the Base Safe in
+# production, then it governs all config writes (two-step transfer).
+REGISTRY_OWNER=
+
+# Phase 6 governance: the Base Safe that will own the registry, both tokens, the
+# fee treasury, and (chain-secured) the signing account. Used by handoffToSafe.js.
+SAFE_ADDRESS=
+
+# Demo token constructor args. Initial supply is minted only on
+# INITIAL_SUPPLY_NETWORK; the other chain starts at zero and gets tokens by
+# bridging.
+TOKEN_NAME=Bridge Coin
+TOKEN_SYMBOL=BRDG
+INITIAL_SUPPLY=1000000
+INITIAL_SUPPLY_NETWORK=baseSepolia
+
+# Public base URL the service advertises (used in UI / API responses).
+PUBLIC_BASE_URL=http://localhost:8000
+
+# Chains shown in the bridging UI (GET /api/config). A JSON array of
+# {chain_id, name, rpc, token, explorer}: `rpc` is a PUBLIC read endpoint the
+# browser hits for balances/gas/usedBurnIds, `token` is the BridgeToken address
+# on that chain, `explorer` is the block explorer base URL (for tx links). The
+# UI's bridge form is hidden until at least two chains are listed.
+#   ⚠ NO SECRETS: every field here is served verbatim to the browser and the
+#     `rpc` is fetched client-side, so it MUST be a public, unauthenticated
+#     endpoint — never an Alchemy/Infura/keyed URL (that key would be exposed to
+#     every visitor). Use the public RPCs (mainnet.base.org, arb1.arbitrum.io).
+#   ⚠ SAME NATIVE ASSET: only list chains that share a native token (all
+#     ETH-native L2s today). The relayer's auto-mint compares prepaid wei to
+#     destination-gas wei 1:1, so a cross-native pair (e.g. an ETH chain +
+#     Polygon) burns fine in the UI but never auto-relays. See
+#     docs/bringing-a-token-to-new-chains.md ("Same native asset").
+# Example:
+# CHAINS_JSON=[{"chain_id":8453,"name":"Base","rpc":"https://mainnet.base.org","token":"0xYourBaseToken","explorer":"https://basescan.org"},{"chain_id":42161,"name":"Arbitrum","rpc":"https://arb1.arbitrum.io/rpc","token":"0xYourArbToken","explorer":"https://arbiscan.io"}]
+CHAINS_JSON=
+
+
+# ===========================================================================
+# Auto-filled by setup — leave blank, the script populates them (and injects
+# BRIDGE_PKP_ID + REGISTRY_ADDRESS into action/bridgeAction.js before pinning
+# the CID)
+# ===========================================================================
+
+# Dedicated signing account (Option B). Its ADDRESS is the oracle every
+# BridgeToken trusts — stable across action logic upgrades.
+BRIDGE_PKP_ID=
+ORACLE_ADDRESS=
+
+# Deployed BridgeConfigRegistry address on the registry chain.
+REGISTRY_ADDRESS=
+
+# The action's IPFS CID + the group/usage key authorizing it to run and to
+# decrypt the registry's RPC secrets. Usage key is shown ONCE by the server;
+# re-running setup mints a fresh one and overwrites this line.
+ACTION_IPFS_CID=
+GROUP_ID=
+LIT_USAGE_API_KEY=
+
+# Deployed BridgeToken addresses per chain.
+BRIDGE_TOKEN_BASE_SEPOLIA=
+BRIDGE_TOKEN_ARB_SEPOLIA=

lit-bridge/.gitignore

@@ -0,0 +1,6 @@
+/target
+.env
+.env.*
+!.env.example
+scripts/node_modules
+action/bridgeAction.built.js