Protocol

You don't need this page to add Knock to a site. It's for writing a verifier of your own, checking one, or knowing exactly what a knock commits to.

Signed messages

Every signature a Wedgie makes is over an EIP-712 digest it builds itself, from fields it shows or holds. It never signs bytes a computer hands it.

The domain is the same for every message, with no chain and no contract:

const DOMAIN = { name: 'Knock', version: '1' }

The digest is EIP-712's: keccak256(0x1901 ‖ domainSeparator ‖ hashStruct(message)).

KnockPass

struct KnockPass {
    bytes32 challenge;
    string origin;
    bytes32 deviceNode;
    uint64 counter;
    uint8 mode;
    uint256 nullifier;
    bytes32 humanRef;
}

A verifier rebuilds the digest from its own origin and challenge, and the knock's other fields. It never takes the digest from the knock.

Signatures and keys

• Curve: P-256 (secp256r1), ECDSA over the 32-byte digest as it is, with no second hash.
• Signatures: r and s, 32 bytes each, with s at most half the curve order. A high s is refused.
• Keys: knock.key is the 33-byte compressed point, 0x02 or 0x03 and then X, in lowercase hex.
• Key hash: keccak256(X ‖ Y) over the 64-byte uncompressed coordinates. This is how a Bound log names a key.

The key is made on the Wedgie's OPTIGA Trust M chip, and stays there.

ENS records

A Wedgie's name, such as wedgie.itzraj.eth, holds these records on Ethereum mainnet. Verifiers read the first five, through ENS's Universal Resolver.

knock.att, the chip maker's attestation of the key, is reserved and not written yet.

A verifier takes records that are active and the same 3 blocks deep as at the latest block, and reads revoked at the latest block. An expired name has no resolver, so its records read as empty.

The binding

A binding is a successful transaction on KnockBinding v3 on World Chain (chain 480). The contract checks a World ID proof whose signal commits to the Wedgie's key and its name's node, and then logs:

event Bound(uint256 indexed nullifier, bytes32 indexed keyHash, bytes32 indexed node, uint64 expiresAtMin);

A verifier takes a binding when the transaction succeeded, and a log from the production address has Bound's signature and exactly this nullifier, key hash and node as its topics. expiresAtMin tells it roughly when the proof was made, which it holds to VERIFIER_MAX_BINDING_DAYS. Bindings from KnockBinding v1 and v2 never count. contracts/deployments/480.json lists every deployment.

Names and origins

Test vectors

spec/vectors/v1.json has a published test key, and every message above with its type string, struct hash, digest and signature, including a whole knock. Both the TypeScript and Rust sides are tested against it. The key is public, so never use it for anything real.

@knock-dev/protocol

The TypeScript side of all this, in packages/protocol: