Skip to content

feat(token-vault): productionize real token custody for vesting, locks, and emergency unlocks - #70

Merged
xqcxx merged 6 commits into
Stellar-Re-Code:mainfrom
Ultra-Tech-code:feat/token-vault-real-custody-43
Jul 29, 2026
Merged

xqcxx merged 6 commits into
Stellar-Re-Code:mainfrom
Ultra-Tech-code:feat/token-vault-real-custody-43

Conversation

@Ultra-Tech-code

@Ultra-Tech-code Ultra-Tech-code commented Jul 29, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Productionizes the token-vault with real token custody for vesting schedules, token locks, and emergency unlocks.

Closes #57

What Changed

Contract (`token-vault/src/lib.rs`)

  • Real token transfers wired into all 6 value-moving paths:
    • `lock_tokens` (owner → vault)
    • `claim` (vault → owner)
    • `create_vesting` (admin → vault)
    • `claim_vested` (vault → beneficiary)
    • `emergency_unlock` (vault → lock owner)
    • `revoke_vesting` (vault → admin) — new
  • Asset storage: `initialize()` now accepts and stores the token contract address
  • Terminal-state discipline: `revoked` flag on `VestingSchedule`; revoked/claimed entries are non-reusable
  • Conservation invariant: `vault token balance == total_locked` enforced across all lifecycles

Emergency Unlock Threat Model

  • Multi-sig gated: requires `emergency_threshold` approvals from designated signers
  • ACL-enforced: each signer must hold `Member+` role in access-control
  • Auditable: every approval and unlock emits contract events
  • Replay-resistant: claimed locks reject re-unlock attempts

Integration Tests

  • All integration tests updated for real Stellar Asset Contract (SAC) tokens
  • `deploy_vault` helper updated to accept `asset` parameter
  • ACL role assignments added where required by contract guards
  • New `revoke_vesting_refunds_unclaimed` test
  • Conservation invariant verified in seeded operation sequences

Test Results

85/85 tests pass, 0 failures

Suite Tests Status
access-control (unit) 33 ✅
token-vault (unit) 17 ✅
governance (unit) 3 ✅
treasury (unit) 3 ✅
vault_invariants 6 ✅
treasury_invariants 6 ✅
governance_invariants 5 ✅
access_control_invariants 3 ✅
cross_contract_invariants 3 ✅
event_lifecycle 2 ✅
resource_report 4 ✅

Acceptance Criteria

  • All value-moving paths transfer real tokens
  • Conservation invariant holds across combined vesting/lock/emergency operations (tested)
  • Emergency unlock is privilege-gated, audited, and threat-modeled
  • `cargo test --all` green including vault invariants"

- Add Asset storage key and store asset address in initialize()
- Add revoked field to VestingSchedule for terminal-state discipline
- Wire token::transfer in lock_tokens (owner → vault)
- Wire token::transfer in claim (vault → owner)
- Wire token::transfer in create_vesting (admin → vault)
- Wire token::transfer in claim_vested (vault → beneficiary)
- Wire token::transfer in emergency_unlock (vault → lock owner)
- Implement revoke_vesting: admin-gated, transfers unclaimed remainder
  to admin, marks revoked=true, adjusts total_locked
- Check revoked flag in claim_vested to enforce terminal-state discipline
- Update unit tests for real token integration

Addresses issue Stellar-Re-Code#43: real token custody across vesting, locks, and
emergency unlock lifecycles with conservation invariant enforcement.

The sum of releasable + locked + emergency-withdrawable never exceeds
deposited. Emergency unlock is multi-sig gated and auditable.
The deploy_vault helper now takes an asset: &Address parameter to pass
to the vault's initialize(), aligning with the new real-token-custody
contract interface.
…rvation

- Setup registers real Stellar Asset Contract and assigns ACL roles
- All tests mint tokens before lock/vesting operations
- Add revoke_vesting_refunds_unclaimed test
- Add conservation invariant assertion: vault token balance == total_locked
- Seeded sequences exercise combined lock/vest/claim/revoke/emergency ops
  with real token balance verification after every step
- Reduce seeded iterations (40→20) to fit Soroban budget with real transfers
- cross_contract: assign ACL Member roles, use real SAC for treasury/vault,
  fix finalize() caller to be a member (not admin)
- event_lifecycle: use real SAC, make event count baseline-relative
- governance_invariants: assign ACL roles in setup, fix finalize() callers
- treasury_invariants: use real SAC and pre-mint tokens to treasury
- resource_report: add asset parameter and token minting
- All test files: add soroban_sdk::testutils::Address trait import
Replace assert_eq! on tuples containing Val (which lacks PartialEq)
with field-level comparisons (last.0 address comparison).
@xqcxx

xqcxx commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Great job @Ultra-Tech-code

@xqcxx
xqcxx merged commit 1b16838 into Stellar-Re-Code:main Jul 29, 2026
1 check failed
@Ultra-Tech-code

Copy link
Copy Markdown
Contributor Author

Great job @Ultra-Tech-code

Thank you

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Productionize token-vault custody, vesting, locks, emergency unlocks

2 participants