A tokenized vault holds other people's funds. A vault that drifts from the
SEP-56
standard, or is open to an inflation (donation) attack, can lose them. Aegis Vault
takes the contract address of a deployed vault, runs 11 checks against it on
Stellar Testnet, and tells you which pass, which fail, and why. It is a CLI tool
with a companion web UI.
- Paste an address, get a verdict. 7 conformance checks and 4 security checks,
in the browser or from the CLI.
- Two ways in. Already deployed a vault? Paste its address into the
web checker. Still building? Run the CLI in your own
development environment while you work.
- Honest results. Each check ends as
PASS, FAIL, INCONCLUSIVE or
NOT_APPLICABLE. When the tool cannot decide, it says so instead of guessing.
- CI-friendly. Exit codes, plus
text, json and markdown output.
[!WARNING]
Our own reference vault currently fails the donation_attack check: a real
inflation-attack vulnerability was confirmed under decimals_offset=0. See
SECURITY.md for details. Aegis Vault is functional and
adversarial testing. It is not a substitute for a formal third-party
security review.
Features
Aegis Vault runs two groups of checks against a deployed SEP-56 vault contract.
Positive Conformance
Calls 7 core SEP-56 functions on the vault and checks their results:
total_assetsdepositmintwithdrawredeemconvert_to_sharesconvert_to_assets
Security / Adversarial
Probes four basic security risks:
| Check | What it probes |
|---|
donation_attack | Inflation / donation attack simulation |
overflow_protection | Arithmetic overflow handling |
rounding_direction | Verifies rounding favors the vault, not the attacker |
access_control_probing | Unauthorized operator / allowance handling |
What each check asserts: VAULT_CHECKS.md.
Example run
Abridged from the unedited report in
docs/sample-reports/reference-vault.md
(CLI 0.5.0, Stellar Testnet, 102 s). The Detail column is left out here; the full
report has it.
Result: Remediation needed
Core function checks: 7 of 7 passed
Basic security checks: 3 of 4 passed
01 total_assets PASS
02 deposit PASS
03 mint PASS
04 withdraw PASS
05 redeem PASS
06 convert_to_shares PASS
07 convert_to_assets PASS
08 donation_attack FAIL
09 overflow_protection PASS
10 rounding_direction PASS
11 access_control_probing PASS
Live checker
The web checker runs the same CLI on a hosted backend, against Stellar Testnet:
https://aegisvault.site
Quick start
In the browser. Open aegisvault.site, paste a vault
contract address, and run the check.
With the CLI.
-
Install the prerequisites and create the seven
testnet identities.
-
Get the binary: download a release or
build from source.
-
Run it:
./sep56-vault-guard --vault <CONTRACT_ADDRESS> --output text
A run usually takes about a minute, sometimes longer, because every check is a
chain of network round trips to testnet. If the vault's underlying asset is a
custom token rather than native XLM, read the
integration guide first.
What a run does to the vault
Testnet only. The network is fixed to testnet in cli/src/rpc.rs; there is no
flag to point this at mainnet.
The 7 conformance checks change the target vault's state. They call
deposit, mint, withdraw and redeem on the vault you pass to --vault,
using testnet funds from your own identities, and assert the exact total_assets
deltas those calls produce. Running the checker against a vault is not a
read-only operation.
The 4 security checks run against throwaway copies. Each one resolves the
target vault's Wasm hash, underlying asset and decimals_offset, deploys its own
fresh instance from that same configuration, and attacks the copy. The target
vault is only read.
Because those copies are deployed from the target's own Wasm, the 4 security
checks need the vault contract to accept a constructor of
(name, symbol, asset, decimals_offset) and to expose a query_asset function.
A vault that does not is reported as NOT_APPLICABLE on those four checks, not
as FAIL:
- a constructor that does not accept those arguments gives the reason code
constructor_mismatch;
- a vault without
query_asset (or whose underlying asset has no decimals())
gives not_a_standard_vault.
NOT_APPLICABLE is not a finding about the vault, and it does not change the
exit code (see Exit codes). The 7 conformance checks still run. A
copy that cannot be deployed for any other reason, such as an unreachable
network, is reported as INCONCLUSIVE instead.
Prerequisites
- Stellar CLI v28.0.0 or newer.
The checker starts the
stellar executable directly rather than through a
shell, so on Windows it needs a package that provides stellar.exe — the
official stellar-cli-<version>-x86_64-pc-windows-msvc archive does. A
stellar.cmd or stellar.bat shim works in a terminal but is not found here;
the checker detects that case and says so before running anything.
- A Rust toolchain new enough for edition 2024. Built and tested with
1.98.1. Only needed if you build from source.
- Git. Only needed if you build from source.
Testnet identities
The checks use seven named identities. They are not interchangeable: concurrent
checks are given separate accounts so they do not race each other for
transaction sequence numbers.
alice bob carol dave erin frank grace
This is the beginning of the README. Read the rest at the original. Read the full README ↗
