Vow

Vow is an event attestation framework for providing on-chain applications with an efficient multi-signed event inclusion statement. The framework is designed to be maximally flexible with minimal gas costs. A single event can be proved for as little as 33'000 gas (1 signer, 1'024-leaf tree).

The project is split into three parts:

• /witness: offchain witness service that indexes blocks, canonicalizes events, builds Merkle roots, signs roots, and serves proofs for individual events.
• /solidity: onchain verification library and witness directory contracts that validate witness signatures plus Merkle proofs and return raw canonical event bytes for consumer-selected decoding.
• /typescript: stateless TypeScript SDK for canonical encoding, Merkle proofs, typed-data signing structures, witness polling, proof merging, and viem-compatible VowLib calls.

Project Goal

Create the cheapest, most flexible, and most efficient cross-chain messaging-adjacent framework possible. Additionally, safety should be built in:

• Finality decisions is determined by witnesses off-chain.
• Multi-vendor solutions throughout the entire stack: Natively support multiple witness, multiple data sources.
• Strong verification and truth policy: Each witness can independently attest to a block event root and each witness can use multiple truth sources.

Strategy

1. Multiple witness operators independently derive the same canonical event set for a block.
2. They compute the same Merkle root and sign a typed message for that root.
3. A client packages one event, its Merkle proof, and witness signatures into a vow payload.
4. Consumer contracts call VowLib.processVow(...) to verify quorum signatures and proof membership, then decode the returned raw event bytes with the strategy they expect.

This gives applications a clear trust model: cryptographic proof of inclusion plus an explicit witness quorum policy.

TypeScript SDK

@vow/protocol is the shared TypeScript package for protocol consumers and witness operators. In this repo, witness/ and web/ consume it locally with file:../typescript; their build/test scripts build the SDK before use, so the package does not need to be published yet. It exposes stateless helpers for the full client flow:

1. Poll one or more witness services with pollWitness / fetchWitnesses.
2. Merge and sort witness attestations with mergeWitnesses.
3. Encode the final bytes vow payload with encodeVow.
4. Validate configured witness signers and call VowLib.processVow through caller-provided viem readContract / estimateContractGas functions.

The SDK intentionally does not own transaction execution or private-key signing. Signing helpers accept an external viem-compatible signTypedData function.