---
title: "4. Events, Metadata, and Royalties"
url: "https://radix-wiki.miow.me/developers/scrypto/04-events-metadata-royalties"
updated: 2026-10-03
description: "Components can emit events during transaction execution. Events are encoded in SBOR and stored in the transaction receipt – useful for indexing, analytics, and…"
---

# 4. Events, Metadata, and Royalties

## Events

[Components](/contents/tech/core-concepts/components) can emit [events](https://docs.radixdlt.com/docs/scrypto-events/) during transaction execution. Events are encoded in [SBOR](https://docs.radixdlt.com/docs/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](https://docs.radixdlt.com/docs/scrypto-events/) 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](/developers/infrastructure/02-radix-apis) responses and can be decoded using the [Radix Engine Toolkit](/contents/tech/core-protocols/transaction-manifests) or the `radix-event-stream` library for real-time indexing.

## Entity Metadata

[Metadata](/contents/tech/core-concepts/metadata-module) is a key-value store available on all entities – [resources](/contents/tech/core-concepts/resources), components, packages, and accounts. The [Radix Wallet](/contents/tech/core-protocols/radix-wallet) and other clients use [standardized keys](/contents/tech/core-concepts/metadata-module) 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

| Key | Used By | Purpose |
| --- | --- | --- |
| `name` | Wallet, Dashboard | Human-readable name |
| `symbol` | Wallet | Short ticker (e.g., [XRD](/contents/tech/core-protocols/xrd-token)) |
| `description` | Dashboard | Brief description |
| `icon_url` | Wallet | Token icon image |
| `info_url` | Dashboard | Project website |

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](/contents/tech/core-concepts/component-royalties) that lets developers earn XRD whenever their [blueprints](https://docs.radixdlt.com/docs/blueprints-and-components) 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.

Pricing strategy

You can specify royalties as a fixed XRD amount or an approximate USD equivalent. Use USD-equivalent pricing for stable fee expectations regardless of XRD price fluctuations.

## Next Steps

- [Testing Scrypto Blueprints](/developers/scrypto/05-testing-scrypto) – move from poking at resim by hand to tests that run in CI

## External Links

- [Events documentation](https://docs.radixdlt.com/docs/scrypto-events/)
- [Metadata documentation](https://docs.radixdlt.com/docs/metadata)
- [Metadata Standards](/contents/tech/core-concepts/metadata-module)
- [Royalties documentation](/contents/tech/core-concepts/component-royalties)