Cardinal
API Reference
Messages

Messages

Messages enable Cardinal to handle state mutating requests in systems.

package msg
 
import "pkg.world.dev/world-engine/cardinal"
 
 
// AttackInput is the input for the Attack message.
type AttackInput struct {
	TargetID uint64
}
 
// AttackResult is the result of the Attack message.
type AttackResult struct {
	Success bool
}
 
// Attack is an attack message.
var Attack = cardinal.NewMessageType[AttackInput, AttackResult]("attack")

NewMessageType

NewMessageType creates a new MessageType. MessageTypes wrap around an Input and Result type. The Input specifies the input for a message and the Result represents the result of the message's execution.

The given name of the message will be used to generate a message endpoint. For example, if NewMessageType is called with "attack", the http endpoint /tx/game/attack will be created. The "/tx" prefix in this context is short for "Transaction". A Transaction is the combination of a cardinal Message along with a cryptographic signature.

func NewMessageType[Input, Result any](name string) *MessageType[Input, Result]

Type Parameters

Type ParameterTypeDescription
InputanyThe input type of the message.
ResultanyThe result type of the message.

Parameters

ParameterTypeDescription
namestringThe name of the message.

Return Value

TypeDescription
*MessageType[Msg, Result]A pointer to a new instance of MessageType[Msg, Result].

NewMessageTypeWithEVMSupport

NewMessageTypeWithEVMSupport creates a new MessageType with EVM support. This adds additional configuration to the message which enables it to handle requests originating from EVM smart contracts.

⚠️

Not all Go types are supported when using EVM supported messages. Read More

func NewMessageTypeWithEVMSupport[Msg, Result any](name string) *MessageType[Msg, Result]

Type Parameters

Type ParameterTypeDescription
InputanyThe input type of the message.
ResultanyThe result type of the message.

Parameters

ParameterTypeDescription
namestringThe name of the message.

Return Value

TypeDescription
*MessageType[Input, Result]A pointer to a new instance of MessageType[Input, Result].

Methods

AddError

AddError adds an error to a specific message that signifies an issue has occurred with the message's execution.

func (t *MessageType[Msg, Result]) AddError(worldCtx WorldContext, hash TxHash, err error)

Example

Attack.AddError(
	worldCtx,
	txHash,
	errors.New("attack failed"),
)

Parameters

ParameterTypeDescription
worldCtxWorldContextA WorldContext object passed in to your System definition
hashTxHashThe hash of the transaction data.
errerrorThe error to be associated with the message.

SetResult

SetResult sets the result for a message's execution. SetResult requires the message type's output data structure for the result data.

func (t *MessageType[Input, Result]) SetResult(
	worldCtx WorldContext,
	hash TxHash,
	result Result,
)

Example

Attack.SetResult(worldCtx, txHash, AttackResult{Success: true})

Parameters

ParameterTypeDescription
worldCtxWorldContextA WorldContext object passed in to your System definition.
hashTxHashThe hash of the transaction data.
resultResultThe result to be associated with the message.

GetReceipt

GetReceipt gets the result and errors, if any, associated with a specific message type.

func (t *MessageType[Msg, Result]) GetReceipt(worldCtx WorldContext, hash TxHash) (r Result, errs []error, ok bool)

Example

result, errs, ok := Attack.GetReceipt(worldCtx, txHash)

Parameters

ParameterTypeDescription
worldCtxWorldContextA WorldContext object passed in to your System definition.
hashTxHashThe hash of the transaction data.

Return Values

TypeDescription
ResultThe result of the message associated with the transaction hash.
[]errorAny errors that may have occurred with the message associated with the transaction hash.
boolA boolean indicating if a receipt was found for the message associated with the transaction hash.

In

In is a method primarily used in Systems that retrieves all messages of the MessageType from the World's TransactionQueue.

func (t *MessageType[Msg, Result]) In(worldCtx WorldContext) []TxData[In]

Example

txs := AttackTx.In(worldCtx)
for _, tx := range txs {
	// ... do something with each msg
	msg := tx.Msg()
	hash := tx.Hash()
	txData := tx.Tx()
}

Parameters

ParameterTypeDescription
worldCtxWorldContextA WorldContext object passed in to your System

Return Value

TypeDescription
[]TxData[Msg]A slice of TxData - containing Transaction data and Message value.