You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/data/indexers/build-your-own/processors/token-transfer-processor/README.mdx
+62-57Lines changed: 62 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,11 +5,11 @@ sidebar_position: 0
5
5
6
6
## Overview
7
7
8
-
The Token Transfer Processor (TTP) is a [package](https://github.com/stellar/go/tree/ttp-v1.0.0/ingest/processors/token_transfer) which uses the [ingest-sdk](../../ingest-sdk/README.mdx) to parse Stellar network transaction data and derive token transfer events. Before TTP, developers had to manually parse complex ledger data, operation results, and ledger entry changes to understand when and how assets moved between accounts, contracts, and other entities on the network.
8
+
The Token Transfer Processor (TTP) is a [Go package](https://github.com/stellar/go/tree/ttp-v1.0.0/ingest/processors/token_transfer) which uses the [ingest-sdk](../../ingest-sdk/README.mdx) to parse Stellar network transaction data and derive token transfer events. Before TTP, developers had to manually parse complex ledger data, operation results, and ledger entry changes to understand when and how assets moved between accounts, contracts, and other entities on the network.
9
9
10
-
Prior to [CAP-67 Unified Events](https://stellar.org/protocol/cap-67), tracking token transfers required significant custom logic to handle different operation types, interpret ledger changes, and reconstruct the flow of assets. CAP-67 introduced a standardized event format that simplifies this process by providing a unified way to represent all token transfer activities.
10
+
Prior to [CAP-67 Unified Events][cap67], tracking token transfers required significant custom logic to handle different operation types, interpret ledger changes, and reconstruct the flow of assets. CAP-67 introduced a standardized event format that simplifies this process by providing a unified way to represent all token transfer activities.
11
11
12
-
TTP serves as the implementation bridge for CAP-67, automatically generating these standardized events from Stellar ledger data. It can operate in two modes:
12
+
TTP serves provides a facade to CAP-67, automatically generating these standardized events from Stellar ledger data. It can operate in two modes:
13
13
14
14
-**Standalone mode**: TTP analyzes operations, operation results, and ledger entry changes to derive transfer events
15
15
-**Unified events mode**: TTP reads directly from CAP-67 compliant unified events when available in the ledger data
@@ -18,7 +18,7 @@ For more details on operational modes, see the [Modes of Operation](#modes-of-op
18
18
19
19
## Key Features
20
20
21
-
- Processes all token movement operations - classic and smart contract:
21
+
- Processes all classic and [SEP-41][sep41] token movements from classic operations and smart contract invocations:
22
22
23
23
- Simple payments
24
24
- Path payments
@@ -28,9 +28,9 @@ For more details on operational modes, see the [Modes of Operation](#modes-of-op
@@ -42,9 +42,40 @@ For more details on operational modes, see the [Modes of Operation](#modes-of-op
42
42
43
43
- Reconciliation for older protocol versions to ensure consistency between operation changes and generated events
44
44
45
-
## Types of Events and Modeling
45
+
## Events
46
46
47
-
TTP generates events based on [protobuf definitions](https://github.com/stellar/go/blob/ttp-v1.0.0/protos/ingest/processors/token_transfer/token_transfer_event.proto) that align closely with the CAP-67 specification. Each event contains metadata and type-specific information structured as follows:
47
+
TTP generates events in Go bindings based on [protobuf definitions](https://github.com/stellar/go/blob/ttp-v1.0.0/protos/ingest/processors/token_transfer/token_transfer_event.proto). The definitions codify an IDL for the standardized token transfer event models put forth in CAP-67. Each event contains metadata and type-specific information structured as follows:
48
+
49
+
| Event Type | Description | Key Fields | When Generated |
50
+
| --- | --- | --- | --- |
51
+
|**Transfer**| Asset movement between two entities |`from`, `to`, `amount`, `asset`, `toMuxedInfo`| When assets move between accounts, contracts, or other entities |
52
+
|**Mint**| Asset creation by the issuer |`to`, `amount`, `asset`, `toMuxedInfo`| When an issuer creates new tokens or when assets are sent from the issuer |
53
+
|**Burn**| Asset destruction to the issuer |`from`, `amount`, `asset`| When assets are returned to the issuer for destruction |
54
+
|**Clawback**| Forced asset recovery by issuer |`from`, `amount`, `asset`| When an issuer uses clawback operations to recover assets |
55
+
|**Fee**| Network fee payment or refund |`account`, `amount`| For all transaction fees and Soroban fee refunds |
56
+
57
+
### Fee Events
58
+
59
+
TTP generates fee events to track network fees associated with transaction processing. Understanding the different types of fee events is important for accurate accounting:
60
+
61
+
Fee events are generated for all transactions, whether they succeed or fail. These represent the network fees that accounts pay to submit transactions to the Stellar network.
Fee refund events are generated only for Soroban (smart contract) transactions and only when there are unused resources that qualify for a refund.
68
+
69
+
-**Present for**: Soroban transactions with unused resource fees
70
+
-**Amount representation**: Negative values to indicate money being returned
71
+
-**Asset**: Always XLM
72
+
-**Event type**: Uses the same `Fee` event type, distinguished by the negative amount
73
+
74
+
:::note
75
+
76
+
TTP uses negative amounts in fee events to represent refunds rather than creating a separate refund event type. This approach maintains consistency with the CAP-67 specification while clearly indicating the direction of the fee transaction.
77
+
78
+
:::
48
79
49
80
### Event Metadata
50
81
@@ -54,38 +85,30 @@ Every token transfer event includes comprehensive metadata to provide context ab
54
85
| --- | --- | --- |
55
86
|`ledgerSequence`|`uint32`| The ledger number where this event occurred. This provides chronological ordering across the entire network. |
56
87
|`txHash`|`string`| The transaction hash that generated this event. This allows you to trace events back to their originating transaction. |
57
-
|`operationIndex`|`uint32*`| The zero-based index of the operation within the transaction that caused this event. This field is `nil` for transaction-level events like fees. |
88
+
|`operationIndex`|`uint32*`| The one-based index of the operation within the transaction that caused this event as defined by [SEP-35][sep35]. This field is `nil` for transaction-level events like fees. |
58
89
|`contractAddress`|`string`| The contract address asociated with the asset/token being moved. For classic operations or Stellar Asset Contract Events, this field will be the contractId of the underlying classic asset. This enables integration with Stellar's smart contract ecosystem. |
59
90
60
91
:::note
61
92
62
-
The `contractAddress` field is particularly important for DeFi applications as it provides the bridge between classic Stellar assets and their smart contract representations.
93
+
The `toMuxedInfo` field is included in Transfer and Mint events when the destination uses a muxed account (M-address) and/or when transaction-level memo is set (in the case of non smart contract transactions), providing additional routing information.
63
94
64
95
:::
65
96
66
-
### Event Types
97
+
Please refer to [this](../../../../../learn/encyclopedia/transactions-specialized/pooled-accounts-muxed-accounts-memos.mdx) section for more information on muxed account/memo usage.
67
98
68
-
TTP generates five distinct types of token transfer events, each modeling different aspects of asset movement:
69
-
70
-
| Event Type | Description | Key Fields | When Generated |
71
-
| --- | --- | --- | --- |
72
-
|**Transfer**| Asset movement between two entities |`from`, `to`, `amount`, `asset`, `toMuxedInfo`| When assets move between accounts, contracts, or other entities |
73
-
|**Mint**| Asset creation by the issuer |`to`, `amount`, `asset`, `toMuxedInfo`| When an issuer creates new tokens or when assets are sent from the issuer |
74
-
|**Burn**| Asset destruction to the issuer |`from`, `amount`, `asset`| When assets are returned to the issuer for destruction |
75
-
|**Clawback**| Forced asset recovery by issuer |`from`, `amount`, `asset`| When an issuer uses clawback operations to recover assets |
76
-
|**Fee**| Network fee payment or refund |`account`, `amount`| For all transaction fees and Soroban fee refunds |
99
+
Please refer to [this](https://stellar.org/protocol/cap-67#prohibit-the-transaction-memo-and-muxed-source-accounts-from-being-set-on-soroban-transactions) section in CAP-67 to learn more on what to expect in the `toMuxedInfo` field.
77
100
78
101
:::note
79
102
80
-
The `toMuxedInfo` field is included in Transfer and Mint events when the destination uses a muxed account (M-address) and/or when transaction-level memo is set (in the case of non smart contract transactions), providing additional routing information.
103
+
The `contractAddress` field is particularly important for DeFi applications as it provides the bridge between classic Stellar assets and their smart contract representations.
81
104
82
-
:::
105
+
For events from classic transactions and SAC events from smart contract transactions, the `contractAddress` field reflects the SAC address for the asset.
83
106
84
-
For more information on what to expect in the `toMuxedInfo` field, please refer to [this](https://github.com/stellar/stellar-protocol/blob/master/core/cap-0067.md#prohibit-the-transaction-memo-and-muxed-source-accounts-from-being-set-on-soroban-transactions) section in CAP-67.
107
+
:::
85
108
86
-
## Functions
109
+
## Go Usage
87
110
88
-
TTP provides three main processing functions that operate at different levels of granularity:
111
+
TTP provides three distinct functions which derive events from different levels of granularity from the underlying Stellar network data.
89
112
90
113
### EventsFromLedger
91
114
@@ -113,7 +136,12 @@ This separation is useful when you need to handle fees differently from operatio
This function processes a single operation within a transaction and returns a list of events generated by that specific operation. This granular approach is useful for applications that need to analyze or react to specific types of operations.
Only use unified events stream mode if you are certain that your ledgers contain unified events. These ledgers must be generated by stellar-core with both `EMIT_CLASSIC_EVENTS=true` and `BACKFILL_STELLAR_ASSET_EVENTS=true` configuration flags enabled. TTP cannot dynamically determine whether a ledger contains unified events or not. If you configure TTP for unified events mode and then feed it ledgers without unified events, processing will fail with errors.
179
+
Only use unified events stream mode if you are certain that your ledgers contain unified events. These ledgers must be generated by stellar-core with both `EMIT_CLASSIC_EVENTS=true` and `BACKFILL_STELLAR_ASSET_EVENTS=true` configuration flags enabled. TTP cannot dynamically determine whether a ledger contains unified events or not. If you configure TTP for unified events mode and then provide it ledgers without unified events, TTP will silently produce no events.
152
180
153
181
:::
154
182
155
183
**When in doubt, always use the default mode**, as it works reliably with all ledger types.
156
184
157
-
## Fee Event Types
158
-
159
-
TTP generates fee events to track network fees associated with transaction processing. Understanding the different types of fee events is important for accurate accounting:
160
-
161
-
### Fee Charges
162
-
163
-
Fee events are generated for all transactions, whether they succeed or fail. These represent the network fees that accounts pay to submit transactions to the Stellar network.
Fee refund events are generated only for Soroban (smart contract) transactions, and only when there are unused resources that qualify for a refund.
172
-
173
-
- **Present for**: Soroban transactions with unused resource fees
174
-
- **Amount representation**: Negative values to indicate money being returned
175
-
- **Asset**: Always XLM
176
-
- **Event type**: Uses the same `Fee` event type, distinguished by the negative amount
177
-
178
-
:::note
179
-
180
-
TTP uses negative amounts in fee events to represent refunds rather than creating a separate refund event type. This approach maintains consistency with the CAP-67 specification while clearly indicating the direction of the fee transaction.
181
-
182
-
:::
183
-
184
185
## Event Ordering
185
186
186
187
The order of events returned by TTP depends on the Stellar protocol version that was active when the ledger was created. This ordering is crucial for maintaining accurate chronological records of asset movements.
@@ -223,7 +224,11 @@ The chronological ordering ensures that when you process events in the order ret
0 commit comments