mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
815 lines
54 KiB
HTML
815 lines
54 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hip-0101</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hip-0101.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hip-0101">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hip-0101.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hip-0101</h1><p class="lede">HIP-101: Hanzo-Lux Bridge Protocol Integration. Status Final. Hanzo architectural specification.</p><h1>HIP-0101: Hanzo-Lux Bridge Protocol Integration</h1>
|
|
<h2>Abstract</h2>
|
|
<p>This proposal specifies a lock-and-mint bridge between Hanzo's sovereign L1 chain (HIP-0024, chain ID 36963) and the Lux Network. The bridge enables bidirectional asset transfer ($AI, wrapped LUX, stablecoins, NFT model certificates) secured by a 7-of-11 multi-signature validator set drawn from both networks. It serves as the economic backbone of the AI compute marketplace, connecting Hanzo's AI execution environment to Lux's settlement and DeFi infrastructure.</p>
|
|
<p>The protocol defines three layers: a <strong>transport layer</strong> (cross-chain message passing with Merkle proof verification), a <strong>consensus layer</strong> (shared validator set coordination using ML-DSA-65 threshold signatures), and a <strong>settlement layer</strong> (lock-mint-burn-unlock state machine with HMM invoice integration). Together these layers provide sub-10-second bridge finality, post-quantum security from day one, and native integration with Lux's multi-consensus architecture.</p>
|
|
<h2>Design Philosophy</h2>
|
|
<p>This section explains the reasoning behind each major design decision. A bridge is critical infrastructure. Every choice must be justified from first principles, not by convention or convenience.</p>
|
|
<h3>Why Not Use Existing Bridges (Wormhole, LayerZero)</h3>
|
|
<p>Third-party bridges like Wormhole and LayerZero introduce trust assumptions that do not match the Hanzo-Lux security model:</p>
|
|
<ul><li><strong>External guardian sets.</strong> Wormhole relies on a set of 19 Guardians operated</li></ul>
|
|
<p> by third-party entities. LayerZero relies on independent oracle and relayer separation. In both cases, Hanzo and Lux must trust external parties with no stake in either network. The Hanzo-Lux bridge uses validators drawn directly from both chains, with staking requirements that align economic incentives.</p>
|
|
<ul><li><strong>No native state verification.</strong> Third-party bridges treat all chains as</li></ul>
|
|
<p> opaque message buses. The Hanzo-Lux bridge has direct access to chain state on both sides: it can verify Merkle proofs against both Hanzo's state trie and Lux's C-Chain state trie without relying on external attestation.</p>
|
|
<ul><li><strong>Incompatible cryptography.</strong> Third-party bridges use ECDSA. Hanzo and Lux</li></ul>
|
|
<p> use ML-DSA-65 (post-quantum). Adapting third-party bridges to PQC would require forking their guardian/oracle software and maintaining a custom build indefinitely. Building natively avoids this maintenance burden.</p>
|
|
<ul><li><strong>Latency overhead.</strong> Third-party bridges add confirmation delays for their</li></ul>
|
|
<p> own consensus (Wormhole: ~15-20s for guardian consensus; LayerZero: variable based on oracle confirmation). The native bridge achieves 5-9 seconds end-to-end because validators are co-located with chain nodes.</p>
|
|
<ul><li><strong>No HMM integration.</strong> The bridge carries structured compute invoice payloads</li></ul>
|
|
<p> (HIP-0008) that third-party bridges have no awareness of. Building natively allows the bridge to validate invoice structure, enforce settlement rules, and trigger Lux-side payment flows without external adapter contracts.</p>
|
|
<h3>Why Post-Quantum From Day One</h3>
|
|
<p>Quantum computing threatens all current bridge cryptography. ECDSA, the signature scheme used by every major bridge today, is broken by Shor's algorithm on a sufficiently large quantum computer. The question is not whether ECDSA will be broken, but when.</p>
|
|
<p>Bridges are especially vulnerable because they hold locked assets. A "harvest now, decrypt later" attack --- recording bridge messages today and forging signatures once quantum hardware matures --- could drain bridge vaults retroactively. Starting with ML-DSA-65 (CRYSTALS-Dilithium, FIPS 204) eliminates this attack vector entirely.</p>
|
|
<p>The cost of starting with PQC is larger signature sizes (~2.4 KB for ML-DSA-65 vs ~64 bytes for ECDSA) and slightly higher verification cost. Both Hanzo and Lux have ML-DSA-65 verification as a native precompile, so the on-chain cost is manageable. The off-chain cost (bandwidth for relaying signatures) is negligible given modern network speeds.</p>
|
|
<p>Starting post-quantum avoids the complexity of a future migration. Hybrid schemes (ECDSA + PQC) are transitional by design and add implementation surface area. Since the bridge is new infrastructure with no backward-compatibility requirement, there is no reason to support legacy cryptography.</p>
|
|
<h2>Specification</h2>
|
|
<h3>Bridge Architecture</h3>
|
|
<p>The bridge consists of three components: on-chain vaults (one per chain), an off-chain relayer service, and the shared validator set.</p>
|
|
<pre><code>Hanzo L1 (chain 36963) Bridge Validators Lux Network
|
|
┌──────────────────┐ ┌───────────────────┐ ┌──────────────────┐
|
|
│ │ Lock event │ │ Mint tx │ │
|
|
│ Lock Vault │───────────>│ Relayer Service │─────────>│ Mint Vault │
|
|
│ (Solidity) │ │ (off-chain) │ │ (C-Chain EVM) │
|
|
│ │<───────────│ │<─────────│ │
|
|
│ │ Unlock tx │ 7-of-11 ML-DSA │ Burn evt │ │
|
|
└──────────────────┘ │ threshold sigs │ └──────────────────┘
|
|
└───────────────────┘
|
|
│
|
|
┌───────────┼───────────┐
|
|
│ │ │
|
|
┌────┴────┐ ┌────┴────┐ ┌────┴────┐
|
|
│Relayer 1│ │Relayer 2│ │Relayer 3│
|
|
│(leader) │ │(follower│ │(follower│
|
|
└─────────┘ └─────────┘ └─────────┘
|
|
Raft consensus for leader election</code></pre>
|
|
<h4>Transfer Flow (Hanzo to Lux)</h4>
|
|
<pre><code>User Hanzo L1 Relayer Validators Lux C-Chain
|
|
│ │ │ │ │
|
|
│── lock(AI, 1000) ──────>│ │ │ │
|
|
│ │── Lock event ─>│ │ │
|
|
│ │ │── verify proof ─>│ │
|
|
│ │ │ │── sign msg ────>│
|
|
│ │ │<── 7 sigs ───────│ │
|
|
│ │ │── mint(wAI) ─────────────────────>│
|
|
│ │ │ │ │── wAI to user
|
|
│<──────────── receipt ───│ │ │ │
|
|
│ │ │ │ │
|
|
│ Total time: 5-9 seconds │</code></pre>
|
|
<h4>Transfer Flow (Lux to Hanzo)</h4>
|
|
<pre><code>User Lux C-Chain Relayer Validators Hanzo L1
|
|
│ │ │ │ │
|
|
│── burn(wAI, 1000) ─────>│ │ │ │
|
|
│ │── Burn event ─>│ │ │
|
|
│ │ │── verify proof ─>│ │
|
|
│ │ │ │── sign msg ────>│
|
|
│ │ │<── 7 sigs ───────│ │
|
|
│ │ │── unlock(AI) ────────────────────>│
|
|
│ │ │ │ │── AI to user
|
|
│<──────────── receipt ───│ │ │ │</code></pre>
|
|
<h3>Supported Assets</h3>
|
|
<p>| Asset | Hanzo Representation | Lux Representation | Direction | Notes | |-------|---------------------|-------------------|-----------|-------| | $AI | Native token | wAI (ERC-20 on C-Chain) | Hanzo -> Lux | Core bridge asset | | LUX | wLUX (ERC-20 on Hanzo) | Native token | Lux -> Hanzo | For staking rewards | | USDC | wUSDC (bridged) | USDC (native C-Chain) | Bidirectional | Stablecoin settlement | | USDT | wUSDT (bridged) | USDT (native C-Chain) | Bidirectional | Stablecoin settlement | | Model NFTs | ERC-721 (native) | wModel (ERC-721 C-Chain) | Hanzo -> Lux | Model certificates | | Compute Credits | ERC-1155 (native) | wCredits (ERC-1155) | Bidirectional | HMM credit tokens |</p>
|
|
<h3>Message Format</h3>
|
|
<p>Bridge messages use canonical ABI encoding for cross-chain communication:</p>
|
|
<pre><code class="lang-solidity">struct BridgeMessage {
|
|
uint256 nonce; // Monotonically increasing per-chain
|
|
uint32 sourceChainId; // 36963 (Hanzo) or Lux chain ID
|
|
uint32 destChainId; // Target chain ID
|
|
address sender; // Sender on source chain
|
|
address recipient; // Recipient on destination chain
|
|
address token; // Token address on source chain (0x0 for native)
|
|
uint256 amount; // Amount in wei (18 decimals)
|
|
bytes payload; // Optional: HMM invoice data, stake proof, etc.
|
|
uint64 timestamp; // Block timestamp of lock/burn event
|
|
bytes32 txHash; // Source transaction hash
|
|
bytes32 stateRoot; // State root of source chain at lock/burn block
|
|
}</code></pre>
|
|
<p>Messages are serialized as ABI-encoded bytes and signed by each validator using ML-DSA-65 (HIP-0005). The destination contract verifies that at least 7 of 11 signatures are valid before executing. The <code>stateRoot</code> field enables Merkle proof verification: the destination contract can verify that the lock/burn event is included in the source chain's state at the claimed block.</p>
|
|
<h3>State Proof Verification</h3>
|
|
<p>The bridge uses Merkle proof verification to confirm that events on the source chain actually occurred. This is stronger than simply trusting validator attestations --- it provides cryptographic proof anchored to chain state.</p>
|
|
<pre><code> Source Chain State Root
|
|
│
|
|
┌──────┴──────┐
|
|
│ │
|
|
┌────┴────┐ ┌────┴────┐
|
|
│ │ │ │
|
|
┌──┴──┐ ┌──┴──┐ ...
|
|
│ │ │ │
|
|
... Lock Event
|
|
Receipt</code></pre>
|
|
<p>The verification flow:</p>
|
|
<ol><li>User locks assets on source chain. The lock emits an event with a receipt.</li><li>Relayer constructs a Merkle proof from the source chain's receipt trie,</li></ol>
|
|
<p> proving the lock event is included in the block's state.</p>
|
|
<ol><li>Relayer presents the proof, block header, and validator signatures to the</li></ol>
|
|
<p> destination chain contract.</p>
|
|
<ol><li>Destination contract verifies: (a) block header is signed by source chain</li></ol>
|
|
<p> validators, (b) Merkle proof is valid against the block's receipts root, (c) at least 7-of-11 bridge validators have signed the bridge message.</p>
|
|
<p>This triple verification (chain consensus + Merkle proof + bridge multi-sig) provides defense in depth. An attacker must compromise source chain consensus, forge a valid Merkle proof, AND compromise 7 bridge validators simultaneously.</p>
|
|
<h3>Validator Set</h3>
|
|
<p>The bridge validator set consists of 11 members: 6 drawn from Hanzo's L1 validator set and 5 from Lux's primary network validators. This ensures neither chain has unilateral control.</p>
|
|
<pre><code class="lang-yaml">validator_set:
|
|
total: 11
|
|
threshold: 7 # 7-of-11 required for any bridge operation
|
|
composition:
|
|
hanzo_validators: 6 # Top 6 by stake from Hanzo L1
|
|
lux_validators: 5 # Top 5 by stake from Lux primary network
|
|
rotation:
|
|
epoch_length: 7 days
|
|
max_rotation_per_epoch: 2 # At most 2 validators rotate per epoch
|
|
cooldown_after_rotation: 14 days # New validators cannot be rotated for 2 epochs
|
|
requirements:
|
|
min_stake_hanzo: 5000 AI # Higher than base validation (2000 AI)
|
|
min_stake_lux: 10000 LUX # Higher than base Lux validation
|
|
uptime: 99.5%
|
|
signature_scheme: ML-DSA-65
|
|
key_encapsulation: ML-KEM-768 # For validator-to-validator communication</code></pre>
|
|
<p>Validator selection is determined by stake weight within each chain's validator set. Rotation occurs every 7 days, with at most 2 validators replaced per epoch to prevent sudden set changes that could compromise the bridge.</p>
|
|
<h3>Lux Network Integration</h3>
|
|
<p>The bridge integrates with all three Lux chains, each serving a different purpose.</p>
|
|
<h4>P-Chain Integration (Validator Management)</h4>
|
|
<p>Hanzo operates as a sovereign L1 on the Lux Network (HIP-0024). The P-Chain manages validator registration, staking, and delegation for both the Lux primary network and all L1s including Hanzo.</p>
|
|
<p>The bridge reads P-Chain state to:</p>
|
|
<ul><li>Verify that bridge validators are active and properly staked on their</li></ul>
|
|
<p> respective chains.</p>
|
|
<ul><li>Track delegation changes that affect validator eligibility.</li><li>Coordinate validator rotation by reading stake rankings from both networks.</li></ul>
|
|
<pre><code class="lang-go">// Bridge validator eligibility check (uses luxfi packages, NOT go-ethereum)
|
|
import (
|
|
"github.com/luxfi/node/vms/platformvm"
|
|
"github.com/luxfi/node/ids"
|
|
)
|
|
|
|
func IsEligibleBridgeValidator(nodeID ids.NodeID, chainID ids.ID) (bool, error) {
|
|
validators, err := platformvm.GetCurrentValidators(chainID)
|
|
if err != nil {
|
|
return false, fmt.Errorf("fetch validators: %w", err)
|
|
}
|
|
for _, v := range validators {
|
|
if v.NodeID == nodeID && v.StakeAmount >= MinBridgeStake {
|
|
return true, nil
|
|
}
|
|
}
|
|
return false, nil
|
|
}</code></pre>
|
|
<h4>X-Chain Integration (Fast Asset Transfers)</h4>
|
|
<p>The Lux X-Chain runs the XVM (UTXO virtual machine) for asset operations under Quasar 3.0 Nova-mode consensus. After $AI arrives on the C-Chain as wAI (ERC-20), users can export it to the X-Chain for fast UTXO-based transfers.</p>
|
|
<p>X-Chain integration enables:</p>
|
|
<ul><li>Sub-second asset transfers between Lux users (Quasar Nova consensus).</li><li>Atomic swaps between wAI and other X-Chain assets.</li><li>Cross-chain exports to the P-Chain for staking operations.</li></ul>
|
|
<p>The bridge does not interact with the X-Chain directly. It bridges to the C-Chain only. Users move assets between Lux chains using Lux's native cross-chain transfer mechanism (export/import transactions).</p>
|
|
<h4>C-Chain Integration (DeFi and Smart Contracts)</h4>
|
|
<p>The C-Chain is the primary bridge endpoint on Lux. It runs the EVM and hosts:</p>
|
|
<ul><li>The Mint Vault contract (wAI minting and burning).</li><li>DeFi protocols (DEXes, lending, liquidity pools) where wAI can be traded.</li><li>The settlement contract for HMM compute invoices.</li><li>Wrapped model NFT contracts for secondary market trading.</li></ul>
|
|
<h4>Custom VM for AI Compute Verification</h4>
|
|
<p>Lux's multi-VM architecture supports custom virtual machines. The bridge leverages a lightweight AI Verification VM deployed as a Lux L1:</p>
|
|
<pre><code class="lang-yaml">ai_verification_vm:
|
|
purpose: Verify AI compute proofs relayed from Hanzo
|
|
consensus: nova
|
|
chain_type: L1
|
|
capabilities:
|
|
- TEE attestation verification
|
|
- Compute invoice validation
|
|
- Model hash verification
|
|
- GPU benchmark proof checking
|
|
integration:
|
|
- Reads proofs from bridge messages (payload field)
|
|
- Writes verification results to C-Chain via cross-chain call
|
|
- Enables Lux DeFi contracts to trust Hanzo compute claims</code></pre>
|
|
<p>This VM allows Lux-side contracts to verify that compute work claimed in HMM invoices actually occurred, without trusting the bridge validators' word alone. The VM replays the TEE attestation proof and confirms the claimed GPU-hours against known hardware benchmarks.</p>
|
|
<h3>Finality Requirements</h3>
|
|
<p>A bridge transfer is considered final when all three conditions are met:</p>
|
|
<p>| Step | Chain | Expected Time | Description | |------|-------|---------------|-------------| | 1 | Source | ~1-2s | Transaction finality on source chain (Nova) | | 2 | Validators | ~3-5s | 7-of-11 validators sign the bridge message | | 3 | Destination | ~1-2s | Mint/unlock transaction finality on destination chain |</p>
|
|
<p><strong>Total expected bridge time: 5-9 seconds.</strong></p>
|
|
<p>The relayer waits for source chain finality (Hanzo Nova: ~2s, Lux Quasar: ~1s) before presenting the lock/burn event to the validator set. Validators independently verify the event against their own chain state before signing.</p>
|
|
<p>For large transfers (>100,000 AI), the elevated 9-of-11 threshold adds ~2-3 seconds to signature collection, bringing total time to 7-12 seconds.</p>
|
|
<h3>Fee Structure</h3>
|
|
<pre><code class="lang-yaml">fees:
|
|
bridge_fee: 0.1% # Of transferred amount
|
|
min_fee: 1 AI # Minimum fee regardless of amount
|
|
max_fee: 10000 AI # Cap for very large transfers
|
|
destination_gas: paid_by_user # User pays gas on destination chain
|
|
fee_distribution:
|
|
validators: 70% # Split among signing validators
|
|
protocol_treasury: 20% # Hanzo DAO treasury
|
|
insurance_fund: 10% # Emergency fund for bridge incidents
|
|
validator_rewards:
|
|
bridge_fees: denominated in $AI # Validators earn $AI for signing
|
|
lux_staking: denominated in $LUX # Lux validators also earn LUX staking rewards</code></pre>
|
|
<h3>Rate Limiting</h3>
|
|
<p>To prevent exploits, the bridge enforces rate limits:</p>
|
|
<pre><code class="lang-yaml">rate_limits:
|
|
per_user:
|
|
max_per_tx: 1000000 AI # 1M AI per transaction
|
|
max_per_hour: 5000000 AI # 5M AI per hour
|
|
max_per_day: 20000000 AI # 20M AI per day
|
|
global:
|
|
max_per_hour: 50000000 AI # 50M AI per hour across all users
|
|
max_per_day: 200000000 AI # 200M AI per day across all users
|
|
cooldown:
|
|
after_large_tx: 60s # 60-second cooldown after >100k AI transfer
|
|
elevated_threshold:
|
|
amount: 1000000 AI # Transfers >1M AI require 9-of-11 sigs
|
|
threshold: 9</code></pre>
|
|
<p>Rate limits are configurable via governance (see Emergency Controls).</p>
|
|
<h3>API Specification</h3>
|
|
<p>The bridge exposes a REST API for client interaction:</p>
|
|
<pre><code class="lang-yaml">bridge_api:
|
|
base_url: /v1/bridge
|
|
|
|
endpoints:
|
|
POST /v1/bridge/transfer:
|
|
description: Initiate a bridge transfer
|
|
request:
|
|
sourceChain: string # "hanzo" or "lux"
|
|
destChain: string # "hanzo" or "lux"
|
|
token: string # Token address or "native"
|
|
amount: string # Amount in wei
|
|
recipient: string # Destination address
|
|
payload: bytes # Optional HMM invoice data
|
|
response:
|
|
transferId: string # Unique transfer identifier
|
|
nonce: uint256 # Bridge nonce
|
|
estimatedTime: uint64 # Estimated completion in seconds
|
|
status: string # "pending_finality"
|
|
|
|
GET /v1/bridge/status/{transferId}:
|
|
description: Query transfer status
|
|
response:
|
|
transferId: string
|
|
status: string # pending_finality | pending_signatures |
|
|
# pending_destination | completed | failed
|
|
sourceChain: string
|
|
destChain: string
|
|
amount: string
|
|
signatures: uint8 # Number of validator signatures collected
|
|
sourceTxHash: string
|
|
destTxHash: string # Populated on completion
|
|
timestamp: uint64
|
|
completedAt: uint64 # Populated on completion
|
|
|
|
POST /v1/bridge/verify:
|
|
description: Verify a bridge message and its Merkle proof
|
|
request:
|
|
message: bytes # ABI-encoded BridgeMessage
|
|
proof: bytes # Merkle proof against source state root
|
|
signatures: bytes[] # ML-DSA-65 validator signatures
|
|
response:
|
|
valid: bool
|
|
validSignatures: uint8
|
|
proofValid: bool
|
|
stateRootMatch: bool
|
|
|
|
GET /v1/bridge/validators:
|
|
description: Current bridge validator set
|
|
response:
|
|
validators: array
|
|
- nodeId: string
|
|
- chain: string # "hanzo" or "lux"
|
|
- stake: string
|
|
- publicKey: string # ML-DSA-65 public key
|
|
- uptime: float
|
|
threshold: uint8
|
|
epoch: uint64
|
|
nextRotation: uint64
|
|
|
|
GET /v1/bridge/stats:
|
|
description: Bridge statistics
|
|
response:
|
|
totalLocked: string # Total AI locked on Hanzo side
|
|
totalMinted: string # Total wAI minted on Lux side
|
|
volume24h: string # 24-hour transfer volume
|
|
transferCount24h: uint64
|
|
avgBridgeTime: float # Average bridge time in seconds
|
|
rateLimitStatus: object # Current rate limit utilization</code></pre>
|
|
<h3>Emergency Controls</h3>
|
|
<p>The bridge can be paused under the following conditions:</p>
|
|
<ol><li><strong>Governance pause.</strong> A governance vote on either chain can pause the bridge.</li></ol>
|
|
<p> Requires simple majority of bridge validators (6 of 11).</p>
|
|
<ol><li><strong>Anomaly pause.</strong> The relayer automatically pauses if transfer volume exceeds</li></ol>
|
|
<p> 3x the 7-day moving average within a 1-hour window.</p>
|
|
<ol><li><strong>Validator pause.</strong> Any 3 validators can trigger an emergency pause lasting</li></ol>
|
|
<p> 24 hours, during which governance must vote to resume or extend.</p>
|
|
<ol><li><strong>Balance divergence pause.</strong> If <code>total_locked_hanzo</code> diverges from</li></ol>
|
|
<p> <code>total_minted_lux</code> by more than 0.01% (accounting for in-flight transfers), the bridge pauses for manual audit.</p>
|
|
<p>During a pause, no new locks or burns are processed. Pending transfers that have already been signed by validators but not yet executed on the destination chain are held in a queue and processed when the bridge resumes.</p>
|
|
<h2>Implementation</h2>
|
|
<h3>Hanzo Side: Lock Vault Contract</h3>
|
|
<p>The Lock Vault is deployed on Hanzo's L1 (chain ID 36963):</p>
|
|
<pre><code class="lang-solidity">// SPDX-License-Identifier: MIT
|
|
pragma solidity ^0.8.24;
|
|
|
|
import {IMLDSA} from "./interfaces/IMLDSA.sol";
|
|
|
|
contract HanzoLockVault {
|
|
uint256 public nonce;
|
|
mapping(bytes32 => bool) public processedMessages;
|
|
mapping(address => bool) public supportedTokens;
|
|
bool public paused;
|
|
|
|
address[] public validators;
|
|
uint8 public constant THRESHOLD = 7;
|
|
uint8 public constant ELEVATED_THRESHOLD = 9;
|
|
uint256 public constant ELEVATED_AMOUNT = 1_000_000 ether;
|
|
|
|
event Locked(
|
|
uint256 indexed nonce,
|
|
address indexed sender,
|
|
address indexed token,
|
|
uint256 amount,
|
|
uint32 destChainId,
|
|
address recipient,
|
|
bytes payload
|
|
);
|
|
|
|
event Unlocked(
|
|
bytes32 indexed messageHash,
|
|
address indexed recipient,
|
|
address indexed token,
|
|
uint256 amount
|
|
);
|
|
|
|
event Paused(address indexed triggeredBy, string reason);
|
|
event Unpaused(address indexed triggeredBy);
|
|
|
|
modifier whenNotPaused() {
|
|
require(!paused, "bridge paused");
|
|
_;
|
|
}
|
|
|
|
/// @notice Lock tokens for bridging to Lux
|
|
function lock(
|
|
address token,
|
|
uint256 amount,
|
|
uint32 destChainId,
|
|
address recipient,
|
|
bytes calldata payload
|
|
) external payable whenNotPaused {
|
|
require(amount > 0, "zero amount");
|
|
require(recipient != address(0), "zero recipient");
|
|
|
|
if (token == address(0)) {
|
|
require(msg.value == amount, "incorrect native amount");
|
|
} else {
|
|
require(supportedTokens[token], "unsupported token");
|
|
IERC20(token).transferFrom(msg.sender, address(this), amount);
|
|
}
|
|
|
|
uint256 currentNonce = nonce++;
|
|
emit Locked(currentNonce, msg.sender, token, amount, destChainId, recipient, payload);
|
|
}
|
|
|
|
/// @notice Unlock tokens returning from Lux (called by relayer with validator sigs)
|
|
function unlock(
|
|
bytes calldata message,
|
|
bytes[] calldata signatures
|
|
) external whenNotPaused {
|
|
bytes32 msgHash = keccak256(message);
|
|
require(!processedMessages[msgHash], "already processed");
|
|
|
|
BridgeMessage memory bm = abi.decode(message, (BridgeMessage));
|
|
uint8 required = bm.amount >= ELEVATED_AMOUNT ? ELEVATED_THRESHOLD : THRESHOLD;
|
|
require(
|
|
_verifySignatures(msgHash, signatures) >= required,
|
|
"insufficient signatures"
|
|
);
|
|
|
|
processedMessages[msgHash] = true;
|
|
|
|
if (bm.token == address(0)) {
|
|
payable(bm.recipient).transfer(bm.amount);
|
|
} else {
|
|
IERC20(bm.token).transfer(bm.recipient, bm.amount);
|
|
}
|
|
|
|
emit Unlocked(msgHash, bm.recipient, bm.token, bm.amount);
|
|
}
|
|
|
|
function _verifySignatures(
|
|
bytes32 msgHash,
|
|
bytes[] calldata signatures
|
|
) internal view returns (uint8 validCount) {
|
|
for (uint i = 0; i < signatures.length; i++) {
|
|
// ML-DSA-65 verification via precompile (HIP-0005)
|
|
if (IMLDSA(ML_DSA_PRECOMPILE).verify(
|
|
validators[i], msgHash, signatures[i]
|
|
)) {
|
|
validCount++;
|
|
}
|
|
}
|
|
}
|
|
}</code></pre>
|
|
<h3>Lux Side: Mint Vault Contract</h3>
|
|
<p>The Mint Vault is deployed on Lux C-Chain. It mints wrapped tokens when assets are locked on Hanzo, and burns them when assets are returned:</p>
|
|
<pre><code class="lang-solidity">// SPDX-License-Identifier: MIT
|
|
pragma solidity ^0.8.24;
|
|
|
|
import {ERC20Burnable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
|
|
|
|
contract LuxMintVault {
|
|
mapping(bytes32 => bool) public processedMessages;
|
|
mapping(address => address) public wrappedTokens;
|
|
bool public paused;
|
|
|
|
address[] public validators;
|
|
uint8 public constant THRESHOLD = 7;
|
|
|
|
event Minted(bytes32 indexed messageHash, address indexed recipient,
|
|
address indexed wrappedToken, uint256 amount);
|
|
event Burned(uint256 indexed nonce, address indexed sender,
|
|
address indexed wrappedToken, uint256 amount,
|
|
uint32 destChainId, address recipient);
|
|
|
|
/// @notice Mint wrapped tokens (called by relayer with validator sigs)
|
|
function mint(bytes calldata message, bytes[] calldata signatures) external {
|
|
require(!paused, "bridge paused");
|
|
bytes32 msgHash = keccak256(message);
|
|
require(!processedMessages[msgHash], "already processed");
|
|
require(_verifySignatures(msgHash, signatures) >= THRESHOLD, "insufficient sigs");
|
|
|
|
processedMessages[msgHash] = true;
|
|
BridgeMessage memory bm = abi.decode(message, (BridgeMessage));
|
|
address wrappedToken = wrappedTokens[bm.token];
|
|
require(wrappedToken != address(0), "no wrapped token");
|
|
|
|
uint256 fee = _calculateFee(bm.amount);
|
|
uint256 netAmount = bm.amount - fee;
|
|
|
|
WrappedToken(wrappedToken).mint(bm.recipient, netAmount);
|
|
WrappedToken(wrappedToken).mint(feeCollector, fee);
|
|
emit Minted(msgHash, bm.recipient, wrappedToken, netAmount);
|
|
}
|
|
|
|
/// @notice Burn wrapped tokens to unlock on Hanzo
|
|
function burn(address wrappedToken, uint256 amount,
|
|
uint32 destChainId, address recipient) external {
|
|
require(!paused, "bridge paused");
|
|
require(amount > 0, "zero amount");
|
|
ERC20Burnable(wrappedToken).burnFrom(msg.sender, amount);
|
|
emit Burned(nonce++, msg.sender, wrappedToken, amount, destChainId, recipient);
|
|
}
|
|
|
|
function _calculateFee(uint256 amount) internal pure returns (uint256) {
|
|
uint256 fee = (amount * 10) / 10000; // 0.1%
|
|
if (fee < 1 ether) return 1 ether; // min 1 AI
|
|
if (fee > 10000 ether) return 10000 ether; // max 10k AI
|
|
return fee;
|
|
}
|
|
}</code></pre>
|
|
<h3>Relayer Service</h3>
|
|
<p>The relayer is an off-chain service that monitors both chains and coordinates the validator set:</p>
|
|
<pre><code class="lang-yaml">relayer:
|
|
architecture: event-driven, stateless with respect to bridge balances
|
|
redundancy:
|
|
instances: 3 # Active-active with Raft leader election
|
|
failover: < 10s # Automatic leader promotion
|
|
|
|
components:
|
|
chain_monitor:
|
|
- watches Hanzo L1 for Lock events via WebSocket subscription
|
|
- watches Lux C-Chain for Burn events via WebSocket subscription
|
|
- confirms finality (waits for Nova acceptance) before relaying
|
|
- constructs Merkle proofs from source chain receipt tries
|
|
|
|
validator_coordinator:
|
|
- presents events + Merkle proofs to validator set
|
|
- collects ML-DSA-65 signatures via encrypted channels (ML-KEM-768)
|
|
- submits signed messages to destination chain
|
|
- retries failed submissions with exponential backoff
|
|
|
|
anomaly_detector:
|
|
- tracks transfer volume (1h, 24h, 7d rolling windows)
|
|
- triggers pause if volume exceeds 3x 7-day moving average
|
|
- monitors balance divergence between locked and minted totals
|
|
- flags suspicious validator signing patterns
|
|
- alerts operators via webhook (PagerDuty, Slack)
|
|
|
|
rate_limiter:
|
|
- enforces per-user and global rate limits
|
|
- maintains cooldown timers per address
|
|
- escalates threshold for large transfers</code></pre>
|
|
<p>The relayer is stateless with respect to bridge balances. All state lives in the on-chain contracts. If all relayer instances fail, the bridge pauses. No funds are at risk because the lock vault holds all assets and only releases them upon valid multi-sig authorization.</p>
|
|
<h3>HMM Settlement Integration</h3>
|
|
<p>The bridge carries compute invoice settlement messages from HMM (HIP-0008). When a compute job completes on Hanzo:</p>
|
|
<ol><li>HMM generates an invoice on Hanzo L1 with job details.</li><li>If the user's $AI balance is on Lux, the invoice is encoded in the bridge</li></ol>
|
|
<p> message <code>payload</code> field.</p>
|
|
<ol><li>The bridge relays the invoice to the Lux-side settlement contract.</li><li>The settlement contract debits the user's wAI or triggers unstake-and-pay.</li></ol>
|
|
<pre><code class="lang-solidity">struct ComputeInvoice {
|
|
bytes32 jobId; // Unique job identifier
|
|
address provider; // Compute provider address
|
|
address consumer; // Consumer address
|
|
uint256 cost; // Cost in $AI (18 decimals)
|
|
uint64 gpuHours; // GPU-hours consumed
|
|
uint64 tokensProcessed; // Tokens processed (inference)
|
|
bytes32 modelHash; // Hash of model used
|
|
bytes attestation; // TEE attestation proof
|
|
}</code></pre>
|
|
<h3>How the Bridge Enables the Compute Marketplace</h3>
|
|
<p>The compute marketplace operates as a cycle:</p>
|
|
<ol><li><strong>Stake.</strong> Users stake $AI on Lux P-Chain (economic security, yield).</li><li><strong>Verify.</strong> The bridge reads Lux staking positions and relays them to Hanzo.</li><li><strong>Allocate.</strong> Hanzo allocates compute proportional to verified stake.</li><li><strong>Execute.</strong> Providers run AI workloads on Hanzo (inference, training).</li><li><strong>Invoice.</strong> The HMM (HIP-0008) generates compute invoices on Hanzo.</li><li><strong>Settle.</strong> Invoices are settled via the bridge, debiting $AI on the user's</li></ol>
|
|
<p> Lux-side balance or relaying payment to Hanzo.</p>
|
|
<p>The bridge is not an accessory to the compute marketplace. It is the economic backbone that connects staking (Lux) to compute allocation (Hanzo) to settlement (Lux).</p>
|
|
<h2>Security</h2>
|
|
<h3>Multi-Sig Validator Rotation</h3>
|
|
<p>Validator rotation follows a controlled schedule:</p>
|
|
<ul><li><strong>Epoch length</strong>: 7 days. At each epoch boundary, eligible validators are</li></ul>
|
|
<p> recalculated based on stake weight.</p>
|
|
<ul><li><strong>Maximum rotation</strong>: 2 validators per epoch. Even if stake rankings change</li></ul>
|
|
<p> significantly, only 2 slots rotate. At least 9 of 11 validators persist across any single epoch.</p>
|
|
<ul><li><strong>Cooldown</strong>: A newly rotated validator cannot be rotated out for 14 days.</li><li><strong>Key handoff</strong>: Outgoing validators co-sign a key rotation message with</li></ul>
|
|
<p> incoming validators. Destination contracts update their validator registries only upon receiving a valid rotation message signed by the current 7-of-11 set.</p>
|
|
<h3>Challenge Period for Disputed Transfers</h3>
|
|
<p>Any bridge validator or staked observer can challenge a transfer within 30 minutes of the mint/unlock transaction on the destination chain. A challenge asserts that the source-chain event is invalid (e.g., a forged Merkle proof or a reorged source block).</p>
|
|
<pre><code class="lang-yaml">challenge_period:
|
|
duration: 30 minutes
|
|
bond: 100 AI # Challenger must post bond
|
|
resolution:
|
|
- If challenge succeeds: transfer is reversed, challenger receives bond back
|
|
plus a reward from the insurance fund.
|
|
- If challenge fails: bond is forfeited to the insurance fund.
|
|
dispute_resolution:
|
|
- Re-verify Merkle proof against source chain state.
|
|
- Check source chain for block reorgs since the original verification.
|
|
- 9-of-11 validator vote on dispute outcome.</code></pre>
|
|
<p>In practice, challenges are expected to be extremely rare because the triple verification (chain consensus + Merkle proof + multi-sig) makes forgery prohibitively expensive.</p>
|
|
<h3>Rate Limiting on Large Transfers</h3>
|
|
<p>Large transfers receive additional scrutiny:</p>
|
|
<ul><li>Transfers >100,000 AI trigger a 60-second cooldown.</li><li>Transfers >1,000,000 AI require 9-of-11 validator signatures.</li><li>The global hourly limit (50M AI) is a hard cap. If reached, all transfers</li></ul>
|
|
<p> queue until the next hour window.</p>
|
|
<h3>Anomaly Detection</h3>
|
|
<p>The relayer maintains rolling volume statistics:</p>
|
|
<pre><code>if volume_1h > 3 * avg_volume_7d:
|
|
trigger emergency_pause
|
|
alert operators
|
|
require governance_vote to resume</code></pre>
|
|
<p>Additional anomaly signals:</p>
|
|
<ul><li>Rapid succession of maximum-size transfers from new addresses.</li><li>Balance divergence: if total locked on Hanzo diverges from total minted on</li></ul>
|
|
<p> Lux by more than 0.01%, the bridge pauses for manual audit.</p>
|
|
<ul><li>Validator timing anomaly: if a validator consistently signs faster than</li></ul>
|
|
<p> physically possible given network latency, flag for investigation.</p>
|
|
<h3>Post-Quantum Cryptography</h3>
|
|
<p>All bridge signatures use ML-DSA-65 (CRYSTALS-Dilithium, FIPS 204) as specified in HIP-0005. This applies to:</p>
|
|
<ul><li>Validator signatures on bridge messages.</li><li>Key rotation messages.</li><li>Emergency pause authorizations.</li><li>Governance vote signatures.</li><li>Challenge/dispute submissions.</li></ul>
|
|
<p>The bridge does not support legacy ECDSA signatures. This is deliberate: the bridge is new infrastructure with no backward-compatibility requirement. Starting with ML-DSA-65 avoids the complexity of a hybrid transition.</p>
|
|
<p>Key encapsulation for validator-to-validator communication (during signature coordination) uses ML-KEM-768, also per HIP-0005. Key sizes:</p>
|
|
<p>| Algorithm | Public Key | Signature/Ciphertext | Security Level | |-----------|-----------|---------------------|----------------| | ML-DSA-65 | 1,952 bytes | 3,293 bytes | NIST Level 3 (AES-192 equivalent) | | ML-KEM-768 | 1,184 bytes | 1,088 bytes | NIST Level 3 (AES-192 equivalent) |</p>
|
|
<h3>Audit and Verification</h3>
|
|
<p>Before mainnet deployment, the bridge contracts must undergo:</p>
|
|
<ol><li><strong>Formal verification</strong> of lock/mint/burn/unlock invariants. The core</li></ol>
|
|
<p> invariant: <code>total_locked_hanzo == total_minted_lux</code> at all times (within 0.01% tolerance for in-flight transactions).</p>
|
|
<ol><li><strong>Third-party security audit</strong> by at least two independent firms.</li><li><strong>Economic audit</strong> of fee structure and rate limits to ensure they do not</li></ol>
|
|
<p> create arbitrage opportunities or denial-of-service vectors.</p>
|
|
<ol><li><strong>Testnet operation</strong> for a minimum of 90 days with adversarial testing</li></ol>
|
|
<p> (simulated validator failures, network partitions, volume spikes).</p>
|
|
<h2>Testing Strategy</h2>
|
|
<h3>Unit Tests</h3>
|
|
<ul><li>Lock vault: lock, unlock, replay protection, fee calculation, rate limiting,</li></ul>
|
|
<p> pause/unpause, elevated threshold for large transfers.</p>
|
|
<ul><li>Mint vault: mint, burn, wrapped token accounting, fee distribution.</li><li>Signature verification: valid ML-DSA-65 signatures, threshold enforcement,</li></ul>
|
|
<p> invalid signature rejection, mixed valid/invalid sets.</p>
|
|
<ul><li>Message encoding: canonical serialization, nonce ordering, cross-chain ID</li></ul>
|
|
<p> validation, state root inclusion.</p>
|
|
<ul><li>Merkle proofs: valid proof acceptance, invalid proof rejection, proof against</li></ul>
|
|
<p> wrong state root.</p>
|
|
<h3>Integration Tests</h3>
|
|
<ul><li>End-to-end bridge transfer (Hanzo testnet to Lux Fuji testnet).</li><li>Validator rotation during active transfers.</li><li>Relayer failover (kill primary, verify secondary takes over within 10s).</li><li>HMM invoice settlement via bridge payload.</li><li>Challenge period exercise (submit and resolve a dispute).</li><li>Rate limiting under sustained load.</li></ul>
|
|
<h3>Adversarial Tests</h3>
|
|
<ul><li>Double-spend attempts (replay same lock event with same nonce).</li><li>Validator collusion (6 malicious validators, verify bridge holds with 5</li></ul>
|
|
<p> honest: 6 < 7 threshold).</p>
|
|
<ul><li>Volume spike (10x normal volume in 10 minutes, verify rate limiting and</li></ul>
|
|
<p> anomaly detection trigger pause).</p>
|
|
<ul><li>Network partition (Hanzo and Lux cannot communicate for 1 hour, verify</li></ul>
|
|
<p> graceful pause and recovery).</p>
|
|
<ul><li>Forged Merkle proof (invalid proof against valid state root).</li></ul>
|
|
<h3>Performance Benchmarks</h3>
|
|
<p>| Metric | Target | Measurement Method | |--------|--------|--------------------| | Bridge latency (lock to mint) | < 10s | End-to-end timer | | Throughput | > 100 transfers/min | Sustained load test | | Validator signature collection | < 5s for 7-of-11 | Coordination timer | | Relayer failover | < 10s | Kill primary, measure recovery | | Merkle proof verification | < 50ms on-chain | Gas profiling | | ML-DSA-65 verification | < 10ms per sig | Precompile benchmark |</p>
|
|
<h2>Implementation Plan</h2>
|
|
<h2>Dependencies</h2>
|
|
<p>| Dependency | HIP/LP | Status | Required For | |-----------|--------|--------|-------------| | $AI Token | HIP-0001 | Draft | Native asset bridging | | Post-Quantum Security | HIP-0005 | Final | ML-DSA-65 signatures | | HMM Market Maker | HIP-0008 | Draft | Compute invoice settlement | | Hanzo Sovereign L1 | HIP-0024 | Final | Lock Vault deployment, chain ID 36963 | | Lux PQC | LP-100 | Final | ML-DSA-65 on Lux side | | Lux Cross-Chain Messaging | LP-226 | Draft | Warp message compatibility |</p>
|
|
<h2>Rationale</h2>
|
|
<h3>Why 0.1% Fee</h3>
|
|
<p>The fee must be:</p>
|
|
<ul><li><strong>Low enough</strong> that it does not deter legitimate usage, especially for compute</li></ul>
|
|
<p> settlement where margins are thin.</p>
|
|
<ul><li><strong>High enough</strong> to compensate validators for operational costs (monitoring,</li></ul>
|
|
<p> signing, key management, infrastructure).</p>
|
|
<ul><li><strong>Comparable</strong> to other bridge protocols (Wormhole: 0% subsidized; LayerZero:</li></ul>
|
|
<p> variable; most bridges: 0.05-0.3%).</p>
|
|
<p>The 10% allocation to the insurance fund creates a growing reserve to cover potential bridge incidents without relying on external insurance.</p>
|
|
<h2>References</h2>
|
|
<ul><li><a href="./hip-0001-ai-coin-hanzos-native-currency.md">HIP-0001: $AI Token</a></li><li><a href="./hip-0005-post-quantum-security-for-ai-infrastructure.md">HIP-0005: Post-Quantum Security</a></li><li><a href="./hip-0008-hmm-hanzo-market-maker-native-dex-for-ai-compute-resources.md">HIP-0008: HMM Market Maker</a></li><li><a href="./hip-0024-hanzo-sovereign-l1-chain-architecture.md">HIP-0024: Hanzo Sovereign L1</a></li><li><a href="https://lps.lux.network/lp-100">LP-100: Lux Post-Quantum Cryptography</a></li><li><a href="https://lps.lux.network/lp-226">LP-226: Enhanced Cross-Chain Communication</a></li><li><a href="https://csrc.nist.gov/pubs/fips/204/final">FIPS 204: ML-DSA (CRYSTALS-Dilithium)</a></li><li><a href="https://csrc.nist.gov/pubs/fips/203/final">FIPS 203: ML-KEM (CRYSTALS-Kyber)</a></li></ul>
|
|
<h2>Copyright</h2>
|
|
<p>Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hip-0101.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |