Notary Relay

Turn provider webhooks into privacy-filtered evidence.

The Notary Relay is the authorized off-chain service that accepts external HTTPS webhooks, removes sensitive data, records deterministic evidence through VLNotary, and delivers matching receipts to subscribed contracts.

Trust boundary

What the service does—and does not—authorize.

The relay derives an entity from <entity>.notary.vowlabs.dev and an event name from the request path. It obtains the caller IP from a trusted reverse proxy, resolves its PTR service name, parses JSON into deterministic sorted fields, and applies VLNotary’s fixed allowlist plus the entity’s signed denylist. Invalid JSON is recorded as verbatim text. A receipt ID is deterministic for the entity, event, and raw body, so repeated requests are acknowledged without a second notarization.

A contract subscription is routing, not authorization. Every receiving contract must validate the expected Notary address, entity, service, event, schema, account binding, and replay policy before it mints, settles, or otherwise acts.

Request flow

Webhook to callback.

Provider posts. Send an HTTPS request to an entity hostname and colon-separated event path, for example https://priceedge.me.notary.vowlabs.dev/finance:bank:deposit.
Relay filters and normalizes. The service caps body size and fields, removes sensitive keys, and creates canonical structured evidence.
Relay notarizes. Its configured wallet, which must be the relay authorized by VLNotary, submits the evidence on-chain.
Relay delivers. It submits one delivery transaction per matching subscription. A failed callback records a failed delivery without deleting evidence or blocking other subscribers.

Entity PII policy

Control additional filtering with DNS and Ed25519.

Publish an Ed25519 public key in _vlnotary.<entity> as a TXT record using v=vlnotary1; k=ed25519; p=<base64-SPKI-DER>. Keep the private key offline. Use the CLI to sign a compact initializer that adds or clears an entity-specific denylist; the initializer is stored locally and is never notarized.

pnpm -C VowLabs/Offchain notary:init -- keygen \
  --private-key /secure/entity/vlnotary-ed25519.pem

pnpm -C VowLabs/Offchain notary:init -- initialize \
  --url https://entity.notary.vowlabs.dev/finance:bank:deposit \
  --private-key /secure/entity/vlnotary-ed25519.pem \
  --fields ssn,accountNumber,routingNumber

Use DNSSEC and a validating resolver where available. Without DNSSEC, this authorization depends on the resolver path.

Deploy and operate

Service requirements.

Node.js, the Offchain checkout, and npm run notary or the provided deploy/notary-openrc service definition.
A loopback-bound relay behind HTTPS Nginx, configured for entity subdomains of notary.vowlabs.dev.
VL_NOTARY_RPC_URL, VL_NOTARY_RELAY_PRIVATE_KEY, and either VL_NOTARY_CONTRACT_ADDRESS or a deployment manifest.
Persistent writable paths for PII policy and domain-registration state, plus secure backups.
A trusted proxy configuration, DNSSEC-validating resolver, log monitoring, RPC health monitoring, and alerting for rejected webhooks and transaction failures.

See the full operational documentation, VLNotary contract guide, and OpenRC definition.