Build, Test, and Understand Stellar Trade Soroban Contracts

Introduction

Stellar Trade Contracts is a Soroban contract workspace for Stellar Trade, an open-source prediction-market prototype built on Stellar. The contracts govern how XLM enters a market pool, how participants reduce positions, and how resolved or cancelled markets distribute payouts and refunds.

The repository is designed for developers who need to build, test, review, or deploy the contracts behind the application. It includes the market contract as well as supporting token, referral, leaderboard, and integration-test crates.

Understand the workspace

The repository is organized into five main crates, each with a focused responsibility:

• prediction_market: Creates markets, accepts positions, reduces positions, handles resolver actions, calculates proportional claims, processes cancellation refunds, accounts for fees, and supports disputes and governance.
• stellar_trade_token: Provides the reward token with administrator controls, authorized minters, pause controls, and an optional supply cap. Fresh deployments use the name Stellar Trade and symbol STRD.
• referral_registry: Registers referrals, limits referral-chain depth, and distributes referral fees.
• leaderboard: Tracks participant points and win/loss records, applies score decay, and supports authorized reward minting.
• cross_contract_invariants: Tests accounting and behavior across the market, referral, leaderboard, and token contracts.

Set up the Rust workspace

The project pins Rust 1.91.0 and the wasm32v1-none target through rust-toolchain.toml. Install the toolchain and target specified by the repository before running the checks from the repository root.

Once the environment is ready, run the complete workspace test suite:

cargo test --workspace --all-features

Format checks verify that the source follows the project’s formatting rules:

cargo fmt --all -- --check

Run Clippy with warnings treated as errors to catch code-quality and correctness issues:

cargo clippy --workspace --all-features -- -D warnings

Build the prediction-market contract for WebAssembly with a release profile:

cargo build --release --target wasm32v1-none -p prediction_market

These commands correspond to the checks used by the repository’s GitHub Actions workflow. The workflow also builds WASM artifacts and runs cross-contract invariant tests for changes to the default branch and pull requests.

Follow the market lifecycle

1. Create a market

An authorized creator publishes a market question, category, and close time. Market creation is permissioned, so the caller must satisfy the authorization rules configured by the contract.

2. Place a position

A participant calls place_bet to stake XLM on either the YES or NO side. The contract applies configured fees and credits the participant’s selected side with the resulting position.

The position-reduction mechanism is not a peer-to-peer sale, an order book, or a short position. It is an operation on the participant’s existing recorded stake.

3. Reduce a position before closing

Before the market closes, a participant can call reduce_position to reduce an existing stake. The contract uses the participant’s recorded side and calculates the returned amount from the reduced stake and the retained fee rules.

Because the contract selects the side from the participant’s existing position, callers should not treat this operation as switching sides or trading with another participant.

4. Resolve the market

An authorized resolver submits the outcome after the market closes. The market contract then calculates proportional payouts for winning positions.

Resolution is permissioned. This workspace does not provide an automated oracle. External price or network data cannot settle a market unless an authorized resolver uses that information and submits the result.

5. Claim winnings or receive a cancellation refund

Participants claim proportional payouts through the contract after a market is resolved. Cancelled markets follow a separate refund path rather than the normal winning-position payout flow.

Resolver selection, resolution criteria, evidence, and dispute handling are important trust assumptions. Review these processes before relying on a deployed market.

Review accounting and safety properties

Before changing contract behavior, read the invariant matrix. It connects important accounting rules with the tests that protect them.

The matrix covers areas including:

• Fee conservation and market-level fee isolation.
• Bounds on proportional payouts.
• Cancellation behavior.
• Referral accounting.
• Reward supply tracking.
• Storage time-to-live handling.
• Emergency pause paths.

If you modify fees, rewards, payout formulas, or storage lifetimes, update the relevant regression and invariant tests at the same time. The cross_contract_invariants crate is especially useful when a change affects more than one contract.

Use the historical issue reports correctly

The issues/ directory contains historical security and correctness reports. Read issues/README.md to understand their context.

These reports document prior design risks. They should not be treated as proof that the contracts have been audited, nor as confirmation that every listed issue is still current. Use them as review input alongside the current source code, tests, and invariant matrix.

Prepare for deployment

Testnet deployments retain their historical contract IDs and token metadata. A fresh deployment creates new addresses and initializes STRD; it does not migrate existing holders or balances.

Before deploying, confirm all of the following:

• The target network.
• The contract IDs.
• The administrator identity.
• Fee settings.
• Resolver configuration.

Never commit secret keys, wallet recovery phrases, .deploy.env, deployment output, or local identity files to the repository.

For local frontend development and application-level deployment instructions, consult the application README.

Advanced development tips

Test cross-contract behavior

A change that appears local to one crate can affect referrals, rewards, leaderboard records, or token supply. Run the full workspace suite and the cross-contract invariant tests rather than relying only on a single crate’s unit tests.

Keep permission boundaries explicit

Market creation, resolution, token administration, minting, and other sensitive actions use authorization controls. When reviewing or extending a contract, verify which identities are allowed to perform each operation and how pause controls affect emergency behavior.

Review storage lifetime changes

Storage TTL handling is part of the project’s safety model. Any change to storage access patterns or lifetimes should be checked against the invariant matrix and covered by regression tests.

Validate release artifacts

Run formatting, Clippy, tests, and the release WASM build before publishing or deploying changes. Treat a clean local build as a development prerequisite, not as a substitute for reviewing configuration and deployment identities.

Conclusion

Stellar Trade Contracts provides the Soroban logic for creating prediction markets, recording YES and NO positions, reducing stakes, resolving outcomes, distributing proportional claims, and refunding cancelled markets. Its supporting crates add reward-token, referral, leaderboard, and integration functionality.

To work safely with the repository, begin with the pinned Rust environment, run all workspace checks, study the market lifecycle, and review the invariant matrix before changing accounting or storage behavior. During deployment, verify every permission and network setting and keep all secrets outside version control.