types

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package types defines shared types for the E2E test framework.

Package types defines shared types for the E2E test framework.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClientHandle 

type ClientHandle struct {
	// contains filtered or unexported fields
}

ClientHandle wraps a traffic generation client and adds payer convenience methods for balance queries and deposit/withdrawal operations.

NOTE: In the current e2e framework, clients publish directly to nodes and sign their own payer envelopes — making them act as both client AND payer. In production, the gateway is the actual payer; the client just sends messages through a gateway. The payer methods here exist for testing direct-publish scenarios only.

func (*ClientHandle) Address 

func (h *ClientHandle) Address() common.Address

Address returns the Ethereum address derived from this client's payer key. In the current e2e framework this is the address that gets charged in the PayerRegistry when publishing directly to a node. In production, the gateway's address would be charged instead.

func (*ClientHandle) CancelWithdrawal 

func (h *ClientHandle) CancelWithdrawal(ctx context.Context) error

CancelWithdrawal cancels a pending withdrawal from the PayerRegistry for this client.

func (*ClientHandle) Deposit 

func (h *ClientHandle) Deposit(ctx context.Context, amount *big.Int) error

Deposit mints fee tokens and deposits them into the PayerRegistry for this client's payer address. Handles the full flow: mint → wrap → approve → deposit.

func (*ClientHandle) FinalizeWithdrawal 

func (h *ClientHandle) FinalizeWithdrawal(
	ctx context.Context,
	recipient common.Address,
) error

FinalizeWithdrawal finalizes a pending withdrawal, transferring funds to the recipient.

func (*ClientHandle) GenerateTraffic 

func (h *ClientHandle) GenerateTraffic(
	ctx context.Context,
	opts client.TrafficOptions,
) *client.TrafficGenerator

GenerateTraffic starts background traffic generation.

func (*ClientHandle) GetFeeTokenBalance 

func (h *ClientHandle) GetFeeTokenBalance(ctx context.Context) (*big.Int, error)

GetFeeTokenBalance returns the fee token (xUSD) balance for this client's address.

func (*ClientHandle) GetGasBalance 

func (h *ClientHandle) GetGasBalance(ctx context.Context) (*big.Int, error)

GetGasBalance returns the native ETH balance for this client's address.

func (*ClientHandle) GetPayerBalance 

func (h *ClientHandle) GetPayerBalance(ctx context.Context) (*big.Int, error)

GetPayerBalance returns this client's balance in the PayerRegistry.

func (*ClientHandle) NodeID 

func (h *ClientHandle) NodeID() uint32

NodeID returns the on-chain nodeID of the node this client publishes to.

func (*ClientHandle) PayerAddress 

func (h *ClientHandle) PayerAddress() string

PayerAddress returns the hex-encoded Ethereum address for this client's payer key. Convenience wrapper around Address().Hex() for use with string-based assertions.

func (*ClientHandle) PublishEnvelopes 

func (h *ClientHandle) PublishEnvelopes(ctx context.Context, count uint) error

PublishEnvelopes publishes the specified number of envelopes to the target node.

func (*ClientHandle) RequestWithdrawal 

func (h *ClientHandle) RequestWithdrawal(ctx context.Context, amount *big.Int) error

RequestWithdrawal requests a withdrawal from the PayerRegistry for this client.

func (*ClientHandle) Stop 

func (h *ClientHandle) Stop()

Stop stops any active background traffic generation.

type ClientOption 

type ClientOption func(*clientConfig)

ClientOption configures optional parameters for NewClient.

func WithClientName 

func WithClientName(name string) ClientOption

WithClientName sets a custom name for the client. By default, clients are named after their target nodeID (e.g. "100"). Use this when creating multiple clients for the same node with different payer keys.

Example: 

env.NewClient(100, types.WithClientName("payer-alice"), types.WithPayerKey(aliceKey))
env.ClientByName("payer-alice").PublishEnvelopes(ctx, 10)

