Skip to content

Documentation

Onyx documentation

Reference for the Onyx vault program on Solana: roles, transfer rules, holds, emergency actions and rule changes. Each section describes behavior enforced by the program.

1. Overview

An Onyx vault is an account of the Onyx program, owned by a standard Solana wallet. The owner's wallet signs every action. Each outgoing transfer is evaluated against the vault's rules before it executes:

  • Routine transfers execute immediately: amounts within the instant limit, and transfers to saved addresses, within the daily limit.
  • High-risk actions are held for the hold delay: large transfers to new addresses, transfers beyond the daily limit, tokens without a rule, and any change that loosens the rules.
  • During a hold, the owner or guardian can cancel the action, freeze the vault, or rescue its balances to the safe harbor. No one, including the owner, can end a hold early.

Anyone holding the owner key has the same permissions as the owner. For that reason every high-risk action is time-locked, which gives the owner time to detect and respond.

Design note. On Solana, a transaction's position in a block can be bought with priority fees and bundles, so an attacker can always outbid the owner. Protection must therefore be enforced by the vault's own rules, through the hold.

2. Getting started

  1. Wallet. Install a Solana wallet such as Phantom, Solflare or Backpack, switch it to Solana's test network, and fund it with test SOL for fees (faucet.solana.com).
  2. Connect. Open the vault app and connect the wallet. The app connects only to Solana's test network.
  3. Safe harbor. Choose a backup wallet on a separate device with its own seed phrase. It is the only destination a rescue can use, and it cannot be the owner wallet or the vault.
  4. Create the vault. Select a preset, optionally add a guardian and saved addresses, and confirm. A single transaction creates the vault and its rules.
  5. Deposit. Transfer SOL or USDC into the vault. Test USDC is available from Circle's faucet (faucet.circle.com).
  6. Verify. Send a small amount, which executes immediately, then a larger amount to a new address, which is held, and cancel it.

The demo vault applies the same rules in the browser with simulated balances and requires no wallet.

3. Roles and permissions

Owner
The wallet that controls the vault. It transfers funds, changes rules and roles, and holds every permission of the guardian.
Safe harbor
The backup address that receives rescued funds. It has no permissions over the vault. It must use a different seed phrase on a different device: if the same compromise reaches both the owner key and the safe harbor, a rescue would send funds to the attacker.
Guardian (optional)
A second trusted address with protective permissions only: cancel, freeze, remove token delegates and rescue to the safe harbor. It cannot send funds elsewhere, change rules or release a hold. An automated guardian service is planned; until it is available, the owner acts as their own guardian.
ActionOwnerGuardian
Transfer within the rulesYesNo
Cancel a held transfer or changeYesYes, except guardian changes
Freeze the vaultYesYes
Remove a token delegateYesYes
Rescue to the safe harborYesYes, to the safe harbor only
Tighten a ruleImmediatelyNo
Loosen a rule, or unfreezeAfter the hold delayCan cancel
Change the safe harborAfter 7 daysCan cancel
Transfer ownershipAfter 7 daysCan cancel
Change or remove the guardianAfter the hold delayCannot block
Release a hold earlyNot possibleNot possible

4. Transfer rules

Hold delay
The time a held action waits before it can execute. Configurable from 1 hour to 7 days.
Instant limit (per token)
The largest single transfer to an unsaved address that executes immediately.
Daily limit (per token)
The total that can leave the vault instantly within a 24-hour window. The window starts with the first instant transfer after the previous window ended, so up to twice the limit can leave around a window boundary. Without a daily limit, no transfer of that token to an unsaved address executes instantly.
Token rules
Each token's limits are stored in a separate rule. Transfers of a token without a rule are always held, so an unconfigured token cannot leave instantly.
Saved addresses
Recipients approved by the owner. Transfers to them bypass the instant limit but count toward the daily limit.

5. Presets

Default rule sets applied at vault creation. Every value can be changed later.

PresetHold delayInstant limitDaily limit
Conservative48 hours0.05 SOL · 5 USDC0.2 SOL · 20 USDC
Balanced24 hours0.25 SOL · 25 USDC1 SOL · 100 USDC
Active6 hours1 SOL · 100 USDC5 SOL · 500 USDC

6. Hold reasons

The vault transfers only SOL and tokens. It cannot call a program chosen by the caller, sign approvals or perform swaps. Each held transfer records one of the following reasons:

ReasonApplies toNotes
NEW_ADDRESSA transfer to an address that is not saved, above the instant limit.If the token has no daily limit, every transfer of it to an unsaved address is held, regardless of amount.
DAILY_LIMITA transfer that would exceed the token's daily limit.Counts every instant transfer in the current window, including transfers to saved addresses.
NO_RULEAny transfer of a token the vault has no rule for.Applies to saved addresses as well. Adding a rule is a loosening and is also held.
FROZENEvery transfer while the vault is frozen.Held transfers cannot execute until the vault is unfrozen.
POLICY_LOOSENAny change that reduces the vault's protection.See section 9, Rule and role changes.
MANUALA transfer the owner chose to hold.The transfer was eligible to execute instantly.

