tracetracking

package
v0.1.0-test Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2025 License: MIT Imports: 11 Imported by: 9

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Sum 

func Sum(values ...*big.Int) *big.Int

Sum calculates the total of multiple big.Int values and returns the result. This is a utility function for aggregating fee amounts and other numeric values.

Types

type MsgStatus 

type MsgStatus int

MsgStatus represents the status of a message in the TON blockchain. It can be one of the following:

  • Received: The message has been received and has outgoing messages, all in Sent state.
  • Cascading: The message has been received and has outgoing messages, some in Received state.
  • Finalized: The message has been received and all outgoing messages have been received.
const (
	NotFound MsgStatus = -1
	Received MsgStatus = iota
	Cascading
	Finalized
)

type OutgoingExternalMessages 

type OutgoingExternalMessages struct {
	CreatedAt uint32
	LT        uint64
	Body      *cell.Cell
}

OutgoingExternalMessages represents external messages sent by a contract, typically used for events or notifications that are emitted to external systems.

func (*OutgoingExternalMessages) AsString 

func (e *OutgoingExternalMessages) AsString() (string, error)

AsString attempts to parse the message body as a string. This is commonly used for external messages that contain text data or event information. Returns an error if the body cannot be parsed as a string.

type ReceivedMessage 

type ReceivedMessage struct {
	InternalMsg *tlb.InternalMessage
	Amount      *big.Int
	ExternalMsg *tlb.ExternalMessageIn
	LamportTime uint64   // Lamport time of sender when emitting the message
	ImportFee   *big.Int // Import fee of the message. This is paid by the receiver of the message when calling acceptMessage(). It is 0 on internal messages.
	FwdFee      *big.Int // Of sending this message. This is paid by the sender of the message. It is 0 on external messages.

	StorageFeeCharged                *big.Int           // Rent due at the moment of sending the message (charged to receiver)
	MsgFeesChargedToSender           *big.Int           // Forward fees
	TotalActionFees                  *big.Int           // Fees charged to the sender for sending messages. This + the fwdFee of each outgoing msg forms the total charged in the action phase.
	GasFee                           *big.Int           // Fees charged to the receiver for processing the message.
	MagicFee                         *big.Int           // Unknown origin fee
	EmittedBouncedMessage            bool               // Indicates if the transaction was bounced
	Success                          bool               // Indicates if the transaction was successful
	ExitCode                         tvm.ExitCode       // Exit code of the transaction execution
	OutgoingInternalSentMessages     []*SentMessage     // Internal messages sent as a result of this message
	OutgoingInternalReceivedMessages []*ReceivedMessage // Internal messages that have been received by their recipients
	OutgoingExternalMessages         []OutgoingExternalMessages
}

ReceivedMessage represents a message that has been received and processed by a contract in the TON blockchain. It contains comprehensive information about both the sending and receiving phases of the message, including fees, execution results, and any outgoing messages generated during processing.

func MapToReceivedMessage 

func MapToReceivedMessage(txOnReceived *tlb.Transaction) (ReceivedMessage, error)

MapToReceivedMessage creates a ReceivedMessage from a transaction that represents a message being received and processed. It extracts all relevant information including fees, execution results, bounced status, and outgoing messages.

The function: - Updates the total fees - Updates the storage fees collected - Updates the status to Received or Finalized if there are no outgoing messages - Maps the outgoing messages to the sent messages - Updates the bounced status if the transaction was bounced

Returns an error if the transaction cannot be properly parsed.

func (*ReceivedMessage) AppendEvent 

func (m *ReceivedMessage) AppendEvent(outMsg *tlb.ExternalMessageOut)

AppendEvent adds an external message to the list of outgoing external messages. External messages are typically used for events or notifications that are emitted by contracts to communicate with external systems.

func (*ReceivedMessage) AppendSentMessage 

func (m *ReceivedMessage) AppendSentMessage(outgoingInternalMessage *tlb.InternalMessage)

AppendSentMessage adds an outgoing internal message to the list of sent messages and updates the total forward fees charged to the sender. This tracks all messages that were sent as a result of processing the current message.

func (*ReceivedMessage) Dump 

func (m *ReceivedMessage) Dump() string

Outputs a nicely indented string representation of the trace tree, with the exit codes, bounced tags and sender-receiver

func (*ReceivedMessage) NetCreditResult 

func (m *ReceivedMessage) NetCreditResult() *big.Int

NetCreditResult calculates the net amount credited to the recipient after accounting for all outgoing payments. This is the amount received minus the total amount sent in outgoing messages.

func (*ReceivedMessage) OutcomeExitCode 

func (m *ReceivedMessage) OutcomeExitCode() tvm.ExitCode

OutcomeExitCode returns the first non-success exit code found in this message or any of its outgoing internal messages. If all messages succeeded, it returns the success exit code.

func (*ReceivedMessage) OutgoingAmount 

func (m *ReceivedMessage) OutgoingAmount() *big.Int

OutgoingAmount calculates the total amount sent in all outgoing messages, including both sent messages and messages that have been received by their recipients. This represents the total outflow from the current message.

func (*ReceivedMessage) Status 

func (m *ReceivedMessage) Status() MsgStatus

Status returns the current status of the message based on its outgoing messages. Returns Finalized if no outgoing messages exist, Cascading if some outgoing messages have been received, or Received if outgoing messages exist but none have been received yet.

