Skip to content

Commit 641cadc

Browse files
karthikiyer56karthikiyer56
committed
Add examples and restructure code under a new section called processors
1 parent a73becc commit 641cadc

7 files changed

Lines changed: 455 additions & 6 deletions

File tree

‎docs/data/indexers/build-your-own/README.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,6 @@ A set of Golang packages which can be used within application as a programmatic
2323
- You want an intuitive, compile-time, type-safe application developer experience.
2424
- You want to programmatically access History Archives to retrieve ledger entries.
2525

26-
## [Token Transfer Processor](./token-transfer-processor/README.mdx)
26+
## [Processors](./processors/README.mdx)
2727

28-
A comprehensive implementation of an indexer(processor) that tracks asset movement on the Stellar blockchain
28+
A suite of Go packages that help you parse Stellar blockchaindata

‎docs/data/indexers/build-your-own/processors/README.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Processors
3+
sidebar_position: 0
4+
---
5+
6+
Learn more about the processors library in the [Stellar Go SDK](github.com/stellar/go)
7+
8+
## [Token Transfer Processor](./token-transfer-processor/README.mdx)
9+
10+
Track all asset movement on the Stellar blockchain

docs/data/indexers/build-your-own/token-transfer-processor/README.mdx renamed to docs/data/indexers/build-your-own/processors/token-transfer-processor/README.mdx

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ sidebar_position: 0
55

