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.

8.7 KB
Raw Blame

erc8056

Reference implementation of ERC-8056 (Scaled UI Amount / uiMultiplier()), the corporate-actions standard used by tokenized equities such as Robinhood Chain Stock Tokens.

When a tokenized stock splits or reinvests a dividend, its raw ERC-20 balances never change. Instead the issuer updates one number, uiMultiplier(), and every correct integration scales its display and valuation by it, exactly once. Every naive integration gets this wrong in one of two ways: showing raw balances as shares (understates positions) or re-applying the multiplier to an already-adjusted price feed (double-counts corporate actions). This package makes both mistakes hard: the math is bit-for-bit the on-chain math, and the price types make the wrong valuation branch a compile error.

The full explainer, with live on-chain data: https://nirholas.github.io/erc8056/

Website

The site in docs/ is a single self-contained index.html (inline CSS + JS, zero external requests, works from file://). It presents ERC-8056 as a typewritten RFC with living margins: the spec reads as a monospaced document, every clause carries a margin annotation that expands in place when engaged, and following a cross-reference (§4, §5, §6) draws a connecting line between the clauses. Every figure is real, pinned to live chain 4663 state.

Deploy the docs/ folder anywhere static:

Deploy to Netlify Deploy to Vercel Deploy to Cloudflare Pages

Config lives in wrangler.toml, netlify.toml, and vercel.json. Each points the platform at docs/.

  • Tiny: about 2.5 kB gzipped, zero runtime dependencies (viem is a peer).
  • Verified: every semantic claim is pinned to live Robinhood Chain mainnet state by the test suites (Vitest live reads + Foundry fork tests), not folklore.
  • Solidity included: IERC8056.sol interfaces and a commented reference consumer contract.

Install

npm install erc8056 viem

Quickstart

import { createPublicClient, http } from 'viem'
import { robinhood } from 'viem/chains'
import {
  readUiMultiplier, readMultiplierState, watchMultiplier,
  trueBalance, trueValue, adjustedPrice, rawPrice,
  supportsErc8056, detectErc8056,
} from 'erc8056'

const client = createPublicClient({ chain: robinhood, transport: http() })
const WEEK = '0xc93a8c440CEa26D7445dF01729f193b27965099f' // a live Stock Token

// The multiplier: underlying shares per token, 18-decimal fixed point.
const multiplier = await readUiMultiplier(client, WEEK)
// 2006182524271844660n on 2026-07-15: 1 raw WEEK token = 2.0062 shares.

// Rule 1 - positions. Raw balances understate holdings:
const shares = trueBalance({ raw: rawBalance, multiplier })
// Bit-for-bit the on-chain balanceOfUI() math (raw * multiplier / 1e18, floored).

// Rule 2 - valuation. Declare what kind of price you hold; a bare number
// does not compile:
const viaFeed = trueValue({
  raw: rawBalance,
  multiplier,
  price: adjustedPrice(100.62), // Chainlink on Robinhood Chain: USD per TOKEN,
})                              // multiplier already applied - it is NOT re-applied

const viaShareQuote = trueValue({
  raw: rawBalance,
  multiplier,
  price: rawPrice(100.53), // off-chain equity quote: USD per SHARE,
})                         // multiplier applied exactly once

// Corporate-action monitoring (UIMultiplierUpdated events):
const unwatch = watchMultiplier(client, WEEK, (update) => {
  console.log(`${update.oldMultiplier} -> ${update.newMultiplier}, effective ${update.effectiveAt}`)
})

// Scheduled-but-not-yet-effective changes:
const { current, pending } = await readMultiplierState(client, WEEK)

// Graceful detection - a plain ERC-20 resolves to false, nothing throws:
await supportsErc8056(client, someToken)
await detectErc8056(client, someToken) // per-extension ERC-165 report

The one trap, spelled out

On Robinhood Chain, Chainlink Stock Token feed answers are already multiplier-adjusted: the answer is the price of one TOKEN, not one underlying share. Robinhood's docs state it, and the market confirms it (at block 10,745,112 the Uniswap v3 SGOV/USDG pool priced the token at $100.6075 vs the feed's $100.6215, while the unadjusted share price was $100.5252). So:

