Abstract
This standard defines a convention for onchain announcements: a way to couple a human-readable disclosure with the state changes it describes, in a form that indexers can correlate reliably.
An announcement is a bracket. An Announcement event opens it, zero or more state-changing calls execute atomically inside it, and an EndAnnouncement event closes it. Both events carry a caller-chosen id that identifies the announcement for the lifetime of the contract, so every effect emitted inside the bracket can be attributed to its disclosure.
A single entrypoint, announce, emits the open event, dispatches the described calls against the same contract in order, and emits the close event. The disclosure and its effects therefore always share one transaction and cannot be separated. A second entrypoint, updateAnnouncement, revises an existing announcement: it signals that the announcement's contents changed and can bracket further state changes under the same id. Assets can optionally designate other addresses, including on other chains, whose announcements are treated as their own.
Motivation
Contracts routinely perform operator-driven state changes, such as a token rescaling, a batched issuance, or a parameter update. These changes materially affect holders or users. Today they surface only as low-level effect logs (Transfer and custom events) with no attached rationale, no summary, and no link to an offchain disclosure. A consumer must reconstruct intent from raw effects and has no reliable way to tell a deliberately disclosed change from an undisclosed direct call.
An announcement makes intent first-class:
- It emits a summary and a URI alongside the effects, atomically.
- It delimits exactly which effects belong to the announced action.
- Its bracket gives indexers a signal to distinguish a disclosed change from an undisclosed one, so the latter can be flagged (for example, as an emergency override).
Many real-world actions also change over time. A corporate action, for example, is often announced before all of its terms are known, is later corrected or confirmed, and is finally executed onchain days or weeks after the first notice. Consumers need a stable handle for the action across that lifecycle and a signal each time its contents change, without reconciling many unrelated announcements offchain.
The convention is deliberately orthogonal to what the state changes are and to how a contract authorizes them. It reuses a contract's existing mutating functions unchanged and attaches disclosure around them.
Specification
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
Interface
interface IAnnouncements {
/// @notice Opens the bracket of a new announcement.
///
/// @param caller The account that authorized the announcement.
/// @param id Caller-chosen id; identifies the announcement for the lifetime of the contract.
/// @param description Human-readable summary of the announcement.
/// @param uri Offchain location of the full announcement contents; may be empty.
event Announcement(address indexed caller, string id, string description, string uri);
/// @notice Opens the bracket of an update to an existing announcement.
///
/// @param caller The account that authorized the update.
/// @param id The id of the announcement being updated.
event AnnouncementUpdated(address indexed caller, string id);
/// @notice Closes the bracket opened by the `Announcement` or `AnnouncementUpdated` with the same id.
///
/// @param id The id of the bracket being closed.
event EndAnnouncement(string id);
/// @notice Posts a new announcement and atomically dispatches each entry in `internalCalls`
/// against this contract, in order.
///
/// @param internalCalls ABI-encoded calldata executed in order against this contract; may be empty.
/// @param id Caller-chosen id; MUST NOT have been used by a prior announcement.
/// @param description Human-readable summary of the announcement.
/// @param uri Offchain location of the full announcement contents; may be empty.
function announce(
bytes[] calldata internalCalls,
string calldata id,
string calldata description,
string calldata uri
) external;
/// @notice Updates an existing announcement and atomically dispatches each entry in
/// `internalCalls` against this contract, in order.
///
/// @param internalCalls ABI-encoded calldata executed in order against this contract; may be empty.
/// @param id The id of an existing announcement.
function updateAnnouncement(bytes[] calldata internalCalls, string calldata id) external;
}General
- A compliant contract MUST open a bracket by emitting either
Announcement(caller, id, description, uri)(for a new announcement) orAnnouncementUpdated(caller, id)(for an update), and MUST close it by emittingEndAnnouncement(id)with the sameid. callerMUST be the account that authorized the announcement or update.- Every state-changing call executed between the opening event and
EndAnnouncementbelongs to that announcement. - Brackets MUST NOT nest. While a bracket is open, no call inside it may open another bracket.
announce
A call to announce(internalCalls, id, description, uri) MUST, in this order:
- Emit
Announcement(caller, id, description, uri)before executing any entry ininternalCalls. - Execute each entry of
internalCallsin array order, against the same contract, as a state-changing call. - Emit
EndAnnouncement(id)after the final entry has executed.
announce MUST revert if id was consumed by a prior successful announce.
updateAnnouncement
A call to updateAnnouncement(internalCalls, id) MUST, in this order:
- Emit
AnnouncementUpdated(caller, id)before executing any entry ininternalCalls. - Execute each entry of
internalCallsin array order, against the same contract, as a state-changing call. - Emit
EndAnnouncement(id)after the final entry has executed.
updateAnnouncement MUST revert if id was not consumed by a prior successful announce on the same contract. updateAnnouncement does not consume a new id and MAY be called any number of times for the same id, subject to the implementation's own rules (see Lifecycle).
Dispatch requirements
The following apply to both announce and updateAnnouncement:
- Atomicity. The entire call MUST be atomic. If any entry in
internalCallsfails, the call MUST revert; no entry may be partially applied andEndAnnouncementMUST NOT be emitted. The specific error surfaced, and whether a failed entry's revert reason is propagated or replaced, is left to the implementation. - Pure disclosure.
internalCallsMAY be empty. In that case no calls execute and the opening event andEndAnnouncementare emitted with nothing between them. - No nesting. No entry in
internalCallsmay re-invokeannounceorupdateAnnouncement. An implementation MUST reject such an attempt by reverting the whole call. - Self-targeted. Each entry in
internalCallsMUST target the announcing contract, not a generic(target, calldata)pair. External effects are still reachable: the contract's own methods MAY call out, and those calls run inside the bracket. See Rationale.
Id uniqueness
- Each
idMUST be consumed at most once byannouncefor the lifetime of the contract. - An
idis consumed only by anannouncecall that succeeds. - After an
idis consumed, it can only be referenced again throughupdateAnnouncement.
Announcement contents (uri)
uri MAY be empty (a disclosure with no offchain document). When non-empty, it MUST resolve to a document conforming to the Announcement Content Schema below: a strict, machine-readable structure. Free-form or arbitrary documents are non-conforming; a consumer MUST be able to parse any announced uri against one schema. Conformance is REQUIRED whenever uri is non-empty.
The document MUST be a JSON object encoded in UTF-8 with at least the following structure:
type AnnouncementContents = {
category: string
}categoryMUST be a non-empty string identifying the kind of announcement (for example,corporateAction).- Each category defines the remaining fields of its documents. Other proposals MAY define category schemas that build on this one.
- A consumer that does not recognize a document's
categoryMUST NOT interpret its other fields, and MAY still display the announcement's onchaindescription.
Lifecycle
An announcement has one identity, its id, and one uri for its whole life. Its contents can change over that life.
- Publication.
announcepublishes the announcement, fixing itsid,description, anduri. Contents MAY be preliminary at this point (for example, terms not yet known or not yet confirmed). - Revision. When the contents at
urichange, the publisher MUST callupdateAnnouncementfor the sameidin or after the transaction that makes the change visible. A publisher MUST NOT change the contents aturiwithout a followingupdateAnnouncement. On eachAnnouncementUpdated, a consumer MUST treat its cached contents for thatidas stale and SHOULD fetchuriagain. - Execution. State changes that carry out the announced action MAY be bracketed by the original
announceor by any laterupdateAnnouncementfor the sameid. All of them are attributed to the same announcement. - Conclusion. This standard defines no onchain terminal state. Whether an announcement is final, cancelled, or withdrawn is part of its contents and is defined by its category. An implementation MAY refuse further updates to an
idit considers final by revertingupdateAnnouncement.
Category schemas that describe actions with a lifecycle SHOULD include in each document:
- a monotonically increasing revision number, so that a consumer can order documents and reject an older document served after a newer one;
- whether the contents are complete and whether they are confirmed by the responsible party; and
- whether the announced action is still in effect, has been cancelled, or has been withdrawn.
The description emitted in Announcement is not changed by updates. Consumers SHOULD prefer summary text from the latest contents, when the category provides it, over the original description.
Announcement references
An asset is the home for discovering announcements about it, but it may not be the only contract that emits them. An asset MAY designate other contracts as announcement references. Announcements emitted by a valid announcement reference SHOULD be treated as if the asset emitted them.
This supports two use cases:
- a service provider that announces on behalf of many asset issuers from one contract; and
- an asset deployed on several chains that keeps a single announcement feed on one home chain.
An asset that supports announcement references MUST implement the following interface:
interface IAnnouncementReferences {
/// @notice Emitted when `delegate` becomes a valid announcement reference.
///
/// @param delegate ERC-7930 Interoperable Address of the reference contract.
/// @param extraData Implementation-defined data about the reference; may be empty.
event AnnouncementReferenceAdded(bytes delegate, bytes extraData);
/// @notice Emitted when `delegate` stops being a valid announcement reference.
///
/// @param delegate ERC-7930 Interoperable Address of the reference contract.
event AnnouncementReferenceRemoved(bytes delegate);
/// @notice Returns whether `reference` is currently a valid announcement reference.
///
/// @param delegate ERC-7930 Interoperable Address of the reference contract.
function isValidAnnouncementReference(bytes calldata delegate) external view returns (bool);
}delegateMUST be encoded as an ERC-7930 Interoperable Address, so that a reference MAY live on a different chain than the asset.- A reference contract MUST implement
IAnnouncements. isValidAnnouncementReferenceMUST returntruefor a reference after itsAnnouncementReferenceAddedand before any laterAnnouncementReferenceRemoved, andfalseotherwise.- A consumer SHOULD treat an announcement from a reference as the asset's only if the reference was valid for the asset at the time of the announcement, as reconstructed from
AnnouncementReferenceAddedandAnnouncementReferenceRemoved. For a reference on another chain, "at the time" is judged by timestamp. - When a reference announces for more than one asset, the contents at
uriMUST identify the asset or assets the announcement applies to. A consumer MUST NOT attribute an announcement from a shared reference to an asset that its contents do not identify. - An update (
AnnouncementUpdated) is attributed to the announcement with the sameidon the same contract that emitted it.
Interface detection
A compliant contract MUST implement ERC-165. supportsInterface(0x4c34fb2a) MUST return true, where 0x4c34fb2a is the interface id of IAnnouncements.
An asset that implements IAnnouncementReferences MUST return true from supportsInterface(0x44a2c3d2), where 0x44a2c3d2 is the interface id of IAnnouncementReferences.
Caller preservation
internalCalls entries are dispatched against the same contract. When those inner mutations enforce their own authorization, the dispatch mechanism SHOULD preserve the original caller, so that authorization observes the announcer rather than the contract's own address. Executing each entry via a self-delegatecall (which preserves msg.sender) is the RECOMMENDED mechanism; an equivalent that preserves the caller is permitted.
This standard does not otherwise prescribe an authorization model. Whether announce, updateAnnouncement, the inner mutations, or all of them are access-controlled is left to the implementation. See Security Considerations.
Rationale
Why a bracket instead of one event carrying an effect list. Effects are heterogeneous and are emitted by each inner call's own logic. A bracket lets a contract reuse its existing mutating functions unchanged and still attribute their logs to the announcement, rather than duplicating every effect into a bespoke schema.
Why the id appears in every event. Carrying id in the opening and closing events lets a consumer pair them and attribute intervening effects without relying on log adjacency, and lets independent tooling reconstruct a bracket from either boundary.
Why a single entrypoint dispatches the calls. Routing the disclosure and the effects through one function guarantees they share a transaction and cannot be separated: a disclosure never lands without its effects, and the effects never land without their disclosure.
Why internal calls rather than generic actions. Self-targeting, not a generic (target, calldata), for three reasons:
- Caller preservation. A self-
delegatecallcarries the announcer's identity, so the contract's own authorization sees the operator. A direct external call cannot: the far contract sees the announcing contract, not the operator. - Finite surface. Announceable effects are exactly the contract's own ABI, which a reviewer can enumerate, not "any function on any contract".
- No foreign code. A self-
delegatecallruns the contract's own code against its own storage; delegatecalling external code would not.
Generality is not lost. The contract's own methods may call out as part of their logic, and those calls run inside the bracket.
Why one announcement per action, revised in place. An alternative is to post a new announcement, with a new id, each time an action's contents change, and to link the versions through a shared identifier inside the contents. That forces every consumer to fetch and index offchain contents just to learn that several announcements describe the same action. Keeping one id for the action's whole life lets a consumer follow it from onchain data alone, and lets a later update bracket the state changes that execute the action under the same handle as the first notice.
Why a separate update function instead of re-announcing an id. Allowing announce to reuse an id would let an operational mistake, such as a retried job or a duplicated identifier, silently overwrite an unrelated announcement. Requiring an explicit updateAnnouncement, which only accepts an existing id, makes revision a deliberate act and keeps announce strictly for new announcements.
Why a distinct AnnouncementUpdated event. Reusing Announcement for updates would make the first publication indistinguishable from a revision without contract state. A distinct event lets an indexer tell them apart from logs alone, and it is lighter because it does not repeat description and uri, which do not change.
Why lifecycle states live in the contents. The states an announcement passes through (preliminary, confirmed, cancelled, withdrawn, and so on) differ by domain and already have established vocabularies in some domains. Defining them onchain would either be too narrow for some categories or too vague to be useful. This standard therefore provides the onchain signal that contents changed, and leaves their meaning to category schemas. Implementations that need onchain finality can refuse updates to a final id.
Why authorization-agnostic. The pattern is orthogonal to any particular access-control model. Its only interaction with authorization is caller preservation, which is a recommendation so that contracts that gate inner mutations can keep those checks meaningful.
Why no id-status getter. Whether an id has been consumed can be fully reconstructed from Announcement logs. Requiring a getter would add cost without serving any consumer that the logs do not already serve.
Why description and uri are separate. description is a cheap onchain summary suitable for direct display; uri points to the full, possibly large, contents held offchain. Splitting them keeps the onchain footprint small while preserving a link to the complete record.
Why a strict content schema with a category. A consumer that encounters an arbitrary uri must know how to parse it. A required category field gives every document a common entry point, and lets each domain define its own fields without this standard enumerating them.
Why empty internalCalls is first-class. Some disclosures carry no onchain effect (a notice, a statement of record, a correction). Allowing an empty batch makes a pure disclosure or a pure revision a normal announcement rather than a special case.
Why announcement references use Interoperable Addresses. A reference may live on another chain, for example a home-chain feed for a multichain asset. ERC-7930 gives a compact binary encoding of an address together with its chain, so one interface covers both same-chain service providers and cross-chain feeds.
Related work. ERC-1129 proposed a board of free-text announcements for a DApp. This standard instead couples a structured disclosure with the state changes it describes and gives each announcement a stable identity across revisions.
Backwards Compatibility
This standard is purely additive: three new events and two new functions, plus an optional interface for announcement references. It introduces no changes to existing behavior and conflicts with no prior standard. Existing effect events (such as Transfer) are unchanged and simply fall inside a bracket when emitted by an inner call.
Reference Implementation
A minimal, authorization-agnostic sketch. Access control on announce and updateAnnouncement is omitted for brevity and is discussed under Security Considerations.
// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.20;
abstract contract OnchainAnnouncements {
event Announcement(address indexed caller, string id, string description, string uri);
event AnnouncementUpdated(address indexed caller, string id);
event EndAnnouncement(string id);
error AnnouncementIdAlreadyUsed(string id);
error AnnouncementNotFound(string id);
error AnnouncementInProgress();
error InternalCallMalformed(bytes call);
error InternalCallFailed(bytes call);
mapping(bytes32 => bool) private _usedId;
bool private _inProgress;
function announce(
bytes[] calldata internalCalls,
string calldata id,
string calldata description,
string calldata uri
) external virtual {
// Implementations SHOULD gate this call; see Security Considerations.
if (_inProgress) revert AnnouncementInProgress();
bytes32 key = keccak256(bytes(id));
if (_usedId[key]) revert AnnouncementIdAlreadyUsed(id);
_usedId[key] = true;
_inProgress = true;
emit Announcement(msg.sender, id, description, uri);
_dispatch(internalCalls);
emit EndAnnouncement(id);
_inProgress = false;
}
function updateAnnouncement(bytes[] calldata internalCalls, string calldata id) external virtual {
// Implementations SHOULD gate this call; see Security Considerations.
if (_inProgress) revert AnnouncementInProgress();
if (!_usedId[keccak256(bytes(id))]) revert AnnouncementNotFound(id);
_inProgress = true;
emit AnnouncementUpdated(msg.sender, id);
_dispatch(internalCalls);
emit EndAnnouncement(id);
_inProgress = false;
}
function supportsInterface(bytes4 interfaceId) public view virtual returns (bool) {
return interfaceId == 0x4c34fb2a // IAnnouncements
|| interfaceId == 0x01ffc9a7; // ERC-165
}
function _dispatch(bytes[] calldata internalCalls) private {
for (uint256 i; i < internalCalls.length; ++i) {
bytes calldata c = internalCalls[i];
if (c.length < 4) revert InternalCallMalformed(c);
// Self-delegatecall preserves msg.sender.
(bool ok,) = address(this).delegatecall(c);
if (!ok) revert InternalCallFailed(c);
}
}
}Security Considerations
An announcement is a claim, not a proof. description and the contents at uri are supplied by the caller and are not verified onchain. A consumer must not trust them beyond the effects actually executed inside the bracket.
Undisclosed effects. A consumer should treat state changes that occur outside any bracket as undisclosed direct calls and may flag them (for example, as emergency overrides). This signal is only as strong as the contract's discipline in routing disclosed changes through announce and updateAnnouncement.
Arbitrary self-dispatch. internalCalls is arbitrary calldata executed against the contract itself, typically with the caller preserved. Any account able to call announce or updateAnnouncement can therefore invoke any inner mutation the contract exposes, as the announcer. Access control on both functions is consequently critical: implementations should gate them and must ensure that self-dispatch cannot reach functions or storage the caller is not entitled to reach. Implementations must guard against re-entering either function (nesting).
Mutable contents. The contents at uri are expected to change over an announcement's life, and nothing onchain binds a given AnnouncementUpdated to particular contents. A publisher could change contents without emitting an update, serve different contents to different consumers, or let uri stop resolving. Consumers should keep a copy of each version of the contents they act on, and category schemas should carry a revision number so that consumers can detect contents that changed without a revision or that went backwards. Content-addressed URIs cannot be used for announcements that are revised, because uri does not change.
Revisions after users act. An update can change the terms of an announcement after a user acted on an earlier version. Consumers should surface material changes to users and should not silently replace terms that a user relied on. Implementations that need finality can refuse updates to final announcements.
Missed updates. A consumer that misses an AnnouncementUpdated event may act on stale contents, including contents later marked cancelled or withdrawn. Consumers should process all announcement events of the asset and its references, not only the most recent ones.
Announcement references. A valid reference can make announcements that consumers attribute to the asset, so compromising a reference is equivalent to compromising the asset's announcement authority. Assets should restrict who can add references and should remove a compromised reference promptly. For references on other chains, consumers depend on reading that chain correctly and on the asset's add and remove events, and should account for differences in finality between chains. A shared reference that serves many assets could name the wrong asset in its contents; consumers must check the asset identification required by this standard.
Id griefing. If id selection is unauthorized, an attacker can consume ids to interfere with an issuer's naming scheme, or update announcements they did not make. Gating announce and updateAnnouncement mitigates this.
Unbounded batches. A large internalCalls array can exceed the block gas limit. Implementations and callers should bound batch size.
Copyright
Copyright and related rights waived via CC0.