func WithPayerKey 

func WithPayerKey(key string) ClientOption

WithPayerKey overrides the default payer key (keys.ClientKey) for this client. Use this to generate traffic from distinct payer addresses, allowing tests to verify per-payer attribution via GetUnsettledUsage.

Generate additional payer keys with env.Keys.NextClientKey(ctx).

type Config 

type Config struct {
	ChainImage   string
	XmtpdImage   string
	GatewayImage string
	CLIImage     string
	TestFilter   []string
	OutputFormat string
}

Config holds the configuration for an E2E test run.

type Environment 

type Environment struct {
	// ID is the unique identifier for this environment.
	ID string
	// Logger is the structured logger for this test run.
	Logger *zap.Logger
	// Config holds the test run configuration.
	Config Config
	// Chain provides access to the Anvil blockchain used for on-chain operations.
	Chain *chain.Chain
	// Chaos is the toxiproxy controller for injecting network faults.
	Chaos *chaos.Controller
	// Keys manages private key allocation across roles (admin, client, node, gateway).
	Keys *keys.Manager
	// Network is the Docker network name shared by all containers.
	Network string

	// Contracts provides read-only access to on-chain state (e.g. payer reports).
	// Initialized by the runner after the chain starts.
	Contracts *chain.Contracts

	Redis testcontainers.Container
	// contains filtered or unexported fields
}

Environment is the central context for an E2E test. It provides access to all infrastructure (nodes, gateways, chain, chaos) and handles for interacting with them. The runner creates a fresh environment for each test.

func (*Environment) AddGateway 

func (e *Environment) AddGateway(ctx context.Context, opts ...GatewayOption) error

AddGateway starts a new gateway container. Gateways are indexed 0, 1, 2, ... in creation order. The alias is auto-generated as "gateway-{index}" unless overridden with WithGatewayAlias.

After AddGateway returns, the gateway is accessible via env.Gateway(index).

func (*Environment) AddNode 

func (e *Environment) AddNode(ctx context.Context, opts ...NodeOption) error

AddNode registers a new node on-chain and starts its container. The node gets the next available nodeID (100, 200, 300, ...) from the NodeRegistry contract. The alias is auto-generated as "node-{nodeID}".

After AddNode returns, the node is accessible via env.Node(nodeID).

func (*Environment) AddNodeToCanonicalNetwork 

func (e *Environment) AddNodeToCanonicalNetwork(ctx context.Context, nodeID uint32) error

AddNodeToCanonicalNetwork adds a node to the canonical network by its node ID.

func (*Environment) AddRates 

func (e *Environment) AddRates(ctx context.Context, cfg RatesConfig) error

AddRates adds a new rate entry to the on-chain rate registry via xmtpd-cli. Nodes will pick up the new rates on their next registry refresh cycle (controlled by XMTPD_SETTLEMENT_CHAIN_RATE_REGISTRY_REFRESH_INTERVAL).

func (*Environment) CancelPayerWithdrawal 

func (e *Environment) CancelPayerWithdrawal(
	ctx context.Context,
	payerPrivateKey string,
) error

CancelPayerWithdrawal cancels a pending withdrawal from the PayerRegistry. Must be called with the payer's private key.

func (*Environment) ClaimFromDistributionManager 

func (e *Environment) ClaimFromDistributionManager(
	ctx context.Context,
	nodeOwnerKey string,
	nodeID uint32,
	originatorNodeIDs []uint32,
	payerReportIndices []*big.Int,
) error

ClaimFromDistributionManager claims earned fees for a node from the DistributionManager. Must be called with the node owner's private key.

func (*Environment) Cleanup 

func (e *Environment) Cleanup(ctx context.Context) error

func (*Environment) Client 

func (e *Environment) Client(nodeID uint32) *ClientHandle

