Skip to content

Link to specs & define compatibility requirements #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AlCutter wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Link to specs & define compatibility requirements #46

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ec70180
Link to specs & define compatibility requirements
AlCutter Jul 3, 2026
a12c135
ML-DSA and Ed
AlCutter Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 39 additions & 4 deletions site/content/participate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,28 @@ when meeting the community on conferences and in various chat rooms like:

[archive]: https://lists.witness-network.org/mailman3/hyperkitty/list/participate@lists.witness-network.org/

## Compatibility requirements

Witnesses and logs need to interoperate in order for the witness network to
function. The network, therefore, relies on several of the `tlog` specifications
from the [C2SP](https://c2sp.org) project:

- [tlog-witness][] defines a witness API contract.
- [tlog-checkpoint][] defines how logs must represent their state when
interacting with witnesses.
- [tlog-cosignature][] defines the signature schemes used on `checkpoints`.

@rgdd rgdd Jul 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: work in that the semantics of what a signature means is also defined in tlog-cosignature.


To participate in the witness network:

- Logs and witnesses MUST be compliant with the [`tlog-witness`[]]
specification.
- Witnesses MUST support verification of either `ML-DSA-44` or `Ed25519`
signatures from logs, but SHOULD support both.
- Witnesses MUST return `ML-DSA-44` cosignatures, and MAY also return
`Ed25519` cosignatures.
- Logs and witnesses MAY also additionally support and return other signature
types, e.g. in order to also participate in other networks or ecosystems.

## Log guidelines

### Specify origin line
Expand All @@ -34,8 +56,16 @@ Examples of origin lines:
### Specify public key

Your log signs [checkpoints][] before sending them to [witnesses][]. Specify
the public key in [vkey format][]. Use key type 0x01 (Ed25519). For key name,
we recommend using the same string as the log's origin line.
the public key in [vkey format][]. Keys may be of the following types:

- `0x01` (Ed25519),
- `0x04` (Timestamped Ed25519 cosignature/v1),
- `0x06` (Timestamped ML-DSA-44 cosignature/v1).

but we recommend that logs use type 0x06 (Timestamped ML-DSA-44 cosignature/v1).

For the key name, we strongly recommend using the same string as the log's
origin line.

Examples of public keys:

Expand Down Expand Up @@ -148,8 +178,10 @@ witness is operated? Specify an about page URL.

The about page should at least include:

- The witness public key in [vkey format][]. Use key type 0x04
(cosignature/v1). Similar to logs, we recommend using a schema-less URL for
- The witness public key in [vkey format][]. Use key type `0x06` (Timestamped
ML-DSA-44 cosignature/v1), and, ideally, an additional type `0x04`
(Timestamped Ed25519 consignature/v1) key for compatibility.
Similar to logs, we strongly recommend using a schema-less URL for
the name.
- An [add-checkpoint URL][ac] (which may be referring to a
[bastion-host][bh]).
Expand All @@ -168,3 +200,6 @@ compose something that strikes the right balance for your intended operations.
- [litewitness](https://github.com/FiloSottile/torchwood/blob/main/cmd/litewitness)

[bh]: https://C2SP.org/https-bastion
[tlog-checkpoint]: https://C2SP.org/tlog-checkpoint
[tlog-cosignature]: https://C2SP.org/tlog-cosignature
[tlog-witness]: https://C2SP.org/tlog-witness
Loading