Events

Events let your contract tell the outside world what happened, without the outside world having to poll and diff your state. Declare them at contract level, emit them from function bodies, and query them from any node.

Declaring and emitting

contract BNS {
    event NameRegistered(name: Str, owner: Str);
    event NameTransferred(name: Str, old_owner: Str, new_owner: Str);

    fn register(name: Str, owner: Str) {
        MAP_SET("names", name, owner);
        emit NameRegistered(name, owner);
        return 1;
    }

    fn transfer(name: Str, new_owner: Str) {
        let old_owner = MAP_GET("names", name);
        MAP_SET("names", name, new_owner);
        emit NameTransferred(name, old_owner, new_owner);
        return 1;
    }
}

Event parameters are typed and named. Emitting is fire-and-forget from the contract's perspective: it can't fail your function.

How events behave

• Events are collected during execution and recorded when the call is confirmed on Bitcoin. Each stored event carries the Bitcoin txid of the call that emitted it and the block height it confirmed at.
• Events emitted inside nested CALL / CALL_AS_CONTRACT invocations are collected too, so the full chain of a transaction's events surfaces together.
• Events appear in your contract's ABI (sclc compile --abi), typed like function inputs, so indexers and frontends can decode them without custom glue.

Querying events

Any node serves a contract's events over REST:

curl "http://localhost:8080/events/<contract_id>"

# Filter by event name and block range
curl "http://localhost:8080/events/<contract_id>?event_name=NameRegistered&from_block=850000&to_block=860000"

Each result includes the event name, decoded parameters, the emitting call's Bitcoin txid, and the confirmation block height: everything an indexer needs to build a provable activity feed.