This document describes the security architecture, trust model, and threat model for the NeuroWealth Vault contract.

The NeuroWealthVault smart contract operates in a multi-actor ecosystem involving privileged governance keys, automated off-chain execution services, end users, external DeFi protocols, and token issuers. System security depends on defining explicit trust boundaries and technical constraints around each actor.

graph TD
    subgraph OwnerZone["Owner Trust Zone (Cold / Multisig Key)"]
        Owner["Owner Key (Multisig / HSM)"]
    end

    subgraph AgentZone["AI Agent Trust Zone (Hot Key)"]
        Agent["AI Agent Hot Key (Automated Server)"]
    end

    subgraph UserZone["User Trust Zone (Public)"]
        User["Depositors / Users"]
    end

    subgraph CoreContract["NeuroWealth Vault Smart Contract"]
        VaultState["Vault State & Share Accounting"]
    end

    subgraph ExternalProtocols["External Protocols & Assets"]
        USDC["USDC Token Issuer (Circle / SEP-41)"]
        Blend["Blend Lending Pool"]
        DEX["DEX Swap / Liquidity Pool"]
    end

    Owner -->|Pause / Caps / Timelocked Upgrades / Pool Addresses| VaultState
    Agent -->|Rebalance / Harvest / Report Assets| VaultState
    User -->|Deposit / Withdraw / Strategy Choice| VaultState
    VaultState -->|Transfer / Balance Query| USDC
    VaultState -->|Supply / Redeem Liquidity| Blend
    VaultState -->|Add / Remove Liquidity / Swap| DEX

The Owner key is the primary administrative authority of the contract. As mandated in docs/MAINNET_CHECKLIST.md (Section 1), the Owner key MUST be stored in an offline/multisig cold environment separate from the AI Agent key.

• CAN:
  • Emergency pause and unpause the vault (pause, emergency_pause, unpause).
  • Configure deposit safety caps (set_caps, set_tvl_cap, set_user_deposit_cap, set_deposit_limits).
  • Set rebalance cooldowns and approval TTLs (set_rebalance_cooldown, set_approval_ttl).
  • Initiate and execute timelocked AI agent rotations (update_agent, confirm_agent_update, cancel_agent_update).
  • Schedule, execute, or cancel contract WASM upgrades behind a 24-hour timelock (schedule_upgrade, execute_upgrade, cancel_upgrade).
  • Configure whitelisted external protocol pool addresses (set_blend_pool, set_dex_pool).
  • Initiate and complete ownership transfers (transfer_ownership, accept_ownership).
  • Execute emergency yield harvests during agent rotation (emergency_harvest).
• CANNOT:
  • Direct user USDC deposits to owner-controlled arbitrary wallets.
  • Withdraw or burn user shares without explicit user authorization.
  • Modify individual user share balances.
  • Bypass upgrade or agent rotation timelocks (must wait 17,280 ledgers ≈ 24 hours).
  • Perform instant WASM code replacements.

The AI Agent key is utilized by automated backend trading engines to execute strategy rebalances and update yield metrics. Because it operates in a hot server environment, it faces higher risk of exposure.

• CAN:
  • Trigger protocol allocation adjustments between whitelisted strategies (rebalance).
  • Execute routine yield compounding (harvest).
  • Report total asset valuations and strategy yield/losses (update_total_assets).
• CANNOT:
  • Transfer vault funds to external addresses outside whitelisted protocol pools.
  • Change vault administrative configurations (caps, pool targets, timelocks, owners).
  • Bypass solvency verification during asset updates (cannot inflate total assets beyond actual balance + pool holdings).
  • Report losses exceeding the per-call decrease cap (capped at max_decrease_bps, default 10%).
  • Pause or unpause the contract.
  • Modify user strategy choices or user balances directly.

Depositors are un-privileged external accounts interacting with the vault to earn yield.

