Introduction

Blocks

A block contains one or more changes to the state machine. Blocks are typically used as a storage optimization to bundle a set of changes to the state machine. There can be many types of blocks. This specification details the basic set of blocks that all Web Ledgers may express.

Configuration Block

A configuration block specifies which software algorithms should be applied when processing a particular Web Ledger. The first entry in a Ledger is typically an entry called a genesis block. The genesis block has the following basic layout:

{
  "@context": "https://w3id.org/web-ledger/v1",
  "id": BLOCK_ID,
  "type": "LedgerConfigurationBlock",
  "ledgerConfig": {
    "id": LEDGER_ID,
    "type": "LedgerConfiguration",
    "name": "example",
    "description": "This is an example ledger.",
    "storageMechanism": STORAGE_DATA_STRUCTURE,
    "consensusAlgorithm": CONSENSUS_ALGORITHM,
  "previousBlock": {
    "hash": "urn:sha256:0000000000000000000000000000000000000000000000000000000000000000"
  },
  "signature": SIGNATURE_VALUE
}
    

In the example above, LEDGER_ID is used to uniquely identify the ledger (e.g. did:f6ea280f-8011-4502-a29f-464954de3427). BLOCK_ID is used to uniquely identify the block in the ledger (e.g. did:f6ea280f-8011-4502-a29f-464954de3427/blocks/1. STORAGE_DATA_STRUCTURE is used to identify the storage mechanism that is used in the ledger (e.g. SequentialList) so that serializing and deserializing the contents of the ledger remains consistent across ledgers. SIGNATURE_VALUE is used to perform the cryptographic proof that the ledger block was created by the entity identified in the signature. A more complete example of a genesis block is available in the appendix.

A standard configuration block update only differs from a genesis block in that the previousBlock value refers to the block before the current block:

{
  "@context": "https://w3id.org/web-ledger/v1",
  "id": BLOCK_ID,
  "type": "LedgerConfigurationBlock",
  "ledgerConfig": {
    "id": LEDGER_ID,
    "type": "LedgerConfiguration",
    "name": "example",
    "description": "This is an example ledger.",
    "storageMechanism": STORAGE_DATA_STRUCTURE,
    "consensusAlgorithm": CONSENSUS_ALGORITHM,
  "previousBlock": {
    "id": PREVIOUS_BLOCK_ID,
    "hash": PREVIOUS_BLOCK_HASH
  },
  "signature": SIGNATURE_VALUE
}
    

The PREVIOUS_BLOCK_ID is the identifier of the previous block in the ledger (e.g. did:f6ea280f-8011-4502-a29f-464954de3427/blocks/1) and the PREVIOUS_BLOCK_HASH value (e.g. urn:sha256:abd465d34f7a3f0f7d849550eb9fc32c17d12881da6b524da0a96e12cc984538 is a hash of the previous block in the ledger.

Storage Block

A storage block stores data in a ledger and has the following general layout:

{
  "@context": ["https://w3id.org/web-ledger/v1", MARKET_VERTICAL_CONTEXT],
  "id": BLOCK_ID,
  "type": "LedgerStorageBlock",
  "setObject": [ OBJECTS ],
  "previousBlock": {
    "id": PREVIOUS_BLOCK_ID
    "hash": PREVIOUS_BLOCK_HASH
  },
  "signature": SIGNATURE_VALUE
}
    

When storing data in the ledger, one may use a MARKET_VERTICAL_CONTEXT to add semantics to the objects stored in OBJECTS (e.g. https://w3id.org/vaccinations/v1). OBJECTS are one or more JSON objects that can be stored in the ledger. It is expected that each object has a unique identifier to enable searching based on that identifier. A detailed example of a storage event is included in the appendix.

Consensus Block

It's currently not specified in a configuration event how often consensus events should occur. The options are: per event, or every N events. This is an active area of research and debate.

A consensus event is an assertion that there is agreement on a subset of entries in a ledger. Some ledgers do not require consensus events as each event establishes an acceptable level of consensus. Other ledgers require consensus events after a pre-determined amount of time. An example of the basic layout of a consensus event is shown below:

{
  "@context": "https://w3id.org/web-ledger/v1",
  "id": BLOCK_ID,
  "type": "ConsensusBlock",
  "previousBlock": {
    "id": PREVIOUS_BLOCK_ID
    "hash": PREVIOUS_BLOCK_HASH
  },
  "signature": [ SIGNATURES ]
}
    

A consensus event has a relatively simple definition. It consists of a number of SIGNATURES from notaries as determined by the previous configuration event. A more complete example of a consensus event is located in the appendix.

Checkpoint Block

A checkpoint event may be used to quickly bootstrap new mirrors for a ledger. An example of the basic layout of a checkpoint event is shown below:

{
  "@context": "https://w3id.org/web-ledger/v1",
  "id": BLOCK_ID,
  "type": "LedgerCheckpointBlock",
  "checkpointLog": CHECKPOINT_LOG_URL,
  "checkpointLogHash": CHECKPOINT_LOG_HASH,
  "signature": [ SIGNATURES ]
}
    

A checkpoint event declares a CHECKPOINT_LOG_URL (e.g. https://example.org/ledger-agents/example/checkpoints/132) and a CHECKPOINT_LOG_HASH (e.g. urn:sha256:7fa3b9eaa8d92d2b87abf83d88a92ff23). All notaries typically download the checkpoint log and check it before providing signatures noting that the checkpoint log is valid. There is a detailed example of a checkpoint event in the appendix.

How checkpoints are generated are a current topic of debate. The configuration event doesn't specify how often checkpoints can/should happen. It is also debatable that a checkpoint should be included in a consensus event and shouldn't be a separate event.

Discovering Service Endpoints

A website may provide service endpoint discover by embedding JSON-LD in their top-most HTML web page (e.g. at https://example.com/):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Example Website</title>
    <link rel="stylesheet" href="style.css">
    <script src="script.js"></script>
    <script type="application/ld+json">
{
  "@context": "https://w3id.org/discovery/v1",
  "id": "https://example.com/",
  "name": "Example Website",
  "ledgerAgentCreateService": "https://example.com/ledger-agents",
  "ledgerAgentListService": "https://example.com/ledger-agents"
}
    </script>
  </head>
  <body>
    <!-- page content -->
  </body>
</html>
    

Service descriptions may also be requested via content negotiation. In the following example a JSON-compatible service description is provided (e.g. curl -H "Accept: application/json" https://example.com/):

{
  "@context": "https://w3id.org/discovery/v1",
  "id": "https://example.com/",
  "name": "Example Website",
  "ledgerAgentCreateService": "https://example.com/ledger-agents",
  "ledgerAgentListService": "https://example.com/ledger-agents"
}
    

Agent Create Service

A ledger is created by performing an HTTP POST of a LedgerConfigurationBlock to the ledgerAgentCreateService. The following HTTP status codes are defined for this service:

An example exchange of a ledger creation is shown below:

POST /ledger-agents HTTP/1.1
Host: example.com
Content-Type: application/ld+json
Content-Length: 1062
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate

{
  "@context": "https://w3id.org/web-ledger/v1",
  "id": "did:1628bf39-c8f9-453f-93d7-0fbdebb3dfef/blocks/1",
  "type": "LedgerConfigurationBlock",
  "ledgerConfig": {
    "id": "did:1628bf39-c8f9-453f-93d7-0fbdebb3dfef",
    "type": "LedgerConfiguration",
    "name": "example",
    "description": "An example ledger.",
    "storageMechanism": "SequentialList",
    "consensusAlgorithm": {
      "type": "ProofOfSignature2016",
      "approvedSigner": [
        "http://blue.example.com/keys/234",
        "http://red.example.com/keys/987",
      ],
      "minimumSignaturesRequired":1
    }
  },
  "previousBlock": {
    "hash": "urn:sha256:0000000000000000000000000000000000000000000000000000000000000000"
  },
  "signature": {
    "type": "RsaSignature2016",
    "created": "2016-10-14T18:35:33Z",
    "creator": "http://blue.example.com/keys/234",
    "signatureValue": "HvfvRQ57EO...J0Q=="
  }
}
    

If the creation of the ledger was successful, an HTTP 201 status code is expected in return:

HTTP/1.1 201 Created
Location: http://ledger.example.com/ledger-agents/example
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Date: Fri, 14 Oct 2016 18:35:33 GMT
Connection: keep-alive
Transfer-Encoding: chunked
    

Agent List Service

One can get a list of active ledgers on a server by performing an HTTP GET on the ledgerListService. The following HTTP status codes are defined for this service:

An example exchange of getting a list of ledgers on an HTTP server is shown below:

GET /ledger-agents HTTP/1.1
Host: example.com
Connection: keep-alive
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8
    

If retrieving the list of ledgers is successful, a HTTP 200 response is expected:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Access-Control-Allow-Origin: *
Vary: Accept, Accept-Encoding
Content-Type: application/ld+json; charset=utf-8
Etag: W/"91d-mHiDWL0kix4rxP7JCtfVCA"
Content-Encoding: gzip
Date: Fri, 14 Oct 2016 18:46:04 GMT
Connection: keep-alive
Transfer-Encoding: chunked

{
  "ledgerAgent": [
    {
      "id": "https://example.com/ledger-agents/example",
      "name": "example",
      "ledgerAgentStatusService": "https://example.com/ledger-agents/example",
      "ledgerQueryService": "https://example.com/ledger-agents/example/query",
      "ledgerEventService": "https://example.com/ledger-agents/example/events",
      "ledgerBlockService": "https://example.com/ledger-agents/example/blocks",
      "ledgerConfig": {
        "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30",
        "type": "LedgerConfiguration",
        "name": "example",
        "description": "An example ledger.",
        "storageMechanism": "SequentialList",
        "consensusAlgorithm": {
          "type": "ProofOfSignature2016",
          "approvedSigner": [
            "https://blue.example.com/keys/234",
            "https://red.example.com/keys/789"
          ],
          "minimumSignaturesRequired": 1
        }
      },
      "latestBlock": {
        "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/1",
        "hash": "urn:sha256:7eb0603c9a3982284c7db09b1eb40bc85a1177bdc594b027fba0e746b79db15b"
      },
      "nextBlock": {
        "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/2"
      }
    },
    {
      ... NEXT_LEDGER_IN_LIST ...
    }
  ]
}
    

Agent Status Service

The metadata related to a ledger agent may be fetched by performing an HTTP GET on the ledgerAgentStatusService. The following HTTP status codes are defined for this service:

An example exchange of fetching metadata for a ledger is shown below:

GET /ledger-agents/example HTTP/1.1
Host: example.com
Connection: keep-alive
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8
    

If retrieving the ledger metadata is successful, an HTTP 200 response is expected:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Access-Control-Allow-Origin: *
Vary: Accept, Accept-Encoding
Content-Type: application/ld+json; charset=utf-8
Etag: W/"91d-mHiDWL0kix4rxP7JCtfVCA"
Content-Encoding: gzip
Date: Fri, 14 Oct 2016 18:46:04 GMT
Connection: keep-alive
Transfer-Encoding: chunked

{
  "id": "https://example.com/ledger-agents/example",
  "name": "example",
  "ledgerAgentStatusService": "https://example.com/ledger-agents/example",
  "ledgerQueryService": "https://example.com/ledger-agents/example/query",
  "ledgerEventService": "https://example.com/ledger-agents/example/events",
  "ledgerBlockService": "https://example.com/ledger-agents/example/blocks",
  "ledgerConfig": {
    "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30",
    "type": "LedgerConfiguration",
    "name": "example",
    "description": "An example ledger.",
    "storageMechanism": "SequentialList",
    "consensusAlgorithm": {
      "type": "ProofOfSignature2016",
      "approvedSigner": [
        "https://blue.example.com/keys/234",
        "https://red.example.com/keys/789"
      ],
      "minimumSignaturesRequired":1
    }
  },
  "latestBlock": {
    "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/1",
    "hash": "urn:sha256:7eb0603c9a3982284c7db09b1eb40bc85a1177bdc594b027fba0e746b79db15b"
  },
  "nextBlock": {
    "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/2"
  }
}
    

Ledger Append Service

Appending to a ledger can be achieved by performing an HTTP POST of a LedgerStorageBlock to the ledgerAppendService. The following HTTP status codes are defined for this service:

An example of an event being appended to a ledger is shown below:

POST /ledger-agents/example/events HTTP/1.1
Host: example.com
Connection: keep-alive
Content-Length: 1054
Content-Type: application/json;charset=UTF-8
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8

{
  "@context": ["https://w3id.org/web-ledger/v1", "https://w3id.org/fema/v1"],
  "type": "LedgerStorageEvent",
  "setObject": [{
    "id": "https://fema.gov/credentials/9754457",
    "type": ["Credential", "EmergencyResponderCredential"],
    "claim": {
      "id": "did:bc380e48-a6d9-4602-ab20-1beb403d4bcc",
      "emsLicense": {
        "id": "ems:FF-12-01655",
        "status": "valid"
      }
    }
  }],
  "signature": {
    "type": "RsaSignature2016",
    "created": "2016-10-14T19:47:15Z",
    "creator": "https://example.com/keys/fema-key-1",
    "signatureValue": "JoS27wqaTX...s0mpBFMgXIMw=="
  }
}
    

If the storage attempt is successful, a HTTP 200 response is expected:

HTTP/1.1 201 Created
Location: https://example.com/ledger-agents/example/events?id=d1328828-3d44-4e14-9c3a-263af54ed032
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Date: Fri, 14 Oct 2016 19:47:16 GMT
Connection: keep-alive
Transfer-Encoding: chunked
    

Ledger Block Service

A ledger read for an block is achieved by performing an HTTP GET on a ledger block identifier. The list of ledger blocks is available by performing an HTTP GET on the ledgerBlockService. The following HTTP status codes are defined for this service:

An example retrieval of a ledger block is shown below:

GET /ledger-agents/example/blocks?id=did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/2 HTTP/1.1
Host: example.com
Connection: keep-alive
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8
    

If the ledger block retrieval is successful, a HTTP 200 response is expected:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Access-Control-Allow-Origin: *
Vary: Accept, Accept-Encoding
Content-Type: application/ld+json; charset=utf-8
Etag: W/"41e-PJKXv/OxofX29WykKb3PZg"
Content-Encoding: gzip
Date: Fri, 14 Oct 2016 20:20:44 GMT
Connection: keep-alive
Transfer-Encoding: chunked

{
  "@context": ["https://w3id.org/web-ledger/v1", "https://w3id.org/fema/v1"],
  "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/2",
  "type": "LedgerStorageBlock",
  "setObject": [{
    "id": "https://fema.gov/credentials/9754457",
    "type": ["Credential", "EmergencyResponderCredential"],
    "claim": {
      "id": "did:bc380e48-a6d9-4602-ab20-1beb403d4bcc",
      "emsLicense": {
        "id": "ems:FF-12-01655",
        "status": "valid"
      }
    }
  }],
  "previousBlock": {
    "id": "did:de7adbe7-79f2-425a-9dfb-76a234782f30/blocks/1",
    "hash": "urn:sha256:7eb0603c9a3982284c7db09b1eb40bc85a1177bdc594b027fba0e746b79db15b"
  },
  "signature": {
    "type": "RsaSignature2016",
    "created": "2016-10-14T19:47:15Z",
    "creator": "http://example.com/keys/789",
    "signatureValue": "JoS27wqa...BFMgXIMw=="
  }
}
    

Ledger Query Service

The current state machine of a ledger may be queried by performing an HTTP GET on the ledgerQueryService. The following HTTP status codes are defined for this service:

An example query of a state machine in a ledger is shown below:

GET /ledger-agents/example/query?id=http://www.coupon-clearing.org/coupons/486211708 HTTP/1.1
Host: example.com
Connection: keep-alive
Accept: application/ld+json, application/json, text/plain, */*
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8
    

If the query is successful, a HTTP 200 response is expected:

{
  "id": "http://www.coupon-clearing.org/coupons/486211708",
  "type": ["Credential", "DiscountCoupon"],
  "claim": {
    "id": "upc:956578900933",
    "discount": "$3",
    "description": "Discount when you buy 5 pounds of JuicyGreen Apples",
    "status": "redeemed"
  }
}