Read an announcement
Discover the dividend notice from Publish an announcement, check its source and contents, and display its terms. Reading does not require a wallet signature or a transaction.
Before you start
You need the token's chain and address, its announcement ABI, access to blockchain logs, and the schema used by the integration. You can query a node directly or use an indexer.
Start with a token your application already tracks. The announcement interface is not a global token directory.
1. Find the announcement
Query historical Announcement records from the token, starting at its deployment block or your last saved checkpoint. For this example, select the record whose ID is example:2027:dividend-q1.
Inspect the transaction receipt. Pair the opening record with EndAnnouncement from the same announcing contract and with the same ID. Retain the chain, contract, transaction hash, block hash, and log positions with the record.
The publishing example uses the token directly. If you support announcement references, check the token's designation before accepting another contract's records. Do not accept a source merely because its JSON names the token.
2. Retrieve the document safely
Read the URI from the announcement and retrieve its JSON document. The example.com address in the publishing guide is illustrative; use the URI from your actual test announcement.
As an integration practice, bound response size, timeout, and redirect count. Server-side readers should prevent requests to private or internal network destinations. Treat URI content as untrusted even when the source is recognized.
If retrieval fails, show the document as unavailable. Do not fabricate terms from the short description or silently treat an older cached version as current.
3. Check the document
Before using its terms:
- Parse the JSON and validate it against the expected schema, including date-time formats.
- Check
categoryandschemaVersion. - Check that
asset.tokenidentifies the token your application is processing. - If
announcementIdis present, require it to equal the onchain ID. - Look up stored state by asset and
eventId. Reject an older revision; treat an identical revision as a duplicate. Reject changed content at the same revision; the specification also recommends warning the user. - Apply
notificationTypebefore displaying the terms. A withdrawn event is not an active offer.
Schema validation alone cannot check the authorized source, identify an older stored version, or prove execution.
4. Interpret this dividend
The example should produce this interpretation:
| Document value | Interpretation |
|---|---|
eventType: DVCA | Cash dividend. |
mandatoryVoluntary: MAND | No holder election is required for this action. |
GrossDividendRateAmount: "0.50", currency: USD | Gross dividend for each underlying share, not a holder-specific payout. |
RecordDate | The record date supplied by the publisher. |
PayDate | The payment date supplied by the publisher, not proof of payment. |
event.summary | The token issuer reinvests the net proceeds. |
An example display is:
Cash dividend: USD 0.50 for each underlying share. The token issuer reinvests the net proceeds. Record date: April 15, 2027, at 20:00 UTC. Payment date: April 30, 2027, at 16:00 UTC. No holder election is required by this notice.
Render the summary as plain text. Use decimal arithmetic for financial values. Do not multiply the dividend rate by a wallet balance to infer entitlement without the issuer's entitlement rules.
If a notice includes a meeting voting link, show the destination host before opening it. The voting service determines eligibility and accepts votes.
The example announcement has no requested token operations and no declared executed effects. Do not label the dividend paid or the reinvestment complete from this notice alone. For notices with declared effects, compare them with the bracketed state-change records.
5. Keep the application synchronized
Save the checked document and its source information. Continue reading new chain records. On an update to an announcement, fetch the same URI again and process the higher document revision.
Use the update signal provided by the token implementation or indexer. This example does not define a new update event or an indexing API.
Apply replacements as complete documents, not patches. A reminder preserves terms. A cancellation stops use of the named revision's terms until a later NEWM or REPL arrives; it does not restore an older revision. A withdrawal ends the event and permits no later versions with that event ID. See the revision rules.
If the current document becomes unavailable, show that status rather than presenting an older copy as current terms. Retain the copies you acted on for historical reference.
For a production reader, keep reorganization-aware checkpoints and replay affected records. Decide how your application displays unconfirmed records and source conflicts before using notices for automated decisions. These are integration practices, not additional schema fields.