go: SPIKE: Parsing Ledger Close Meta in Stellar Blockchain to Generate Token Transfer Events
WIP-------
This issue deals with capturing the task of creating a generic token transfer processor library/package that parses the LedgerCloseMeta to generate a list of TokenTransfer events that detail how balances have been updated for Ledger Entries of the type LedgerEntryTypeAccount or LedgerEntryTypeTrustline
The endgoal for this issue is to define and agree upon a data model for the type TokenTransferEvent struct
Scope:
- Identify classic operations that can cause balance updates. Include relevant information about what was the operation and result that caused the balance to be updated - either debited or credited.
- For token transfers that occur in smart contracts - so long as they conform to SEP-41, track events of the nature: Transfer, Mint, Clawback, and Burn, by parsing the LCM
Not in Scope:
- Custom smart tokens created in smart contracts that don’t conform to SEP-41 are not in scope for this work (because those can’t be tangibly tracked to begin with)
Basic TokenTransferEvent DataModel
It is intuitive to think of a token transfer as an event that impacts an entity’s balance. The entity could be a trustline, an account, or a smart contract. Transfers can be classified as either a Debit or a Credit, with the reason for the transfer varying widely—stemming from classic operations in Stellar, a transaction fee, or one of the [Transfer, Mint, Burn, Clawback] events generated by a smart contract.
The following represents the basic fields that are common to all TokenTransferEvent, no matter the cause
type TokenTransferEvent struct {
EntityID string // Represents an account, trustline, or smart contract
Asset xdr.Asset // or some other representation of the asset, perhaps string?? // The asset involved in the transfer
Amount float64 // Always positive, represents the quantity transferred
LedgerSequence uint32 // The Ledger associated that brought about this token transfer
TxHash Hash // The Hash of the transactin that brought about this token transfer
TransferType Enum // Type can be Credit or Debit
Reason Enum // Reason can be Fee, SmartContract, or ClassicOperation.
/*
Interface implemented by specific actions causing this event.
Each of classic operations will have different information that they would show
For e.g -
a ManageOffer Buy/Sell operation might show the claim atoms that were filled as a part of this tokenTransfer
a Simple Payment might show the "from" and "to" fields
a burn smart contract event will have the details of the the address holding the balance of tokens that was burned
*/
Details TokenTransferDetails
}
What causes an account’s balance to change
This section highlights all the reasons that can cause an account/trustline/smart contract’s balance to be updated, and what can be included in the Details TokenTransferDetails field for each reason.
Broadly, reasons for account balance updates can be categorized as:
- Transaction Fees
- Changes caused by classic operations.
- Events generated by smart contracts
Transaction Fees
Paid for by the source of the transaction when submitted to Horizon or Soroban Sample Details to be included:
type TransactionFeeDetails struct {
sourceAccount string
txhash string
}
Classic Operations
- Create Account This will cause the source’s balance to ⬇ and newly created account’s balance to ⬆
type CreateAccountDetails struct {
sourceAccount string
destinationAccount string
}
type SimplePaymentDetails struct {
sourceAccount string
destinationAccount string
}
- Account Merge This will cause the sourceAccount to stop existing (and thus cause it’s balance to go ⬇ ), and the destination account’s balance to go ⬆
type AccountMergeDetails struct {
sourceAccount string
destinationAccount string
}
- Clawback Note: There is nothing here in details
type ClawbackDetails struct {
}
- Create Claimable Balance This will cause the source account’s balance to ⬇
type CreateClaimableBalanceDetails struct {
destinationAccounts []string
}
- Claim Claimable Balance This will cause the account’s (that is claiming this CB) balance to go ⬆
type ClaimClaimableBalanceDetails struct {
balanceId string
}
-
Clawback Claimable Balance NOTE - A
ClawbackClaimableBalanceoperation does not cause any account or trustline’s balance to go up or down. Meaning, there never will be aTokenTransferEventgenerated in response to aClawbackClaimableBalanceOperation. I am simply adding this section for articulating the above point. -
Manage Offer Buy The kind of events to expect when a
ManageBuyOfferoperation is successful is best understood with an example. Existing State of the Ledger: Suppose 3 sell offers of BTC-USD exist on the orderbook. 1. offerId = 123, sellerID = account X 2. offerId = 234, sellerID = account Y 3. offerID = 456, sellerId = account ZGiven a
ManageOfferBuyoperation for BTC-USD with a sourceAccount = Account P, that fills against the 3 existing offers, we will generate 6 events for account P, and 2 each for account X, Y, Z, so a total of 12 events. In general, number of transfer events = len(claimAtom list) * 2 * 2- eventType = debit, account = P, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=123), fromAccount = P, toAccount = X
- eventType = debit, account = P, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=234), fromAccount = P, toAccount = Y
- eventType = debit, account = P, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=456), fromAccount = P, toAccount = Z
- eventType = credit, account = P, asset = BTC, amount = (amountSold from the claimAtom corresponding to offerId=123), fromAccount = X, toAccount = P
- eventType = credit, account = P, asset = BTC, amount = (amountSold from the claimAtom corresponding to offerId=234), fromAccount = Y, toAccount = P
- eventType = credit, account = P, asset = BTC, amount = (amountSold from the claimAtom corresponding to offerId=456), fromAccount = Z, toAccount = P
- eventType = credit, account = X, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=123), fromAccount = P, toAccount = X (inverse of 1)
- eventType = credit, account = Y, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=234), fromAccount = P, toAccount = Y (inverse of 2)
- eventType = credit, account = Z, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=456), fromAccount = P, toAccount = Z (inverse of 3)
- eventType = debit, account = X, asset = BTC, amount = (amountSold from claimAtom corresponding to offerId=123), fromAccount = X, toAccount = P (inverse of 4)
- eventType = debit, account = Y, asset = BTC, amount = (amountSold from claimAtom corresponding to offerId=234), fromAccount = Y, toAccount = P (inverse of 5)
- eventType = debit, account = Z, asset = BTC, amount = (amountSold from claimAtom corresponding to offerId=456), fromAccount = Z, toAccount = P (inverse of 6)
This is what will be included in the Details section
type ManageOfferBuyDetails struct {
fromAccount string // AccountId that is debited
toAccount string // AccountId that is credited
offerId int64 // The resting offerId that was filled as a part of this transfer
}
Smart Contract Events
Smart Contract events are emiited as a part of the transaction meta when the an InvokeHostFn operation is executed.
There are four types of events emitted that deal with token movement, as described in SEP-41 and CAP-46-6
**Note: The names of the fields in these events are named so as to conform to the topic and field names as specified in CAP-46-6 **
Refer to these snippets in CAP-46-6
/// Emits an event with:
/// - topics - `["transfer", from: Address, to: Address]`
/// - data - `amount: i128`
....
/// Emits an event with:
/// - topics - `["burn", from: Address]`
/// - data - `amount: i128`
....
/// Emits an event with topics `["mint", admin: Address, to: Address, sep0011_asset: String], data
/// = amount: i128`
....
/// Emits an event with topics `["clawback", admin: Address, from: Address, sep0011_asset: String],
/// data = amount: i128`
- Transfer
type SmartContractTransferEventDetails struct {
from string // represents either a contractID or an accountId
to string
}
- Mint
type SmartContractMintEventDetails struct {
admin string // represents either a contractID or an accountId
to string
}
- Burn
type SmartContractBurnEventDetails struct {
from string // represents either a contractID or an accountId
}
- ClawBack
type SmartContractClawbackEventDetails struct {
admin string // represents either a contractID or an accountId
from string
}
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Comments: 20 (12 by maintainers)
This particular
TokenTransferEventthat has thisCreateClaimableBalanceDetailssection is generated in response to aCreateClaimableBalanceoperation. TheentityIdin the top-levelTokenTransferEventis the source account, whose balance was immediately debited by the said amount after the operation was completed. So, there is no need for sourceAccount to show up in the detailsThe TokenTransferEvent was caused in response to the operation
CreateClaimableBalanceOperation, and will be claimed by one of the destinationAccounts presented in theDetailsin due time. To rephrase it, think of this usecase in Freighter UI - “I can see that my balance was deducted because of a claimableBalance operation I created. And the recipients can are one amongst this list”Same reasoning as above. This particular
TokenTransferEventthat has thisClaimClaimableBalanceDetailssection is generated in response to aClaimClaimableBalanceoperation. TheentityIdis the destination account that claimed this claimable balance–
This is not true. The moment a CB is created, the source account’s balance is reduced by that much. So, there is no notion of
pendingper se. And when you claim it, the claimant account’s balance is increased by that much. When working on these events, I am working in isolation. Meaning, I cannot look at aBalanceIdin the input operation and identify who created the claimable balance entry.That comment was more of a footnote for me. A
ClawbackClaimableBlaanceoperation does not generate a token transfer of any sort. Meaning, no account or trustline’s balance is debited or credited. And so, as such, it doesnt contribute or generate a tokenTransferEvent. It was incorrect of me to include that operation as something that can cause somethig’s balance to go up or down. I am going to remove that operation from the list of operations.EDIT: I didnt remove it, but rather left a note detailing as to why this operation wont generate a
TokenTransferEventThree reasons to have the
TransferDirectionfield in the result:Imagine a usecase where you are a wallet like Freighter and using a list of
TokenTransferEventsto build your own datastores. Now on the Freighter UI, you want to only show credits (or debits) for an account, and the only thing you will need to filter on at isTransferDirection.It is not always true that a transferEvent will have a src/dst.
For e.g, in case of clawbacks, claimable clawbacks and smart contract burn type events.
Consider a create claimable balance operation. In this case the source is known. i.e the amount will be debited from the source’s account. We dont know the destination yet, especially if you specify more than one destinations. Following that train of thought, when you have a claim claimable balance operation, all that you have (currently) is the balanceId. So, the account that is specified in the operation is credited with the amount, but there is no way to identify what the source might be in this case. We only have the
balanceIdfield to go by, and that doesnt give an indication of who the creator (debited account) of the CB was.The
Amountshould be a string to avoid imprecision, or a whole integer without a decimal involved. You can leverage ouramountpackage to make this easier.For SAC events, note that the
support/contracteventspackage should make this easier, as well.