Skip to content

docs(vault): explain how to choose interval from threshold and extend_to #9

Description

@0dillon

Summary

A vault's interval is the minimum number of ledgers between paid claims. Nothing explains how to
pick it, and the obvious guess is wrong.

The maintenance period of a target is extend_to - threshold, not threshold. A contract with
threshold: 100_000, extend_to: 500_000 has its TTL pushed to 500,000 ledgers and does not need
attention again until it falls to 100,000 — a gap of 400,000 ledgers. An owner who sets
interval to threshold pays for four times as many claims as the target needs. That mistake was
in scripts/init_testnet.sh until it was fixed by deriving the interval from the two macro values;
the contract's own documentation still says nothing about it.

Acceptance Criteria

  • open and set_terms rustdoc give the relationship as extend_to - threshold with the
    worked example above.
  • It is stated that the vault cannot read the target's compiled values, so the owner has to
    supply a consistent interval and nothing on-chain checks it.
  • The existing limit — the vault proves maintenance happened, not that it was needed — is
    linked rather than restated.
  • The README's vault paragraph points at the guidance.

Tech Stack

Rust (edition 2021, toolchain 1.93.0 pinned in rust-toolchain.toml), soroban-sdk 27.0.4,
target wasm32v1-none. Build with stellar contract build, never cargo build. Tests are
#[cfg(test)] modules on Env::default(); run them with cargo test --all.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions