Crate thruput_testkit 

A harness for writing multi-agent integration tests as ordinary application code.

A test builds a Scenario against an explicit NetworkConfig, hands it a set of Agents, and asserts on what they observe. Test scenarios are run in #[tokio::test] functions.

Each agent receives a deterministic native account derived from the scenario seed. Agents deploy contracts with explicit funding and optional initialization, call them, await receipts, and read chain state, in addition to coordinating with other agents off-chain and using the virtual clock and deterministic randomness.

use thruput_testkit::{Agent, DeployOptions, LocalNetworkConfig, NetworkConfig, Scenario};

let mut config = LocalNetworkConfig::default();
config.hog_devnode_binary = Some("/path/to/supporting/hog-devnode".into());
config.contract_artifact_directories.push("/path/to/built_contracts".into());
let scenario = Scenario::builder("counter-test")
    .network(NetworkConfig::local(config))
    .artifact("counter", "target/thruput/counter.rv32a")
    .build()
    .await?;

scenario.run_agents([Agent::new("alice", |mut ctx| async move {
    ctx.fund(1_000_000_000).await?; // 100 native tokens from the bootstrap faucet
    let deployed = ctx.deploy_artifact("counter", DeployOptions::funded(100_000_000)).await?;
    assert!(deployed.registered);
    Ok(())
})]).await?;
scenario.stop().await?;

Networks and accounts

NetworkConfig::existing attaches to a running node, NetworkConfig::local launches and owns an ephemeral hog-devnode, and NetworkConfig::offline runs agents with locally-derived accounts and no chain (for coordination/timing/messaging tests). Scenario::run_agents returns an error when any agent returns an error, so the ordinary .await? test path cannot silently ignore agent failures.

Before using a live network, the scenario checks that the endpoint is compatible and serves the network hash named in its runtime manifest, so nothing is signed for a different network.

The scenario owns its fixture accounts’ keys, derived from its seed; ScenarioBuilder::accounts sets how many there are. A local node receives only their public allocations, of LocalNetworkConfig::initial_account_tokens raw native token units each (100 native tokens by default). On an existing network the accounts start empty: fund them explicitly with AgentContext::fund or AgentContext::submit_fund.

Manual blocks and uncertain submissions

AgentContext::submit_fund, AgentContext::submit_deploy_artifact and the submit forms of calls return handles without waiting, for tests that drive blocks by hand (see BlockDriverConfig): await pending, produce a block, then await the receipt. Receipt waits are read-only.

Each submission reserves its nonce before dispatch. When a submission’s outcome is uncertain, the harness never resends it: the error retains the original transaction hash and exact signed bytes for reconciliation (TestkitError::Submission, or TestkitError::ReceiptWait for a wait that stopped), as does a SubmittedTransaction. In particular:

• A deployment is accepted only once its successful receipt matches the original hash and predicted address; until then TestkitError::UnverifiedDeployment retains both. A new request for the same artifact with different funding or initialization is refused (TestkitError::DeploymentRequestMismatch) until the retained attempt is resolved, and scheduler statuses never replay or discard it.
• Local funding is retained on the Network handle before it is sent. After an uncertain response, retry the same recipient and amount on that handle, and keep it alive during recovery; a changed amount is refused (TestkitError::FundingRequestMismatch). Conflicting or invalid funding evidence is kept inspectable in TestkitError::InvalidFundingEvidence or TestkitError::InvalidFundingResponse; it does not prove admission.

Typed calls

With thruput-sdk’s remote feature (typically on a dev-dependency), #[contract] generates an <Iface>Remote proxy for each interface. Bound to an agent’s Caller, each of its methods encodes the arguments and returns a prepared invocation: a ContractView for a method declared pure or readOnly, which awaiting simulates with the agent as msg.sender, or otherwise a ContractCall, which awaiting submits through the agent’s wallet. Either decodes the method’s return type. A method with no effect annotation gets the same proxy method as one declared stateChanging, so the annotation can be omitted; the omission is only visible in the contract’s spec, where the effect is recorded as undeclared.

mod counter {
    use thruput_sdk::contract;

    #[contract(version = "0.1.0")]
    pub trait Counter {
        /// Add `by` to the count, returning the new count.
        fn increment(&mut self, by: u64) -> u64;

        #[contract(effect = "readOnly")]
        fn get(&self) -> u64;
    }
}

use counter::CounterRemote;
use thruput_testkit::Agent;
use thruput_testkit::xdr::types::ContractAddress;

fn alice(address: ContractAddress) -> Agent {
    Agent::new("alice", move |ctx| async move {
        let counter = CounterRemote::new(ctx.caller().clone(), &address);
        let count = counter.increment(1).await?; // submitted
        assert_eq!(counter.get().await?, count); // simulated
        Ok(())
    })
}

See contract for receipts, deferred submission, and reads through methods without a declared effect, and Contract for calling a method by name when no interface crate is at hand.

Re-exports

pub use agent::Agent;

pub use agent::AgentContext;

pub use agent::AgentId;

pub use caller::Caller;

pub use clock::Clock;

pub use contract::Contract;

pub use contract::ContractCall;

pub use contract::ContractView;

pub use contract::SubmittedContractCall;

pub use contract::entrypoint_id;

pub use contract::try_entrypoint_id;

pub use error::AgentFailure;

pub use error::AgentFailures;

pub use error::Result;

pub use error::TestkitError;

pub use mailbox::Envelope;

pub use mailbox::Mailbox;

pub use mailbox::Message;

pub use network::LocalNetworkConfig;

pub use network::Network;

pub use network::NetworkConfig;

pub use network::SubmittedTransaction;

pub use rng::AgentRng;

pub use scenario::AgentOutcome;

pub use scenario::Scenario;

pub use scenario::ScenarioBuilder;

pub use scenario::ScenarioReport;

pub use thruput_json_rpc_types as rpc_types;

pub use thruput_xdr as xdr;

pub use xdrs;

Modules

agent

Agents and the context the harness hands them.

caller

A cloneable handle for submitting transactions from an agent’s account.

clock

Virtual clock owned by the harness.

contract

Contract method helpers.

error

Error type for the test harness.

mailbox

Off-chain messaging between agents.

network

The network a scenario runs against: how to reach it (NetworkConfig) and the live handle agents use (Network).

rng

Deterministic per-agent randomness.

scenario

Scenario builder, runner, and result types.

Structs

BlockDriverConfig

Local block production policy used by the hogd-dev supervisor.

ContractEntrypointID

8-byte identifier for a contract method (entrypoint).

DeployOptions

Explicit funding and optional initialization in the deployment transaction.

Deployed

Result of a contract deploy.

ProducedBlock

Metadata returned after the scheduler commits a manually-produced block.

SubmittedDeploy

A submitted deployment whose receipt can be awaited after manual block production.

WalletInitCall

Optional initialization of the newly deployed contract, called by the wallet. A failed invocation rolls back funding and deployment; return bytes are discarded.

Enums

ArtifactKind

Which artifact format a contract binary is in.

BlockDriverMode

Block driver wake mode.

BlockProductionError

Errors returned while manually producing a local block.

LogLevel

Log verbosity level for hog-devnode

Functions

init_tracing

Install a stderr tracing subscriber that prints forwarded hog-devnode logs and supervisor diagnostics.