Messages

All data requests in a DWN are made in Message JSON objects. These messages contain all data required to process a request in a DWN network including execution parameters, signing/encryption information, signatures, and authorization material. Messages can be modified or changed to fit the needs of a developer provided the data stored follows the Message Object’s format and has an accompanied Schema to store the data.

Basic Message Object(Without Signing or Authorization)

 {  // Request Object
  "messages": [  // Message Objects
    {
      "recordId": GENERATED_CID_STRING,
      "data": BASE64URL_STRING,
      "descriptor": {
        "method": INTERFACE_METHOD_STRING,
        "dataCid": DATA_CID_STRING,
        "dataFormat": DATA_FORMAT_STRING,
      },
      "processing": {
        "nonce": "4572616e48616d6d65724c61686176",
        "author": "did:example:alice",
        "recipient": "did:example:bob",
      }
    },
    {...}
  ]
}

In order to enable data replication features for a DWN, all data listed above must be included in a Message Object. More information on the specific formatting of Message Objects can be found here.

Signed Data

If the Message is to be attested by the signer(the owner of the Node) then it must be formatting as the following:

{ // Message
  "data": {...},
  "recordId": "b65b7r8n7bewv5w6eb7r8n7t78yj7hbevsv567n8r77bv65b7e6vwvd67b6",
  "descriptor": {
    "method": "CollectionsWrite",
    "schema": "https://schema.org/InviteAction",
    "dataCid": CID(data),
    "dateCreated": 123456789,
    "dataFormat": "application/json"
  },
  "processing": {
    "nonce": "4572616e48616d6d65724c61686176",
    "author": "did:example:alice",
    "recipient": "did:example:bob",
  },
  "attestation": {
    "payload": "89f5hw458fhw958fq094j9jdq0943j58jfq09j49j40f5qj30jf",
    "signatures": [{
      "protected": "4d093qj5h3f9j204fq8h5398hf9j24f5q9h83402048h453q",
      "signature": "49jq984h97qh3a49j98cq5h38j09jq9853h409jjq09h5q9j4"
    }]
  }
  ...
}

This object must include an attestation property that contains a signature and payload. More information on this object’s formatting can be found here

Authorization

Messages may require authorization if the DWN owner set permissions to require it. A message must include an authorization property that is a JSON Web Signature(JWS) if it requires authorization. It's format is as follows:

{  // Request Object
  "messages": [  // Message Objects
      "data": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "recordId": "b65b7r8n7bewv5w6eb7r8n7t78yj7hbevsv567n8r77bv65b7e6vwvd67b6",
      "descriptor": {
        "method": "CollectionsWrite",
        "schema": "https://schema.org/SocialMediaPosting",
        "dataCid": CID(data),
        "dateCreated": 123456789,
        "dataFormat": "application/json"
      },
      "processing": {
        "nonce": "4572616e48616d6d65724c61686176",
        "author": "did:example:alice",
        "recipient": "did:example:bob",
      },
      "attestation": {
        "payload": "89f5hw458fhw958fq094j9jdq0943j58jfq09j49j40f5qj30jf",
        "signatures": [{
          "protected": "4d093qj5h3f9j204fq8h5398hf9j24f5q9h83402048h453q",
          "signature": "49jq984h97qh3a49j98cq5h38j09jq9853h409jjq09h5q9j4"
        }]
      },
      "authorization": {
        "payload": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
        "signatures": [{
          "protected": "f454w56e57r68jrhe56gw45gw35w65w4f5i54c85j84wh5jj8h5",
          "signature": "5678nr67e56g45wf546786n9t78r67e45657bern797t8r6e5"
        }]
      }
    },
    {...}
  ]
}

Unlike the basic Message Object, the authorization property includes payload and signature data in order to properly process a Message. More information on this object’s formatting can be found here.

Encrypted Data

All encrypted Messages must include the following:

{ // Message
  "data": { 
    "protected": ...,
    "recipients": ...,
    "ciphertext": ...,
    "iv": ...,
    "tag": ... 
  },
  "recordId": "b65b7r8n7bewv5w6eb7r8n7t78yj7hbevsv567n8r77bv65b7e6vwvd67b6",
  "descriptor": {
    "method": "CollectionsQuery",
    "schema": "https://schema.org/SocialMediaPosting"
  },
  "processing": {
    "nonce": "4572616e48616d6d65724c61686176",
    "author": "did:example:alice",
    "recipient": "did:example:bob",
  }
  ...
}

The additional information under "data" is used for message encryption and utilizes JSON Web Encryption. More information on message encryption can be found here