Skip to content
Onchain Rights

Announcements

Token issuers need a way to alert indexers and wallets when a token's state changes. An announcement does that: it can apply the change on the token and couple that change with an identifier and a description. This building block defines that capability.

Overview

On an Ethereum Virtual Machine (EVM) chain, the contract exposes announce. That function emits an Announcement event: a log written into the transaction, separate from the token's stored state. Indexers read that log to recognize the state changes that belong to the announcement.

function announce(
    bytes[] calldata internalCalls,
    string calldata id,
    string calldata description,
    string calldata uri
) external;

event Announcement(
    address indexed caller,
    string id,
    string description,
    string uri
);
FieldEVM typeMeaning
calleraddressThe address that calls announce and executes the transaction.
idstringThe publisher's identifier for the announcement.
descriptionstringA short human-readable summary.
uristringThe location of the full document.

announce can couple that event with token changes in the same call, such as a mint or a burn. The chain keeps the event and those changes as a permanent record. Users and indexers can look back and see which state changes occurred with which announcement.

In practice

A cash dividend, example:2027:dividend-q1, is the announcement used below. The address and URI are illustrative. uri may be empty. These docs use a non-empty URI that resolves to a corporate action JSON document.

Before payment, the issuer publishes the terms and does not change the token. announce still builds a bracket in one transaction:

  1. Emit Announcement with the id, description, and uri.
  2. Run each supplied call, in order, against the same contract.
  3. Emit EndAnnouncement with the same id.
announce(
    new bytes[](0),
    "example:2027:dividend-q1",
    "Cash dividend of USD 0.50 for each underlying share. The token issuer reinvests the net proceeds.",
    "https://example.com/corporate-actions/dividend-q1.json"
);

Indexers see the opening event. Readers pair it with EndAnnouncement by example:2027:dividend-q1. Nothing sits between the two events.

emit Announcement(
    0x1111111111111111111111111111111111111111,
    "example:2027:dividend-q1",
    "Cash dividend of USD 0.50 for each underlying share. The token issuer reinvests the net proceeds.",
    "https://example.com/corporate-actions/dividend-q1.json"
);

When the reinvestment is part of the same announcement, the call list carries the token change instead of an empty list. A mint is one such call. Each entry is ABI-encoded calldata for this contract, and every effect between the two events belongs to the dividend. These are two shapes of the announcement, not two successful calls: a successful announce consumes example:2027:dividend-q1 for the lifetime of the contract. Identifiers are not globally unique. A reader must keep the chain and announcing contract with the id.

announce(
    internalCalls, // for example, a mint on this contract
    "example:2027:dividend-q1",
    "Cash dividend of USD 0.50 for each underlying share. The token issuer reinvests the net proceeds.",
    "https://example.com/corporate-actions/dividend-q1.json"
);

The bracket is a single transaction. If any call fails, the transaction reverts, no changes or event records from that call remain committed, and the id stays available. An inner call cannot open a second bracket.

Each call targets the announcing contract. The contract's own methods can call other contracts, and those effects remain inside the same bracket. A state change with no bracket around it has no disclosure through this mechanism. Readers can flag that change as undisclosed.

Announcements and revisions

The dividend example:2027:dividend-q1 can change after it is announced. A second announce cannot reuse that id, because a successful announce consumed it. The publisher keeps the id and the URI, replaces the document at that URI, and calls updateAnnouncement.

function updateAnnouncement(bytes[] calldata internalCalls, string calldata id) external;

An update uses the same bracket rules. internalCalls can be empty when only the terms change. When the action changes the token, the call carries those changes inside the existing announcement.

updateAnnouncement(internalCalls, "example:2027:dividend-q1");

The new document's revision and notification type tell readers how to interpret the changed terms. See Corporate action schema.

Authorization and trust

The caller on the record is the address that called announce and executed the transaction. That address does not prove that it represents the issuer of the underlying security. The description and the document at uri are claims made by that publisher.

The specification does not choose who may call announce. The implementation must still keep the call from reaching an operation that address is not allowed to perform. It should preserve the caller's identity while the inner calls run.

Designated announcement sources

A token can optionally designate another address as an announcement reference. Applications can then read that address's announcements for the token. This supports a shared provider or an announcement feed on another network.

The reference interface provides addition and removal events and isValidAnnouncementReference. References use multichain addresses, so a reader must retain the network as well as the address.

A document naming a token is not enough to establish this relationship. Readers check the token's designation before accepting a referenced source. A designation permits discovery of disclosures; it is not a general permission to change token state.

A shared source may describe more than one asset. Readers check asset.token in each document before applying it. A name the feed states for itself is not that check.