Weights documents

Bandwidth documents contain aggregate statistics of a relay's or bridge's consumed bandwidth for different time intervals. Bandwidth documents are available for all relays and bridges that have been running in the past week. Bandwidth documents contain the following fields:

Example

{
    "relays_published":"1970-01-01 01:00:00",
    "relays":[{
            "fingerprint":"1111111111111111111111111111111111111111",
            "advertised_bandwidth_fraction":{
                "1_week":{
                    "first":"1970-01-01 01:00:00",
                    "last":"1970-01-02 01:00:00",
                    "interval":3600,
                    "factor":0.00001,
                    "count":170,
                    "values":[1,2,3]
                },
            },
            "consensus_weight_fraction":{
                "1_week":{
                    "first":"1970-01-01 01:00:00",
                    "last":"1970-01-02 01:00:00",
                    "interval":3600,
                    "factor":0.00001,
                    "count":170,
                    "values":[1,2,3]
                }
            }
            "guard_probability":{
                "1_week":{
                    "first":"1970-01-01 01:00:00",
                    "last":"1970-01-02 01:00:00",
                    "interval":3600,
                    "factor":0.00001,
                    "count":170,
                    "values":[1,2,3]
                }
            },
            "middle_probability":{
                "1_week":{
                    "first":"1970-01-01 01:00:00",
                    "last":"1970-01-02 01:00:00",
                    "interval":3600,
                    "factor":0.00001,
                    "count":170,
                    "values":[1,2,3]
                }
            },
            "exit_probability":{
                "1_week":{
                    "first":"1970-01-01 01:00:00",
                    "last":"1970-01-02 01:00:00",
                    "interval":3600,
                    "factor":0.00001,
                    "count":170,
                    "values":[1,2,3]
                }
            }],
    "bridges_published":"1970-01-01 01:00:00",
    "bridges":[]
}

• Property details

• required string relays_published

  UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known relay network status consensus started being valid. Indicates how recent the relay weights documents in this document are.

• required array relays

  Array of objects representing relay weights documents. Required field. Each array object contains the following key-value pairs

  • relays content

  • required string fingerprint

    Relay fingerprint consisting of 40 upper-case hexadecimal characters.

  • optional object advertised_bandwidth_fraction

    History object containing relative advertised bandwidth of this relay compared to the total advertised bandwidth in the network. If there were no bandwidth authorities, this fraction would be a very rough approximation of the probability of this relay to be selected by clients.

    Keys are string representation of the time period covered by the weights history object. Keys are fixed strings "1_week", "1_month", "3_months", "1_year", and "5_years". Keys refer to the last known weights history of a relay, not to the time when the weights document was published. A weights history object is only contained if the time period it covers is not already contained in another weights history object with shorter time period and higher data resolution

    • advertised_bandwidth_fraction content

    • required string first

      UTC timestamp (YYYY-MM-DD hh:mm:ss) of the first data data point in the weights history.

    • required string last

      UTC timestamp (YYYY-MM-DD hh:mm:ss) of the first data data point in the weights history.

    • required number interval

      Time interval between two data points in seconds.

    • required number factor

      Factor by which subsequent weights values need to be multiplied to get the path-selection probability. The idea is that contained weights values are normalized to a range from 0 to 999 to reduce document size while still providing sufficient detail for both slow and fast relays.

    • optional number count

      Number of provided data points, included mostly for debugging purposes. Can also be derived from the number of elements in the subsequent array.

    • required array values

      Array of normalized bandwidth values in bytes per second. May contain null values if the relay did not provide any bandwidth data or only data for less than 20% of a given time period. Only includes non-null values for series of at least two subsequent data points to enable drawing of line graphs.

  • optional object consensus_weight_fraction @see advertised_bandwidth_fraction

    History object containing the fraction of this relay's consensus weight compared to the sum of all consensus weights in the network. This fraction is a very rough approximation of the probability of this relay to be selected by clients.

  • optional object guard_probability @see advertised_bandwidth_fraction

    History object containing the probability of this relay to be selected for the guard position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation.

  • optional object middle_probability @see advertised_bandwidth_fraction

    History object containing the probability of this relay to be selected for the middle position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation.

  • optional object exit_probability @see advertised_bandwidth_fraction

    History object containing the probability of this relay to be selected for the exit position. This probability is calculated based on consensus weights, relay flags, and bandwidth weights in the consensus. Path selection depends on more factors, so that this probability can only be an approximation.