Security model

Grantline enforces authority at the point where a proposal can move Vault capital. The current contracts separate agent intent, Mandate evaluation, controller approval, and Vault execution, so the agent's key is never the Vault authority.

The current enforcement path

Agent signs a typed Action Plan
            ↓
Grantline routes to MandateEvaluator
            ↓
ALLOW / ESCALATE / DENY
            ↓
Grantline routes to VaultExecutor or EscalationManager
            ↓
          Vault

Grantline is the stable public entrypoint for all controller and agent workflows. It routes operations to the correct internal module. The other components are internal modules that do not accept direct external calls.

For a normal execution, VaultExecutor evaluates the signed plan when the execution call is made. An ALLOW result lets it consume the shared nonce, call the Vault, and execute the ordered actions atomically. An ESCALATE result is submitted to EscalationManager, which stores the complete plan and signature for the current Vault controller to approve or deny. The executor evaluates an approved escalation again against current state before it moves capital.

GrantlineAdmin

GrantlineAdmin is a separate non-upgradeable coordinator that manages protocol administration. It has no independent owner; its authority derives from Grantline.owner().

Its responsibilities:

• Module configuration: validates and wires the registry, evaluator, escalation manager, executor, Vault factory, and swap adapters.
• Module upgrades: upgrades internal module proxies through UUPS.
• Vault template changes: sets the implementation used for future Vault proxies.
• Existing Vault upgrades: upgrades individual Vault proxies while preserving authority, owner, pause state, and recorded identity.
• Vault controller reassignment: changes the controller of an existing Vault.
• Adapter validation: checks that swap adapters expose the correct component type, grantline binding, and configuration.

Replacing the coordinator updates one Grantline pointer. The old coordinator loses module and Vault upgrade authority without a module-ownership migration.

The Vault is the capital boundary

The agent signs an Action Plan, but the agent address is not the Vault's execution authority. The Vault accepts its generic execution surface only from the configured authority, which is the executor for the agent-led path. A direct call from the agent therefore cannot turn a valid signature into unrestricted Vault access.

The Vault controller remains responsible for custody and administration. That controller can deposit and withdraw capital, change the Vault authority, transfer ownership, and administer the Mandates that govern the Vault. Routine agent execution does not require the controller to sign each transaction, while configured boundary crossings can require controller approval through Escalation.

Grantline's guarantee is limited to capital held behind this execution boundary. An agent may still obtain another wallet, acquire assets outside the Vault, or use an off-platform resource that Grantline does not control.

Effective authority

The evaluator determines a Mandate's effective authority from its current rules, active ancestor boundaries, and the effective validity window:

effective authority
= current Mandate
  ∩ active ancestor boundaries
  ∩ validity window

Delegation can narrow that result but cannot broaden it. Revoking a Mandate or an ancestor makes the lineage inactive for future evaluation. Pausing an ancestor blocks execution for descendants. The current implementation applies this inheritance to the implemented Mandate limits, escalation permissions, delegation permission, Preflight rules, and validity window.

Effective authority is not the same thing as every check that can affect execution. Preflight is an additional state gate: it checks whether the projected Vault balance remains above the inherited reserve and can return DENY or ESCALATE according to the configured rule. Guardians are a planned way to add external conditions; no Guardian check runs in the current contracts.

Escalation is also separate from ordinary effective authority. It gives the controller a path to review a configured boundary crossing, but approval is tied to the exact stored plan and execution still checks current Mandate state, lineage, nonce state, and conditions.

Authorisation is separate from execution

ALLOW, ESCALATE, and DENY describe what Grantline permits next. They do not describe whether a transaction was mined successfully or whether a downstream asset call accepted the action.

Authorisation: ALLOW
Execution:     FAILED

An authorised transfer can still revert during the Vault call or in a downstream token integration. A read-only DENY returns a result without creating a state change, while a reverted transaction does not preserve events emitted inside that transaction.

Metering is not enforcement

A counter can measure how much authority has been used, but it does not stop capital from moving by itself. A budget becomes an enforcement rule only when the execution path checks the same state before calling the Vault or another capital-holding system. Shared cumulative budgets remain future work, so the current contracts do not claim to enforce a total allowance across siblings.

Current limitations

The current typed action surface supports TRANSFER version 1 and SWAP version 1. TRANSFER does not yet enforce a destination allowlist; an authorised transfer can send capital to any non-zero address. SWAP validates routes through the configured adapter, but adapter support is immutable after one-time module configuration.

See Vaults for the custody model, Action commitments, signatures and nonces for the canonical plan digest, and Transaction lifecycle for the execution and receipt boundary.