Client returns the ClientHandle bound to the node with the given nodeID. The default client is the one created without WithClientName (named after the nodeID). Panics if no default client for that nodeID exists.

Example: 

env.Client(100).PublishEnvelopes(ctx, 10)
env.Client(100).Deposit(ctx, amount)
env.Client(100).GetPayerBalance(ctx)
env.Client(100).Stop()

func (*Environment) ClientByName 

func (e *Environment) ClientByName(name string) *ClientHandle

ClientByName returns the ClientHandle registered with the given name. Panics if no client with that name exists.

Example: 

env.ClientByName("alice").PublishEnvelopes(ctx, 10)
env.ClientByName("alice").Address() // Ethereum address for assertions

func (*Environment) Clients 

func (e *Environment) Clients() []*ClientHandle

Clients returns all registered client handles.

func (*Environment) DepositPayer 

func (e *Environment) DepositPayer(
	ctx context.Context,
	payer common.Address,
	amount *big.Int,
) error

DepositPayer deposits funds into the PayerRegistry for a given payer address. The deposit is made by the admin signer.

func (*Environment) FinalizePayerWithdrawal 

func (e *Environment) FinalizePayerWithdrawal(
	ctx context.Context,
	payerPrivateKey string,
	recipient common.Address,
) error

FinalizePayerWithdrawal finalizes a pending withdrawal from the PayerRegistry, transferring funds to the given recipient address. Must be called with the payer's private key.

func (*Environment) FundPayer 

func (e *Environment) FundPayer(
	ctx context.Context,
	payer common.Address,
	amount *big.Int,
) error

FundPayer mints fee tokens and deposits them into the PayerRegistry for the given payer address. Handles the full flow: mint underlying → wrap → approve → deposit.

func (*Environment) Gateway 

func (e *Environment) Gateway(index int) *GatewayHandle

Gateway returns the GatewayHandle at the given creation index (0, 1, 2, ...). Panics if no gateway with that index exists.

Example: 

env.Gateway(0).AddLatency(ctx, 500)
env.Gateway(1).Stop(ctx)

func (*Environment) Gateways 

func (e *Environment) Gateways() []*GatewayHandle

Gateways returns all registered gateway handles in creation order.

func (*Environment) GetDistributionManagerOwedFees 

func (e *Environment) GetDistributionManagerOwedFees(
	ctx context.Context,
	nodeID uint32,
) (*big.Int, error)

GetDistributionManagerOwedFees returns the owed fees for a given node.

func (*Environment) GetFeeTokenBalance 

func (e *Environment) GetFeeTokenBalance(
	ctx context.Context,
	addr common.Address,
) (*big.Int, error)

GetFeeTokenBalance returns the fee token (xUSD) balance for the given address.

func (*Environment) GetGasBalance 

func (e *Environment) GetGasBalance(
	ctx context.Context,
	addr common.Address,
) (*big.Int, error)

GetGasBalance returns the native ETH balance for the given address.

func (*Environment) GetPayerBalance 

func (e *Environment) GetPayerBalance(
	ctx context.Context,
	payer common.Address,
) (*big.Int, error)

GetPayerBalance returns the payer's balance in the PayerRegistry.

func (*Environment) GetPayerRegistryExcess 

func (e *Environment) GetPayerRegistryExcess(ctx context.Context) (*big.Int, error)

GetPayerRegistryExcess returns the current excess balance in the PayerRegistry.

func (*Environment) MintFeeToken 

func (e *Environment) MintFeeToken(ctx context.Context, amount *big.Int) error

MintFeeToken mints mock underlying tokens to the admin, wraps them into fee tokens (xUSD), and returns the amount minted. This is only available on anvil.

func (*Environment) NewClient 

func (e *Environment) NewClient(nodeID uint32, opts ...ClientOption) error

NewClient creates a traffic generation client bound to the node with the given nodeID. By default, the client uses keys.ClientKey() as the payer key and is named after the nodeID (e.g. "100"). Use ClientOption functions to customize.

