Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

34.2 KB
Raw Blame
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
<title>ERC-8056, Scaled UI Amount, a typewritten spec with living margins</title>
<meta name="description" content="A reference implementation and living specification of ERC-8056 (Scaled UI Amount / uiMultiplier), the corporate-actions standard for tokenized equities. Read the spec as a typewritten RFC; every clause carries a margin annotation that expands in place, verified against live Robinhood Chain state." />
<link rel="canonical" href="https://nirholas.github.io/erc8056/" />
<meta name="theme-color" content="#efece4" />
<meta property="og:type" content="website" />
<meta property="og:title" content="ERC-8056, the multiplier, spelled out in the margins" />
<meta property="og:description" content="Scaled UI Amount (uiMultiplier) as a typewritten RFC with living margins. Apply the corporate-action multiplier exactly once, the wrong branch is a compile error. Verified bit-for-bit against live Robinhood Chain Stock Tokens." />
<meta property="og:url" content="https://nirholas.github.io/erc8056/" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="ERC-8056, Scaled UI Amount, a living spec" />
<meta name="twitter:description" content="Read ERC-8056 as a typewritten RFC. Clauses carry margin annotations that expand in place; cross-references draw connecting lines. Verified against live chain 4663." />
<meta name="twitter:creator" content="@nichxbt" />
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect width='32' height='32' fill='%23efece4'/><path d='M8 8 L14 14 M14 8 L8 14' stroke='%2317150f' stroke-width='2' stroke-linecap='square'/><path d='M18 11 L26 11 M18 16 L26 16 M18 21 L23 21' stroke='%2317150f' stroke-width='1.6' stroke-linecap='square'/></svg>" />
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"TechArticle","headline":"ERC-8056, Scaled UI Amount (uiMultiplier)","description":"Reference implementation and living specification of ERC-8056, the corporate-actions (uiMultiplier) standard for tokenized equities, verified against live Robinhood Chain Stock Tokens.","author":{"@type":"Person","name":"nirholas","url":"https://x.com/nichxbt"},"about":["ERC-8056","Scaled UI Amount","uiMultiplier","tokenized equities","corporate actions","Robinhood Chain"],"url":"https://nirholas.github.io/erc8056/","codeRepository":"https://github.com/nirholas/erc8056","license":"https://github.com/nirholas/erc8056/blob/main/LICENSE"}
</script>
<style>
  :root{
    --paper:#efece4; --ink:#17150f; --graphite:#6b6659; --faint:#a39d8f;
    --hair:rgba(23,21,15,.16); --hair2:rgba(23,21,15,.30);
    --mono:ui-monospace,"SFMono-Regular","JetBrains Mono","Menlo","Consolas",monospace;
    --ease:cubic-bezier(.16,1,.3,1);
  }
  *{margin:0;padding:0;box-sizing:border-box}
  html{-webkit-text-size-adjust:100%}
  body{background:var(--paper); color:var(--ink); font-family:var(--mono);
    font-size:clamp(13px,.95vw,15.5px); line-height:1.72; overflow-x:hidden;
    -webkit-font-smoothing:antialiased; font-feature-settings:"zero" 1}
  ::selection{background:var(--ink); color:var(--paper)}
  a{color:inherit}
  b,strong{font-weight:700}

  /* typewriter ink texture: faint horizontal fibres, no repaint */
  body::before{content:""; position:fixed; inset:0; z-index:0; pointer-events:none; opacity:.5;
    background:
      repeating-linear-gradient(0deg, rgba(23,21,15,.018) 0 1px, transparent 1px 4px),
      radial-gradient(140% 60% at 50% -10%, rgba(23,21,15,.03), transparent 60%);}
  @media(prefers-reduced-motion:reduce){*{animation-duration:.001s!important; transition-duration:.001s!important}}

  .doc{position:relative; z-index:1; max-width:1120px; margin:0 auto; padding:0 clamp(16px,4vw,40px)}

  /* ---- masthead: RFC cover ---- */
  .mast{padding:clamp(30px,6vh,70px) 0 clamp(22px,3vh,38px); border-bottom:2px solid var(--ink)}
  .mhead{display:flex; justify-content:space-between; flex-wrap:wrap; gap:8px 24px;
    font-size:11px; letter-spacing:.06em; color:var(--graphite); text-transform:uppercase}
  .mhead b{color:var(--ink)}
  .title{margin:26px 0 6px; font-weight:700; letter-spacing:-.01em; line-height:1;
    font-size:clamp(40px,8.5vw,120px)}
  .title .cur{display:inline-block; width:.56ch; height:.82em; background:var(--ink); vertical-align:-2px;
    animation:blink 1.05s steps(1) infinite}
  @keyframes blink{50%{opacity:0}}
  .subtitle{font-size:clamp(15px,1.8vw,24px); letter-spacing:.02em; color:var(--ink); min-height:1.4em}
  .abs{margin-top:22px; max-width:74ch; color:#2c2a22; font-size:clamp(13.5px,1.05vw,16px)}
  .tags{margin-top:22px; display:flex; flex-wrap:wrap; gap:8px}
  .tag{border:1px solid var(--hair2); padding:6px 10px; font-size:10.5px; letter-spacing:.1em; text-transform:uppercase; color:var(--graphite)}
  .tag b{color:var(--ink)}

  /* ---- table of contents ---- */
  .toc{display:flex; flex-wrap:wrap; gap:2px 0; margin:26px 0 0; padding-top:20px; border-top:1px solid var(--hair)}
  .toc a{flex:1 1 260px; display:flex; gap:12px; padding:7px 6px; text-decoration:none; color:var(--ink);
    transition:background .2s, padding-left .2s var(--ease)}
  .toc a:hover{background:rgba(23,21,15,.05); padding-left:12px}
  .toc a .s{color:var(--graphite)}
  .toc a .d{border-bottom:1px dotted var(--hair2); flex:1}

  /* ---- the document body: two columns, text + living margin ---- */
  .clauses{position:relative; padding:clamp(30px,5vh,54px) 0 0}
  .sec{position:relative; display:grid; grid-template-columns:1fr 300px; gap:clamp(20px,3vw,54px);
    padding:clamp(26px,4vh,44px) 0; border-bottom:1px solid var(--hair); scroll-margin-top:20px}
  @media(max-width:900px){.sec{grid-template-columns:1fr; gap:0}}

  .sec > .body{max-width:74ch}
  .sh{display:flex; align-items:baseline; gap:14px; margin-bottom:16px}
  .sh .no{font-weight:700; font-size:15px; color:var(--ink); white-space:nowrap}
  .sh h2{font-weight:700; font-size:clamp(18px,2.1vw,27px); letter-spacing:-.01em; line-height:1.1}
  .sec.flash h2{animation:flash 1.1s var(--ease)}
  @keyframes flash{0%,100%{color:var(--ink)}30%{color:var(--graphite)}}
  .sec p{margin:0 0 14px; color:#2c2a22}
  .sec p:last-child{margin-bottom:0}
  .sec .mono-em{color:var(--ink); border-bottom:1px solid var(--hair2)}
  ul.plain{list-style:none; margin:6px 0 14px}
  ul.plain li{position:relative; padding:6px 0 6px 24px; color:#2c2a22}
  ul.plain li::before{content:attr(data-b); position:absolute; left:0; top:6px; color:var(--graphite)}

  /* cross-reference links */
  .xref{cursor:pointer; color:var(--ink); border-bottom:1px solid var(--ink); text-decoration:none; white-space:nowrap;
    transition:background .2s}
  .xref:hover, .xref.on{background:var(--ink); color:var(--paper); border-color:var(--ink)}
  .sec.xtarget{background:linear-gradient(90deg, rgba(23,21,15,.06), transparent 70%)}

  /* code blocks, typed listings */
  .list{border:1px solid var(--hair2); background:rgba(23,21,15,.03); padding:16px 18px; margin:6px 0 14px;
    font-size:12.5px; line-height:1.7; white-space:pre; overflow-x:auto}
  .list .cm{color:var(--graphite)}
  .list .st{color:#4f4b3f}
  .copy{float:right; appearance:none; border:1px solid var(--hair2); background:transparent; color:var(--ink);
    font:600 10px/1 var(--mono); letter-spacing:.12em; padding:6px 9px; cursor:pointer; margin:-4px -6px 8px 8px; transition:background .2s}
  .copy:hover{background:rgba(23,21,15,.08)}

  /* ---- the living margin ---- */
  .margin{position:relative}
  @media(max-width:900px){.margin{margin-top:14px}}
  .note{border-left:2px solid var(--ink); background:transparent}
  .note > button{appearance:none; width:100%; text-align:left; background:transparent; border:0; cursor:pointer;
    color:var(--ink); font-family:var(--mono); font-size:11px; letter-spacing:.08em; text-transform:uppercase;
    padding:8px 0 8px 14px; display:flex; align-items:center; gap:10px; transition:color .2s}
  .note > button:hover{color:var(--graphite)}
  .note > button .mk{display:inline-flex; width:16px; height:16px; border:1px solid var(--ink); align-items:center; justify-content:center;
    font-size:11px; line-height:1; transition:background .25s, color .25s, transform .35s var(--ease)}
  .note.open > button .mk{background:var(--ink); color:var(--paper); transform:rotate(45deg)}
  .note > button .mk b{transform:rotate(0)}
  .note.open > button .mk b{transform:rotate(-45deg)}
  .note .panel{display:grid; grid-template-rows:0fr; opacity:0;
    transition:grid-template-rows .45s var(--ease), opacity .4s var(--ease)}
  .note.open .panel{grid-template-rows:1fr; opacity:1}
  .note .panel > div{overflow:hidden}
  .note .panel .in{padding:2px 0 14px 14px; font-size:12.5px; line-height:1.66; color:#2c2a22}
  .note .panel .in b{color:var(--ink)}
  .note .panel .in .k{color:var(--graphite)}
  .note .panel .in code{border-bottom:1px solid var(--hair2); word-break:break-all}
  .note + .note{margin-top:14px}
  .mtag{font-size:10px; letter-spacing:.16em; text-transform:uppercase; color:var(--faint); margin-bottom:10px}

  /* cross-reference line overlay */
  #xrefsvg{position:fixed; inset:0; z-index:40; pointer-events:none}
  #xrefsvg path{fill:none; stroke:var(--ink); stroke-width:1.3; stroke-dasharray:5 4}

  /* ---- footer sections ---- */
  .install{border:1px solid var(--ink); background:rgba(23,21,15,.03); padding:18px 20px; margin-top:8px;
    font-size:13px; line-height:1.95; position:relative; overflow-x:auto}
  .install .c{color:var(--graphite)} .install .p::before{content:"$ "; color:var(--graphite)}
  .btns{display:flex; flex-wrap:wrap; gap:10px; margin-top:22px}
  .btn{appearance:none; text-decoration:none; border:1px solid var(--ink); color:var(--ink); background:transparent;
    font:600 11px/1 var(--mono); letter-spacing:.1em; text-transform:uppercase; padding:14px 20px; cursor:pointer;
    transition:background .2s,color .2s,transform .25s var(--ease)}
  .btn:hover{background:var(--ink); color:var(--paper); transform:translateY(-2px)}
  .btn.solid{background:var(--ink); color:var(--paper)}
  .btn.solid:hover{background:transparent; color:var(--ink)}

  footer{padding:clamp(34px,6vh,60px) 0; margin-top:10px; border-top:2px solid var(--ink);
    display:flex; flex-wrap:wrap; justify-content:space-between; gap:20px; align-items:flex-end}
  footer .big{font-weight:700; font-size:clamp(26px,5vw,54px); line-height:.95; letter-spacing:-.01em}
  footer .meta{font-size:11.5px; line-height:1.9; color:var(--graphite); text-align:right}
  footer a{text-decoration:none; border-bottom:1px solid var(--hair2)}
  footer a:hover{border-color:var(--ink)}
</style>
</head>
<body>
<svg id="xrefsvg" aria-hidden="true"><path id="xrefpath" d=""/></svg>

<div class="doc">
  <!-- ============ MASTHEAD ============ -->
  <header class="mast">
    <div class="mhead">
      <span>Request for Implementation &#183; <b>ERC-8056</b></span>
      <span>Category: <b>Standards Track</b> &#183; Reference</span>
      <span>Chain <b>4663</b> &#183; verified live</span>
    </div>
    <h1 class="title">ERC-8056<span class="cur" aria-hidden="true"></span></h1>
    <div class="subtitle" id="subtitle"></div>
    <p class="abs">When a tokenized stock splits or reinvests a dividend, its raw ERC-20 balances never change. The issuer updates one number, <span class="mono-em">uiMultiplier()</span>, and every correct integration scales its display and valuation by it, exactly once. This document is that rule, spelled out clause by clause, with the deployed-reality caveats in the margins. Engage any note to expand it in place; follow a cross-reference and the spec draws the line for you.</p>
    <div class="tags">
      <span class="tag"><b>~2.5 kB</b> gzipped</span>
      <span class="tag">zero runtime deps &#183; <b>viem</b> peer</span>
      <span class="tag">Solidity + <b>Foundry</b> fork tests</span>
      <span class="tag">verified against <b>AAPL / SGOV / WEEK</b></span>
    </div>

    <nav class="toc" aria-label="Contents">
      <a href="#s1"><span class="s">1</span><span>Abstract</span><span class="d"></span></a>
      <a href="#s2"><span class="s">2</span><span>Motivation</span><span class="d"></span></a>
      <a href="#s3"><span class="s">3</span><span>The multiplier</span><span class="d"></span></a>
      <a href="#s4"><span class="s">4</span><span>Rule 1 &#183; positions</span><span class="d"></span></a>
      <a href="#s5"><span class="s">5</span><span>Rule 2 &#183; valuation</span><span class="d"></span></a>
      <a href="#s6"><span class="s">6</span><span>The one trap</span><span class="d"></span></a>
      <a href="#s7"><span class="s">7</span><span>Deployed reality</span><span class="d"></span></a>
      <a href="#s8"><span class="s">8</span><span>API surface</span><span class="d"></span></a>
      <a href="#s9"><span class="s">9</span><span>Interface IDs</span><span class="d"></span></a>
      <a href="#s10"><span class="s">10</span><span>Reference implementation</span><span class="d"></span></a>
    </nav>
  </header>

  <main class="clauses">

    <!-- 1 ABSTRACT -->
    <section class="sec" id="s1">
      <div class="body">
        <div class="sh"><span class="no">1.</span><h2>Abstract</h2></div>
        <p>ERC-8056 (&#8220;Scaled UI Amount&#8221;) defines <span class="mono-em">uiMultiplier()</span>: an 18-decimal fixed-point factor a token issuer maintains so that a token's <em>displayed</em> and <em>valued</em> amounts track corporate actions while its raw on-chain balances stay immutable. It is the standard behind Robinhood Chain Stock Tokens.</p>
        <p>This package is both the reference implementation and, on this page, the living specification: the math is bit-for-bit the on-chain math, and the price types make the wrong valuation branch a compile error. See <a class="xref" data-ref="s4">&#167;4 (positions)</a> and <a class="xref" data-ref="s5">&#167;5 (valuation)</a> for the two rules everything reduces to.</p>
      </div>
      <div class="margin">
        <div class="mtag">// margin</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> what &#8220;scaled UI amount&#8221; means</button>
          <div class="panel"><div><div class="in">A raw balance is what the ledger stores; the <b>UI amount</b> is what a human should see. <span class="k">balanceOfUI = balanceOf &#215; uiMultiplier &#247; 1e18</span>, floored. The multiplier is the only moving part, so a split becomes a single storage write instead of a rebase across every holder.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 2 MOTIVATION -->
    <section class="sec" id="s2">
      <div class="body">
        <div class="sh"><span class="no">2.</span><h2>Motivation</h2></div>
        <p>Every naive integration gets tokenized equities wrong in one of exactly two ways. This standard, and this package, make both mistakes hard.</p>
        <ul class="plain">
          <li data-b="a)">Showing <b>raw balances as shares</b> understates positions: after a split or reinvested dividend the true share-equivalent has diverged from the raw ERC-20 number. Fixed by <a class="xref" data-ref="s4">&#167;4</a>.</li>
          <li data-b="b)">Re-applying the multiplier to an <b>already-adjusted price feed</b> double-counts the corporate action. Fixed by <a class="xref" data-ref="s5">&#167;5</a> and the trap in <a class="xref" data-ref="s6">&#167;6</a>.</li>
        </ul>
        <p>The remedy is a discipline, not a library call: apply the multiplier <em>exactly once</em>, and know which side of the trade already applied it.</p>
      </div>
      <div class="margin">
        <div class="mtag">// margin</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> why not just rebase?</button>
          <div class="panel"><div><div class="in">A rebasing token rewrites every balance on every corporate action, expensive, and it breaks any contract that cached a balance. Scaled UI Amount keeps balances immutable and moves the adjustment to read time, so integrators opt in by reading <code>uiMultiplier()</code> rather than being forced to track rebases.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 3 THE MULTIPLIER -->
    <section class="sec" id="s3">
      <div class="body">
        <div class="sh"><span class="no">3.</span><h2>The multiplier</h2></div>
        <p><span class="mono-em">uiMultiplier()</span> returns underlying shares per token as an 18-decimal fixed-point number. <span class="mono-em">MULTIPLIER_ONE</span> is <span class="mono-em">10n ** 18n</span>. A token that has never had a corporate action reads exactly one; a split or dividend moves it.</p>
        <p>Read it with <span class="mono-em">readUiMultiplier(client, token)</span>, which throws <span class="mono-em">Erc8056NotImplementedError</span> for a plain ERC-20 rather than returning a misleading zero. For scheduled changes, <span class="mono-em">readMultiplierState</span> returns the current value and a <em>pending</em> one.</p>
      </div>
      <div class="margin">
        <div class="mtag">// margin &#183; live</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> a real value on chain 4663</button>
          <div class="panel"><div><div class="in">Token <b>WEEK</b> at <code>0xc93a8c440CEa26D7445dF01729f193b27965099f</code>. On <b>2026-07-15</b> its multiplier read <code>2006182524271844660n</code>, i.e. <b>1 raw WEEK token = 2.0062 shares</b>. Read it yourself; the value is pinned by this package's live test suite, not folklore.</div></div></div>
        </div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> pending vs applied</button>
          <div class="panel"><div><div class="in">After a scheduled change activates, <code>newUIMultiplier()</code> and <code>effectiveAt()</code> retain the last applied values. &#8220;Pending&#8221; means a <em>future</em> <code>effectiveAt</code> <b>and</b> a differing value, exactly what <code>readMultiplierState</code> encodes, so you never mistake history for a queued action.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 4 RULE 1 POSITIONS -->
    <section class="sec" id="s4">
      <div class="body">
        <div class="sh"><span class="no">4.</span><h2>Rule 1 &#183; positions</h2></div>
        <p>Raw balances understate holdings. The true share-equivalent is:</p>
        <div class="list"><span class="cm">// bit-for-bit the on-chain balanceOfUI() math</span>
trueBalance({ raw, multiplier })  =  raw &#215; multiplier &#247; 1e18   <span class="cm">// floored</span></div>
        <p><span class="mono-em">trueBalance</span> floors exactly as the chain does, so your number equals <span class="mono-em">balanceOfUI</span> to the wei. This is the number to show a user as &#8220;shares held&#8221;, never the raw ERC-20 balance. It depends only on <a class="xref" data-ref="s3">&#167;3 (the multiplier)</a>.</p>
      </div>
      <div class="margin">
        <div class="mtag">// margin</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> conversion, computed locally</button>
          <div class="panel"><div><div class="in"><code>toUiAmount</code> / <code>fromUiAmount</code> perform the spec conversion math in JS, because the on-chain conversion extension (<code>toUIAmount</code>/<code>fromUIAmount</code>) is <b>not deployed</b>, calls revert. See <a class="xref" data-ref="s7">&#167;7</a>.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 5 RULE 2 VALUATION -->
    <section class="sec" id="s5">
      <div class="body">
        <div class="sh"><span class="no">5.</span><h2>Rule 2 &#183; valuation</h2></div>
        <p>To value a position you must declare <em>what kind of price you hold</em>. A bare <span class="mono-em">number</span> does not compile; the only way to make a <span class="mono-em">StockPrice</span> is a branded constructor:</p>
        <div class="list"><span class="cm">// feed price (USD per TOKEN): multiplier NOT re-applied</span>
trueValue({ raw, multiplier, price: <b>adjustedPrice</b>(100.62) })

<span class="cm">// share quote (USD per SHARE): multiplier applied once</span>
trueValue({ raw, multiplier, price: <b>rawPrice</b>(100.53) })</div>
        <p>The multiplier is applied by <span class="mono-em">trueValue</span> exactly zero or one times, decided by the price's brand. Choosing the wrong brand is the trap in <a class="xref" data-ref="s6">&#167;6</a>, and here it is a type error, not a silent loss.</p>
      </div>
      <div class="margin">
        <div class="mtag">// margin &#183; the table</div>
        <div class="note" data-note open>
          <button type="button"><span class="mk"><b>+</b></span> which constructor, when</button>
          <div class="panel"><div><div class="in"><b>adjustedPrice(usd)</b>, a Chainlink feed answer on Robinhood Chain. The multiplier is already inside the price; <code>trueValue</code> applies it <b>never</b>.<br><br><b>rawPrice(usd)</b>, an off-chain exchange or broker share quote. The multiplier is applied <b>exactly once</b>. Passing a plain <code>number</code> is a deliberate compile error.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 6 THE TRAP -->
    <section class="sec" id="s6">
      <div class="body">
        <div class="sh"><span class="no">6.</span><h2>The one trap, spelled out</h2></div>
        <p>On Robinhood Chain, <b>Chainlink Stock Token feed answers are already multiplier-adjusted</b>: the answer is the price of one TOKEN, not one underlying share. Robinhood's docs state it, and the market confirms it. So you scale the balance (<a class="xref" data-ref="s4">&#167;4</a>), and you take the feed price as-is (<a class="xref" data-ref="s5">&#167;5</a>).</p>
        <p>Get this backwards and every position off a live feed is wrong by the multiplier, here, off by roughly 2&#215; on WEEK.</p>
      </div>
      <div class="margin">
        <div class="mtag">// margin &#183; evidence</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> three numbers at one block</button>
          <div class="panel"><div><div class="in">At block <b>10,745,112</b> the Uniswap v3 <b>SGOV/USDG</b> pool priced the token at <code>$100.6075</code>; the Chainlink feed answered <code>$100.6215</code>; the unadjusted share price was <code>$100.5252</code>. The pool and the feed agree on the <em>token</em>; only the share price differs, proof the feed already carries the multiplier.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 7 DEPLOYED REALITY -->
    <section class="sec" id="s7">
      <div class="body">
        <div class="sh"><span class="no">7.</span><h2>Deployed reality vs the draft</h2></div>
        <p>Facts about Robinhood's deployed <span class="mono-em">Stock</span> implementation (<span class="mono-em">0xb354&#8230;5aE2</span>, verified source) that the spec draft alone will not tell you. This package encodes the deployed flavor, not the draft's.</p>
        <ul class="plain">
          <li data-b="&#8226;">The optional transfer event is <span class="mono-em">TransferWithScaledUI</span>, not the draft's <span class="mono-em">TransferWithUIAmount</span>. Both ABIs ship; indexers need the deployed topic.</li>
          <li data-b="&#8226;">The conversion extension is <b>not implemented</b>; calls revert. This package computes conversions locally (<a class="xref" data-ref="s4">&#167;4</a>).</li>
          <li data-b="&#8226;">Issuer updates go through <span class="mono-em">updateMultiplier(uint256)</span> and <span class="mono-em">updateMultiplier(uint256,uint256)</span>.</li>
        </ul>
      </div>
      <div class="margin">
        <div class="mtag">// margin</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> the event topic indexers need</button>
          <div class="panel"><div><div class="in"><code>TransferWithScaledUI</code> hashes to topic <code>0x37e7f0db&#8230;3802</code>. Subscribe to that, not to the draft's <code>TransferWithUIAmount</code>, or you will index nothing on the live chain.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 8 API -->
    <section class="sec" id="s8">
      <div class="body">
        <div class="sh"><span class="no">8.</span><h2>API surface</h2></div>
        <p>Nine reads and constructors, one ABI. Detection never throws; a plain ERC-20 resolves cleanly to false.</p>
        <ul class="plain">
          <li data-b="&#8226;"><span class="mono-em">readUiMultiplier</span> &#183; <span class="mono-em">readMultiplierState</span> &#183; <span class="mono-em">watchMultiplier</span>, read and follow the factor and its <em>UIMultiplierUpdated</em> events (<a class="xref" data-ref="s3">&#167;3</a>).</li>
          <li data-b="&#8226;"><span class="mono-em">trueBalance</span> &#183; <span class="mono-em">trueValue</span> &#183; <span class="mono-em">adjustedPrice</span> &#183; <span class="mono-em">rawPrice</span>, the two rules and their branded prices (<a class="xref" data-ref="s4">&#167;4</a>, <a class="xref" data-ref="s5">&#167;5</a>).</li>
          <li data-b="&#8226;"><span class="mono-em">supportsErc8056</span> &#183; <span class="mono-em">detectErc8056</span>, ERC-165 first, direct probe fallback, per-extension report.</li>
          <li data-b="&#8226;"><span class="mono-em">erc8056Abi</span> &#183; <span class="mono-em">INTERFACE_IDS</span> &#183; <span class="mono-em">MULTIPLIER_ONE</span>, ABI fragments and constants (<a class="xref" data-ref="s9">&#167;9</a>).</li>
        </ul>
      </div>
      <div class="margin">
        <div class="mtag">// margin &#183; quickstart</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> read a multiplier in four lines</button>
          <div class="panel"><div><div class="in"><div class="list" style="margin:0"><span class="st">import</span> { readUiMultiplier } <span class="st">from</span> <span class="st">'erc8056'</span>
<span class="st">const</span> m = <span class="st">await</span> readUiMultiplier(
  client, WEEK)
<span class="cm">// 2006182524271844660n</span></div></div></div></div>
        </div>
      </div>
    </section>

    <!-- 9 INTERFACE IDS -->
    <section class="sec" id="s9">
      <div class="body">
        <div class="sh"><span class="no">9.</span><h2>Interface IDs</h2></div>
        <p>Four ERC-165 interface identifiers, taken from the spec, re-derived from selector XOR, and confirmed by live <span class="mono-em">supportsInterface</span> reads against real Stock Tokens.</p>
        <div class="list">core          <b>0xa60bf13d</b>
metadata      <b>0x4bd27648</b>
events        <b>0x57854fc3</b>
conversion    <b>0xd890fd71</b>  <span class="cm">// declared, not deployed (&#167;7)</span></div>
      </div>
      <div class="margin">
        <div class="mtag">// margin</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> why re-derive them</button>
          <div class="panel"><div><div class="in">Trusting a draft's printed ID is how indexers ship dead detection. Every ID here is XORed from its own selectors <b>and</b> checked against a live <code>supportsInterface</code> call, so the constant and the chain agree before you depend on it.</div></div></div>
        </div>
      </div>
    </section>

    <!-- 10 REFERENCE IMPL -->
    <section class="sec" id="s10">
      <div class="body">
        <div class="sh"><span class="no">10.</span><h2>Reference implementation</h2></div>
        <p><span class="mono-em">contracts/src/IERC8056.sol</span> declares all four spec interfaces plus an <span class="mono-em">ERC8056InterfaceIds</span> constants library. <span class="mono-em">ERC8056Consumer.sol</span> is the commented pattern for consuming these tokens from another contract, detection, true balances, and both valuation branches, with the multiplier deliberately absent from the adjusted-feed branch.</p>
        <p>Fork tests run against live mainnet Stock Tokens, read-only, no keys, no funds:</p>
        <div class="list"><button class="copy" data-copy="forge test --fork-url https://rpc.mainnet.chain.robinhood.com">COPY</button><span class="cm"># asserts, against the chain itself:</span>
<span class="cm">#   totalSupplyUI == totalSupply * uiMultiplier / 1e18</span>
forge test --fork-url https://rpc.mainnet.chain.robinhood.com</div>
      </div>
      <div class="margin">
        <div class="mtag">// margin</div>
        <div class="note" data-note>
          <button type="button"><span class="mk"><b>+</b></span> what the fork test proves</button>
          <div class="panel"><div><div class="in">Against <b>AAPL / SGOV / WEEK</b> it asserts: mandatory ERC-165 answers, live multiplier values, <code>totalSupplyUI == totalSupply &#215; uiMultiplier &#247; 1e18</code> bit-for-bit, <code>balanceOfUI</code> agreement on a real top holder, the absence of the conversion extension, and that valuation never re-applies the multiplier.</div></div></div>
        </div>
      </div>
    </section>

    <!-- INSTALL -->
    <section class="sec" id="get" style="grid-template-columns:1fr">
      <div class="body" style="max-width:none">
        <div class="sh"><span class="no">&#167;</span><h2>Install &amp; verify</h2></div>
        <div class="install">
          <button class="copy" data-copy="npm install erc8056 viem">COPY</button>
<span class="p">npm install erc8056 viem</span>
<span class="c"># unit + type-level tests (misuse must not compile)</span>
<span class="p">npm test</span>
<span class="c"># live reads against Robinhood Chain mainnet (public RPC, read-only)</span>
<span class="p">npm run test:live</span>
        </div>
        <div class="btns">
          <a class="btn solid" href="https://www.npmjs.com/package/erc8056">npm</a>
          <a class="btn" href="https://github.com/nirholas/erc8056">source</a>
          <a class="btn" href="https://eips.ethereum.org/EIPS/eip-8056">the eip</a>
          <a class="btn" href="https://robinhoodchain.blockscout.com/address/0xb35490d6f9163DE4F80d88dc75c3516eb64C5aE2?tab=contract">deployed Stock</a>
        </div>
      </div>
    </section>
  </main>

  <footer>
    <div class="big">apply it<br>exactly once.</div>
    <div class="meta">
      ERC-8056 &#183; Scaled UI Amount &#183; uiMultiplier<br>
      <a href="https://github.com/nirholas/erc8056">github.com/nirholas/erc8056</a><br>
      <a href="https://www.npmjs.com/package/erc8056">npmjs.com/package/erc8056</a><br>
      built by <a href="https://x.com/nichxbt">@nichxbt</a> &#183; <a href="https://three.ws">three.ws</a> &#183; not affiliated with Robinhood Markets
    </div>
  </footer>
</div>

<script>
"use strict";

/* ---------- masthead subtitle types itself ---------- */
(function(){
  const el = document.getElementById('subtitle');
  const text = 'Scaled UI Amount, the uiMultiplier standard, with living margins.';
  const reduce = matchMedia('(prefers-reduced-motion:reduce)').matches;
  if(reduce){ el.textContent = text; return; }
  let i = 0;
  const t = setInterval(()=>{
    i += 1; el.textContent = text.slice(0,i);
    if(i >= text.length) clearInterval(t);
  }, 26);
})();

/* ---------- living margin notes: expand in place ---------- */
document.querySelectorAll('.note[data-note]').forEach(note=>{
  const btn = note.querySelector('button');
  if(note.hasAttribute('open')) note.classList.add('open');
  btn.addEventListener('click', ()=> note.classList.toggle('open'));
});

/* ---------- cross-references: draw a line, scroll, flash ---------- */
const svg = document.getElementById('xrefsvg');
const path = document.getElementById('xrefpath');
let activeXref = null, rafId = 0;

function centerRight(el){
  const r = el.getBoundingClientRect();
  return { x: r.right, y: r.top + r.height/2, top:r.top, bottom:r.bottom };
}
function drawLine(fromEl, toEl){
  const a = fromEl.getBoundingClientRect();
  const b = toEl.getBoundingClientRect();
  const ax = a.right, ay = a.top + a.height/2;
  // aim at the target heading's left edge, clamped into the viewport vertically
  const bx = b.left + 8;
  const by = Math.max(12, Math.min(innerHeight-12, b.top + 18));
  const midx = Math.max(ax, bx) + 60;
  const d = `M ${ax+4} ${ay} C ${midx} ${ay}, ${midx} ${by}, ${bx} ${by}`;
  path.setAttribute('d', d);
  const len = path.getTotalLength();
  path.style.strokeDasharray = '5 4';
  path.style.opacity = '1';
}
function clearLine(){ path.setAttribute('d',''); path.style.opacity='0'; }

document.querySelectorAll('.xref').forEach(x=>{
  const targetId = x.getAttribute('data-ref');
  const target = document.getElementById(targetId);
  if(!target) return;
  function show(){
    activeXref = { x, target };
    x.classList.add('on');
    target.classList.add('xtarget');
    drawLine(x, target);
  }
  function hide(){
    x.classList.remove('on');
    target.classList.remove('xtarget');
    clearLine();
    activeXref = null;
  }
  x.addEventListener('pointerenter', show);
  x.addEventListener('pointerleave', hide);
  x.addEventListener('focus', show);
  x.addEventListener('blur', hide);
  x.addEventListener('click', e=>{
    e.preventDefault();
    target.scrollIntoView({ behavior:'smooth', block:'center' });
    target.classList.remove('flash'); void target.offsetWidth; target.classList.add('flash');
    // keep the line briefly during the scroll, then clear
    setTimeout(()=>{ if(activeXref && activeXref.x===x){ hide(); } }, 900);
  });
});

/* redraw the active line on scroll/resize without layout thrash */
function tick(){
  rafId = 0;
  if(activeXref) drawLine(activeXref.x, activeXref.target);
}
function schedule(){ if(!rafId) rafId = requestAnimationFrame(tick); }
addEventListener('scroll', schedule, { passive:true });
addEventListener('resize', ()=>{ svg.setAttribute('viewBox',`0 0 ${innerWidth} ${innerHeight}`); schedule(); });
svg.setAttribute('viewBox',`0 0 ${innerWidth} ${innerHeight}`);

/* ---------- copy buttons ---------- */
document.querySelectorAll('.copy').forEach(btn=>{
  btn.addEventListener('click', e=>{
    e.stopPropagation();
    navigator.clipboard.writeText(btn.dataset.copy||'').then(()=>{
      const t=btn.textContent; btn.textContent='COPIED'; setTimeout(()=>btn.textContent=t,1200);
    }).catch(()=>{});
  });
});

/* ---------- smooth-scroll the TOC ---------- */
document.querySelectorAll('.toc a').forEach(a=>{
  a.addEventListener('click', e=>{
    const t = document.querySelector(a.getAttribute('href'));
    if(t){ e.preventDefault(); t.scrollIntoView({behavior:'smooth', block:'start'}); }
  });
});
</script>
</body>
</html>