out_actions

Module defining out actions.

This module provides structures and helpers for working with "out actions" generated by smart contracts. Out actions include sending messages, updating code, reserving currency, and changing libraries.

Examples:

// Retrieve actions after contract execution
val actions = testing.outActions();

// Check the first action
val firstAction = actions.at(0);
if (firstAction is TlbOutActionSendMessage) {
    println("Sending message with mode: {}", firstAction.mode);
}

// Get specific message body
val transfer = actions.getSendMessageBodyAt<Transfer>(0);
if (transfer != null) {
    println("Transferred: {:ton}", transfer.amount);
}

Definitions

`TlbOutList`

struct TlbOutList {
    /// Link to previous out-list node.
    prev: Cell<TlbOutList>
    /// Serialized out action stored in this node.
    action: TlbOutAction
}

Represents a node in the out list. This is an internal linked-list node, you should not use it directly.

prev is stored in the list node itself and points to the previous list node. It is not a field of any TlbOutAction* payload.

Source code

`TlbOutActionSendMessage`

struct (0x0ec3c86d) TlbOutActionSendMessage {
    /// Mode of the send message. See `SEND_MODE_*` constants.
    mode: uint8
    /// Message to send.
    ///
    /// To load the actual message, use [TlbOutActionSendMessage.loadMessage] method.
    outMsg: cell
}

Represents send message action.

Source code

`TlbOutActionSendMessage.loadMessage`

fun TlbOutActionSendMessage.loadMessage<Msg>(self): TlbMessageRelaxed<Msg>

Loads the message from the out message cell.

Note that you should provide the message type as a generic parameter.

If you want to access the body of the message, use TlbOutActionSendMessage.loadBody method.

Example:

val outActions = testing.outActions();
val action = outActions.at(0);
if (action is TlbOutActionSendMessage) {
    val message = action.loadMessage<IncreaseCounter>();
    val body = message.loadBody();
    println(body.increaseBy);
}

Source code

`TlbOutActionSendMessage.loadBody`

fun TlbOutActionSendMessage.loadBody<Msg>(self): Msg

Loads the body of the message.

Note that you should provide the message type as a generic parameter.

Example:

val outActions = testing.outActions();
val action = outActions.at(0);
if (action is TlbOutActionSendMessage) {
    val body = action.loadBody<IncreaseCounter>();
    println(body.increaseBy);
}

Source code

`TlbOutActionSendMessage.loadGenericMessage`

fun TlbOutActionSendMessage.loadGenericMessage(self): TlbMessageRelaxedGeneric

Loads the generic message from the out message cell. Unlike TlbOutActionSendMessage.loadMessage, this method does not require type of the message to load. Instead it loads the message with body as a slice. Use this method if don't know the type of the message.

Example:

val outActions = testing.outActions();
val action = outActions.at(0);
if (action is TlbOutActionSendMessage) {
    val message = action.loadGenericMessage();
    val opcode = message.loadOpcode();
    println(opcode);
}

Source code

`TlbOutActionSetCode`

struct (0xad4de08e) TlbOutActionSetCode {
    /// New code to set.
    newCode: cell
}

Represents set code action.

Source code

`TlbOutActionReserveCurrency`

struct (0x36e6b809) TlbOutActionReserveCurrency {
    /// Mode of the reserve currency. See `RESERVE_MODE_*` constants.
    mode: uint8
    /// Currency to reserve.
    currency: TlbCurrencyCollection
}

Represents reserve currency action.

Source code

`TlbOutActionChangeLibrary`

struct (0x26fa1dd4) TlbOutActionChangeLibrary {
    /// Mode of the change library.
    mode: uint7
    /// Library reference, either hash or cell reference.
    libref: TlbLibRef
}

Represents change library action.

Source code

`TlbLibRefHash`

struct (0b0) TlbLibRefHash {
    /// Hash of the library.
    libHash: bits256
}

Represents library reference as a hash.

Source code

`TlbLibRefRef`

struct (0b1) TlbLibRefRef {
    /// Cell reference to the library.
    library: cell
}

Represents library reference as a cell reference.

Source code

`TlbLibRef`

type TlbLibRef = TlbLibRefHash | TlbLibRefRef

Type alias for library reference used by TlbOutActionChangeLibrary.libref. Value is either a hash-only reference (TlbLibRefHash) or an in-cell library (TlbLibRefRef).

Source code

`TlbOutAction`

type TlbOutAction =
    | TlbOutActionSendMessage
    | TlbOutActionSetCode
    | TlbOutActionReserveCurrency
    | TlbOutActionChangeLibrary

Type alias for tagged union of all supported out action variants.

Source code

`TlbOutAction.kind`

fun TlbOutAction.kind(self): string

Returns the kind of the out action as a string.

Exact return values:

"send-message" for TlbOutActionSendMessage
"set-code" for TlbOutActionSetCode
"reserve-currency" for TlbOutActionReserveCurrency
"change-library" for TlbOutActionChangeLibrary

Source code

`OutActionList`

type OutActionList = array<Cell<TlbOutAction>>

Type alias for the out action list array.

To get the out actions, use testing.outActions method.

Source code

`OutActionList.at`

fun OutActionList.at(self, i: int): TlbOutAction

Returns the out action at the given index.

NOTE: this list is reversed, so the last action is at index 0.

Fails with Assert.fail if the stored tuple element cannot be decoded as TlbOutAction.

Example:

val outActions = testing.outActions();
val action = outActions.at(0);
println(action.kind());

Source code

`OutActionList.getSendMessageAt`

fun OutActionList.getSendMessageAt(self, i: int): TlbOutActionSendMessage?

Returns the send message action at the given index.

If the action is not a send message, returns null.

Example:

val outActions = testing.outActions();
val action = outActions.getSendMessageAt(0);
if (action != null) {
    println(action.mode);
}

Source code

`OutActionList.getSendMessageBodyAt`

fun OutActionList.getSendMessageBodyAt<Msg>(self, i: int): Msg?

Returns the body of the send message at the given index.

Note that you should provide the message type as a generic parameter.

If the action is not a send message, returns null. If the action is a send message but Msg does not match actual body type, this call throws (for example with exit code 63 from typed message decoding).

Example:

val outActions = testing.outActions();
val body = outActions.getSendMessageBodyAt<IncreaseCounter>(0);
if (body != null) {
    println(body.increaseBy);
}

Source code

`OutMessage.outActions`

fun OutMessage.outActions(self, mode: int): OutActionList

Returns the out actions for the message.

Source code

`Expectation<OutActionList>.toBeSendMessageAt`

fun Expectation<OutActionList>.toBeSendMessageAt<Msg>(self, index: int): void

Expect the out action at the given index to be a send message that can be loaded as TlbMessageRelaxed<Msg>.

Indexing is reverse-chronological (same as OutActionList.at): index 0 is the last produced action.

Example:

val outActions = testing.outActions();
expect(outActions).toBeSendMessageAt<IncreaseCounter>(0);

Note that you should provide the message type as a generic parameter.

This matcher validates action kind and typed message loading only. It does not call loadBody(), so it does not validate message body fields. For body-level checks, load and validate the body separately.

Failure diagnostics:

if the action is not a send message, assertion fails with index information;
if typed load fails with opcode mismatch (exit code 63), assertion includes expected type/prefix and actual opcode (plus known type name when available);
for other decode errors, assertion includes the decoder exit code.

Source code

out_actions

On this page