Merge pull request #91 from dfns/add-ahtung

Add note about serialization to the key share docs

key-share/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.2.1
+* Add a notice about the serialization to key share docs [#91]
+
+[#91]: https://github.com/dfns/cggmp21/pull/91
+
 ## v0.2.0
 * Add support of HD wallets compatible with BIP-32 and SLIP-10 [#68],
   [#74], [#75]

key-share/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "key-share"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 description = "Key share of any Threshold Signature Scheme (TSS)"
@@ -32,3 +32,7 @@ serde = ["dep:serde", "serde_with", "hex"]
 hd-wallets = ["slip-10"]
 spof = ["dep:rand_core"]
 udigest = ["dep:udigest"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs", "--html-in-header", "katex-header.html"]

key-share/katex-header.html

@@ -0,0 +1,30 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/katex.min.css" integrity="sha384-RZU/ijkSsFbcmivfdRBQDtwuwVqK7GMOw6IMvKyeWL2K5UAlyp6WonmB8m7Jd0Hn" crossorigin="anonymous" type="text/css">
+<script defer src=
+"https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/katex.min.js" integrity="sha384-pK1WpvzWVBQiP0/GjnvRxV4mOb0oxFuyRxJlk6vVw146n3egcN5C925NCP7a7BY8" crossorigin="anonymous" type="text/javascript">
+</script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.13.13/dist/contrib/auto-render.min.js" integrity="sha384-vZTG03m+2yp6N6BNi5iM4rW4oIwk5DfcNdFfxkk9ZWpDriOkXX8voJBFrAO7MpVl" crossorigin="anonymous" type="text/javascript">
+</script>
+<script type="text/javascript">
+document.addEventListener("DOMContentLoaded", function() {
+    renderMathInElement(document.body, {
+        delimiters: [
+            {left: "$$", right: "$$", display: true},
+            {left: "\\(", right: "\\)", display: false},
+            {left: "$", right: "$", display: false},
+            {left: "\\[", right: "\\]", display: true}
+        ],
+        macros: {
+            "\\Zq": "\\mathbb{Z}_q",
+            "\\G": "\\mathbb{G}",
+            "\\T": "\\mathbb{T}",
+            "\\O": "\\mathcal{O}",
+            "\\P": "\\mathcal{P}",
+            "\\V": "\\mathcal{V}",
+            "\\H": "\\mathcal{H}",
+            "\\?": "\\stackrel{?}{=}",
+            "\\ith": "i^{\\text{th}}",
+            "\\sk": "\\text{sk}",
+        },
+    });
+});
+</script>

key-share/src/lib.rs

@@ -88,6 +88,24 @@ use serde_with::As;
 ///   [extended_public_key](DirtyCoreKeyShare::extended_public_key) method).
 ///   * Setting `chain_code` to `None` disables HD wallets support for the key
 /// * Convenient methods are provided such as [derive_child_public_key](DirtyCoreKeyShare::derive_child_public_key)
+///
+/// # Serialization format via `serde`
+/// We make our best effort to keep serialization format the same between the versions (even with breaking changes),
+/// and so far we've never introduced breaking change into the serialization format. This ensures that newer versions
+/// of library are able to deserialize the key shares produced by the old version version of the library.
+///
+/// It's unlikely, but at some point, we might introduce a breaking change into the serialization format. In this case,
+/// we'll announce it and publish the migration instructions.
+///
+/// Not every serde backend supports features that we use to ensure backwards compatibility. We require that field names
+/// are being serialized, that helps us adding new fields as the library grows. We strongly advise using either
+/// [`serde_json`](https://docs.rs/serde_json/), if verbose/human-readable format is needed, or
+/// [`ciborium`](https://docs.rs/ciborium/latest/ciborium/), if you'd like to opt for binary format. Other serialization
+/// backends are not tested and may not work or stop working at some point (like [bincode](https://github.com/dfns/cggmp21/issues/89) did)
+/// or be not backwards compatible between certain versions.
+///
+/// If you need the smallest size of serialized key share, we advise implementing serialization manually (all fields of
+/// the key share are public!).
 #[derive(Clone)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(bound = ""))]