Creating a client with the same name as an existing client replaces it (stopping its traffic first).

Use WithPayerKey to specify a custom payer identity for this client. By default, all clients share keys.ClientKey() (anvil account 1).

Example: 

env.NewClient(100)                                                    // default payer
env.NewClient(100, types.WithClientName("alice"), types.WithPayerKey(aliceKey)) // custom payer

func (*Environment) Node 

func (e *Environment) Node(nodeID uint32) *NodeHandle

Node returns the NodeHandle for the node with the given on-chain nodeID. Panics if no node with that ID exists — use this after AddNode has succeeded.

Example: 

env.Node(100).AddLatency(ctx, 500)
env.Node(200).Stop(ctx)
env.Node(100).WaitForEnvelopes(ctx, 10)

func (*Environment) Nodes 

func (e *Environment) Nodes() []*NodeHandle

Nodes returns all registered node handles in creation order.

func (*Environment) Observer 

func (e *Environment) Observer() *observe.Observer

Observer returns the database observer for direct queries when needed. Prefer using NodeHandle observer methods (e.g. env.Node(100).GetEnvelopeCount) which automatically provide the node's connection string.

func (*Environment) RemoveNodeFromCanonicalNetwork 

func (e *Environment) RemoveNodeFromCanonicalNetwork(ctx context.Context, nodeID uint32) error

RemoveNodeFromCanonicalNetwork removes a node from the canonical network by its node ID.

func (*Environment) RequestPayerWithdrawal 

func (e *Environment) RequestPayerWithdrawal(
	ctx context.Context,
	payerPrivateKey string,
	amount *big.Int,
) error

RequestPayerWithdrawal requests a withdrawal from the PayerRegistry. Must be called with the payer's private key since only the payer can request withdrawals.

func (*Environment) SendExcessToFeeDistributor 

func (e *Environment) SendExcessToFeeDistributor(ctx context.Context) error

SendExcessToFeeDistributor moves excess funds from PayerRegistry to the DistributionManager.

func (*Environment) SetCleanupFunc 

func (e *Environment) SetCleanupFunc(fn func(ctx context.Context) error)

func (*Environment) SetObserver 

func (e *Environment) SetObserver(obs *observe.Observer)

SetObserver sets the database observer. Called by the runner during environment setup.

func (*Environment) SetTestingT 

func (e *Environment) SetTestingT(t *TestingT)

SetTestingT sets the TestingT adapter for this environment. Called by the runner before each test — test authors should not call this directly.

func (*Environment) T 

func (e *Environment) T() *TestingT

T returns the TestingT adapter for use with testify's require and assert packages. The runner injects this automatically before each test run.

Example: 

require := require.New(env.T())
require.NoError(env.AddNode(ctx))

func (*Environment) UpdateRates 

func (e *Environment) UpdateRates(ctx context.Context, opts RateOptions) error

UpdateRates adds new rates to the RateRegistry.

func (*Environment) WithdrawFromDistributionManager 

func (e *Environment) WithdrawFromDistributionManager(
	ctx context.Context,
	nodeOwnerKey string,
	nodeID uint32,
) error

WithdrawFromDistributionManager withdraws claimed fees for a node from the DistributionManager. Must be called with the node owner's private key. The recipient defaults to the node owner's address.

type GatewayHandle 

type GatewayHandle struct {
	// contains filtered or unexported fields
}

GatewayHandle provides a fluent API for interacting with an xmtpd gateway. It wraps the underlying gateway container and composes lifecycle management and chaos injection into a single addressable handle.

Gateways are addressed by their creation index (0, 1, 2, ...): 

env.Gateway(0).AddLatency(ctx, 500)
env.Gateway(1).Stop(ctx)

func (*GatewayHandle) AddBandwidthLimit 

func (h *GatewayHandle) AddBandwidthLimit(ctx context.Context, kbps int) error