• CAN:
  • Deposit USDC into the vault to mint proportional shares (deposit, batch_deposit).
  • Redeem vault shares for underlying USDC at any time (withdraw, withdraw_all).
  • Select individual yield strategy preferences (set_user_strategy).
  • Call permissionless maintenance utilities (touch_user_ttl).
• CANNOT:
  • Withdraw funds belonging to other depositors.
  • Trigger vault rebalances or alter asset accounting.
  • Modify vault caps or administrative settings.
  • Inflate share exchange rates (defeated by storage-based asset accounting & minimum deposit floors).

External lending pool integration.

• CAN:
  • Receive supplied USDC from the vault.
  • Generate interest on deployed USDC positions.
  • Return liquidity upon vault redemption requests.
  • Report current pool utilization and liquidity availability.
• CANNOT:
  • Mutate NeuroWealthVault contract storage or state.
  • Seize idle USDC held in the vault contract.
  • Force liquidations or alter share accounting inside the vault.

External Automated Market Maker (AMM) pool integration.

• CAN:
  • Execute token swaps during strategy shifts.
  • Receive and return liquidity pool tokens.
• CANNOT:
  • Access vault funds outside explicit allowance approvals.
  • Mutate vault contract state or storage.

The asset issuer controlling the underlying USDC token contract on Stellar.

• CAN:
  • Issue, mint, or burn global USDC tokens.
  • Freeze or clawback token balances on flagged Stellar accounts (Stellar Asset Control flags).
• CANNOT:
  • Access or alter internal vault share accounting (DataKey::Shares, DataKey::TotalShares).
  • Bypass contract authorization rules.

Every external contract call in neurowealth-vault/contracts/vault/src/lib.rs relies on specific trust assumptions and implements technical mitigations:

This threat model has been formally reviewed against docs/MAINNET_CHECKLIST.md:

• Section 1 Compliance (Key Management & Separation):
  • Confirms complete independence of Owner ($G_{owner}$) and Agent ($G_{agent}$) keypairs.
  • Strictly isolates the Hot Agent Key (capable only of rebalance/harvest/update_total_assets) from the Cold Owner Key (capable of administrative governance and code upgrades).
• Section 7 Compliance (Upgrade & Governance Multisig Plan):
  • Enforces mandatory 24-hour timelock (UPGRADE_TIMELOCK_LEDGERS = 17_280) for all contract code upgrades (schedule_upgrade $\rightarrow$ execute_upgrade).
  • Provides a cancellation window (cancel_upgrade) allowing security monitoring to block malicious or mistaken upgrades during the 24-hour window.
  • Recommends Stellar Multisig or hardware cold storage for the Owner key on mainnet deployments.

The vault automatically manages liquidity between idle USDC (held in the contract) and deployed assets (e.g., in Blend protocol):

1. Idle Withdrawals: If the vault holds sufficient idle USDC, withdrawals are processed immediately.
2. Protocol Withdrawals: If idle USDC is insufficient, the vault automatically attempts to withdraw the required amount from the active protocol (e.g., Blend).
3. Partial Withdrawals: If the protocol has insufficient liquidity (e.g., high utilization), the user receives all available USDC and retains their remaining shares in the vault. This ensures users are not forced into unfavorable liquidations during protocol-wide liquidity crunches.

Users can withdraw their USDC at any time without:

• Lock-up periods
• Withdrawal fees
• Approval requirements beyond their signature

The vault can route idle USDC into external protocols (get_current_protocol reports idle, blend, or dex). Each integration introduces systemic risk:

• Liquidity Risk (Blend): If Blend utilization is 100%, the vault cannot pull funds immediately. Users will experience partial withdrawals until liquidity returns to the protocol.
• Slippage & Liquidity Risk (DEX): When the active strategy is a DEX pool, withdrawals and strategy switches execute swaps. Thin pool liquidity can cause slippage or a failed switch; the low-liquidity strategy-switch path returns funds to idle rather than forcing an unfavorable swap.
• Protocol Failure: A bug or exploit in Blend or the DEX could result in loss of deployed assets.

