vaults: define explicit feature contract and implementation scope

[timbrinded]

Summary

We need a first-class, explicit vault feature scope in hlgo. Today the low-level plumbing exists (vaultAddress in /exchange wire payloads and vault-aware L1 connection hashing), but there is no productized CLI contract for vault behavior.

This issue defines what vaults are for, why we want them, and which system areas they touch so implementation can proceed intentionally.

What Vaults Are For

Vaults provide explicit account segregation for trading/risk workflows under Hyperliquid's exchange model:

• Isolate strategy/risk buckets from a primary wallet context.
• Route L1 exchange actions to a vault context where the API supports it.
• Support agent/automation setups that need clear account-context boundaries beyond signer identity.

Why We Want Vaults

• Unlock advanced managed-account and strategy-segregation workflows.
• Achieve explicit parity with Hyperliquid API capabilities (vaultAddress) and Python SDK concepts.
• Eliminate ambiguity between delegated account context (account_address / --on-behalf-of) and vault routing.
• Reduce accidental UX drift by defining one canonical contract before exposing CLI surfaces.

Primary References

• Exchange endpoint (vaultAddress semantics):
  • https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint
• Nonces + API wallets context:
  • https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets
• Python SDK references:
  • https://raw.githubusercontent.com/hyperliquid-dex/hyperliquid-python-sdk/master/hyperliquid/exchange.py
  • https://raw.githubusercontent.com/hyperliquid-dex/hyperliquid-python-sdk/master/hyperliquid/utils/signing.py

Interaction Areas (Code + Product)

• pkg/client/client.go
  • /exchange request envelope includes optional vaultAddress.
• pkg/signer/signer.go, pkg/signer/phantom.go
  • L1 connection-id hashing includes vault flag/address bytes.
• pkg/exchange/executor.go
  • Must define where vault input is allowed and how it is threaded to signer/client.
• cmd/* (CLI contract)
  • Decide explicit vault surfaces (e.g. selected L1 commands via --vault-address) and validation rules.
  • Keep account/user-signed flows clearly separated from vault semantics.
• pkg/info/*
  • Confirm whether any read paths need explicit vault-aware querying or documentation.
• skill/hlgo/* + plans/hlgo-technical-spec-v0.1.0.md
  • Update command matrices and safety docs once contract is finalized.

Out of Scope (for initial vault rollout)

• Implicit vault behavior based on signer or config side effects.
• Mixing vault semantics into user-signed account actions without API-backed rationale.
• Top-level vault command group unless justified by concrete API operations and UX value.

Proposed Deliverables

• ADR/spec section: vault contract, terminology, and safety boundaries.
• Command matrix: which commands accept --vault-address and why.
• Validation contract: address format + unsupported-command failure behavior.
• Executor/signer/client plumbing updates where needed.
• Unit tests for wire payload + connection-id hashing with vault address.
• Integration tests for at least one vault-aware L1 action path.
• Skill/docs updates to reflect final contract (no ambiguous wording).

Acceptance Criteria

• Vault behavior is explicit, opt-in, and documented.
• Delegated account context and vault routing are distinct, with no mixed semantics.
• Unsupported vault usage fails loudly with structured validation errors.
• Test coverage includes command, executor, signer, and integration layers.