Add support for initial-state

core.html

@@ -169,6 +169,9 @@ <h2>Recognizing and handling peer DIDs</h2>
         capture group 1, <code>transform</code> in capture group 2, and <code>encnumbasis</code> in capture group 3.
     </p>
 
+    <p>Note that peer DIDs can also be used in DID URIs, with query parameters. Currently, the only query parameter formally defined for peer DIDs is <code>initial-state</code>, discussed <a target="#initial-state">below</a>. However, support for `hl` and `version-id` will be specified soon,
+        and other parameters may be used by a given implementation, so recipients of a peer DID URI should at least be prepared to parse the DID into its base DID value and its query string portion (which begins with the <code>?</code> character. All query parameter values in peer DID URIs are base64url encoded without padding (consistent with JOSE conventions).</p>
+
     <p>A few peer DID values are reserved and convey special meaning. See <a href="#reserved-values">Reserved Values</a>
         in the appendix.
     </p>

did-docs.html

@@ -1,7 +1,5 @@
 <h1>DID docs</h1>
 
-<p>A special, ultra-simple form of DID doc is supported.</p>
-
 <section>
     <h2>Backing Storage</h2>
 
@@ -114,6 +112,37 @@ <h2>CRDTs</h2>
 
 </section>
 
+<section>
+    <h2><code>initial-state</code></h2>
+    <p>
+        Sometimes it is useful (or even required) to communicate a doc-capable peer DID value
+        (one with <code>numalgo</code> != 0) and its genesis or evolved DID doc as a single
+        combined value, instead of sharing the DID as one piece of data, and its DID doc and
+        deltas as another. This situation commonly occurs in connection protocols that are
+        built on <a target="_blank" href="https://identity.foundation/didcomm-messaging/docs/spec/">
+        DIDComm messaging</a>, for example: <var>A</var> wants to share with <var>B</var> the new
+        pairwise DID they've allocated (A.did@A:B), plus the DID's full DID doc (A.diddoc@A:B),
+        and DIDComm requires all information about the sender to be passed in a single
+        <code>from</code> field.
+    </p>
+    <p>
+        The way to do this is to use the <code>initial-state</code> query parameter of a peer
+        DID URI. All implementations of peer DIDs are required to recognize the meaning of this
+        query parameter, though only implementations that support deltas (layer 2 or 3) need to
+        process it. The parameter value can be extracted from a peer DID URI with the following
+        regex:
+    </p>
+    <pre class="example nohighlight" title="Regex to extract initial-state" id="initial-state-regex">
+^did:peer:[^0].+[?](.*&)?initial-state=([^&]*)(?:&|$)
+    </pre>
+    <p>
+        This places the value of the <code>initial-state</code> parameter in capture group 1.
+    </p>
+    <p>To interpret the parameter value, it must first be base64url (minus padding) decoded. The
+        result MUST be a JSON array containing zero or more deltas. An empty parameter value is
+        also allowed, and is considered equivalent to an empty JSON array.</p>
+</section>
+
 <section>
     <h2><code><dfn>publicKey</dfn></code></h2>