AddBandwidthLimit restricts the gateway's network throughput to the specified rate in KB/s.

func (*GatewayHandle) AddConnectionReset 

func (h *GatewayHandle) AddConnectionReset(ctx context.Context, timeoutMs int) error

AddConnectionReset simulates TCP connection resets (RST) on the gateway's connections. Connections are reset after the specified timeout in milliseconds.

func (*GatewayHandle) AddLatency 

func (h *GatewayHandle) AddLatency(ctx context.Context, ms int) error

AddLatency injects a network latency toxic on this gateway. All connections to/from the gateway will experience the specified delay in milliseconds.

func (*GatewayHandle) AddTimeout 

func (h *GatewayHandle) AddTimeout(ctx context.Context, timeoutMs int) error

AddTimeout blocks all data and closes connections after the specified timeout. If timeoutMs is 0, data is dropped indefinitely without closing the connection, effectively simulating a network partition (black hole).

func (*GatewayHandle) Address 

func (h *GatewayHandle) Address() common.Address

Address returns the Ethereum address derived from this gateway's signer key. This is the gateway's payer address on-chain — the address that gets charged in the PayerRegistry when the gateway wraps client messages into payer envelopes.

func (*GatewayHandle) Alias 

func (h *GatewayHandle) Alias() string

Alias returns the container's network alias (e.g. "gateway-0").

func (*GatewayHandle) CancelWithdrawal 

func (h *GatewayHandle) CancelWithdrawal(ctx context.Context) error

CancelWithdrawal cancels a pending withdrawal from the PayerRegistry for this gateway.

func (*GatewayHandle) Deposit 

func (h *GatewayHandle) Deposit(ctx context.Context, amount *big.Int) error

Deposit mints fee tokens and deposits them into the PayerRegistry for this gateway's payer address. Handles the full flow: mint → wrap → approve → deposit.

func (*GatewayHandle) DisableProxy 

func (h *GatewayHandle) DisableProxy(ctx context.Context) error

DisableProxy completely disables this gateway's proxy, refusing all connections.

func (*GatewayHandle) EnableProxy 

func (h *GatewayHandle) EnableProxy(ctx context.Context) error

EnableProxy re-enables this gateway's proxy after it was disabled.

func (*GatewayHandle) Endpoint 

func (h *GatewayHandle) Endpoint() string

Endpoint returns the internal network address for this gateway (e.g. "http://gateway-0:5050").

func (*GatewayHandle) FinalizeWithdrawal 

func (h *GatewayHandle) FinalizeWithdrawal(ctx context.Context, recipient common.Address) error

FinalizeWithdrawal finalizes a pending withdrawal, transferring funds to the recipient.

func (*GatewayHandle) GetFeeTokenBalance 

func (h *GatewayHandle) GetFeeTokenBalance(ctx context.Context) (*big.Int, error)

GetFeeTokenBalance returns the fee token (xUSD) balance for this gateway's address.

func (*GatewayHandle) GetGasBalance 

func (h *GatewayHandle) GetGasBalance(ctx context.Context) (*big.Int, error)

GetGasBalance returns the native ETH balance for this gateway's address.

func (*GatewayHandle) GetPayerBalance 

func (h *GatewayHandle) GetPayerBalance(ctx context.Context) (*big.Int, error)

GetPayerBalance returns this gateway's balance in the PayerRegistry.

func (*GatewayHandle) Index 

func (h *GatewayHandle) Index() int

Index returns the gateway's creation index (0, 1, 2, ...).

func (*GatewayHandle) RemoveAllToxics 

func (h *GatewayHandle) RemoveAllToxics(ctx context.Context) error

RemoveAllToxics removes all active toxics from this gateway, restoring normal network conditions.

func (*GatewayHandle) RequestWithdrawal 

func (h *GatewayHandle) RequestWithdrawal(ctx context.Context, amount *big.Int) error

