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,
}
 
#[blueprint]
#[events(SwapEvent)]
mod my_dex {
    // ...
}
 
// Inside a method:
Runtime::emit_event(SwapEvent {
    input_amount: dec!("100"),
    output_amount: dec!("95.5"),
    pool_address: Runtime::global_address(),
});

The #[events(SwapEvent)] line is the one that is easy to leave out, and leaving it out does not stop the build. The blueprint macro publishes each registered event's schema with the package, and the engine checks every emitted event against it. Without the registration, the method that emits fails when it runs: compiled and called under Scrypto 1.4.0 on 27 September 2026, it returned SystemError(TypeCheckError(BlueprintPayloadDoesNotExist(..., Event("SwapEvent")))). With the line in place, the same call commits and the receipt carries the event. Several events go in one list: #[events(SwapEvent, DepositEvent)].

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
    }
 
    // ...
}

The macro has to name every function and method in the blueprint, Free where there is no charge. Leaving one out is a compile error, E0063, missing field.

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.

Next Steps

• Testing Scrypto Blueprints – move from poking at resim by hand to tests that run in CI

External Links

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