From 8f61b066b773000d453e40190bc24c3ef828d713 Mon Sep 17 00:00:00 2001 From: licette32 Date: Mon, 30 Mar 2026 09:37:28 -0300 Subject: [PATCH] chore(soroban): doc amount-bounds --- README.md | 6 +++--- src/lib.rs | 23 ++++++++++++++++++++--- vesting.md | 30 ------------------------------ 3 files changed, 23 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 72e375c..2813f49 100644 --- a/README.md +++ b/README.md @@ -747,9 +747,9 @@ To reduce abuse, spam, and potential overflow risk, strict bounds are enforced d The following constants were introduced: ```rust -pub const MAX_VAULT_DURATION: u64 = 365 * 24 * 60 * 60; // 1 year -pub const MIN_AMOUNT: i128 = 10_000_000; // 1 USDC (7 decimals) -pub const MAX_AMOUNT: i128 = 10_000_000_000_000; // 10 million USDC (7 decimals) +pub const MAX_VAULT_DURATION: u64 = 365 * 24 * 60 * 60; // 365 days in seconds +pub const MIN_AMOUNT: i128 = 10_000_000; // 1 USDC (1 × 10^7 stroops) +pub const MAX_AMOUNT: i128 = 10_000_000_000_000; // 10,000,000 USDC (10^13 stroops) ``` ## Validation Rules diff --git a/src/lib.rs b/src/lib.rs index 70ae578..5840d92 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -85,9 +85,26 @@ pub struct ProductivityVault { // --------------------------------------------------------------------------- // Constants to prevent abuse, spam, and potential overflow issues -pub const MAX_VAULT_DURATION: u64 = 365 * 24 * 60 * 60; // 1 year in seconds -pub const MIN_AMOUNT: i128 = 10_000_000; // 1 USDC with 7 decimals -pub const MAX_AMOUNT: i128 = 10_000_000_000_000; // 10 million USDC with 7 decimals + +/// Maximum allowed vault duration in seconds (365 days). +/// +/// Enforced in `create_vault`: `end_timestamp − start_timestamp` must not +/// exceed this value, otherwise returns `Error::DurationTooLong`. +pub const MAX_VAULT_DURATION: u64 = 365 * 24 * 60 * 60; + +/// Minimum vault amount in stroops (1 USDC). +/// +/// Stellar USDC uses 7 decimal places: 1 USDC = 10_000_000 stroops. +/// Enforced in `create_vault`: `amount` must be ≥ `MIN_AMOUNT`, +/// otherwise returns `Error::InvalidAmount`. +pub const MIN_AMOUNT: i128 = 10_000_000; // 1 USDC + +/// Maximum vault amount in stroops (10,000,000 USDC). +/// +/// Stellar USDC uses 7 decimal places: 1 USDC = 10_000_000 stroops. +/// Enforced in `create_vault`: `amount` must be ≤ `MAX_AMOUNT`, +/// otherwise returns `Error::InvalidAmount`. +pub const MAX_AMOUNT: i128 = 10_000_000_000_000; // 10M USDC #[contracttype] #[derive(Clone)] diff --git a/vesting.md b/vesting.md index d3479e5..2018242 100644 --- a/vesting.md +++ b/vesting.md @@ -297,7 +297,6 @@ Emitted when a milestone is successfully validated. ## Security and Trust Model -<<<<<<< HEAD This section outlines the security properties, trust assumptions, and known limitations of the Disciplr Vault contract to assist auditors and users. ### Trust Model @@ -331,35 +330,6 @@ This section outlines the security properties, trust assumptions, and known limi 4. **Upgradeability**: Consider proxy pattern for contract upgrades 5. **Comprehensive Tests**: Achieve 95%+ test coverage 6. **External Audits**: Have security experts review before mainnet deployment -======= -This section outlines the security assumptions, trust model, and known limitations of the Disciplr Vault contract. It is intended for auditors, developers, and users to understand the risks and guarantees provided by the system. - -### Trust Model - -1. **Verifier Trust (Critical)**: When a `verifier` is designated (via `Some(Address)`), that address has **absolute power** to validate the milestone and cause funds to be released to the `success_destination` before the deadline. If the verifier is compromised or malicious, they can release funds prematurely or to a non-compliant recipient. -2. **Creator Power**: If no `verifier` is set (`None`), only the `creator` can validate the milestone. Additionally, the `creator` can cancel the vault at any time to reclaim funds, assuming the vault is still `Active`. -3. **Immutable Destinations**: Once a vault is created, the `success_destination` and `failure_destination` are immutable. This prevents redirection of funds after the vault is funded, assuming the core contract logic remains secure. - -### Security Assumptions - -1. **Stellar Ledger Integrity**: We assume the underlying Stellar blockchain and Soroban runtime correctly enforce authorization (`require_auth`) and maintain state integrity. -2. **Ledger Timestamp**: The contract relies on `env.ledger().timestamp()` for all time-based logic (start/end windows). We assume ledger timestamps are reasonably accurate and monotonic as per Stellar network consensus. -3. **Token Contract Behavior**: The contract interacts with a USDC token contract (standard Soroban token interface). We assume the token contract is honest and follows the expected transfer behavior. - -### Known Limitations & Risks - -1. **USDC Token Address Consistency**: The `usdc_token` address is **not stored** in the vault data. Instead, it is passed as an argument to methods like `release_funds`, `redirect_funds`, and `cancel_vault`. - > [!WARNING] - > There is a risk that a caller provides a different token address than the one used during vault creation. Users should verify the token contract used in interactions matches the intended asset. -2. **CEI Pattern Violations**: Some methods perform token transfers **before** updating the internal vault status. While Soroban's atomicity mitigates some traditional reentrancy risks, following the Checks-Effects-Interactions (CEI) pattern more strictly is a recommended enhancement for future versions. -3. **No Administrative Overrides**: There is no "admin" or "owner" role with the power to rescue funds from a stalled vault (e.g., if a verifier loses their key and the deadline is far in the future). Funds are strictly bound by the `end_timestamp` and authorization rules. -4. **Lack of Reentrancy Guards**: The contract does not currently implement explicit reentrancy guards, relying instead on the synchronous and atomic nature of Soroban contract calls. - -### Recommendations for Integration - -- **Off-chain Verification**: The `milestone_hash` should represent a clear, legally or technically binding document that both creator and verifier agree upon. -- **Multisig Verifiers**: For high-value vaults, we highly recommend using a multisig address (G-address or contract-based account) as the `verifier`. ->>>>>>> c6890851d8814bd858b9c8b6f3777c8363ab4c49 ---