Contract Events

Every state change worth watching in Superhero emits an event. This is the cross-contract catalogue: event names, argument types, the Blake2b topic hash the middleware indexes them by, and how to read them from a call, from the middleware, or from a live subscription.

How an æternity event is encoded

A Sophia Chain.event produces a log entry with a topics array and a data field:

Mint(address, int) produces three topics (the name hash, the account, and the value) and empty data. An indexer filters logs on topics[0] and reads the amount from topics[2].

PostWithoutTipReceived(address, string) produces two topics (the name hash and the author) and puts the title in data.

The name hash is derivable offline:

import { blake2b } from 'blakejs';   // or any Blake2b-256 implementation
 
function eventTopic(name) {
  const digest = blake2b(new TextEncoder().encode(name), undefined, 32);
  return BigInt('0x' + Buffer.from(digest).toString('hex')).toString();
}
 
eventTopic('Mint');
// '97248968993606906149864095761415446114204891017168990930824289305879066770211'

import hashlib
def event_topic(name):
    return int.from_bytes(hashlib.blake2b(name.encode(), digest_size=32).digest(), 'big')

The catalogue

Tipping v3

datatype event = PostWithoutTipReceived(address, string)
                                     // author,  title

FungibleTokenFull (AEX-9)

Emitted by every community token and by the ProtocolDAO token.

datatype event =
    Transfer(address, address, int)    // from, to, value
  | Allowance(address, address, int)   // owner, spender, value
  | Burn(address, int)                 // account, value
  | Mint(address, int)                 // account, value
  | Swap(address, int)                 // account, value

CommunityFactory

datatype event =
    CreateCommunity(string, DAO, TokenSale, CommunityManagement)
                 // name,  dao, sale,      community management
  | CreateCollection(string, address)
                 // collection id, creator

CreateCommunity is the most useful event in the system for an indexer: one log entry gives you a new community's name and all three of its contract addresses.

AffiliationBondingCurveTokenSale

datatype event =
    Buy(int, int, int)        // total_price, affiliation_amount, total_supply
  | Sell(int, int)            // return, total_supply
  | PriceChange(int, int)     // previous_price, next_price

The traded token count is not in any of these. Get it from the transaction's call arguments or from the paired Mint / Burn event on the token contract. The total_supply in Buy and Sell is the supply before the trade.

DAO

datatype event =
    VoteAdded(DAOVote, int)            // vote contract, seq id
  | AppliedVoteSubject(DAOVote, int)   // vote contract, seq id

DAOVote

datatype event =
    Vote(address, vote_option, amount)         // voter, true/false, token amount
  | RevokeVote(address, vote_option, amount)
  | Withdraw(address, amount)

CommunityManagement

datatype event =
    ChangeMinimumTokenThreshold(int)
  | AddModerator(address)
  | DeleteModerator(address)
  | MuteUserId(string)
  | UnmuteUserId(string)
  | SetOwner(address)
  | ChangedMetaInfo

MuteUserId and UnmuteUserId carry their string in data, not in a topic. ChangedMetaInfo has no arguments, so it has one topic and empty data. On seeing it, re-read meta_info() to find out what changed.

AffiliationTreasury

datatype event =
    UserInvited(address, address)                  // invitee, inviter
  | RewardAdded(address, int)                      // user, added amount
  | Withdrawn(address, int)                        // user, reward amount
  | InvitationRegistered(address, address, int)    // caller, invitation_address, amount
  | InvitationRedeemed(address, address, address)  // invitee_address, inviter_address, caller
  | InvitationRevoked(address, address)            // invitation_address, inviter_address
  | RecordSaleTransaction(address, int)            // buyer, amount

Two orderings are easy to transpose: InvitationRedeemed leads with the invitee, while InvitationRevoked leads with the invite address. The third address on InvitationRedeemed is the caller, which for a redemption is the invite address itself.

UserInvited fires only from register_invitation. An invite claimed through a code emits InvitationRedeemed instead, even though both write the same affiliation-tree entry. Watch both to capture every invite relationship.

RewardAdded fires once per credited level, so one buy under a four-deep referral chain emits four of them alongside a single RecordSaleTransaction.

Registry (governance)

datatype event =
    AddPoll(Poll, int)              // poll contract, poll id
  | Delegation(address, address)    // delegator, delegatee
  | RevokeDelegation(address)       // delegator

Poll (governance)

datatype event =
    Vote(address, address, int)
  | RevokeVote(address, address)

