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

  1. Create Account This will cause the source’s balance to ⬇ and newly created account’s balance to ⬆
type CreateAccountDetails struct {
	sourceAccount      string
	destinationAccount string
}
  1. Simple Payment
type SimplePaymentDetails struct {
	sourceAccount      string
	destinationAccount string
}
  1. 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
}
  1. Clawback Note: There is nothing here in details
type ClawbackDetails struct {
}
  1. Create Claimable Balance This will cause the source account’s balance to ⬇
type CreateClaimableBalanceDetails struct {
	destinationAccounts []string
}
  1. Claim Claimable Balance This will cause the account’s (that is claiming this CB) balance to go ⬆
type ClaimClaimableBalanceDetails struct {
	balanceId string
}
  1. Clawback Claimable Balance NOTE - A ClawbackClaimableBalance operation does not cause any account or trustline’s balance to go up or down. Meaning, there never will be a TokenTransferEvent generated in response to a ClawbackClaimableBalanceOperation. I am simply adding this section for articulating the above point.

  2. LiquidityPool Deposit

  3. LiquidityPool Withdraw

  4. Manage Offer Buy The kind of events to expect when a ManageBuyOffer operation 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 Z

    Given a ManageOfferBuy operation 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

    1. eventType = debit, account = P, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=123), fromAccount = P, toAccount = X
    2. eventType = debit, account = P, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=234), fromAccount = P, toAccount = Y
    3. eventType = debit, account = P, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=456), fromAccount = P, toAccount = Z
    4. eventType = credit, account = P, asset = BTC, amount = (amountSold from the claimAtom corresponding to offerId=123), fromAccount = X, toAccount = P
    5. eventType = credit, account = P, asset = BTC, amount = (amountSold from the claimAtom corresponding to offerId=234), fromAccount = Y, toAccount = P
    6. eventType = credit, account = P, asset = BTC, amount = (amountSold from the claimAtom corresponding to offerId=456), fromAccount = Z, toAccount = P
    7. eventType = credit, account = X, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=123), fromAccount = P, toAccount = X (inverse of 1)
    8. eventType = credit, account = Y, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=234), fromAccount = P, toAccount = Y (inverse of 2)
    9. eventType = credit, account = Z, asset = USD, amount = (amountBought from the claimAtom corresponding to offerId=456), fromAccount = P, toAccount = Z (inverse of 3)
    10. eventType = debit, account = X, asset = BTC, amount = (amountSold from claimAtom corresponding to offerId=123), fromAccount = X, toAccount = P (inverse of 4)
    11. eventType = debit, account = Y, asset = BTC, amount = (amountSold from claimAtom corresponding to offerId=234), fromAccount = Y, toAccount = P (inverse of 5)
    12. 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
}
  1. Manage Sell Offer

  2. Path Payment Strict Send

  3. Path Payment Strict Receive

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`
  1. Transfer
type SmartContractTransferEventDetails struct {
	from string  // represents either a contractID or an accountId
	to string
}
  1. Mint
type SmartContractMintEventDetails struct {
	admin string // represents either a contractID or an accountId
	to    string
}
  1. Burn
type SmartContractBurnEventDetails struct {
	from string // represents either a contractID or an accountId
}
  1. 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)

Most upvoted comments

You mention a source account in your CreateClaimableBalanceDetails struct and yet I don’t see it in the struct definition:

This particular TokenTransferEvent that has this CreateClaimableBalanceDetails section is generated in response to a CreateClaimableBalance operation. The entityId in the top-level TokenTransferEvent is 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 details


why list all the destinationAccounts here

The TokenTransferEvent was caused in response to the operation CreateClaimableBalanceOperation, and will be claimed by one of the destinationAccounts presented in the Details in 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”


For ClaimClaimableBalanceDetails, how do we know the account that actually claimed the balance?

Same reasoning as above. This particular TokenTransferEvent that has this ClaimClaimableBalanceDetails section is generated in response to a ClaimClaimableBalance operation. The entityId is the destination account that claimed this claimable balance

–

Maybe we can use “pending_credit” or “pending_debit” for claimable balances, since they aren’t crediting or debiting your balance until they’re claimed.

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 pending per 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 a BalanceId in the input operation and identify who created the claimable balance entry.


To answer your question about ClawbackClaimableBalanceDetails we’d like to model (at least for now) getting assigned as a claimant on the balance as a state change, so yes, we’d like this to be included as well

That comment was more of a footnote for me. A ClawbackClaimableBlaance operation 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 TokenTransferEvent

If each field has the appropriate src/dst (or equivalent, if possible) in its details, then there’s no need for a TransferDirection since it’s implied by amount always being positive.

Three reasons to have the TransferDirection field in the result:

  • Imagine a usecase where you are a wallet like Freighter and using a list of TokenTransferEvents to 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 is TransferDirection.

  • 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 balanceId field to go by, and that doesnt give an indication of who the creator (debited account) of the CB was.

The Amount should be a string to avoid imprecision, or a whole integer without a decimal involved. You can leverage our amount package to make this easier.

For SAC events, note that the support/contractevents package should make this easier, as well.