Skip to content
Onchain Rights

Publish an announcement

Publish a dividend notice through a token that already supports Onchain Announcements. This example publishes information only. It does not deploy a token or execute a dividend payment.

The reading guide follows the same notice from the application's side.

Before you start

You need:

  • A token contract that implements the announcement interface, with its chain, address, and ABI.
  • An account authorized by that implementation to publish announcements.
  • A host for the JSON document and a URI readers can retrieve.
  • The corporate action schema used by the integration and a compatible validator.

Use a local environment or testnet for a first integration. The identifiers below are illustrative, not deployment targets. Replace the token and security identifiers with values from your test environment.

1. Prepare the document

This example describes a mandatory cash dividend of USD 0.50 for each underlying share. The token issuer reinvests the net proceeds. The notice does not state an individual holder's payout.

{
  "schemaVersion": "1",
  "category": "corporateAction",
  "eventId": "example:2027:dividend-q1",
  "eventRevision": 1,
  "announcementId": "example:2027:dividend-q1",
  "notificationType": "NEWM",
  "processingStatus": { "complete": true, "confirmed": true },
  "publishedAt": "2027-04-01T09:00:00Z",
  "asset": {
    "token": "eip155:1/erc20:0x0000000000000000000000000000000000000001",
    "underlying": [{ "type": "ISIN", "value": "US0000000001" }]
  },
  "event": {
    "eventType": "DVCA",
    "mandatoryVoluntary": "MAND",
    "summary": "Cash dividend of USD 0.50 for each underlying share. The token issuer reinvests the net proceeds."
  },
  "dates": [
    { "type": "RecordDate", "value": "2027-04-15T20:00:00Z" },
    { "type": "PayDate", "value": "2027-04-30T16:00:00Z" }
  ],
  "options": [{
    "number": 1,
    "type": "CASH",
    "isDefault": true,
    "currency": "USD",
    "movements": [{
      "number": 1,
      "direction": "credit",
      "assetType": "cash",
      "currency": "USD",
      "amounts": [{
        "type": "GrossDividendRateAmount",
        "value": "0.50",
        "currency": "USD"
      }]
    }]
  }]
}

The cash option describes the underlying corporate action. The summary explains the token issuer's reinvestment model. Other issuers can distribute dividends differently.

Here, processingStatus.complete means that all terms are known, and processingStatus.confirmed means that the issuer confirmed the event. Neither means that the dividend has been paid or the reinvestment executed.

2. Validate and host it

Validate the document against the schema, including date-time format checks. Also check the rules that depend on context: the correct asset, an unused announcement ID, and no holder-specific data.

Host the document at a stable URI. For this walkthrough, use the illustrative location:

https://example.com/corporate-actions/dividend-q1.json

Retrieve the document from the reader's environment before announcing it. Confirm that the retrieved contents match what you intend to publish. The JSON Schema page describes validation expectations; the schema will be published there soon.

3. Submit the announcement

Use the token's ABI and your authorized account to call announce with these arguments, in order:

ArgumentValue
internalCallsAn empty list: no token operation accompanies this notice.
idexample:2027:dividend-q1
descriptionThe document's event.summary.
uriThe location where you actually hosted the document.

This is a call description, not an executable transaction script. Check the target chain, contract, and arguments before submitting through your integration tooling.

4. Verify the result

After a successful transaction, inspect its receipt:

  • The expected token emits Announcement with the submitted ID, summary, and URI.
  • caller identifies the account that authorized it.
  • EndAnnouncement closes the bracket with the same ID.
  • No token operation is requested by this example's empty call list.

Use your chain's confirmation policy before treating the record as stable. If submission times out, check the transaction result before retrying. A successful announce consumes its ID; a second announce with that ID must fail.

Finally, follow Read an announcement from a separate reader to check discovery and interpretation.

Later changes

Keep the same event ID, announcement ID, and URI. Publish a higher document revision and use the implementation's updateAnnouncement path. A correction uses REPL with the full replacement terms; a cancellation or withdrawal follows the lifecycle rules.

Reporting an outcome uses the same update path. Set an effect's executed to true only when the announcement or an update brackets that state change. For meetings, publish results in a REPL document after the meeting. There is no separate finish operation.

This example covers initial publication only. Before adding update transactions, confirm the implementation's update call and the signal your reader uses to detect it. Do not reuse the initial announce call to simulate an update.