m

MystenLabs · Jan 29, 2025 · 8caa1e5 · 8caa1e5
1 parent b2e5cdb
commit 8caa1e5
Show file tree

Hide file tree

Showing 6 changed files with 256 additions and 41 deletions.
diff --git a/crates/sui-sdk-types/src/crypto/bls12381.rs b/crates/sui-sdk-types/src/crypto/bls12381.rs
@@ -7,8 +7,12 @@
 /// The BCS serialized form for this type is defined by the following ABNF:
 ///
 /// ```text
-/// bls-public-key = 96OCTECT
+/// bls-public-key = %x60 96OCTECT
 /// ```
+///
+/// Due to historical reasons, even though a min-sig `Bls12381PublicKey` has a fixed-length of 96,
+/// Sui's binary representation of a min-sig `Bls12381PublicKey` is prefixed with its length
+/// meaning its serialized binary form (in bcs) is 97 bytes long vs a more compact 96 bytes.
 #[derive(Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(
     feature = "serde",
@@ -19,7 +23,7 @@ pub struct Bls12381PublicKey(
     #[cfg_attr(
         feature = "serde",
         serde(
-            with = "::serde_with::As::<::serde_with::IfIsHumanReadable<super::Base64Array96, [::serde_with::Same; 96]>>"
+            with = "::serde_with::As::<::serde_with::IfIsHumanReadable<super::Base64Array96, ::serde_with::Bytes>>"
         )
     )]
     [u8; Self::LENGTH],

diff --git a/crates/sui-sdk-types/src/crypto/intent.rs b/crates/sui-sdk-types/src/crypto/intent.rs
@@ -8,6 +8,14 @@
 ///
 /// The serialization of an Intent is a 3-byte array where each field is represented by a byte and
 /// it is prepended onto a message before it is signed in Sui.
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// intent = intent-scope intent-version intent-app-id
+/// ```
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct Intent {
     pub scope: IntentScope,
@@ -41,6 +49,15 @@ impl Intent {
     }
 }
 
+/// Byte signifying the scope of an [`Intent`]
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// intent-scope = u8
+/// ```
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u8)]
 #[non_exhaustive]
@@ -56,13 +73,31 @@ pub enum IntentScope {
     ConsensusBlock = 8,    // Used for consensus authority signature on block's digest
 }
 
+/// Byte signifying the version of an [`Intent`]
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// intent-version = u8
+/// ```
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u8)]
 #[non_exhaustive]
 pub enum IntentVersion {
     V0 = 0,
 }
 
+/// Byte signifying the application id of an [`Intent`]
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// intent-app-id = u8
+/// ```
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[repr(u8)]
 #[non_exhaustive]

diff --git a/crates/sui-sdk-types/src/crypto/multisig.rs b/crates/sui-sdk-types/src/crypto/multisig.rs
@@ -16,6 +16,34 @@ const MAX_COMMITTEE_SIZE: usize = 10;
 // TODO validate sigs
 // const MAX_BITMAP_VALUE: BitmapUnit = 0b1111111111;
 