RequestWithdrawal requests a withdrawal from the PayerRegistry for this gateway.

func (*GatewayHandle) Stop 

func (h *GatewayHandle) Stop(ctx context.Context) error

Stop terminates the gateway's container.

type GatewayOption 

type GatewayOption func(*gatewayConfig)

GatewayOption configures optional parameters for AddGateway.

func WithGatewayAlias 

func WithGatewayAlias(alias string) GatewayOption

WithGatewayAlias overrides the auto-generated container alias for a gateway. By default, aliases are "gateway-0", "gateway-1", etc.

func WithGatewayEnvVars 

func WithGatewayEnvVars(vars map[string]string) GatewayOption

WithGatewayEnvVars sets additional environment variables on the gateway container.

func WithGatewayImage 

func WithGatewayImage(image string) GatewayOption

WithGatewayImage overrides the default gateway Docker image for this gateway. Use this to test a specific version or a locally built image.

type NodeHandle 

type NodeHandle struct {
	// contains filtered or unexported fields
}

NodeHandle provides a fluent API for interacting with an xmtpd node. It wraps the underlying node container and composes lifecycle management, chaos injection, and database observation into a single addressable handle.

Nodes are addressed by their on-chain nodeID (100, 200, 300, ...): 

env.Node(100).AddLatency(ctx, 500)
env.Node(200).Stop(ctx)
env.Node(100).WaitForEnvelopes(ctx, 10)

func (*NodeHandle) AddBandwidthLimit 

func (h *NodeHandle) AddBandwidthLimit(ctx context.Context, kbps int) error

AddBandwidthLimit restricts the node's network throughput to the specified rate in KB/s.

func (*NodeHandle) AddConnectionReset 

func (h *NodeHandle) AddConnectionReset(ctx context.Context, timeoutMs int) error

AddConnectionReset simulates TCP connection resets (RST) on the node's connections. Connections are reset after the specified timeout in milliseconds.

func (*NodeHandle) AddLatency 

func (h *NodeHandle) AddLatency(ctx context.Context, ms int) error

AddLatency injects a network latency toxic on this node. All connections to/from the node will experience the specified delay in milliseconds.

func (*NodeHandle) AddTimeout 

func (h *NodeHandle) AddTimeout(ctx context.Context, timeoutMs int) error

AddTimeout blocks all data and closes connections after the specified timeout. If timeoutMs is 0, data is dropped indefinitely without closing the connection, effectively simulating a network partition (black hole).

func (*NodeHandle) AddToCanonicalNetwork 

func (h *NodeHandle) AddToCanonicalNetwork(ctx context.Context) error

AddToCanonicalNetwork adds this node to the on-chain canonical network, allowing it to participate in replication and consensus.

func (*NodeHandle) Address 

func (h *NodeHandle) Address() common.Address

Address returns the Ethereum address derived from this node's signer key. This is the node owner's address used for on-chain operations and fee distribution.

func (*NodeHandle) Alias 

func (h *NodeHandle) Alias() string

Alias returns the container's network alias (e.g. "node-100").

func (*NodeHandle) DBConnectionString 

func (h *NodeHandle) DBConnectionString() string

DBConnectionString returns the Postgres connection string for this node's database.

func (*NodeHandle) DisableProxy 

func (h *NodeHandle) DisableProxy(ctx context.Context) error

DisableProxy completely disables this node's proxy, refusing all connections. This is a stronger isolation than toxics — no data flows at all.

func (*NodeHandle) EnableProxy 

func (h *NodeHandle) EnableProxy(ctx context.Context) error

EnableProxy re-enables this node's proxy after it was disabled.

func (*NodeHandle) Endpoint 

func (h *NodeHandle) Endpoint() string

Endpoint returns the host-accessible gRPC address (e.g. "http://localhost:XXXXX"). Use this to create clients that publish to this node.