7. Hold execution

  • A held transfer can execute once its hold delay has passed.
  • After the delay, the owner executes it from the app. The owner can also enable public execution on the Rules page, which allows anyone to trigger a due transfer; funds still go only to the recipient recorded in the hold.
  • A held transfer executes exactly as recorded. Its recipient and amount cannot be changed.
  • Held transfers cannot execute while the vault is frozen.
  • No hold can be released early.

8. Emergency actions

Cancel
Permanently stops a held transfer or a pending change. Available to the owner and the guardian at any time before execution; only the owner can cancel a guardian change.
Freeze
Takes effect immediately. Every transfer is held and no held transfer can execute. Pending rule and role changes can still be applied once their delay has passed. Unfreezing is a loosening and waits for the hold delay.
Remove delegate
Clears any delegate on one of the vault's token accounts. The vault never sets a delegate itself; this action is a safeguard. Takes effect immediately and is available to the owner and the guardian.
Rescue
Moves the vault's SOL (above its rent reserve) and token balances to the safe harbor, or to the safe harbor's token account for each token. The app rescues SOL and every token it displays in one action; any other token requires its own rescue instruction. A rescue has no configurable destination.

Recommended response to an unrecognized held transfer: cancel it, freeze the vault, and rescue its balances to the safe harbor. Then move to a new wallet, as the owner key should be treated as compromised.

9. Rule and role changes

  • Tightening takes effect immediately: a longer hold delay, lower limits, removing a saved address or a token rule, and freezing.
  • Loosening waits for the hold delay: a shorter delay, higher limits, a new token rule, adding a saved address, enabling or disabling a daily limit, and unfreezing. The guardian can cancel it.
  • Safe harbor and ownership changes wait 7 days, regardless of the hold delay, and the guardian can cancel them.
  • Guardian changes wait for the hold delay, and only the owner can cancel them, so a guardian cannot block its own removal. The guardian can never be the safe harbor.

Pending changes are shown in the app until the owner applies them after their delay, or until they are cancelled.

10. Current limitations

  • Test network only. Test SOL and test USDC have no value. Use test funds only.
  • Not audited. The program has automated tests but has not yet had an external audit.
  • Upgradeable. The current program can still be replaced by its deploy key. Whether the mainnet program will be immutable or upgradeable behind a delay will be decided before mainnet and documented here.
  • No guardian service yet. The owner acts as their own guardian.
  • Token issuer powers. A token's issuer can keep a freeze authority over every account, the vault included, and a Token-2022 token can also give its issuer a permanent delegate that can move it. Tokens with transfer hooks cannot be sent or rescued by the vault.

For the threat model and known limitations, see Security.

11. Program and network

Network
Solana's test network
USDC (test)
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Public RPC
https://api.devnet.solana.com

Each vault is a program account at an address derived from its creator and a salt. The program charges no fee and has no admin instruction over any vault. While the program is upgradeable, its deploy key could replace the program itself (see section 10).

12. FAQ

What can someone do with a compromised private key?

Only what your rules allow without delay: sends up to your instant limit, plus sends to addresses you saved, up to your daily limit in total. Anything bigger, and every send of a token without a rule, is held for your hold delay, so you or your guardian can cancel it. The vault can't sign approvals or call any program you choose.

What is the Guardian, and can it take my funds?

An optional second address you add to your vault, like a wallet you keep elsewhere or someone you trust. It can only cancel, freeze, remove token delegates and rescue to your safe harbor. It can't send anywhere else, change your rules or release a hold. An automated Guardian service is planned but not running yet.

What isn't protected?

Funds outside the vault, and whatever your instant and daily limits allow. If one person holds both your key and your safe-harbor wallet, a rescue can't help, so keep the safe harbor on a different device and seed phrase.

Does it cost anything?

Onyx takes no fee: the program has no fee or cut built in. You pay Solana's network fee for each transaction, plus a small rent deposit for the vault and for each hold, rule or saved-address account (a hold's rent goes into the vault when it closes).

Which assets does it hold?

The vault program holds SOL and SPL tokens, with limits set per token. The app shows SOL and Circle's test USDC. Tokens that run extra code on every transfer (transfer hooks) aren't supported, and NFTs aren't either.

Can I use it with real money?

Not yet. The vault program is deployed on Solana's test network only and has not been externally audited. Use test SOL, which has no real value, or the browser demo, which requires no wallet.