Skip to content

Architecture

Overview

Gatekeeper is a lightweight decoding & evaluation engine that decouples DeFi transaction decoding & whitelist decision-making from your software.

This allows you to extend an existing transaction processing system to support arbitrarily complex DeFi transactions. You can use Gatekeeper to decode DeFi transactions for Clear Sign display, validate pre-sign in trusted signing environments, or extend a Policy Engine to add DeFi policy rules.

alt text

Terminology

  • Descriptor - Metadata file that tells Gatekeeper how to decode and display transactions.
  • Protocol Preset - Whitelisting rules. A collection of policy rules encoding a specific protocol's expected behavior.
  • Transaction - A signature request (evm transaction, eip712 typed data, or other).
  • Bundle - A signed, packed bundle of descriptors and policies.
  • Bundle Manifest - A file describing the contents of the bundle and verification information (data hash, signature, version).

Deployment Modes

Gatekeeper is packaged as a Docker image and supports flexible deployment configurations. It does not require a database or persistent storage.

Standalone

Run Gatekeeper as a service in your environment. Call it anywhere you need to verify a DeFi transaction is whitelisted or you need Clear Sign decoding for display. This model allows for full control over the deployment and security properties of the infrastructure.

Sidecar

Run Gatekeeper as a sidecar for each decoding or whitelisting decision point. This model minimizes latency by connecting over the local network and inherits the security properties of the host environment. This pattern can be used to first decode a transaction for clear-signing on approval UI, and then performing an additional last-mile pre-sign validation in the trusted environment.

Trusted Execution Environment (TEE)

Gatekeeper can be deployed in a Trusted Execution Environment (TEE) to add TEE-based attestation to your decoding & whitelisting results. Contact Narval for details on TEE configuration.

Bundle Loading

Gatekeeper uses Descriptor metadata files and Protocol Preset whitelisting rules to evaluate transactions at runtime. The "Bundle" is managed externally to Gatekeeper, provided via configuration, and fetched/verified by Gatekeeper.

This decouples management of the Descriptors & Whitelisting rules from the Gatekeeper service itself, enabling centralized management while distributing the evaluation logic.