4. Events, Metadata, and Royalties

Events

Components can emit events during transaction execution. Events are encoded in SBOR and stored in the transaction receipt — useful for indexing, analytics, and off-chain reactions.

#[derive(ScryptoSbor, ScryptoEvent)]
pub struct SwapEvent {
    pub input_amount: Decimal,
    pub output_amount: Decimal,
    pub pool_address: ComponentAddress,
}
 
// Inside a method:
Runtime::emit_event(SwapEvent {
    input_amount: dec!("100"),
    output_amount: dec!("95.5"),
    pool_address: self_address,
});

Events appear in Gateway API responses and can be decoded using the Radix Engine Toolkit or the radix-event-stream library for real-time indexing.

Entity Metadata

Metadata is a key-value store available on all entities — resources, components, packages, and accounts. The Radix Wallet and other clients use standardized keys to display assets consistently.

Setting Metadata at Creation

ResourceBuilder::new_fungible(OwnerRole::None)
    .metadata(metadata!(
        init {
            "name" => "My Token", locked;     // Cannot be changed
            "symbol" => "MYT", locked;
            "description" => "A token", updatable;  // Can be updated
            "icon_url" => Url::of("https://example.com/icon.png"), locked;
        }
    ))
    .mint_initial_supply(1000);

Standard Metadata Keys

Keys are strings (max 100 chars). You can add custom keys beyond the standard set — clients will display them as-is.

Royalties

Radix has a built-in royalty system that lets developers earn XRD whenever their blueprints or components are used. Royalties are collected automatically as part of transaction fees — users see the total cost upfront.

Package Royalties

Set royalties on specific functions or methods when publishing a package:

#[blueprint]
#[types(/* ... */)]
mod my_dex {
    enable_package_royalties! {
        instantiate => Free;
        swap => Xrd(1.into());  // 1 XRD per swap call
    }
 
    // ...
}

Component Royalties

Component instantiators can also set per-method royalties at instantiation time. The total royalty for a transaction is the sum of all package and component royalties for every method called.

External Links

• Events documentation
• Metadata documentation
• Metadata Standards
• Royalties documentation