diff --git a/docs/learn/fundamentals/stellar-data-structures/_category_.json b/docs/learn/fundamentals/stellar-data-structures/_category_.json new file mode 100644 index 000000000..5d21b285a --- /dev/null +++ b/docs/learn/fundamentals/stellar-data-structures/_category_.json @@ -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." +} diff --git a/docs/learn/fundamentals/stellar-data-structures/assets.mdx b/docs/learn/fundamentals/stellar-data-structures/assets.mdx index 41d1da223..42563d108 100644 --- a/docs/learn/fundamentals/stellar-data-structures/assets.mdx +++ b/docs/learn/fundamentals/stellar-data-structures/assets.mdx @@ -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). :::note @@ -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 @@ -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. ## Relevance in Stellar Client Libraries diff --git a/docs/learn/fundamentals/stellar-data-structures/events.mdx b/docs/learn/fundamentals/stellar-data-structures/events.mdx index d3a0c7dde..6aa8cd3ed 100644 --- a/docs/learn/fundamentals/stellar-data-structures/events.mdx +++ b/docs/learn/fundamentals/stellar-data-structures/events.mdx @@ -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. --- 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 @@ -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. @@ -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 // for all compatible transfer events. [ nativeToScVal("transfer", { type: "symbol" }).toXDR("base64"),