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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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