> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy-Gated Execution

> Why protecting a private key is necessary but not sufficient, how policy-gated execution asks a second question of every action, and how the WalletWall Vault research prototype implements bounded spend limits, destination restrictions, timelocks and composable policies.

Most wallet security is about one question: **who can authorize?** Keys are kept offline, split
across signers, rotated, and guarded. That work is necessary. It is not sufficient, because the thing
that eventually calls the key — a signing service, an operator workstation, an automation host — can
be compromised without the key ever leaving its enclosure. A compromised execution path does not need
to steal the key. It only needs to ask the key to sign.

Policy-gated execution adds a second, independent question that is asked even when the first was
answered correctly:

```text theme={null}
Key custody:                Who can authorize?
Policy-gated execution:     What is an authorized path allowed to do?
```

A policy does not make the key safer. It bounds what a valid authorization can achieve: how much, how
often, to whom, how fast, and under what delay. That is the research direction behind the
[WalletWall Vault](https://docs.walletwall.org/features/vault.md) prototype, and this page explains it before the implementation.

> [!WARNING]
>
> **TESTNET · PROTOTYPE · NOT AUDITED**
>
> Everything below describes a **research prototype** in the public
> [`Wallet-Wall/walletwall-vault`](https://github.com/Wallet-Wall/walletwall-vault) repository: not
> audited, deployed to testnets only, holding mock assets, and not production custody. WalletWall the
> application holds no keys and operates no vault. Policy bounds damage; it does not eliminate
> compromise. See [Vault Boundaries & Disclosures](https://docs.walletwall.org/vault/boundaries.md) and
> [what you can use today](https://docs.walletwall.org/concepts/product-status.md).

## Case study: unauthorized withdrawals without a proven key theft

On 29 October 2026 Binance reported unauthorized withdrawals from its wallets, which it estimated
at about \$6.3 billion in assets. Its initial public statements said the incident "may involve a
compromised DevOps engineer's laptop, which allowed an attacker to gain access to a service container
and submit unauthorized withdrawal transactions", and that it had "found no evidence of any wallet
private key leak". A later company statement, reported by The Hacker News, said the investigation had
"uncovered additional points of breach", and the company said it would publish a detailed technical
post-mortem once the investigation is complete. Among independent analysts, Elliptic described the
attacker as having been able to get the exchange's own systems to sign transactions rather than
stealing its keys, and TRM Labs described a batch of authorizations obtained in advance and executed
in one burst.

> [!NOTE]
>
> **This investigation is incomplete at the time of writing (1 November 2026).** No root cause has
> been published. Loss figures vary by source. Attribution has been reported by some analysts and
> agencies and is not asserted here. The statements above are the company's preliminary statements and
> contemporaneous independent reporting, cited below; later reporting may change them.

What the incident supports, as a security principle, is narrow and does not depend on the final
details:

* A system can suffer unauthorized transactions **without demonstrated private-key theft**.
* Protecting keys and protecting execution authorization are **different security boundaries**, and an
  architecture needs both.

What it does not support, and this documentation does not claim:

* that WalletWall or any policy design would have prevented it, or that WalletWall's architecture
  resembles the systems involved;
* that keys did or did not leak, until the final report establishes it;
* any root cause beyond what the company itself has stated;
* any connection to quantum computing.

Sources: Binance,
["Security Incident Update"](https://www.binance.com/en/support/announcement/detail/c5a8729a97ac486d963784d96c5642d7)
(2026-10-30) and its [initial investigation statement](https://x.com/binance/status/2115993361517891592)
(an X post; sign-in may be required);
The Hacker News,
["Binance Suffers Security Breach Affecting \$6.3 Billion in Assets"](https://thehackernews.com/2026/10/binance-suffers-security-breach.html)
(2026-10-30); Al Jazeera,
["Binance says \$6.3bn stolen in biggest crypto heist in history"](https://www.aljazeera.com/economy/2026/10/30/binance-says-2-54bn-in-crypto-funds-frozen-amid-potential-security-issue)
(2026-10-30).

## The second question, in the prototype

The prototype's vault contracts verify a withdrawal's signatures first (an EIP-712 typed message signed
by the vault owner's wallet, plus the hybrid post-quantum path), and then ask the policy question before
any state changes. Every answer is explicit: a permitted action emits events that record what was
allowed, and a refused one reverts with a named error that says why.

```mermaid theme={null}
flowchart TD
    accTitle: Two gates before a vault withdrawal executes
    accDescr: A withdrawal request first passes the authorization gate, which checks the EIP-712 signature, the nonce and the deadline. It then passes the policy gate, where every enabled policy module must approve: the rolling 24-hour spend limit, the recipient allow-list and the sanctions deny list. A small withdrawal executes. A withdrawal above the large-transaction threshold is queued behind a timelock, may require guardian approvals, is revalidated against the current policy at finalization, and only then executes. Any refusal reverts with a named error.
    req["Withdrawal request<br/>owner · recipient · amount · nonce · deadline"]:::input
    auth{"Gate 1 · Who can authorize?<br/>EIP-712 signature, nonce, deadline<br/>hybrid PQ path"}:::decision
    pol{"Gate 2 · What may this path do?<br/>every enabled policy must approve"}:::decision
    spend["Rolling 24-hour spend limit"]:::process
    allow["Recipient allow-list"]:::process
    sanc["Sanctions deny list"]:::process
    large{"Above the large-withdrawal<br/>threshold?"}:::decision
    exec["Execute"]:::output
    queue["Queue behind timelock<br/>guardian quorum if configured"]:::datastore
    reval{"Revalidate against current<br/>policy at finalization (read-only)"}:::decision
    refuse["Revert with a named error"]:::risk
    req --> auth
    auth -->|"invalid"| refuse
    auth -->|"valid"| pol
    pol --> spend --> allow --> sanc --> large
    pol -->|"any module refuses"| refuse
    large -->|"no"| exec
    large -->|"yes"| queue --> reval
    reval -->|"still allowed"| exec
    reval -->|"no longer allowed"| refuse
    classDef input fill:#FAF8F3,stroke:#C9A47A,color:#1E1A14,stroke-width:1.5px;
    classDef process fill:#BF4E32,stroke:#8B3120,color:#FAF8F3,stroke-width:1.5px;
    classDef decision fill:#C9A47A,stroke:#8B6F47,color:#1E1A14,stroke-width:1.5px;
    classDef output fill:#E6DED2,stroke:#9A9186,color:#1E1A14,stroke-width:1.5px;
    classDef risk fill:#8B3120,stroke:#1E1A14,color:#FAF8F3,stroke-width:1.5px;
    classDef datastore fill:#1E1A14,stroke:#9A9186,color:#FAF8F3,stroke-width:1.5px;
```

### Bounded policies

> [accordion] Per-period spend limits
>
> `DailySpendLimitPolicy` caps how much of one asset one vault owner may withdraw through one vault
> during any trailing 24-hour window. It is an exact rolling ledger, not a daily reset: allowance
> returns in the same increments it was consumed, at the instants the individual spends age out.
> Storage is bounded, so a subject that has filled the ledger is refused rather than approximated.
> Spend is booked once, at admission, and never re-booked at finalization.

> [accordion] Destination and action restrictions
>
> `RecipientAllowlistPolicy` admits withdrawals only to recipients the owner has listed, unless the
> owner has deliberately opened the list to any recipient;
> `SanctionsListPolicy` refuses recipients on an administrator-managed deny list. Both are stateless
> predicates over current state, evaluated at admission and again at finalization.

> [accordion] Timelocks and guardian quorum
>
> Withdrawals above a configured threshold are authorized and reserved at queue time, then finalized
> only after a delay, optionally after a quorum of guardians has approved the specific queued
> operation. The owner can cancel a pending withdrawal during the window. Changes to the verifier,
> the policy engine and the large-transaction parameters themselves go through a two-day
> propose-then-apply flow with a bounded grace period, so a pending change cannot be banked and
> sprung later; credential recovery waits seven days behind a guardian quorum.

> [accordion] Composable policy conditions
>
> `CompositePolicyEngine` fans one admission check out to several modules and permits a withdrawal
> only if every active module approves. Composition is deliberately asymmetric: adding a module can
> only strengthen the effective policy and is immediate; removing one can only weaken it and is
> delayed, with the module still enforced throughout the pending window.

> [accordion] Weakening is slow, strengthening is fast
>
> Limit strength is treated as an order, not a number: arming a limit where none existed or lowering
> it applies immediately, while raising or removing a limit is delayed. The design rule, from the
> repository's policy-control authority design, is that a credential capable of spending must not be
> able to instantly weaken the restriction limiting that spending, and an emergency control may
> freeze authority but may never relax it.

> [accordion] Explicit evidence for every decision
>
> Admission happens in `check`, which may book accounting; finalization uses `revalidate`, a read-only
> call that cannot mutate anything, so a misbehaving policy makes finalization fail closed instead of
> corrupting accounting. Custom errors name the refusing condition; events record queueing,
> cancellation, approvals, parameter proposals and recoveries, so a reviewer can reconstruct why an
> action was permitted or refused.

### What this does, and does not, change

| It changes | It does not change |
| - | - |
| A valid signature is no longer sufficient on its own: the action must also fit the policy | Whether a key can be stolen; custody of keys stays with the owner's wallet |
| A compromised path is bounded by rate, destination and delay | A compromised path acting inside those bounds still spends inside them |
| Weakening a protection takes time and is visible | The owner's own governance remains an attack surface that needs its own protection |
| Every permission and refusal leaves an explicit record | The research prototype's status: not audited, testnet only, mock assets |

## Status and limits

The policy contracts, composite engine and timelocked governance described here exist in the public
repository at version 0.13.31 (22 October 2026) and are exercised by its test suite. They are a research
prototype: no audit, no mainnet deployment, no production custody, and no claim that any policy design
would have changed the outcome of any real incident. The post-quantum authorization path in the same
contracts remains a trusted-attestation and mock-verifier path on Ethereum Sepolia, not on-chain ML-DSA
verification; see [PQ Evidence, Testnet Rehearsal & ZK/SP1 Status](https://docs.walletwall.org/vault/pq-evidence-and-rehearsal.md).

The WalletWall application reads and explains; it never holds keys, signs on anyone's behalf or executes
a vault action. The MCP tool `assess_vault_readiness` evaluates whether presented evidence meets the
technical readiness criteria; it does not configure, authorize or execute a vault. The six gates that
would have to be cleared before any production custody consideration are listed in
[Vault Boundaries & Disclosures](https://docs.walletwall.org/vault/boundaries.md), and all six are not started.

## Where to go next

> [card] [Vault Boundaries & Disclosures](https://docs.walletwall.org/vault/boundaries.md)
>
> Custody, financial, testnet and quantum-resistance boundaries, and the six production gates.

> [card] [Key Management & Recovery Model](https://docs.walletwall.org/security/key-management-recovery-model.md)
>
> The non-custodial hard rules and why recovery must be simulated, delayed and cancellable.

> [card] [PQ Evidence, Rehearsal & ZK/SP1 Status](https://docs.walletwall.org/vault/pq-evidence-and-rehearsal.md)
>
> The separate, read-only gates for post-quantum evidence and testnet rehearsal.

> [card] [Vault technical readiness in MCP](https://docs.walletwall.org/mcp/tools.md#assess_vault_readiness)
>
> Evidence-only classification of identity and balance evidence — never vault execution.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.