The update_total_assets function used by the AI agent has built-in guardrails:

• Solvency Check: The agent cannot inflate total assets beyond the combined balance of idle USDC and funds actually deployed to external protocols.
• Decrease Bounding: Reporting a loss is capped (default 10% per call) to prevent sudden, massive devaluations from a single malicious or erroneous call.

The AI agent can move funds between protocols via rebalance(), but is constrained:

• Rebalance Cooldown: Consecutive rebalances are rate-limited by a configurable cooldown (get_rebalance_cooldown / get_last_rebalance_ledger), which bounds how quickly a compromised or malfunctioning agent can churn funds across protocols.
• No Direct Custody: Rebalancing only moves funds between the vault's own positions in whitelisted pools; the agent cannot redirect funds to an arbitrary address.

The contract owner can upgrade the contract code. To protect against malicious or accidental instant code changes, upgrade risk is mitigated via a mandatory two-step timelock mechanism:

• Two-Step Timelock: Upgrades must first be scheduled via schedule_upgrade(new_wasm_hash), initiating a timelock delay before execute_upgrade() can be called.
• Cancellation Window: During the timelock window, the owner or security monitoring can invoke cancel_upgrade() to abort a compromised or erroneous upgrade proposal.
• Owner Multi-Sig Governance: For mainnet deployment, owner authority must be held by a Stellar native multi-sig account (e.g. 2-of-3 threshold).
• Guardian Key Evaluation & Formal Deferral (Issues #607, #922): A contract-level second-signature pattern (DataKey::Guardian gating execute_upgrade) was evaluated in docs/GUARDIAN_KEY_DESIGN.md and formally deferred in favor of native Stellar protocol multi-sig. Native multi-sig protects all owner actions at the ledger level rather than adding bespoke contract logic for upgrades alone.

Soroban persistent entries (such as each user's Shares record) accrue state rent and expire if their TTL is not periodically extended:

• Pure Read-Only Getters: get_balance and get_shares are side-effect free — they do not extend storage TTL. This keeps pure reads cheap and prevents read traffic from silently mutating ledger state.
• Explicit Maintenance: Off-chain indexers or maintenance jobs should call the permissionless touch_user_ttl(user) to refresh a user's Shares TTL. State-changing calls (deposit, withdraw) already rewrite Shares and refresh its TTL during normal operation.
• Risk: A long-dormant user who never transacts and whose entry is never touched could see their Shares entry expire and require restoration. Active users, and any indexer running touch_user_ttl, are unaffected.

Every accounting path in the vault (deposit, withdraw, rebalance) assumes the amount received by a token transfer equals the amount requested. Today this holds because the vault's configured asset is Stellar's canonical USDC (a Stellar Asset Contract): SAC transfers move the exact requested amount with no protocol-level fee.

This assumption would silently break in either of these scenarios:

• The underlying USDC issuer ever introduced fee-on-transfer or rebasing/deflationary semantics on the Stellar Asset Contract.
• The vault's configured usdc_token address were ever misconfigured to point at a wrapper or non-standard token that does not deliver the full requested amount on transfer.

Impact if it happened silently: get_total_assets() / get_shares() accounting would diverge from the vault's actual physical token balance — shares would be backed by fewer tokens than recorded, socializing the loss across all holders on the next redemption.

Rejection stance: this vault does not support fee-on-transfer or deflationary assets, and does not plan to add support. If the configured asset's transfer semantics ever changed to violate the "received == requested" assumption:

1. Do not treat this as a vault bug to patch around. The correct response is to pause the vault (pause()) and initiate the owner-compromise-style incident response (see the runbook below), not to add fee-compensation logic to the accounting math — that logic is itself a well-known attack surface (see the ERC-4626 inflation-attack class of vulnerabilities).
2. Any future integration with a different asset must independently verify (and this document must be updated to record) that the asset has fixed, fee-free transfer semantics before it is wired into usdc_token.

Detection: test_transfer_delta_sanity.rs pins this assumption in CI — it measures the actual token balance delta around every fund-moving call (deposit, withdraw, rebalance) against the requested amount and fails immediately if they ever diverge, so a regression (or a misconfigured test token in a future integration) is caught before it reaches a real deployment.

Legacy deposits, withdrawals, and Blend/DEX protocol movements use only the vault's configured UsdcToken. batch_deposit rejects every other token with the typed UnsupportedAsset error before transfers or rate-limit writes. Asset-aware deposit_asset and withdraw_asset accept only symbols registered by the owner and resolve each symbol to its configured token address; unknown symbols return the same typed error. Owner-registered non-USDC assets remain idle and are not supplied to or redeemed from the USDC-only Blend/DEX integrations. Protocol clients independently enforce the configured token before querying token balances or calling a pool.

Threat: Yield reaches the share price only when the agent calls update_total_assets, which can raise TotalAssets by any amount up to the real balance in one step. With MinHoldingPeriod defaulting to 0, anyone watching the mempool or the agent's schedule could deposit just before the update and withdraw right after, capturing yield accrued over a period they were not invested.

Mitigation: The vault now initializes with a non-zero default MinHoldingPeriod of 120 ledgers (~10 minutes). This prevents same-block deposit/withdraw cycles that would allow yield sniping. The owner can adjust this period via set_min_holding_period if needed for operational reasons, but the default provides baseline protection.

Impact: Attackers attempting to snipe yield must now wait at least 120 ledgers between deposit and withdrawal, making the attack unprofitable for typical yield reporting intervals.

Threat: update_total_assets(agent, new_total, allow_decrease, max_decrease_bps) capped a loss report at max(max_decrease_bps, 100) bps of the old total. The cap was a caller-supplied argument, so the caller could pass 10_000 and report a 100% loss in one call. The only safeguard was the owner co-sign requirement.

Mitigation: The decrease cap is now stored in owner-configured storage (DataKey::MaxDecreaseBps) with a sane default of 1000 bps (10%) and a hard ceiling of 10_000 bps (100%). The caller-supplied argument in update_total_assets is ignored. The owner can configure the cap via set_max_decrease_bps, but cannot exceed the hard ceiling.

Impact: Even with owner co-sign, a single transaction cannot report a loss exceeding the configured cap (default 10%). Repeated calls cannot chain past the limit without additional owner authorization for each call.

Threat: convert_to_shares_internal used a bootstrap 1:1 rate when total_shares == 0 || total_assets == 0. If shares were outstanding but assets were zero (e.g., after a full loss report, or dust shares remaining after rounding), a new depositor would get amount shares while existing holders, whose shares were worth nothing, would immediately own a pro-rata slice of the new deposit.

Mitigation: When total_shares > 0 && total_assets == 0, deposits are rejected with the typed error VaultError::DepositRejectedZeroAssetsWithShares. This prevents the dilution attack. The vault must be in a recovery mode (owner intervention) to accept new deposits in this state.

Impact: New depositors cannot be diluted by existing worthless shares. The vault requires explicit recovery action (e.g., owner-initiated loss write-down or share restructuring) before accepting new deposits after a total loss event.

This register documents every owner-only and agent-only capability, the blast radius if the corresponding key is compromised, and the existing mitigation status.

The table above names the caller for every privileged function, but not whether that call is delayed by a timelock or still reachable while the vault is paused. Both properties matter for an incident responder deciding whether a given function can be used to make the situation worse (or better) right now. The table below covers the functions added since the table above was last extended; update_agent and switch_to_standby_agent are included for contrast, since together they are the timelock gap this issue asks to be noted explicitly.

The standby-agent timelock gap (tracked in #954, open). update_agent (primary agent rotation) is timelocked specifically so a compromised owner key cannot instantly hand agent authority to an attacker-controlled address — the delay gives the real owner a window to notice and react via cancel_agent_update. update_standby_agent and switch_to_standby_agent provide no equivalent delay: an owner (or an attacker who has compromised the owner key) can set an arbitrary address as standby and instantly promote it to primary agent in two calls, with no timelock and no cooldown between them, which defeats the timelock users rely on to react to a malicious agent change. Until #954 is resolved, treat standby-agent rotation as carrying the same trust assumptions as an instant, undelayed owner action, not the delayed-and-cancellable guarantee update_agent provides.

When the agent key is lost, compromised, or mid-rotation via the update_agent timelock, the normal harvest() function is unusable because it requires agent authorization. The owner can call emergency_harvest(min_out) to compound yield during this window:

• Gating: Owner auth only (not agent auth)
• Pause bypass: Works even when the vault is paused, so the owner can compound yield during an emergency pause without unpausing first
• Same mechanics: Withdraws accrued yield from the active protocol and re-supplies it (same round-trip as harvest())
• Distinct event: Emits EmergencyHarvestEvent (topic em_harv) so indexers can differentiate from agent-initiated HarvestEvent (topic harvest)

Issue #601 — Definitive table of which functions are blocked vs. allowed while the vault is paused. This table is the source of truth; the exhaustive test in neurowealth-vault/contracts/vault/src/tests/test_pause.rs encodes it as parameterised assertions so future functions cannot silently bypass pause checks.

All view/getter functions are 🟢 ALLOWED while paused. They perform no state changes and emit no events. Blocking them during a pause would prevent operators from assessing vault state.

Both withdraw and withdraw_all are blocked while the vault is paused. This is a deliberate design choice:

• The pause mechanism is an emergency stop intended to freeze all fund movement while a security incident is investigated.
• Allowing withdrawals while paused could enable a race between an attacker (draining funds) and the security team (trying to stop the drain).
• The owner-compromise runbook documents how to unpause safely once the incident is resolved, at which point normal withdrawals resume immediately.

If a future version of the protocol wishes to allow emergency withdrawals while paused, this would require a separate "withdrawal-allowed" flag that is independent of the pause flag, along with careful analysis of reentrancy and ordering risks.

When adding a new contract function, the author must update this matrix and the corresponding test in test_pause.rs. The PR review checklist (.github/pull_request_template.md) includes a pause-semantics item for this purpose.

1. Checks-Effects-Interactions Pattern: All state updates happen before external calls
2. Auth on Withdrawals: require_auth() ensures users can only access their own funds
3. Minimum Deposits: Prevents dust attacks
4. Deposit Caps: Limits exposure per user
5. TVL Caps: Limits total exposure
6. Pausable: Emergency stop functionality

If the owner keypair is suspected or confirmed to be compromised, follow this sequence immediately. Every step that requires owner auth is marked [owner].

For agent-key compromise procedures, see the Agent-Key Compromise Runbook.

The single fastest action to protect user funds is an emergency pause. No new deposits or withdrawals can execute while the vault is paused.

stellar contract invoke \
  --id $VAULT_CONTRACT_ID \
  --source <OWNER_SECRET_KEY> \
  --network mainnet \
  -- pause

Requires: owner auth [owner]

Note: Unlike pause, the emergency_pause function also requires owner auth. If the owner key is already confirmed compromised and you cannot sign with it, see Step 2 to assess whether the attacker has already rotated the owner address.

Before taking further action, determine what the attacker could have done or is still doing:

Owner-only actions an attacker with the key could have taken:

• Initiated update_agent or schedule_upgrade to queue a malicious agent or WASM upgrade.
• Called set_blend_pool or set_dex_pool to point the vault at a drain contract.
• Called set_caps to raise or remove deposit limits.
• Initiated transfer_ownership to a new address they control.

The attacker cannot directly withdraw user funds — withdrawals require the user's own auth signature, not the owner key.

Generate a new owner keypair on an air-gapped machine. Then initiate the two-step ownership transfer from the current (compromised) key while you still control it:

# Step 3a — propose new owner [owner]
stellar contract invoke \
  --id $VAULT_CONTRACT_ID \
  --source <CURRENT_OWNER_SECRET_KEY> \
  --network mainnet \
  -- transfer_ownership \
  --new_owner <NEW_OWNER_ADDRESS>

# Step 3b — accept from the new keypair [pending owner]
stellar contract invoke \
  --id $VAULT_CONTRACT_ID \
  --source <NEW_OWNER_SECRET_KEY> \
  --network mainnet \
  -- accept_ownership

If the compromised key has already been used to initiate an attacker-controlled transfer_ownership, the pending owner is stored under DataKey::PendingOwner. You must call accept_ownership from the legitimate new owner before the attacker does. Check DataKey::PendingOwner on-chain immediately.

Once the new owner key is in place, audit and reset all owner-controlled state and cancel pending malicious timelocks:

# Cancel any pending malicious agent update or contract upgrade scheduled by attacker [owner]
stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- cancel_agent_update

stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- cancel_upgrade

# Initiate and confirm agent update to legitimate AI agent address via timelock [owner]
stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- update_agent --new_agent <LEGITIMATE_AGENT_ADDRESS>

# (After timelock window expires)
stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- confirm_agent_update

# Reset pool addresses to audited contracts [owner]
stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- set_blend_pool --pool_address <AUDITED_BLEND_POOL>

stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- set_dex_pool --pool_address <AUDITED_DEX_POOL>

# Restore caps to pre-incident values [owner]
stellar contract invoke --id $VAULT_CONTRACT_ID --source <NEW_OWNER_KEY> \
  --network mainnet -- set_caps \
  --user_deposit_cap <ORIGINAL_CAP> --tvl_cap <ORIGINAL_TVL_CAP>

Only unpause once Steps 1–4 are fully complete and verified.

stellar contract invoke \
  --id $VAULT_CONTRACT_ID \
  --source <NEW_OWNER_SECRET_KEY> \
  --network mainnet \
  -- unpause

Requires: owner auth [owner]

If the vault has funds deployed to a protocol (Blend or DEX) and the agent key is being rotated, use emergency_harvest to compound yield without waiting for the new agent key:

stellar contract invoke \
  --id $VAULT_CONTRACT_ID \
  --source <NEW_OWNER_SECRET_KEY> \
  --network mainnet \
  -- emergency_harvest \
  --min_out 0

Requires: owner auth [owner]

Note: emergency_harvest bypasses the paused-state check, so it can be called before or after unpause. It still respects the rebalance cooldown and requires an active protocol (panics with UnsupportedProtocol if CurrentProtocol == "none"). The emitted EmergencyHarvestEvent (topic em_harv) is distinct from the regular HarvestEvent (topic harvest).

Resume normal agent-initiated harvest() calls once the new agent key is confirmed.

• Revoke and rotate all credentials that were co-located with the compromised key.
• Publish a post-mortem within 72 hours.
• Consider migrating to a multi-sig owner address before resuming normal operations.

A flash-loan attack against a yield vault exploits the fact that an attacker can deposit a very large amount, trigger a favourable state change (harvest, rebalance, or share-price update), and withdraw in the same transaction — or across a very small number of consecutive ledgers — to extract yield that belongs to long-term depositors.

The vault enforces a configurable minimum holding period tracked per user:

On deposit: LastDepositLedger(user) is set to env.ledger().sequence().

On withdraw: If MinHoldingPeriod > 0 and current_ledger - LastDepositLedger < MinHoldingPeriod, the transaction panics with VaultError::HoldingPeriodNotElapsed (#75) and emits a FlashLoanProtectionTriggeredEvent (topic fl_block).

On mainnet, set the holding period to at least 1 ledger (≈ 5 seconds) during initial deployment, and tighten to 120–240 ledgers (10–20 minutes) after TVL exceeds a meaningful threshold. The owner can update the period at any time via set_min_holding_period.

Setting ledgers = 0 disables flash-loan protection entirely (acceptable on testnet; not recommended for mainnet once funds are deployed).

Maximal Extractable Value (MEV) in the context of this vault arises during rebalances, where an agent-submitted transaction moves assets between protocols (Blend → DEX, etc.). An adversary who can observe pending rebalance transactions can front-run or sandwich-attack the swap, extracting value from the vault at the expense of depositors.

The vault does not currently block MEV extraction on-chain (MEV largely occurs at the sequencing layer, outside of contract logic). Instead, it implements on-chain observability so the agent can react and governance can act:

Reporting flow:

1. After each rebalance, the off-chain agent compares min_out to the actual amount received. If the difference exceeds a configured threshold, it calls submit_mev_report(protocol, estimated_loss_stroops, min_out_used).
2. The contract increments CumulativeMevLoss and MevIncidentCount and emits a MevExtractionSuspectedEvent (topic mev_susp) for indexers.
3. Governance (owner) monitors cumulative loss via get_mev_stats(). If CumulativeMevLoss > MaxAcceptableMevLoss, the agent should halt rebalances and wait for owner review.

• Set min_out on every rebalance() call to bound slippage on-chain (current implementation uses min_out to revert if output is below the threshold).
• Use a private mempool or Stellar's fee-bump transactions to reduce the window for front-running.
• Rotate rebalance timing randomly to prevent predictable extraction patterns.
• Monitor MevExtractionSuspectedEvent events via an indexer; alert if more than 3 incidents occur within 100 ledgers.

Before any mainnet deployment, you must refer to and complete the formal Mainnet Deployment Checklist.

Additionally, ensure:

• All functions have documented panic conditions
• All state changes emit events
• Access control verified for each function
• Upgrade mechanism tested on testnet
• Pause/unpause tested
• Withdrawal flow tested with edge cases
• Maximum deposit limits enforced
• TVL cap enforced
• Integration with USDC token tested
• Integration with Blend protocol tested (Phase 2)

Rate limiting is enforced inside NeuroWealthVault, before any token transfer or external protocol invocation. It is a defense against transaction spam, block space abuse, protocol churn, TTL-maintenance griefing, and repeated expensive share-conversion calls. It complements—not replaces—the pause switch, TVL and per-user deposit caps, user authentication, and the existing MinRebalanceInterval cooldown.

The owner uses set_rate_limit(category, max_calls, window_ledgers) to configure six bounded categories: per-user deposit, per-user withdraw, global rebalance, per-user touch_ttl, global preview, and per-user batch_dep. rebalance, harvest, and emergency_harvest share the same global bucket so harvest cannot be used to bypass the rebalance frequency policy. Every preview and conversion method shares one global bucket so changing the method name does not evade computational protection. A zero max_calls explicitly disables a category; an enabled category must have a non-zero ledger window.

batch_deposit has two independent protections: an owner-configured maximum entry count (set_max_batch_size, default 50; zero means unlimited) and the per-user deposit/batch frequency buckets. A batch is counted once in each frequency bucket, not once per entry. This bounds the transfer/event loop while preserving atomic all-or-nothing semantics.

Policies and counters use the appended DataKey::RateLimitConfig, DataKey::RateLimitGlobalState, DataKey::RateLimitUserState, and DataKey::MaxBatchSize entries in instance storage. Counters are keyed by the user address for user-scoped categories and by category for global categories. They are fixed-window counters based only on env.ledger().sequence() and are reset by overwriting the bucket after the configured window. Instance storage is intentional: a persistent TTL expiry must not give a caller a free reset. The trade-off is a small per-user instance key for each category used; sybil addresses remain economically constrained by transaction fees and the vault's other caps.

RateLimitConfigUpdatedEvent (rate_cfg) and BatchSizeLimitUpdatedEvent (batch_lim) provide configuration audit trails. RateLimitExceededEvent (rate_hit) includes the category, optional user, current ledger, window start, maximum, and observed count. It is emitted immediately before the contract returns VaultError::RateLimitExceeded. Operators should consume both the event stream and failed transaction error codes, since an over-limit transaction itself is reverted by the host.

• Set non-zero, workload-specific values before mainnet operation and verify them with get_rate_limit and the state getters.
• Keep MinRebalanceInterval non-zero as a second independent control on agent churn; lowering one policy does not silently remove the other.
• Treat preview functions as state-writing contract calls when submitted on chain. RPC simulations do not commit state, so they are useful for display but are not a substitute for the transaction-level guard.
• Alert on repeated rate_hit events, especially global preview/rebalance hits and a single address exhausting deposit, withdrawal, or TTL buckets.
• Rate limits do not stop a user from creating many addresses; retain the TVL cap, user deposit cap, fee policy, and authentication checks as the sybil resistance layer.

The WhatsApp bot (whatsapp/) creates a custodial Stellar keypair per verified phone number and signs vault transactions on the user's behalf. Unlike the vault contract, these keys are held by the operator, so this section records what is protected, from whom, and what is explicitly not protected. Operational detail is in docs/WHATSAPP_BOT.md.

• Envelope encryption. Each secret has its own random DEK; the DEK is wrapped with the KEK (AES-256-GCM, version label bound as AAD). Database contents alone (dump, backup, SQL injection, replica access) reveal no usable key material.
• KEK rotation without re-exposing secrets. npm run rotate-keys re-wraps DEKs under a new ENCRYPTION_KEY_VERSION; Stellar secrets are never re-encrypted or logged. Old KEKs are kept only in ENCRYPTION_KEY_RETIRED until rotation completes. Runbook: docs/WHATSAPP_BOT.md.
• Isolation seam for KMS/HSM. KEK access is confined to wrapDek / unwrapDek; a managed key service can replace the env-var KEK without touching storage or callers.
• Fail-closed configuration. The service refuses to boot with a missing, short, placeholder or default secret (src/envGuard.ts), and CI forbids source-level fallbacks (see the policy below).
• Plaintext handling. The decrypted secret exists only inside getDecryptedSecretKey for the duration of signing; it is never persisted, returned to chat, or logged.

Compromise of the Stellar network or the vault contract (covered by the vault threat model above), and endpoint security of users' own phones.

Rotate the KEK at least every 12 months and immediately on: any suspected exposure of the secret store or a replica, departure of someone with access to it, or a change of secret-store provider. Record each rotation (date, old/new version, operator) in the operations log.

Production-sensitive defaults must not be embedded in application source. The WhatsApp encryption key, phone hashing salt, and vault contract identifiers must come from deployment environment variables. If any of these values are missing, the affected service should fail during startup rather than silently falling back to a shared development secret or stale testnet contract id.

CI enforces this posture with scripts/check-no-production-defaults.py, which is run from the secret-scan job. The check is intentionally narrow and focused on the env vars that would create direct custody, privacy, or routing risk if a default value drifted into production code.

Required fail-closed values:

At runtime the WhatsApp service enforces the same policy: whatsapp/src/bootstrapEnv.ts (first import of every entry point) runs assertEnv() from whatsapp/src/envGuard.ts and aborts the boot with a list of every missing, too-short, placeholder or default value, and refuses TWILIO_SKIP_SIGNATURE_VALIDATION=true under NODE_ENV=production (Issue #945). check-no-production-defaults.py additionally fails CI if an entry point stops importing the guard.