func (*ReceivedMessage) TotalActionPhaseFees 

func (m *ReceivedMessage) TotalActionPhaseFees() *big.Int

TotalActionPhaseFees calculates the total fees charged during the action phase, including the base action fees and forward fees for all outgoing messages (both sent and received). This represents the complete cost of message processing and forwarding during transaction execution.

func (*ReceivedMessage) TotalTransactionExecutionFee 

func (m *ReceivedMessage) TotalTransactionExecutionFee() *big.Int

TotalTransactionExecutionFee calculates the total fees for executing a transaction, excluding storage fees. This includes import fees (for external messages), gas fees (compute phase), action phase fees, and any additional fees. This represents the complete execution cost for processing the message. Excludes the storage fee

func (*ReceivedMessage) TraceSucceeded 

func (m *ReceivedMessage) TraceSucceeded() bool

TraceSucceeded recursively checks if this message and all its OutgoingInternalMessagesReceived succeeded.

func (*ReceivedMessage) WaitForOutgoingMessagesToBeReceived 

func (m *ReceivedMessage) WaitForOutgoingMessagesToBeReceived(c ton.APIClientWrapped) error

WaitForOutgoingMessagesToBeReceived waits for all outgoing messages to be received by their respective recipients and blocks until completion. It subscribes to transactions for each recipient address and matches incoming transactions with the sent messages. The OutgoingInternalMessagesReceived field is updated with the received messages.

Returns an error if any of the outgoing messages failed to be processed or if there are issues with transaction monitoring.

TODO: This could be optimized by grouping outgoing messages by recipient address

func (*ReceivedMessage) WaitForTrace 

func (m *ReceivedMessage) WaitForTrace(c ton.APIClientWrapped) error

WaitForTrace waits for the complete execution trace of a message, including all outgoing messages and their subsequent outgoing messages recursively. This ensures that the entire message cascade has been processed and finalized. It modifies the OutgoingInternalMessagesReceived field and returns an error if any part of the trace fails to process.

The function returns immediately if the message is already in Finalized state. Otherwise, it processes all cascading messages until the entire trace is complete.

type SentMessage 

type SentMessage struct {
	InternalMsg *tlb.InternalMessage
	Amount      *big.Int
	LamportTime uint64   // Lamport time of sender when emitting the message
	FwdFee      *big.Int // Of sending this message. This is paid by the sender of the message. It is 0 on external messages.
}

func NewSentMessage 

func NewSentMessage(internalMessage *tlb.InternalMessage) SentMessage

NewSentMessage creates a SentMessage from an internal message. It extracts the amount, Lamport time, and forward fees from the internal message to create a complete SentMessage representation.

func (*SentMessage) Dump 

func (m *SentMessage) Dump() string

func (SentMessage) MapToReceivedMessageIfMatches 

func (m SentMessage) MapToReceivedMessageIfMatches(rTX *tlb.Transaction) (*ReceivedMessage, error)

MapToReceivedMessageIfMatches checks if a transaction corresponds to the reception of this sent message and returns a ReceivedMessage if there's a match. It validates that the transaction contains an internal message and that the message details (addresses, Lamport time) match the originally sent message.

Returns nil if the transaction doesn't match this sent message, or an error if the transaction cannot be processed properly.

TODO: This matching could be more efficient with proper indexing by recipient address or other identifiers.

func (SentMessage) MatchesReceived 

func (m SentMessage) MatchesReceived(incomingMessage *tlb.InternalMessage) bool

MatchesReceived verifies if an incoming message corresponds to this originally sent message by comparing source address, destination address, and creation Lamport time. This is used to track the lifecycle of messages across the TON blockchain network.

Implementation note: This message uses explicit boolean logic rather than early returns to facilitate debugging and verification of matching criteria.

type SignedAPIClient 

type SignedAPIClient struct {
	Client ton.APIClientWrapped
	Wallet wallet.Wallet
}

SignedAPIClient provides a high-level interface for interacting with the TON blockchain. It wraps the low-level TON API client and wallet functionality to provide convenient messages for sending transactions, deploying contracts, and monitoring message flows.

func NewSignedAPIClient 

func NewSignedAPIClient(client ton.APIClientWrapped, wallet wallet.Wallet) SignedAPIClient

func (*SignedAPIClient) SendAndWaitForTrace 

func (c *SignedAPIClient) SendAndWaitForTrace(ctx context.Context, dstAddr address.Address, messageToSend *wallet.Message) (*ReceivedMessage, error)

SendAndWaitForTrace sends a transaction to the specified address and waits for the complete execution trace, including all outgoing messages and their subsequent outgoing messages recursively. It ensures that the entire message cascade has been processed and finalized before returning.

The message returns the resulting message in a Finalized state, meaning all outgoing messages have been confirmed and processed.

func (*SignedAPIClient) SendWaitTransaction 

func (c *SignedAPIClient) SendWaitTransaction(ctx context.Context, dstAddr address.Address, messageToSend *wallet.Message) (*ReceivedMessage, *ton.BlockIDExt, error)

SendWaitTransaction sends a transaction to the specified address and waits for it to be confirmed on the blockchain. It returns the resulting ReceivedMessage with outgoing messages (if any) and the block sequence number where the transaction was included.

This message only waits for the initial transaction confirmation, not for any outgoing messages to be processed. Use SendAndWaitForTrace for complete trace waiting.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.