func (*NodeHandle) GetEnvelopeCount 

func (h *NodeHandle) GetEnvelopeCount(ctx context.Context) (int64, error)

GetEnvelopeCount returns the total number of envelopes stored in this node's database.

func (*NodeHandle) GetFeeTokenBalance 

func (h *NodeHandle) GetFeeTokenBalance(ctx context.Context) (*big.Int, error)

GetFeeTokenBalance returns the fee token (xUSD) balance for this node's owner address.

func (*NodeHandle) GetGasBalance 

func (h *NodeHandle) GetGasBalance(ctx context.Context) (*big.Int, error)

GetGasBalance returns the native ETH balance for this node's owner address.

func (*NodeHandle) GetNodeInfo 

func (h *NodeHandle) GetNodeInfo(ctx context.Context) (int32, error)

GetNodeInfo returns the node_id stored in this node's database.

func (*NodeHandle) GetPayerReportCount 

func (h *NodeHandle) GetPayerReportCount(ctx context.Context) (int64, error)

GetPayerReportCount returns the total number of payer reports in this node's database.

func (*NodeHandle) GetPayerReportStatusCounts 

func (h *NodeHandle) GetPayerReportStatusCounts(
	ctx context.Context,
) (*observe.PayerReportStatusCounts, error)

GetPayerReportStatusCounts returns a breakdown of payer report statuses (attestation and submission) from this node's database.

func (*NodeHandle) GetSettledPayerReports 

func (h *NodeHandle) GetSettledPayerReports(
	ctx context.Context,
) ([]observe.SettledPayerReport, error)

GetSettledPayerReports returns settled payer reports with their originator node ID and submitted report index, needed for claiming from the DistributionManager.

func (*NodeHandle) GetStagedEnvelopeCount 

func (h *NodeHandle) GetStagedEnvelopeCount(ctx context.Context) (int64, error)

GetStagedEnvelopeCount returns the number of staged originator envelopes waiting to be processed in this node's database.

func (*NodeHandle) GetUnsettledUsage 

func (h *NodeHandle) GetUnsettledUsage(ctx context.Context) ([]observe.PayerUsageStats, error)

GetUnsettledUsage returns per-payer spending stats for unsettled usage from this node's database.

func (*NodeHandle) GetVectorClock 

func (h *NodeHandle) GetVectorClock(ctx context.Context) ([]observe.VectorClockEntry, error)

GetVectorClock returns the vector clock entries from this node's database, showing the latest sequence ID received from each originator node.

func (*NodeHandle) ID 

func (h *NodeHandle) ID() uint32

ID returns the on-chain nodeID assigned by the NodeRegistry contract.

func (*NodeHandle) RemoveAllToxics 

func (h *NodeHandle) RemoveAllToxics(ctx context.Context) error

RemoveAllToxics removes all active toxics from this node, restoring normal network conditions.

func (*NodeHandle) RemoveFromCanonicalNetwork 

func (h *NodeHandle) RemoveFromCanonicalNetwork(ctx context.Context) error

RemoveFromCanonicalNetwork removes this node from the on-chain canonical network. The node container keeps running but is excluded from the active set.

func (*NodeHandle) SignerKey 

func (h *NodeHandle) SignerKey() string

SignerKey returns the private key hex string used by this node for signing. This is also the key associated with the node's owner address on-chain.

func (*NodeHandle) Start 

func (h *NodeHandle) Start(ctx context.Context) error

Start restarts a previously stopped node by creating a new container with the same configuration. The node retains its nodeID and alias.

func (*NodeHandle) Stop 

func (h *NodeHandle) Stop(ctx context.Context) error

Stop terminates the node's container. The node can be restarted with Start.

func (*NodeHandle) WaitForEnvelopes 

func (h *NodeHandle) WaitForEnvelopes(ctx context.Context, minCount int64) error

