RFC 2: Metadata Layout

I see three ways in which metadata may be provided in an annotated torrent:

## Directory in torrent

A top level directory in the torrent named `annotations`. The bulk of the metadata is in `annotations/info.bencode`, but may also contain additional files such as timestamps, digital signatures, and public keys.

Pros:

- Allows skipping or delaying downloading large pieces of metadata. Timestamps, public keys, and digital signatures are relatively small, but if many files are timestamped or signed separately, or if many public keys are included, they may add up.

- Data contained within files on disk, as opposed to appearing as entries in a bencoded dictionary, are easier to interact with manually, for example using command line utilities to verify digital signatures and timestamps.

- A non-annotated-torrent-aware torrent client may be used to download a torrent, after which annotated-torrent-aware software may take over to process the data further, which will be easier of the data appears on disk in the torrent, as opposed to in a separate file. (This is also a pro of using a single bencoded dictionary.

Cons:

- Code dealing with a directory full of files is more complex than that for dealing with a single bencoded object.

- If metadata is transmitted out-of-band it will be harder to verify that it has not been tampered with, since it will need to compare hashes of all files in `annotations` directory to the root hashes in the torrent, instead of needing to compare a single file hash.

- Will be necessary to define a transformation from directory to bencoded dictionary if we want to define a format that contains both annotated torrent metadata and `.torrent`.

## Single file in torrent:

A single file in the torrent named `annotations.bencode` containing all metadata.

Pros:

- Simpler library and application logic compared to a directory

- If metadata is transmitted out-of-band, for example in a single augmented `.torrent` file, verifying metadata is easy, as its hash will appear in the `info` dictionary.

Cons:

- Clients can't skip or delay downloading large pieces of metadata

- All metadata appears in a single file, and so cannot be manipulated with command-line utilities that expect, for example, individual digital signatures or timestamps

## In `info` dictionary

An additional entry in the `info` dictionary containing data describing the entire torrent, as well as data describing files under their respective `file tree` entries.

Pros:

+ Single canonical file containing both torrent metainfo and annotated torrent metadata

+ Application logic simplified, since all metadata downloaded, validated, and stored as a single byte stream

+ Most compact representation, since per-file metadata can appear directly in the `file tree` entry, instead of having to duplicate it in another structure

Cons:

- Clients can't avoid downloading metadata

- Users of non-annotated-torrent-aware software won't know that the torrent is annotated

- Non-annotated-torrent-aware software may munge or choke on additional data in metainfo

## In another torrent

Another option is to provide it in a completely different torrent, which references the torrent that actually contains the data.

In this scheme, torrent A would contain the data itself, and torrent B would contain all the annotated torrent metadata, as well as either the infohash, or the complete `.torrent` file.

This would have the advantage that existing torrents could be annotated without needing to reupload them, although there would be some resource overhead from having to track twice as many torrents.

Review issue #6 and compare the four proposed metadata layouts: a directory, a single file, an info-dictionary entry, and another torrent. Since no files, tests, or entry points are named, begin by locating the project’s format or specification materials; done means reaching and documenting a clear layout decision.

Written by the indexing model from the issue text.