Mixnet integration (#1346)

See #1345, <https://github.com/paritytech/substrate/pull/14207>.

This adds all the necessary mixnet components, and puts them together in
the "kitchen-sink" node/runtime. The components added are:

- A pallet (`frame/mixnet`). This is responsible for determining the
current mixnet session and phase, and the mixnodes to use in each
session. It provides a function that validators can call to register a
mixnode for the next session. The logic of this pallet is very similar
to that of the `im-online` pallet.
- A service (`client/mixnet`). This implements the core mixnet logic,
building on the `mixnet` crate. The service communicates with other
nodes using notifications sent over the "mixnet" protocol.
- An RPC interface. This currently only supports sending transactions
over the mixnet.

---------

Co-authored-by: David Emett <dave@sp4m.net>
Co-authored-by: Javier Viola <javier@parity.io>

substrate/primitives/core/src/crypto.rs

@@ -1161,6 +1161,8 @@ pub mod key_types {
 	pub const STAKING: KeyTypeId = KeyTypeId(*b"stak");
 	/// A key type for signing statements
 	pub const STATEMENT: KeyTypeId = KeyTypeId(*b"stmt");
+	/// Key type for Mixnet module, used to sign key-exchange public keys. Identified as `mixn`.
+	pub const MIXNET: KeyTypeId = KeyTypeId(*b"mixn");
 	/// A key type ID useful for tests.
 	pub const DUMMY: KeyTypeId = KeyTypeId(*b"dumy");
 }

substrate/primitives/mixnet/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+description = "Substrate mixnet types and runtime interface"
+name = "sp-mixnet"
+version = "0.1.0-dev"
+license = "Apache-2.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2021"
+homepage = "https://substrate.io"
+repository = "https://github.com/paritytech/substrate/"
+readme = "README.md"
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "3.6.1", default-features = false, features = ["derive"] }
+scale-info = { version = "2.5.0", default-features = false, features = ["derive"] }
+sp-api = { default-features = false, path = "../api" }
+sp-application-crypto = { default-features = false, path = "../application-crypto" }
+sp-std = { default-features = false, path = "../std" }
+
+[features]
+default = [ "std" ]
+std = [
+	"codec/std",
+	"scale-info/std",
+	"sp-api/std",
+	"sp-application-crypto/std",
+	"sp-std/std",
+]

substrate/primitives/mixnet/README.md

@@ -0,0 +1,3 @@
+Substrate mixnet types and runtime interface.
+
+License: Apache-2.0

substrate/primitives/mixnet/src/lib.rs

@@ -0,0 +1,24 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Substrate mixnet types and runtime interface.
+
+#![warn(missing_docs)]
+#![cfg_attr(not(feature = "std"), no_std)]
+
+pub mod runtime_api;
+pub mod types;

substrate/primitives/mixnet/src/runtime_api.rs

@@ -0,0 +1,52 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Runtime API for querying mixnet configuration and registering mixnodes.
+
+use super::types::{Mixnode, MixnodesErr, SessionIndex, SessionStatus};
+use sp_std::vec::Vec;
+
+sp_api::decl_runtime_apis! {
+	/// API to query the mixnet session status and mixnode sets, and to register mixnodes.
+	pub trait MixnetApi {
+		/// Get the index and phase of the current session.
+		fn session_status() -> SessionStatus;
+
+		/// Get the mixnode set for the previous session.
+		fn prev_mixnodes() -> Result<Vec<Mixnode>, MixnodesErr>;
+
+		/// Get the mixnode set for the current session.
+		fn current_mixnodes() -> Result<Vec<Mixnode>, MixnodesErr>;
+
+		/// Try to register a mixnode for the next session.
+		///
+		/// If a registration extrinsic is submitted, `true` is returned. The caller should avoid
+		/// calling `maybe_register` again for a few blocks, to give the submitted extrinsic a
+		/// chance to get included.
+		///
+		/// With the above exception, `maybe_register` is designed to be called every block. Most
+		/// of the time it will not do anything, for example:
+		///
+		/// - If it is not an appropriate time to submit a registration extrinsic.
+		/// - If the local node has already registered a mixnode for the next session.
+		/// - If the local node is not permitted to register a mixnode for the next session.
+		///
+		/// `session_index` should match `session_status().current_index`; if it does not, `false`
+		/// is returned immediately.
+		fn maybe_register(session_index: SessionIndex, mixnode: Mixnode) -> bool;
+	}
+}