WaitForEnvelopes polls this node's database until at least minCount envelopes are present, or the context is cancelled. Polls every 2 seconds.

func (*NodeHandle) WaitForPayerReports 

func (h *NodeHandle) WaitForPayerReports(
	ctx context.Context,
	checkFn func(*observe.PayerReportStatusCounts) bool,
	description string,
) error

WaitForPayerReports polls this node's database until the checkFn returns true for the current payer report status counts, or the context is cancelled. The description is used in timeout error messages for debugging.

type NodeOption 

type NodeOption func(*nodeConfig)

NodeOption configures optional parameters for AddNode.

func WithNodeEnvVars 

func WithNodeEnvVars(vars map[string]string) NodeOption

WithNodeEnvVars sets additional environment variables on the node container. These are merged with (and override) the default environment variables.

func WithNodeImage 

func WithNodeImage(image string) NodeOption

WithNodeImage overrides the default xmtpd Docker image for this node. Use this to test a specific version or a locally built image.

type RateOptions 

type RateOptions struct {
	MessageFee    int64
	StorageFee    int64
	CongestionFee int64
	TargetRate    uint64
	StartTime     uint64 // 0 = default (2h from now)
}

RateOptions holds the parameters for updating rates.

type RatesConfig 

type RatesConfig struct {
	// MessageFee in picodollars.
	MessageFee int64
	// StorageFee in picodollars.
	StorageFee int64
	// CongestionFee in picodollars.
	CongestionFee int64
	// TargetRatePerMinute is the target message rate.
	TargetRatePerMinute uint64
	// StartTime is the unix timestamp when rates take effect.
	// If zero, defaults to 10 seconds from now.
	StartTime uint64
}

RatesConfig holds the parameters for adding rates to the on-chain rate registry.

type Test 

type Test interface {
	// Name returns a short, unique identifier for the test (e.g. "smoke", "chaos-latency").
	Name() string
	// Description returns a human-readable summary of what the test verifies.
	Description() string
	// Run executes the test. Return nil on success or an error on failure.
	// Use require/assert with env.T() for assertions — FailNow panics are
	// caught by the runner and reported as test failures.
	Run(ctx context.Context, env *Environment) error
}

Test is the interface that all E2E tests must implement. The runner calls Run with a fully initialized environment. Tests use env.T() with testify's require/assert for assertions.

type TestFailedError 

type TestFailedError struct {
	Messages []string
}

TestFailedError is a sentinel error used by the TestingT adapter when FailNow() is called. The runner recovers this panic and reports the test as failed without crashing the process.

func (*TestFailedError) Error 

func (e *TestFailedError) Error() string

type TestingT 

type TestingT struct {
	// contains filtered or unexported fields
}

TestingT implements testify's TestingT interface so that require/assert work in E2E tests that run outside of `go test`.

Usage in tests: 

func (t *MyTest) Run(ctx context.Context, env *Environment) error {
    require := require.New(env.T())
    require.NoError(err)
}

The environment's T() is set automatically by the runner before each test. Errorf logs the failure message and marks the test as failed. FailNow panics with TestFailedError, which the runner recovers.

func NewTestingT 

func NewTestingT(logger *zap.Logger) *TestingT

NewTestingT creates a new TestingT adapter backed by the given logger.

func (*TestingT) Errorf 

func (t *TestingT) Errorf(format string, args ...any)

Errorf logs a test failure message and marks the test as failed. This satisfies the testify TestingT interface.

func (*TestingT) FailNow 

func (t *TestingT) FailNow()

FailNow marks the test as failed and aborts execution by panicking with a TestFailedError. The runner catches this panic and reports the test as a failure. This satisfies the testify TestingT interface.

func (*TestingT) Failed 

func (t *TestingT) Failed() bool

Failed reports whether the test has been marked as failed.

func (*TestingT) Messages 

func (t *TestingT) Messages() []string

Messages returns all failure messages recorded so far.

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.