Struct AgentContext 

pub struct AgentContext { /* private fields */ }

Everything an agent needs to interact with the world.

The context is the only channel through which an agent touches the network, the clock, randomness, and other agents. Agents must not reach around it to raw I/O or std::time.

Chain operations take &self: they go through the agent’s Caller, which can also be cloned out to hold independently of the context. Only receiving messages and drawing randomness take &mut self, since those consume per-agent streams in order, along with artifact deployment and registration. Those treat an in-flight registration from the same agent as a retry of the same request, so overlapping requests from one agent must not be possible.

Implementations

impl AgentContext

pub fn address(&self) -> ContractAddress

The on-chain wallet address of this agent’s assigned account.

pub fn account_index(&self) -> u32

Index of this agent’s assigned account.

pub async fn deploy_artifact( &mut self, name: &str, options: DeployOptions<'_>, ) -> Result<Deployed>

Deploy an instance of a registered artifact, registering its binary once (on the first deploy of that artifact, in the same transaction) and deploying by hash thereafter. Awaits the receipt; fails if execution is not successful.

Requests from one agent cannot overlap, since a second request would be taken as a retry of the first:

let options = thruput_testkit::DeployOptions::funded(0);
let first = ctx.deploy_artifact("counter", options);
let second = ctx.deploy_artifact("counter", options);
let _ = (first.await, second.await);

pub async fn submit_deploy_artifact( &mut self, name: &str, options: DeployOptions<'_>, ) -> Result<SubmittedDeploy>

Submit an artifact deployment without waiting for its receipt.

Returns TestkitError::ArtifactRegistrationPending when another agent is registering the same artifact. The error carries that transaction’s hash so a manual scenario can produce its block and await its receipt before retrying this deployment. The error also retains signed bytes for explicit caller recovery. Scheduler statuses never replay or discard a retained attempt.

pub async fn register_artifact( &mut self, name: &str, options: DeployOptions<'_>, ) -> Result<Deployed>

Explicitly register an artifact’s binary, deploying its first instance in the same transaction. Prefer AgentContext::deploy_artifact unless a test needs to control when registration happens.

pub async fn submit_register_artifact( &mut self, name: &str, options: DeployOptions<'_>, ) -> Result<SubmittedDeploy>

Submit an explicit artifact registration without waiting for its receipt.

Returns TestkitError::ArtifactRegistrationPending when a registration transaction is already in flight.

pub async fn deploy_registered( &self, name: &str, options: DeployOptions<'_>, ) -> Result<Deployed>

Deploy an instance by hash only, without carrying the binary. The artifact must already be registered and committed, or the transaction fails. Prefer AgentContext::deploy_artifact unless a test is asserting on the hash-only path.

pub async fn submit_deploy_registered( &self, name: &str, options: DeployOptions<'_>, ) -> Result<SubmittedDeploy>

Submit a hash-only artifact deployment without waiting for its receipt.

pub fn contract_hash(&self, name: &str) -> Result<SHA256Hash>

The network identity (contract hash) of a registered artifact.

pub fn is_registered(&self, name: &str) -> Result<bool>

Whether the harness has observed this artifact registered this run.

pub async fn deploy( &self, artifact: &[u8], kind: ArtifactKind, options: DeployOptions<'_>, ) -> Result<Deployed>

Deploy raw contract bytes not held in the registry, awaiting the receipt. The binary is carried in every such transaction. Fails if execution is not successful.

pub async fn submit_deploy( &self, artifact: &[u8], _kind: ArtifactKind, options: DeployOptions<'_>, ) -> Result<SubmittedDeploy>

Submit a raw artifact deployment without waiting for its receipt.

pub async fn submit_fund(&self, amount: u128) -> Result<SubmittedTransaction>

Submit an exact raw native token transfer from the runtime’s bootstrap faucet. Existing-network fixtures start empty; local fixtures receive explicit genesis allocations. Retry uncertain local funding with the same amount on this scenario/network handle.

pub async fn fund(&self, amount: u128) -> Result<TransactionReceipt>

Fund this account explicitly and require a successful matching receipt. In manual mode, use submit_fund, produce a block, then await the receipt.

pub async fn call( &self, target: ContractAddress, entrypoint: ContractEntrypointID, calldata: &[u8], ) -> Result<TransactionReceipt>

Call a deployed contract method from this agent’s account, awaiting the receipt. The receipt is returned even when execution reverted.

pub async fn submit_call( &self, target: ContractAddress, entrypoint: ContractEntrypointID, calldata: &[u8], ) -> Result<SubmittedTransaction>

Submit a contract call without waiting for its receipt.

pub fn id(&self) -> &AgentId

This agent’s identity.

pub fn name(&self) -> &str

This agent’s name.

pub fn network(&self) -> &Network

Handle to the network the scenario is running against.

pub fn caller(&self) -> &Caller

This agent’s account bound to the network, for submitting transactions independently of the context. Clone it to keep it past the borrow.

pub fn clock(&self) -> &Clock

The scenario’s virtual clock.

pub fn rng(&mut self) -> &mut AgentRng

This agent’s deterministic random stream.

pub fn send<T>(&self, to: &str, msg: &T) -> Result<()>

where T: WriteXDR + ?Sized,

CXS-encode msg and send it to the agent named to.

pub async fn recv<T>(&mut self) -> Option<Result<Message<T>>>

where T: for<'r> ReadXDR<'r>,

Wait for the next inbound message, decoding its CXS payload as T.

Returns None once all peers finish; the inner Result is Err when the payload does not decode as T.

pub fn try_recv<T>(&mut self) -> Option<Result<Message<T>>>

where T: for<'r> ReadXDR<'r>,

Take a pending inbound message without waiting, decoding its payload as T.

pub async fn recv_from<T>(&mut self, from: &str) -> Option<Result<Message<T>>>

where T: for<'r> ReadXDR<'r>,

Wait for the next message from the agent named from, decoding its CXS payload as T.

Messages from other senders that arrive first are held for later recv / recv_from calls rather than dropped. Returns None once all peers finish without a matching message; the inner Result is Err when the payload does not decode as T.

pub fn try_recv_from<T>(&mut self, from: &str) -> Option<Result<Message<T>>>

where T: for<'r> ReadXDR<'r>,

Take a pending message from the agent named from without waiting, decoding its payload as T.

pub async fn recv_from_any<T>( &mut self, from: &[&str], ) -> Option<Result<Message<T>>>

where T: for<'r> ReadXDR<'r>,

Wait for the next message from any of the agents named in from, decoding its CXS payload as T. Message::from identifies which one.

Like recv_from, messages from senders outside the set are held for later calls rather than dropped.

pub fn try_recv_from_any<T>( &mut self, from: &[&str], ) -> Option<Result<Message<T>>>

where T: for<'r> ReadXDR<'r>,

Take a pending message from any of the agents named in from without waiting, decoding its payload as T.

Trait Implementations

impl AsRef<Caller> for AgentContext

fn as_ref(&self) -> &Caller

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for AgentContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.