NEP | Title | Author | Status | DiscussionsTo | Type | Category | Created |
---|---|---|---|---|---|---|---|
297 |
Events |
Olga Telezhnaya <[email protected]> |
Final |
Standards Track |
Contract |
03-Mar-2022 |
Events format is a standard interface for tracking contract activity. This document is a meta-part of other standards, such as NEP-141 or NEP-171.
Apps usually perform many similar actions. Each app may have its own way of performing these actions, introducing inconsistency in capturing these events.
NEAR and third-party applications need to track these and similar events consistently. If not, tracking state across many apps becomes infeasible. Events address this issue, providing other applications with the needed standardized data.
Initial discussion is here.
- Why is this design the best in the space of possible designs?
- What other designs have been considered and what is the rationale for not choosing them?
- What is the impact of not doing this?
Many apps use different interfaces that represent the same action. This interface standardizes that process by introducing event logs.
Events use the standard logs capability of NEAR.
Events are log entries that start with the EVENT_JSON:
prefix followed by a single valid JSON string.
JSON string may have any number of space characters in the beginning, the middle, or the end of the string.
It's guaranteed that space characters do not break its parsing.
All the examples below are pretty-formatted for better readability.
JSON string should have the following interface:
// Interface to capture data about an event
// Arguments
// * `standard`: name of standard, e.g. nep171
// * `version`: e.g. 1.0.0
// * `event`: type of the event, e.g. nft_mint
// * `data`: associate event data. Strictly typed for each set {standard, version, event} inside corresponding NEP
interface EventLogData {
standard: string;
version: string;
event: string;
data?: unknown;
}
Thus, to emit an event, you only need to log a string following the rules above. Here is a bare-bones example using Rust SDK near_sdk::log!
macro (security note: prefer using serde_json
or alternatives to serialize the JSON string to avoid potential injections and corrupted events):
use near_sdk::log;
// ...
log!(
r#"EVENT_JSON:{"standard": "nepXXX", "version": "1.0.0", "event": "YYY", "data": {"token_id": "{}"}}"#,
token_id
);
// ...
EVENT_JSON:{
"standard": "nepXXX",
"version": "1.0.0",
"event": "xyz_is_triggered"
}
EVENT_JSON:{
"standard": "nepXXX",
"version": "1.0.0",
"event": "xyz_is_triggered",
"data": {
"triggered_by": "foundation.near"
}
}
- Two events in a single log entry (instead, call
log
for each individual event)
EVENT_JSON:{
"standard": "nepXXX",
"version": "1.0.0",
"event": "abc_is_triggered"
}
EVENT_JSON:{
"standard": "nepXXX",
"version": "1.0.0",
"event": "xyz_is_triggered"
}
- Invalid JSON data
EVENT_JSON:invalid json
- Missing required fields
standard
,version
orevent
EVENT_JSON:{
"standard": "nepXXX",
"event": "xyz_is_triggered",
"data": {
"triggered_by": "foundation.near"
}
}
Fungible Token Events Implementation
Non-Fungible Token Events Implementation
There is a known limitation of 16kb strings when capturing logs. This impacts the amount of events that can be processed.
Copyright and related rights waived via CC0.