Relayer

The relayer bridges your backend API calls to blockchain transactions. Each instance can configure one relayer that signs and submits transactions using a private key stored in your external vault provider. Trusset never holds or sees your private keys - they are fetched at execution time, used to sign, and discarded.

​

How It Works

When your backend calls a Trusset API endpoint that requires an on-chain transaction, the relayer handles execution automatically:

​

Wallet Registration

Before configuring a relayer, you must register and verify ownership of the wallet address that corresponds to your vault-stored private key. Registration uses a signature challenge to prove you control the address. The flow is straightforward: request a nonce for the address, sign the nonce message with the wallet’s private key, and submit the signature. Once verified, the wallet is available for relayer configuration. Each issuer account supports up to 10 registered wallets. The first wallet registered becomes the primary wallet automatically. You can change the primary wallet or remove wallets at any time, provided they are not actively used by a relayer.

​

Vault Providers

The relayer retrieves your private key from an external secrets manager at transaction time. Two providers are supported: You can test vault connectivity before committing to a configuration. The test endpoint verifies that the vault is reachable, the credentials are valid, the secret exists, and the derived wallet address matches a registered wallet.

​

Setup

Configure a relayer for a specific instance through the Issuer Platform or API. The setup process validates your vault connection, verifies the derived address matches a registered wallet, and activates the relayer. Configuration options at setup: Daily transaction counters reset at midnight UTC automatically.

​

Operational Controls

Once active, the relayer provides several management capabilities: Freeze and unfreeze. Immediately halt all relayer transactions by freezing. Frozen relayers reject every transaction attempt until explicitly unfrozen. Use this during security incidents, maintenance windows, or when investigating suspicious activity. An optional reason string is logged for audit purposes. Limit adjustments. Update dailyTxLimit and maxGasPerTx at any time without reconfiguring the vault connection. Changes take effect immediately. Transaction history. Query paginated transaction logs filtered by status (pending, confirmed, failed). Each record includes the transaction hash, target contract, function name, gas used, and timestamp. Removal. Delete the relayer configuration entirely. This does not affect the underlying wallet registration or vault secrets - only the link between the instance and the vault is removed.

​

Security Model

The relayer enforces multiple layers of protection:

• No key storage. Private keys exist only in your vault provider. Trusset fetches them per-transaction and never persists them.
• Address verification. At setup and at every transaction, the system verifies the key derived from the vault matches the configured relayer address. Mismatches halt execution.
• Rate limiting. Daily transaction limits prevent runaway costs or abuse from compromised API keys.
• Gas caps. Optional per-transaction gas limits prevent unexpectedly expensive operations.
• Instance isolation. Each instance has its own independent relayer. Compromising one instance’s relayer has no effect on others.
• Audit logging. Every relayer action (setup, freeze, unfreeze, limit changes, removal) is recorded in the audit log with actor, timestamp, and metadata.