Skip to content

📊 Refresh Stellar Data Structures #2446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JFWooten4 wants to merge 5 commits into
base: main
Choose a base branch
from
+22 −16
Open

📊 Refresh Stellar Data Structures #2446

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3aa578d
🧭 Add data structures category
JFWooten4 May 13, 2026
66c8f4b
📝 Refresh asset data structures
JFWooten4 May 13, 2026
e7e29f8
📝 Refresh event data structures
JFWooten4 May 13, 2026
bbdf7da
Potential fix for pull request finding
JFWooten4 May 13, 2026
3d2fdef
🔢 Plural number typo outside of backticks
JFWooten4 Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/learn/fundamentals/stellar-data-structures/_category_.json
View file
Open in desktop

@ElliotFriend ElliotFriend Jul 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we've been moving away from category json files for these kinds of directories. pretty much anything you need to modify can be done so directly in the README.mdx frontmatter.

Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"label": "Stellar Data Structures",
"position": 50,
"link": {
"type": "doc",
"id": "learn/fundamentals/stellar-data-structures/README"
},
"description": "Learn how accounts, assets, contracts, events, and ledgers fit together to describe everything living on the Stellar network."
}
16 changes: 8 additions & 8 deletions docs/learn/fundamentals/stellar-data-structures/assets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,9 @@ description: "Learn how assets work on the Stellar network, including issuing, t
sidebar_position: 30
---

:::info

The term "custom token" has been deprecated in favor of "contract token". View the conversation in the [Stellar Developer Discord](https://discord.com/channels/897514728459468821/966788672164855829/1359276952971640953).

:::

# Assets

Accounts on the Stellar network can be used to track, hold, and transfer any type of asset. Assets can represent many things: cryptocurrencies (such as bitcoin or ether), fiat currencies (such as dollars or pesos), other tokens of value (such as NFTs), pool shares, or bonds and equity.
Accounts on the Stellar network can be used to track, hold, and transfer any type of asset. Assets can represent many things: cryptocurrencies (such as bitcoin or ether), fiat currencies (such as dollars or pesos), other tokens of value (such as NFTs, pool shares, or securities).

@ElliotFriend ElliotFriend Jul 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think i like the parenthesis the way it was before. and maybe securities belongs as an addition to bonds and equity rather than a replacement?


:::note

Expand All @@ -27,6 +21,12 @@ Learn more about the differences in the [Assets and Tokens section](../../../tok

Classic assets on Stellar have two identifying characteristics: the asset code and the issuer. Since more than one organization can issue a credit representing the same asset, asset codes often overlap (for example, multiple companies offer a USD token on Stellar). Assets are uniquely identified by the combination of their asset code and issuer.

:::info

"Contract token" is the preferred term over "custom token," as discussed in the [Stellar Developer Discord](https://discord.com/channels/897514728459468821/966788672164855829/1359276952971640953).

:::

## Asset components

### Asset code
Expand Down Expand Up @@ -95,7 +95,7 @@ For example, the integer amount value 25,123,456 equals 2.5123456 units of the a

The smallest non-zero amount unit, also known as a stroop, is 0.0000001 (one ten-millionth) represented as an integer value of one. The largest amount unit possible is $\frac{2^{63}-1}{10^7}$ (derived from the maximum 64-bit integer, scaled down) which is 922,337,203,685.4775807.

The numbers are represented as int64s. Amount values are stored as only signed integers to avoid bugs that arise from mixing signed and unsigned integers.
The numbers are represented as `int64s`. Amount values are stored as only signed integers to avoid bugs that arise from mixing signed and unsigned integers.
Comment thread
JFWooten4 marked this conversation as resolved.
Outdated

## Relevance in Stellar Client Libraries

Expand Down
13 changes: 5 additions & 8 deletions docs/learn/fundamentals/stellar-data-structures/events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,16 @@
---
sidebar_position: 11
title: Events
description: Monitor off-chain movement of value and smart contract changes.
description: Monitor on-chain movement of value and smart contract events from off-chain applications.
Comment thread
JFWooten4 marked this conversation as resolved.
---

Events are the mechanism that applications off-chain can use to monitor movement of value of any Stellar operation, as well as custom events in contracts on-chain.

## How are events emitted?

`ContractEvents` are emitted in Stellar Core's `TransactionMeta`. The location of events will depend on the version of `TransactionMeta` emitted. You can see in the [TransactionMetaV3] XDR below that for Soroban transactions, there is a `sorobanMeta` field containing `SorobanTransactionMeta` which includes both `events` (custom events from contracts) and `diagnosticEvents`. Note that `events` will only be populated if the transaction succeeds.
`ContractEvents` are emitted in Stellar Core's `TransactionMeta`. The location of events will depend on the version of `TransactionMeta` emitted. You can see in the [TransactionMetaV3](#transactionmetav3) XDR below that for Soroban transactions, there is a `sorobanMeta` field containing `SorobanTransactionMeta` which includes both `events` (custom events from contracts) and `diagnosticEvents`. Note that `events` will only be populated if the transaction succeeds.

[TransactionMetaV4] is more complex because it supports events for not only Soroban, but also classic operations, fees, and refunds. The top-level `events` vector is used for transaction level events, and currently contains `fee` events for both the initial fee charged and the refund (if applicable). Events tied to operations can be found under `OperationMetaV2`.

[transactionmetav3]: #transactionmetav3
[transactionmetav4]: #transactionmetav4
[TransactionMetaV4](#transactionmetav4) is more complex because it supports events for not only Soroban, but also classic operations, fees, and refunds. The top-level `events` vector is used for transaction level events, and currently contains `fee` events for both the initial fee charged and the refund (if applicable). Events tied to operations can be found under `OperationMetaV2`.

### ContractEvent

Expand Down Expand Up @@ -188,7 +185,7 @@ Events are ephemeral: RPC providers typically only keep short chunks (less than

To learn more about working with events, take a look at the [events guides](../../../build/guides/events/README.mdx) and [this example contract](../../../build/smart-contracts/example-contracts/events.mdx).

For a quick high-level demonstration, though, we'll use the [TypeScript SDK](../../../tools/sdks/README.mdx) to infinitely fetch all `transfer` events (defined by the [Soroban Token Interface](https://stellar.org/protocol/sep-41#interface)) involving the [XLM contract](https://stellar.expert/explorer/testnet/contract/CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC) and display them in a human-friendly format.
For a quick high-level demonstration, though, we'll use the [TypeScript SDK](../../../tools/sdks/README.mdx) to infinitely fetch all `transfer` events (defined by the [Soroban Token Interface](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md#interface)) involving the [XLM contract](https://stellar.expert/explorer/testnet/contract/CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC) and display them in a human-friendly format.

<CodeExample>

Expand All @@ -212,7 +209,7 @@ async function main() {
type: "contract",
contractIds: [Asset.native().contractId(Networks.TESTNET)],
topics: [
// Defined in https://stellar.org/protocol/sep-41#interface
// Defined in https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md#interface
Comment thread
JFWooten4 marked this conversation as resolved.
// for all compatible transfer events.
[
nativeToScVal("transfer", { type: "symbol" }).toXDR("base64"),
Expand Down
Loading