AddressLink

datatype event =
    ProviderRegistered(address, string)   // provider owner, provider id
  | Link(address, string)
  | Unlink(address, string)
  | PrincipalLink(address, string)
  | PrincipalUnlink(address, string)

Every one carries an address topic and a string in data. The Link / Unlink pair covers account links; the Principal pair covers links made against an AENS name.

The data string on a link event is provider:value, colon-joined. Split it on the first colon. Provider ids match /^[a-z]{1,10}$/, so a value may contain a colon but a provider id may not. prefaens is the provider id for a preferred AENS name.

Tipping v4

Not part of Superhero's social layer, which runs v3, but in the same contract family:

datatype event = PostViaBurnReceived(tip_id, address, string, TokenContract)

Name collisions: filter by contract, always

The topic hash is computed from the name alone. It carries no contract identity and no argument types. Three names collide across the suite:

A Vote log from a governance poll and a Vote log from a community DAO have the same topic hash and different argument shapes. An indexer that matches on topics[0] alone and then decodes positionally will mis-parse one of them.

Filter on the emitting contract address first, then decode. The same discipline applies within a single transaction: a token buy emits Mint twice, from two different token contracts.

Reading events from a call you made

The SDK decodes them for you against the ACI:

const result = await sale.buy(count, { amount, omitUnknown: true });
 
for (const e of result.decodedEvents) {
  console.log(e.name, e.contract.address, e.args);
}

decodedEvents covers events from every contract the call touched, so a buy gives you the sale's Buy and PriceChange plus both Mint events. Match on e.contract.address to tell the community token's mint from the ProtocolDAO token's:

const tokenMint = result.decodedEvents.find(
  (e) => e.name === 'Mint' && e.contract.address === tokenAddress,
);

Reading events from the middleware

For transactions you did not submit, query the middleware's contract log index:

GET {middlewareUrl}/v3/contracts/logs?contract_id={ct_...}&tx_hash={th_...}&limit=100

Drop tx_hash to get a contract's full log history, paged. Each entry carries topics as an array of big-integer strings and data as the string payload, so matching is a string compare against the hashes above:

const MINT_TOPIC = '97248968993606906149864095761415446114204891017168990930824289305879066770211';
 
const res = await fetch(
  `https://mainnet.aeternity.io/mdw/v3/contracts/logs?contract_id=${saleAddress}&limit=100`,
);
const { data } = await res.json();
 
const mints = data.filter((log) => log.topics?.[0] === MINT_TOPIC);
for (const log of mints) {
  console.log('account topic:', log.topics[1], 'value:', log.topics[2]);
}

A log entry also carries event_hash and, when the middleware can resolve the contract's ACI, a decoded event_name and an args array:

const eventHash = log.event_hash;
const eventName = log.event_name;       // may be absent
const addressTopic = log.args?.[0];     // decoded topic arguments
const payload = log.data;

event_hash is the same 32-byte Blake2b-256 digest as topics[0], encoded as padded base32hex (RFC 4648's extended-hex alphabet, not standard base32). Match on event_hash when you want a stable identifier, and on event_name only as a convenience, since it is present only when the middleware has the contract's ACI.

Two operational notes:

• Paginate. The response carries a next field with a relative path. Follow it until it is absent; do not assume one page is the whole history.
• Logs lag the transaction. A transaction hash is available the moment it is mined, but the middleware may not have indexed its logs yet, so a tx_hash-filtered query can return an empty list for a transaction that emitted events. Retry, or reconcile in a later catch-up pass.

Live subscriptions

The middleware exposes a WebSocket interface for subscribing to chain activity, so an indexer does not have to poll /v3/contracts/logs.

The subscribe message is a JSON object with up to four fields:

{ "op": "Subscribe", "payload": "Transactions", "source": "mdw" }

Unsubscribing sends the identical object with op flipped to Unsubscribe. Reconnect on a timeout: a dropped socket is silent, and the gap is otherwise invisible.

The Superhero API republishes decoded token activity on its own WebSocket, which is usually the easier integration if you only care about tokens. It emits two channels, token-updated and token-history. See WebSocket API.

Related

• Calling Contracts: decodedEvents in context, plus reverts and gas
• AffiliationBondingCurveTokenSale: where the four events of a buy come from
• Node and middleware API: the middleware endpoints in full
• WebSocket API: the Superhero API's own real-time channels
• æternity contract events specification (opens in a new tab): the topic and data encoding rules