Announce a Distribution

Wrap a holder-impacting action with an onchain disclosure using the B20 Asset announce function.

Bracket a holder-impacting action with an onchain description and supporting URI. announce emits Announcement before the inner calls and EndAnnouncement after, giving indexers a reliable bracket for every announced change.

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.

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 Announcements Work

announce takes internalCalls, a single-use id, a description, and a uri.

• internalCalls: ABI-encoded calldata blobs targeting this asset. Each blob must be at least 4 bytes. Pass an empty array for a notice with no onchain effect.
• id: chosen by the caller and consumed on success. Reuse reverts AnnouncementIdAlreadyUsed. After success, isAnnouncementIdUsed(id) returns true.
• description and uri: operator-supplied strings. The asset does not verify them.

The asset emits Announcement(caller, id, description, uri), runs the inner calls atomically, then emits EndAnnouncement(id). If any inner call fails, the whole transaction reverts. Nesting announce inside an inner call reverts AnnouncementInProgress.

The caller must hold OPERATOR_ROLE. Any other caller reverts AccessControlUnauthorizedAccount. Inner calls keep their own role gates. If an inner call needs MINT_ROLE or BURN_ROLE, grant those to the operator as well.

Announce and Distribute the Stock Dividend

TypeScript

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

export async function announceStockDividend(token: Address, holders: Address[]) {
  const mint = encodeFunctionData({
    abi: assetAbi,
    functionName: "batchMint",
    args: [holders, [parseUnits("30", 6), parseUnits("20", 6)]],
  });
  const id = `dividend-${Date.now()}`;
  await sendContract({
    address: token,
    abi: assetAbi,
    functionName: "announce",
    args: [[mint], id, "Five-percent stock dividend", "https://example.com/actions/dividend"],
  });
  const used = await publicClient.readContract({ address: token, abi: assetAbi, functionName: "isAnnouncementIdUsed", args: [id] });
  if (!used) throw new Error("Announcement was not recorded");
}

The operator needs OPERATOR_ROLE and MINT_ROLE. Recipients must pass MINT_RECEIVER_POLICY. MINT must not be paused. On success the asset emits Announcement, then one Transfer(address(0), recipient, amount) per recipient, then EndAnnouncement.

On success, the unique announcement id is marked used and the batch mint executes between Announcement and EndAnnouncement.

This example issues additional shares. It does not distribute a cash dividend. A reinvested dividend that only rescales displayed balances is a multiplier update, covered below and in Apply a Multiplier.

Announce Other Changes

The same bracket discloses any operator-driven change. Each scenario below lists the roles the operator needs and the events the asset emits.

Multiplier Update

Wrap updateUIMultiplier(newMultiplier, effectiveAt). A 2-for-1 split uses 2e18. A reverse split uses a value below 1e18. The operator needs OPERATOR_ROLE only.

Announce a multiplier update

function announceMultiplierUpdate(address token, uint256 newMultiplier, uint256 effectiveAt) public {
    bytes[] memory calls = new bytes[](1);
    calls[0] = abi.encodeCall(IB20Asset.updateUIMultiplier, (newMultiplier, effectiveAt));
    IB20Asset(token).announce(
        calls,
        "2026-multiplier-01",
        "2-for-1 multiplier update",
        "https://example.com/announcements/2026-multiplier-01"
    );
}

On success the asset emits Announcement, UIMultiplierUpdated, then EndAnnouncement. UIMultiplierUpdated means the schedule was recorded, not that the multiplier is already active. See Apply a Multiplier for the full schedule, cancel, and override flow.

To replace a live pending update, cancel and reschedule in one 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, (newMultiplier, effectiveAt));
IB20Asset(token).announce(calls, id, description, uri);

Treasury Burn

Wrap burnWithMemo(amount, memo). The call burns the operator’s own balance. The operator needs OPERATOR_ROLE and BURN_ROLE. BURN must not be paused.

Announce a treasury burn

bytes[] memory calls = new bytes[](1);
calls[0] = abi.encodeCall(IB20Asset.burnWithMemo, (amount, memo));
IB20Asset(token).announce(calls, id, "Treasury burn", uri);

On success the asset emits Announcement, Transfer(operator, address(0), amount), Memo, then EndAnnouncement. totalSupply decreases.

Notice With No Onchain Effect

Pass an empty internalCalls array. The operator needs OPERATOR_ROLE only. The asset emits Announcement then EndAnnouncement with nothing between them. The id is still consumed.

Notice only

IB20Asset(token).announce(new bytes[](0), id, description, uri);

Common Errors

Error	Cause	Fix
AccessControlUnauthorizedAccount(caller, OPERATOR_ROLE)	Caller does not hold OPERATOR_ROLE.	Grant OPERATOR_ROLE to the operator.
AnnouncementIdAlreadyUsed(id)	A prior successful announce consumed id.	Choose a new single-use id.
InternalCallMalformed(call)	An inner-call blob is shorter than 4 bytes.	Pass ABI-encoded calldata that includes a selector.
AnnouncementInProgress()	An inner call targeted announce.	Do not nest announce.
InternalCallFailed(call)	An inner call reverted. The reason is not bubbled.	Replay call directly to see the underlying error, then fix the cause.

Typical inner causes of InternalCallFailed: missing MINT_ROLE or BURN_ROLE, paused MINT or BURN, UIMultiplierUpdateExists, PolicyForbids, SupplyCapExceeded, InsufficientBalance. A Solidity Panic (for example overflow) propagates raw and is not wrapped as InternalCallFailed.

See Also

Issue Shares

Mint asset units to holders.