66
## Overview
77

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 [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.
99

1010
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.
1111

@@ -20,10 +20,11 @@ For more details on operational modes, see the [Modes of Operation](#modes-of-op
2020

2121
- Processes all token movement operations - classic and smart contract:
2222

23-
- Simple Payments
23+
- Simple payments
2424
- Path payments
25+
- DEX operations
2526
- Account merges
26-
- Trustline Revocations
27+
- Trustline revocations
2728
- Claimable balance operations
2829
- Liquidity pool operations
2930
- Clawback operations

‎docs/data/indexers/build-your-own/processors/token-transfer-processor/examples/README.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Example Usages
3+
sidebar_position: 10
4+
---
5+
6+
This section contains examples of how Token Transfer Processor can be used in your application logic
7+
8+
## Prerequisites
9+
10+
Some of the examples listed here might invoke the `stellar-core` binary. Refer [this section](../../../ingest-sdk/developer_guide/ledgerbackends/captivecore.mdx) for more details on how to compile `stellar-core` for your platform.
11+
12+
```
13+
//filename: go.mod
14+
15+
require (
16+
github.com/stellar/go horizonclient-v23.0.0-rc
17+
)
18+
19+
```
20+
21+
You may want to optionally run `go mod tidy` in your codebase to pull the latest version of the ingest package.
22+
23+
## Helper Code
24+
25+
This section contains some helper code that will be used in all the examples.
26+
27+
<CodeExample>
28+
29+
```go
30+
package main
31+
32+
import (
33+
"context"
34+
"fmt"
35+
"github.com/sirupsen/logrus"
36+
"github.com/stellar/go/ingest/ledgerbackend"
37+
"github.com/stellar/go/network"
38+
"github.com/stellar/go/support/log"
39+
"github.com/stellar/go/xdr"
40+
"os"
41+
)
42+
43+
func panicIf(err error) {
44+
if err != nil {
45+
panic(err)
46+
}
47+
}
48+
49+
// This example runs a captive core instance to get a ledger.
50+
// You can just as easily replace it with a BufferedStorageBackend to read from GCS.
51+
func fetchLedger(ledgerSeq uint32, unifiedEventsEnabled bool) xdr.LedgerCloseMeta {
52+
archiveURLs := network.PublicNetworkhistoryArchiveURLs
53+
networkPassphrase := network.PublicNetworkPassphrase
54+
captiveCoreToml, err := ledgerbackend.NewCaptiveCoreToml(ledgerbackend.CaptiveCoreTomlParams{
55+
EmitUnifiedEvents: unifiedEventsEnabled,
56+
NetworkPassphrase: networkPassphrase,
57+
HistoryArchiveURLs: archiveURLs,
58+
})
59+
panicIf(err)
60+
61+
config := ledgerbackend.CaptiveCoreConfig{
62+
// Change these based on your environment:
63+
BinaryPath: "/Users/karthik/WS/stellar-core-2/src/stellar-core",
64+
NetworkPassphrase: networkPassphrase,
65+
HistoryArchiveURLs: archiveURLs,
66+
Toml: captiveCoreToml,
67+
}
68+
69+
// Log Captive Core straight to stdout by default
70+
if config.Log == nil {
71+
config.Log = log.New()
72+
config.Log.SetOutput(os.Stdout)
73+
config.Log.SetLevel(logrus.ErrorLevel)
74+
}
75+
76+
// Prepare backend connection
77+
ctx := context.Background()
78+
backend, err := ledgerbackend.NewCaptive(config)
79+
panicIf(err)
80+
defer backend.Close()
81+
82+
fmt.Printf("Fetching ledgerSequence: %v\n", ledgerSeq)
83+
// Prepare and retrieve the ledger
84+
err = backend.PrepareRange(ctx, ledgerbackend.BoundedRange(ledgerSeq, ledgerSeq))
85+
panicIf(err)
86+
87+
ledger, err := backend.GetLedger(ctx, ledgerSeq)
88+
panicIf(err)
89+
90+
return ledger
91+
}
92+
93+
// Helper function to print the protobuf event.
94+
func printProtoEvent(event *token_transfer.TokenTransferEvent) {
95+
jsonBytes, _ := protojson.MarshalOptions{
96+
Multiline: true,
97+
EmitDefaultValues: true,
98+
Indent: " ",
99+
}.Marshal(event)
100+
fmt.Printf("### Event Type : %v\n", event.GetEventType())
101+
fmt.Println(string(jsonBytes))
102+
}
103+
104+
```
105+
106+
</CodeExample>

‎docs/data/indexers/build-your-own/processors/token-transfer-processor/examples/event_stats.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Retrieve token transfer events from a ledger
3+
sidebar_position: 10
4+
---
5+
6+
This example fetches a specific Stellar ledger and uses the Token Transfer Processor to extract all token movement events from it. The code processes each event, categorizes them by type (transfers, mints, burns, clawbacks, fees), and prints both the individual event details and summary statistics. This demonstrates the basic usage of EventsFromLedger() to analyze all asset activity within a single ledger.
7+
8+
<CodeExample>
9+
10+
```go
11+
package main
12+
13+
import (
14+
"fmt"
15+
"github.com/stellar/go/network"
16+
"github.com/stellar/go/processors/token_transfer"
17+
"log"
18+
"strings"
19+
)
20+
21+
func main() {
22+
ledgerSeq := uint32(58155263)
23+
24+
// Toggle this flag to read from ledgerEntrychanges or from P23 unified events stream
25+
unifiedEventsEnabled := false
26+
27+
ledger := fetchLedger(ledgerSeq, unifiedEventsEnabled)
28+
29+
var ttp *token_transfer.EventsProcessor
30+
31+
if unifiedEventsEnabled {
32+
ttp = token_transfer.NewEventsProcessorForUnifiedEvents(network.PublicNetworkPassphrase)
33+
} else {
34+
ttp = token_transfer.NewEventsProcessor(network.PublicNetworkPassphrase)
35+
}
36+
37+
// Process events from a single ledger
38+
events, err := ttp.EventsFromLedger(ledger)
39+
if err != nil {
40+
log.Fatal("Error processing ledger:", err)
41+
}
42+
43+
// Statistics counters
44+
var transferCount, mintCount, burnCount, clawbackCount, feeCount, refundCount int
45+
46+
// Process events to analyze token transfers
47+
for _, event := range events {
48+
switch {
49+
case event.GetTransfer() != nil:
50+
transfer := event.GetTransfer()
51+
fmt.Printf("Transfer: %s -> %s, Amount: %s, Asset: %s\n",
52+
transfer.From, transfer.To, transfer.Amount, transfer.Asset)
53+
transferCount++
54+
55+
case event.GetMint() != nil:
56+
mint := event.GetMint()
57+
fmt.Printf("Mint: %s, Amount: %s, Asset: %s\n",
58+
mint.To, mint.Amount, mint.Asset)
59+
mintCount++
60+
61+
case event.GetBurn() != nil:
62+
burn := event.GetBurn()
63+
fmt.Printf("Burn: %s, Amount: %s, Asset: %s\n",
64+
burn.From, burn.Amount, burn.Asset)
65+
burnCount++
66+
67+
case event.GetClawback() != nil:
68+
clawback := event.GetClawback()
69+
fmt.Printf("Clawback: %s, Amount: %s, Asset: %s\n",
70+
clawback.From, clawback.Amount, clawback.Asset)
71+
clawbackCount++
72+
73+
case event.GetFee() != nil:
74+
fee := event.GetFee()
75+
if strings.HasPrefix(fee.Amount, "-") {
76+
fmt.Printf("Fee Refund: %s, Amount: %s, Asset: %s\n",
77+
fee.From, fee.Amount, fee.Asset)
78+
refundCount++
79+
} else {
80+
fmt.Printf("Fee: %s, Amount: %s, Asset: %s\n",
81+
fee.From, fee.Amount, fee.Asset)
82+
feeCount++
83+
}
84+
}
85+
}
86+
87+
// Print statistics
88+
fmt.Printf("\n--- Ledger %d Statistics ---\n", ledgerSeq)
89+
fmt.Printf("Total Events: %d\n", len(events))
90+
fmt.Printf("Transfers: %d\n", transferCount)
91+
fmt.Printf("Mints: %d\n", mintCount)
92+
fmt.Printf("Burns: %d\n", burnCount)
93+
fmt.Printf("Clawbacks: %d\n", clawbackCount)
94+
fmt.Printf("Fees: %d\n", feeCount)
95+
fmt.Printf("Refunds: %d\n", refundCount)
96+
}
97+
98+
```
99+
100+
</CodeExample>

0 commit comments

Comments
 (0)