Apply a Multiplier

Schedule a B20 Asset multiplier update so displayed share counts change at a future time without rewriting raw balances. A stock split is one example.

Schedule a 2-for-1 stock split by calling updateUIMultiplier(2e18, effectiveAt) on a B20 Asset. Raw balanceOf, totalSupply, and transfer amounts stay unchanged. Wallets and indexers read the post-split share count through balanceOfUI and related views once effectiveAt passes.

Real-world asset (RWA) tokenization is one of many use cases for the B20 Asset standard. The examples on this page use a stock token for illustration; the same flows apply to other asset types.

Tokenized securities examples shown for illustration. Base is a general-purpose blockchain; issuance and compliance are the responsibility of the issuer under applicable law.

The routine path is updateUIMultiplier. The deprecated updateMultiplier applies a value immediately and clears any pending update. Use it only as an emergency override.

Demo

The demo uses a local browser-generated account to submit real transactions on Base Vibenet. If Vibenet or its B20 features are unavailable, it automatically switches to an illustrative offline version.

New to B20? See the B20 Token Standard for the concepts and a full launch walkthrough. These samples target base-std@be6d045, viem@2.55.11, and Base Foundry v1.1.1.

How the Multiplier Works

Raw balanceOf is unchanged by a split. The multiplier changes only the derived UI view:

Read	Formula
uiMultiplier()	Effective multiplier at block.timestamp
balanceOfUI(account)	balanceOf(account) * uiMultiplier() / 1e18
totalSupplyUI()	totalSupply() * uiMultiplier() / 1e18
toUIAmount(raw) / fromUIAmount(ui)	Convert at the effective multiplier

The multiplier is an 18-decimal WAD: 1e18 is 1.0. A 2-for-1 split uses 2e18. A 1-for-2 reverse split uses 5e17. Integer division rounds down, so the rounding loss is confined to the scaled view and is at most one unit of the scaled amount. The raw-side difference on a round trip through fromUIAmount can be larger when the multiplier is below 1e18. Prefer 18 decimals for stock tokens to keep that effect small.

Schedule and Verify the Split Multiplier

Only an account holding OPERATOR_ROLE may call updateUIMultiplier, cancelUIMultiplierUpdate, or updateMultiplier. Any other caller reverts AccessControlUnauthorizedAccount. The token created in Create an Asset Token grants OPERATOR_ROLE to the deployer.

TypeScript

import { type Address } from "viem";
import { publicClient } from "../../shared/clients.js";
import { assetAbi } from "../abi.js";
import { sendContract } from "../write.js";

export async function scheduleTwoForOneSplit(token: Address) {
  const effectiveAt = BigInt(Math.floor(Date.now() / 1000) + 86_400);
  await sendContract({ address: token, abi: assetAbi, functionName: "updateUIMultiplier", args: [2n * 10n ** 18n, effectiveAt] });
  const pending = await publicClient.readContract({ address: token, abi: assetAbi, functionName: "newUIMultiplier" });
  if (pending !== 2n * 10n ** 18n) throw new Error("Split was not scheduled");
  return effectiveAt;
}

On success, the asset emits UIMultiplierUpdated(oldMultiplier, newMultiplier, effectiveAtTimestamp). That event fires when the update is recorded, not when the multiplier becomes active.

Read the Live Pending State

Read the pending state

asset.uiMultiplier();     // still the current multiplier
asset.newUIMultiplier();  // scheduled target
asset.effectiveAt();      // flip timestamp

A second updateUIMultiplier while a pending update is live reverts UIMultiplierUpdateExists. To replace a pending update, cancel first, then reschedule.

Confirm After the Effective Time

When block.timestamp >= effectiveAt, uiMultiplier() returns the new multiplier. Maturation emits no event. Do not wait for a second event at the flip.

uiMultiplier() returns 2e18 at or after effectiveAt. Raw balanceOf stays unchanged. balanceOfUI doubles.

Cancel a Pending Update

Call before effectiveAt to discard the pending split:

Cancel the pending update

asset.cancelUIMultiplierUpdate();

Emits UIMultiplierUpdateCancelled(cancelledMultiplier, cancelledEffectiveAt). Calling with no live pending update, including after maturity, reverts UIMultiplierUpdateDoesNotExist.

To cancel and reschedule atomically, wrap both calls in announce:

Cancel and reschedule in one announcement

bytes[] memory calls = new bytes[](2);
calls[0] = abi.encodeCall(IB20Asset.cancelUIMultiplierUpdate, ());
calls[1] = abi.encodeCall(IB20Asset.updateUIMultiplier, (secondMultiplier, secondEffectiveAt));
asset.announce(calls, "2026-multiplier-02", "Rescheduled multiplier update", "https://example.com/announcements/2026-multiplier-02");

Emergency Override

Use updateMultiplier(newMultiplier) only when a pending update is wrong and you cannot wait for effectiveAt. It applies the value immediately and clears any pending update. The interface guarantees that it emits both MultiplierUpdated and UIMultiplierUpdated. The base-std stock-split guide documents the sequence as:

Situation	Events (in order)
Live pending (effectiveAt > block.timestamp)	UIMultiplierUpdateCancelled, then MultiplierUpdated(new), then UIMultiplierUpdated(old, new, effectiveAtTimestamp)
Matured or no pending	MultiplierUpdated(new), then UIMultiplierUpdated(old, new, effectiveAtTimestamp)

MultiplierUpdated is deprecated. Process only UIMultiplierUpdated to avoid handling the same update twice.

Integrator Rules

• Listen for UIMultiplierUpdated, not the deprecated MultiplierUpdated.
• If effectiveAtTimestamp > block.timestamp, treat the update as pending until that time.
• Maturation emits nothing. Do not wait for a second event at the flip.
• On UIMultiplierUpdateCancelled, discard the pending update.
• Detect a live pending update with effectiveAt() > block.timestamp. Do not check effectiveAt() == 0.

Common Errors

Error	Cause	Fix
AccessControlUnauthorizedAccount(caller, OPERATOR_ROLE)	Caller lacks OPERATOR_ROLE.	Grant OPERATOR_ROLE to the operator.
InvalidMultiplier()	newMultiplier is zero or above MAX_UI_MULTIPLIER.	Pass a value in (0, MAX_UI_MULTIPLIER].
EffectiveAtInPast(effectiveAt)	effectiveAt <= block.timestamp.	Pass a strictly future timestamp.
EffectiveAtTooFar(effectiveAt)	effectiveAt > type(uint64).max.	Pass a timestamp that fits in uint64.
UIMultiplierUpdateExists(effectiveAt)	A live pending update already exists.	Cancel first, or cancel and reschedule in one announce.
UIMultiplierUpdateDoesNotExist()	cancelUIMultiplierUpdate with no live pending update, including after maturity.	Call only while effectiveAt() > block.timestamp.
AnnouncementIdAlreadyUsed(id)	announce reused an id.	Choose a new single-use id.
InternalCallFailed(call)	An inner call in announce reverted.	Fix the encoded calldata and retry.

See Also

Announce a Stock Dividend

Record an onchain distribution announcement.

Pause Transfers

Halt transfers in an emergency.