substrate/primitives/mixnet/src/types.rs

@@ -0,0 +1,100 @@
+// This file is part of Substrate.
+
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Mixnet types used by both host and runtime.
+
+use codec::{Decode, Encode};
+use scale_info::TypeInfo;
+use sp_std::vec::Vec;
+
+mod app {
+	use sp_application_crypto::{app_crypto, key_types::MIXNET, sr25519};
+	app_crypto!(sr25519, MIXNET);
+}
+
+/// Authority public session key, used to verify registration signatures.
+pub type AuthorityId = app::Public;
+/// Authority signature, attached to mixnode registrations.
+pub type AuthoritySignature = app::Signature;
+
+/// Absolute session index.
+pub type SessionIndex = u32;
+
+/// Each session should progress through these phases in order.
+#[derive(Decode, Encode, TypeInfo, PartialEq, Eq)]
+pub enum SessionPhase {
+	/// Generate cover traffic to the current session's mixnode set.
+	CoverToCurrent,
+	/// Build requests using the current session's mixnode set.
+	RequestsToCurrent,
+	/// Only send cover (and forwarded) traffic to the previous session's mixnode set.
+	CoverToPrev,
+	/// Disconnect the previous session's mixnode set.
+	DisconnectFromPrev,
+}
+
+/// The index and phase of the current session.
+#[derive(Decode, Encode, TypeInfo)]
+pub struct SessionStatus {
+	/// Index of the current session.
+	pub current_index: SessionIndex,
+	/// Current session phase.
+	pub phase: SessionPhase,
+}
+
+/// Size in bytes of a [`KxPublic`].
+pub const KX_PUBLIC_SIZE: usize = 32;
+
+/// X25519 public key, used in key exchange between message senders and mixnodes. Mixnode public
+/// keys are published on-chain and change every session. Message senders generate a new key for
+/// every message they send.
+pub type KxPublic = [u8; KX_PUBLIC_SIZE];
+
+/// Ed25519 public key of a libp2p peer.
+pub type PeerId = [u8; 32];
+
+/// Information published on-chain for each mixnode every session.
+#[derive(Decode, Encode, TypeInfo)]
+pub struct Mixnode {
+	/// Key-exchange public key for the mixnode.
+	pub kx_public: KxPublic,
+	/// libp2p peer ID of the mixnode.
+	pub peer_id: PeerId,
+	/// External addresses for the mixnode, in multiaddr format, UTF-8 encoded.
+	pub external_addresses: Vec<Vec<u8>>,
+}
+
+/// Error querying the runtime for a session's mixnode set.
+#[derive(Decode, Encode, TypeInfo)]
+pub enum MixnodesErr {
+	/// Insufficient mixnodes were registered for the session.
+	InsufficientRegistrations {
+		/// The number of mixnodes that were registered for the session.
+		num: u32,
+		/// The minimum number of mixnodes that must be registered for the mixnet to operate.
+		min: u32,
+	},
+}
+
+impl sp_std::fmt::Display for MixnodesErr {
+	fn fmt(&self, fmt: &mut sp_std::fmt::Formatter) -> sp_std::fmt::Result {
+		match self {
+			MixnodesErr::InsufficientRegistrations { num, min } =>
+				write!(fmt, "{num} mixnode(s) registered; {min} is the minimum"),
+		}
+	}
+}