Your price source Construct with Multiplier applied by trueValue
Chainlink feed on Robinhood Chain adjustedPrice(usd) never (already inside the price)
Off-chain share quote (exchange, broker) rawPrice(usd) exactly once

Passing a bare number as price is a type error. That is deliberate.

API

Export What it does
readUiMultiplier(client, token) Read uiMultiplier(); throws Erc8056NotImplementedError for non-implementers
supportsErc8056(client, token) true/false, never throws; ERC-165 first, direct probe fallback
detectErc8056(client, token) Full report: core, ERC-165 route, per-extension flags
readMultiplierState(client, token) Current + scheduled multiplier (pending is null unless a change is queued)
watchMultiplier(client, token, cb) Poll-based watcher for UIMultiplierUpdated; returns unwatch
trueBalance({ raw, multiplier }) Underlying-share balance, floored like on-chain balanceOfUI
trueValue({ raw, multiplier, price, decimals? }) USD value with the multiplier applied exactly once
adjustedPrice(usd) / rawPrice(usd) Branded price constructors (the only way to make a StockPrice)
toUiAmount(raw, multiplier) / fromUiAmount(ui, multiplier) Spec conversion math, computed locally (the on-chain conversion extension is not deployed)
erc8056Abi, INTERFACE_IDS, MULTIPLIER_ONE ABI fragments, ERC-165 IDs, 10n ** 18n

All interface IDs (0xa60bf13d, 0x4bd27648, 0x57854fc3, 0xd890fd71) are from the spec, re-derived from selector XOR, and confirmed by live supportsInterface reads.

Solidity

contracts/src/IERC8056.sol declares all four spec interfaces plus an ERC8056InterfaceIds constants library. contracts/src/ERC8056Consumer.sol is the commented reference pattern for consuming ERC-8056 tokens from another contract: detection, true balances, and both valuation branches, with the multiplier deliberately absent from the adjusted-feed branch.

Fork tests run against live mainnet Stock Tokens (read-only, no keys, no funds):

cd contracts
forge soldeer install
forge test --fork-url https://rpc.mainnet.chain.robinhood.com

They assert, against the chain itself: mandatory ERC-165 answers on AAPL/SGOV/WEEK, live multiplier values, totalSupplyUI == totalSupply * uiMultiplier / 1e18 bit-for-bit, balanceOfUI agreement on a real top holder, the absence of the conversion extension, and that the valuation math never re-applies the multiplier.

Deployed reality vs the draft

Facts about Robinhood's deployed Stock implementation (0xb35490d6f9163DE4F80d88dc75c3516eb64C5aE2, verified source) that the spec draft alone will not tell you:

  • The optional transfer event is emitted as TransferWithScaledUI, not the draft's TransferWithUIAmount. Both event ABIs ship in erc8056Abi; indexers need the deployed flavor's topic (0x37e7f0db...3802).
  • The conversion extension (toUIAmount/fromUIAmount) is not implemented; calls revert. This package computes the conversions locally instead.
  • Issuer updates go through updateMultiplier(uint256) / updateMultiplier(uint256,uint256).
  • After a scheduled change activates, newUIMultiplier()/effectiveAt() retain the last applied values; "pending" means a future effectiveAt AND a differing value. readMultiplierState encodes exactly that.

Tests

npm test          # unit math + type-level tests (misuse must not compile)
npm run test:live # live reads against Robinhood Chain mainnet (public RPC, read-only)

Docs site

docs/ is a self-contained static site (the explainer above, with a live multiplier widget reading chain 4663 client-side). One-time GitHub Pages setup: repository Settings, then Pages, then deploy from branch main, folder /docs.

Publishing (owner step)

npm publish --access public

License

All rights reserved. See LICENSE.

Built by nirholas · three.ws