Skip to content

Commit

Permalink
Update getEvents retention window
Browse files Browse the repository at this point in the history
  • Loading branch information
janewang committed Sep 12, 2024
1 parent 9c1b42f commit f9ed481
Show file tree
Hide file tree
Showing 8 changed files with 485 additions and 27 deletions.
4 changes: 2 additions & 2 deletions docs/build/guides/dapps/frontend-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -721,7 +721,7 @@ This is made possible by using the `server.getEvents` method which allows you to

We will be editing the `CounterPage` component to read events from the counter smart contract immediately the page loads to get the initial counter value and update instead of using "Unknown". Before we continue, please take a look at the [contract code](https://github.com/stellar/soroban-examples/blob/main/events/src/lib.rs). In the contract code, an event named `increment` is emitted whenever the `increment` function is called. It is published over 2 topics, `increment` and `COUNTER` and we need to listen to these topics to get the events.

The topics are stored in a data type called `symbol` and we will need to convert both `increment` and `COUNTER` to `symbol` before we can use them in the [`server.getEvents`](https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents) method. By default, soroban RPCs keep track of events for 24 hours and you can query events that happened within the last 24 hours, so if you need to store events for longer, you may need to make use of an [indexer](/docs/tools/developer-tools/data-indexers).
The topics are stored in a data type called `symbol` and we will need to convert both `increment` and `COUNTER` to `symbol` before we can use them in the [`server.getEvents`](https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents) method. By default, soroban RPCs keep track of events for 7 days and you can query events that happened within the last 7 days, so if you need to store events for longer, you may need to make use of an [indexer](/docs/tools/developer-tools/data-indexers).

To use events,we edit our counter page and add the following code:

Expand Down Expand Up @@ -819,5 +819,5 @@ State Archival is a characteristic of soroban contracts where some data stored o

A few things to note about data retention in soroban contracts:

- Events Data can be queried within 24 hours of the event happening. So you may need an indexer to store events for longer periods.
- Events Data can be queried within 7 days of the event happening. So you may need an indexer to store events for longer periods.
- Transaction data is stored with a retention period of 1440 ledgers. This means after 1440 ledgers, the transaction data cannot be queried using the RPC. Again, you may need an indexer to store transaction data for longer periods.
8 changes: 4 additions & 4 deletions docs/build/guides/events/ingest.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: Ingest events published from a contract
description: Use Soroban RPC's getEvents method for querying events, with a 24-hour retention window
description: Use Soroban RPC's getEvents method for querying events, with a 7 days retention window
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

Soroban RPC provides a `getEvents` method which allows you to query events from a smart contract. However, the data retention window for these events is roughly 24 hours. If you need access to a longer-lived record of these events you'll want to "ingest" the events as they are published, maintaining your own record or database as events are ingested.
Soroban RPC provides a `getEvents` method which allows you to query events from a smart contract. However, the data retention window for these events is 7 days. If you need access to a longer-lived record of these events you'll want to "ingest" the events as they are published, maintaining your own record or database as events are ingested.

There are many strategies you can use to ingest and keep the events published by a smart contract. Among the simplest might be using a community-developed tool such as [Mercury](https://mercurydata.app) which will take all the infrastructure work off your plate for a low subscription fee.

Expand Down Expand Up @@ -139,13 +139,13 @@ We are making some assumptions here. We'll assume that your contract sees enough

<TabItem value="python" label="Python">

If we start from scratch, there is no known ledger so we can try to ingest roughly the last 24 hours assuming a ledger closes every 6s.
If we start from scratch, there is no known ledger so we can try to ingest roughly the last 7 days assuming a ledger closes every 6s.

```python
import stellar_sdk

soroban_server = stellar_sdk.SorobanServer()
ledger = soroban_server.get_latest_ledger().sequence-int(3600 / 6 * 24)
ledger = soroban_server.get_latest_ledger().sequence-int(3600 / 6 * 24 * 7)
```

Later on, we will be able to start from the latest ingested ledger by making a query to our DB.
Expand Down
4 changes: 0 additions & 4 deletions docs/data/rpc/admin-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -352,10 +352,6 @@ DEFAULT_EVENTS_LIMIT = 100
# Endpoint to listen and serve on
ENDPOINT = "0.0.0.0:8000"

# configures the event retention window expressed in number of ledgers, the
# default value is 17280 which corresponds to about 24 hours of history
EVENT_RETENTION_WINDOW = 17280

# The friendbot URL to be returned by getNetwork endpoint
# FRIENDBOT_URL = ""

Expand Down
2 changes: 1 addition & 1 deletion docs/learn/encyclopedia/contract-development/events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Events are the mechanism that applications off-chain can use to monitor changes

:::info

Events are ephemeral, the data retention window is roughly 24 hours. See the [ingestion guide](../../../build/guides/events/ingest.mdx) to learn how to work with this constraint.
Events are ephemeral, the data retention window is 7 days. See the [ingestion guide](../../../build/guides/events/ingest.mdx) to learn how to work with this constraint.

:::

Expand Down
2 changes: 1 addition & 1 deletion openrpc/src/stellar-rpc/methods/getEvents.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "getEvents",
"summary": "returns contract events",
"description": "Clients can request a filtered list of events emitted by a given ledger range.\n\nSoroban-RPC will support querying within a maximum 24 hours of recent ledgers.\n\nNote, this could be used by the client to only prompt a refresh when there is a new ledger with relevant events. It should also be used by backend Dapp components to \"ingest\" events into their own database for querying and serving.\n\nIf making multiple requests, clients should deduplicate any events received, based on the event's unique id field. This prevents double-processing in the case of duplicate events being received.\n\nBy default soroban-rpc retains the most recent 24 hours of events.",
"description": "Clients can request a filtered list of events emitted by a given ledger range.\n\nSoroban-RPC will support querying within a maximum 7 days of recent ledgers.\n\nNote, this could be used by the client to only prompt a refresh when there is a new ledger with relevant events. It should also be used by backend Dapp components to \"ingest\" events into their own database for querying and serving.\n\nIf making multiple requests, clients should deduplicate any events received, based on the event's unique id field. This prevents double-processing in the case of duplicate events being received.\n\nBy default soroban-rpc retains the most recent 7 days of events.",
"externalDocs": {
"url": "https://developers.stellar.org/docs/data/rpc/api-reference/methods/getEvents"
},
Expand Down
2 changes: 1 addition & 1 deletion openrpc/src/stellar-rpc/schemas/LedgerEntries.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"description": "Ledger key, serialized as a base64 string, corresponding to an existing ledger entry you wish to retrieve."
},
"LedgerKeys": {
"description": "Array containing ledger keys.",
"description": "Array containing ledger keys. The maximum number of ledger keys accepted is 200.",
"type": "array",
"items": {
"$ref": "#/components/schemas/LedgerKey"
Expand Down
Loading

0 comments on commit f9ed481

Please sign in to comment.