+/// Enum of valid public keys for multisig committee members
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// multisig-member-public-key = ed25519-multisig-member-public-key /
+///                              secp256k1-multisig-member-public-key /
+///                              secp256r1-multisig-member-public-key /
+///                              zklogin-multisig-member-public-key
+///
+/// ed25519-multisig-member-public-key   = %x00 ed25519-public-key
+/// secp256k1-multisig-member-public-key = %x01 secp256k1-public-key
+/// secp256r1-multisig-member-public-key = %x02 secp256r1-public-key
+/// zklogin-multisig-member-public-key   = %x03 zklogin-public-identifier
+/// ```
+///
+/// There is also a legacy encoding for this type defined as:
+///
+/// ```text
+/// legacy-multisig-member-public-key = string ; which is valid base64 encoded
+///                                            ; and the decoded bytes are defined
+///                                            ; by legacy-public-key
+/// legacy-public-key = (ed25519-flag ed25519-public-key) /
+///                     (secp256k1-flag secp256k1-public-key) /
+///                     (secp256r1-flag secp256r1-public-key)
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
 pub enum MultisigMemberPublicKey {
@@ -25,6 +53,23 @@ pub enum MultisigMemberPublicKey {
     ZkLogin(ZkLoginPublicIdentifier),
 }
 
+/// A member in a multisig committee
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// multisig-member = multisig-member-public-key
+///                   u8    ; weight
+/// ```
+///
+/// There is also a legacy encoding for this type defined as:
+///
+/// ```text
+/// legacy-multisig-member = legacy-multisig-member-public-key 
+///                          u8     ; weight
+/// ```
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[cfg_attr(
     feature = "serde",
@@ -37,19 +82,43 @@ pub struct MultisigMember {
 }
 
 impl MultisigMember {
+    /// Construct a new member from a `MultisigMemberPublicKey` and a `weight`.
     pub fn new(public_key: MultisigMemberPublicKey, weight: WeightUnit) -> Self {
         Self { public_key, weight }
     }
 
+    /// This member's public key.
     pub fn public_key(&self) -> &MultisigMemberPublicKey {
         &self.public_key
     }
 
+    /// Weight of this member's signature.
     pub fn weight(&self) -> WeightUnit {
         self.weight
     }
 }
 
+/// A multisig committee
+///
+/// A `MultisigCommittee` is a set of members who collectively control a single `Address` on the
+/// Sui blockchain. The number of required signautres to authorize the execution of a transaction
+/// is determined by `(signature_0_weight + signature_1_weight ..) >= threshold`.
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// multisig-committee = (vector multisig-member)
+///                      u16    ; threshold
+/// ```
+///
+/// There is also a legacy encoding for this type defined as:
+///
+/// ```text
+/// legacy-multisig-committee = (vector legacy-multisig-member)
+///                             u16     ; threshold
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(
     feature = "serde",
@@ -60,23 +129,33 @@ pub struct MultisigCommittee {
     /// A list of committee members and their corresponding weight.
     #[cfg_attr(feature = "proptest", any(proptest::collection::size_range(0..=10).lift()))]
     members: Vec<MultisigMember>,
-    /// If the total weight of the public keys corresponding to verified signatures is larger than threshold, the Multisig is verified.
+
+    /// If the total weight of the public keys corresponding to verified signatures is larger than
+    /// threshold, the Multisig is verified.
     threshold: ThresholdUnit,
 }
 
 impl MultisigCommittee {
+    /// Construct a new committee from a list of `MultisigMember`s and a `threshold`.
+    ///
+    /// Note that the order of the members is significant towards deriving the `Address` governed
+    /// by this committee.
     pub fn new(members: Vec<MultisigMember>, threshold: ThresholdUnit) -> Self {
         Self { members, threshold }
     }
 
+    /// The members of the committee
     pub fn members(&self) -> &[MultisigMember] {
         &self.members
     }
 
+    /// The total signature weight required to authorize a transaction for the address
+    /// corresponding to this `MultisigCommittee`.
     pub fn threshold(&self) -> ThresholdUnit {
         self.threshold
     }
 
+    /// Return the flag for this signature scheme
     pub fn scheme(&self) -> SignatureScheme {
         SignatureScheme::Multisig
     }
@@ -111,6 +190,7 @@ impl MultisigCommittee {
 }
 
 /// The struct that contains signatures and public keys necessary for authenticating a Multisig.
+///
 #[derive(Debug, Clone)]
 #[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
 pub struct MultisigAggregatedSignature {
@@ -188,6 +268,23 @@ fn roaring_bitmap_to_u16(roaring: &roaring::RoaringBitmap) -> Result<BitmapUnit,
     Ok(val)
 }
 
+/// A signature from a member of a multisig committee.
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// multisig-member-signature = ed25519-multisig-member-signature /
+///                             secp256k1-multisig-member-signature /
+///                             secp256r1-multisig-member-signature /
+///                             zklogin-multisig-member-signature
+///
+/// ed25519-multisig-member-signature   = %x00 ed25519-signature
+/// secp256k1-multisig-member-signature = %x01 secp256k1-signature
+/// secp256r1-multisig-member-signature = %x02 secp256r1-signature
+/// zklogin-multisig-member-signature   = %x03 zklogin-authenticator
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "proptest", derive(test_strategy::Arbitrary))]
 pub enum MultisigMemberSignature {