Contracts

Tally deploys two groups of Soroban contracts:

• Tally's own round registry in contracts/round-registry, built with soroban-sdk 28.
• Thin wrappers around OpenZeppelin stellar-contracts v0.9.0 (df602b6) in ct/contracts: the confidential token, the verifier and the auditor registry, built with soroban-sdk 27.0.2 to match the version the vendored OpenZeppelin tree pins. The same directory holds bench-batch, a measurement-only contract.

All of them run on Stellar testnet only.

Current testnet deploymentCopy Anchor Link

From demo/deployment.testnet.json, deployed 2026-10-05 at ledger 5029204 against stellar-contracts v0.9.0 @ df602b613fbc4ae1e98ff62ba3caef671a370f65.

Auditor key id 0 is registered with public point:

x = 0x1fba511e82a3447a5a9b1d932fe51144a40b813284d8da8ab209afc7db10facc
y = 0x22b432a1fd14d70cbb46dabd3c5302dc3ca9b81e445c29fb6035b9d0171f3a50

The token's address-as-field value is 0x1309464167a95f0a2ff6b4db85a5fbc2d1c607e785597e1b28b592572fa9bf05.

Measurement-only contractsCopy Anchor Link

From ct/measurements.testnet.json. These are not part of the payout flow and never hold funds.

Retired deploymentsCopy Anchor Link

The August 2026 round registry CCKWYTHG…R3ES (soroban-sdk 26) and token CCDZ52D7…JYHD are retired and no longer used.

Round registryCopy Anchor Link

The round registry records which sender accounts count for a round (the lane set) and over what ledger window. It records nothing else. Source: contracts/round-registry/src/lib.rs.

It does not record individual transfers. Transfer.from and Transfer.to are topic-indexed, and the token emits the event on every confidential_transfer, so a donor enumerates a round's transfers directly from chain events. Recording transfers in the registry would let a funder simply leave one out.

FunctionsCopy Anchor Link

open_round(funder, round_id, lanes[])  -> Round    // stamps opened_at from the ledger
close_round(funder, round_id)          -> Round    // stamps closed_at
get_round(funder, round_id)            -> Round
is_lane(funder, round_id, who)         -> bool

round_id is BytesN<32>. A Round is:

pub struct Round {
    pub funder: Address,          // the account that declared the round; the only one that may close it
    pub lanes: Vec<Address>,      // immutable
    pub opened_at: u32,           // stamped by the contract
    pub closed_at: Option<u32>,   // stamped by the contract; None while open
}

EventsCopy Anchor Link

ErrorsCopy Anchor Link

Code 4 was NotRoundFunder. It was removed when rounds became namespaced by funder: a foreign caller now resolves its own empty namespace and gets RoundNotFound.

The tally CLI maps error 2 to "no round with that id is declared by that funder" and error 1 to "that round id is already declared by this funder".

ConstraintsCopy Anchor Link

A declaration cannot be backdated, extended or revised after the fact. Otherwise a funder could run the round, then declare only the lanes that look good.

Because both ends of the window are stamped by the contract and the lane set is immutable, a donor can apply one rule: reject any event outside [opened_at, closed_at] or from a sender not in lanes.

The registry cannot observe the token, so it cannot stop a funder sending from an account it never declared. That limit is stated in the trust statement.

TestsCopy Anchor Link

16 tests in contracts/round-registry/src/test.rs, 10 of them negative: each enforced constraint has a test showing it rejects the violation.

cd contracts && cargo test -p tally_round_registry
stellar contract build          # -> target/wasm32v1-none/release/tally_round_registry.wasm

pnpm test:contracts runs the same tests from the repository root.

OpenZeppelin v0.9.0 wrappersCopy Anchor Link

The confidential-token logic lives in OpenZeppelin's stellar-tokens package, vendored as the git submodule vendor/stellar-contracts. Tally's wrappers in ct/contracts add a constructor and little else. Provenance is in ct/NOTICE.md. Build them with stellar contract build, not plain cargo build, because stellar-tokens enables soroban-sdk's experimental_spec_shaking_v2 feature.

Token (ct/contracts/token)Copy Anchor Link

Wraps OpenZeppelin's ConfidentialToken with NoHooks (no extension behaviour). Taken from brozorec/stellar-confidential-token-demo at 9500ed7 with an updated doc comment.

__constructor(underlying_asset, verifier, auditor) binds the underlying SEP-41 asset, the verifier and the auditor registry, and freezes the contract's address-as-field value, which every account's viewing key is bound to.

Entry points come from the OpenZeppelin trait:

A transfer emits an event with topics ["transfer", from, to] and data that holds ciphertexts (r_e_point, v_tilde, sigma, b_tilde and the auditor ciphertexts), not the amount.

Verifier (ct/contracts/verifier)Copy Anchor Link

Copied verbatim from OpenZeppelin examples/confidential/verifier at v0.9.0, with a #![no_std] header added. It stores one UltraHonk verification key per circuit type and exposes verify_proof, which the token calls on every state-changing operation. The backend is the UltraHonk verifier from NethermindEth/rs-soroban-ultrahonk.

__constructor(admin, manager). register_verification_key and update_verification_key require the manager role. OpenZeppelin treats key updates as a break-glass operation, because a wrong key makes the circuit accept forged proofs.

pnpm deploy:testnet registers all six v0.9.0 keys, copied byte for byte from the vendored OpenZeppelin tree.

Auditor registry (ct/contracts/auditor)Copy Anchor Link

Copied verbatim from OpenZeppelin examples/confidential/auditor at v0.9.0, with a #![no_std] header added. It holds Grumpkin auditor public keys indexed by auditor_id. __constructor(admin, manager); register_key and rotate_key require the manager role.

The current deployment registers one auditor key, id 0, whose secret was written outside the repository at deploy time. Split auditor-key custody is part of the operator service, which is designed but not built.

bench-batch (measurement only)Copy Anchor Link

A Stellar transaction can carry only one InvokeHostFunctionOp, so batching needs a contract that makes the calls itself. ct/contracts/bench-batch has one function:

pub fn transfer_many(e: Env, token: Address, from: Address, to: Vec<Address>, data: Vec<Bytes>)

It calls token.confidential_transfer(from, to[i], data[i]) for each i. Each proof must be built against the balance the previous transfer leaves. It authorises the root with from.require_auth_for_args([]), which keeps the proofs from being copied into the root authorisation entry a second time. An earlier version used require_auth() and pushed the k = 3 envelope to 140,968 B, over the size limit.

Four transfers from one sender fit in one transaction this way; see Measurements. The payout flow does not use this contract.

BuildingCopy Anchor Link

pnpm build:contracts    # stellar contract build in contracts/ and in ct/contracts/
pnpm test:contracts     # cargo test for the round registry