chore(ffi): Add docs to remote impls (#111)

* chore(ffi): Add docs to remote impls

* update bindings

* add graphql client doc

* bindings

* add more missing comments

* bindings again

---------

Co-authored-by: Thibault Martinez <[email protected]>

Author: DaughterOfMars

bindings/go/iota_sdk_ffi/iota_sdk_ffi.go

@@ -32,6 +32,7 @@ use crate::{
     },
 };
 
+/// The GraphQL client for interacting with the IOTA blockchain.
 #[derive(uniffi::Object)]
 pub struct GraphQLClient(RwLock<iota_graphql_client::Client>);
 

bindings/kotlin/lib/iota_sdk/iota_sdk_ffi.kt

@@ -133,6 +133,17 @@ impl From<CheckpointSummary> for iota_types::CheckpointSummary {
     }
 }
 
+/// A commitment made by a checkpoint.
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// ; CheckpointCommitment is an enum and each variant is prefixed with its index
+/// checkpoint-commitment = ecmh-live-object-set
+/// ecmh-live-object-set = %x00 digest
+/// ```
 #[derive(Clone, Debug, derive_more::From, uniffi::Object)]
 pub struct CheckpointCommitment(pub iota_types::CheckpointCommitment);
 

bindings/python/lib/iota_sdk_ffi.py

@@ -98,6 +98,34 @@ impl MultisigMemberSignature {
     }
 }
 
+/// 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, derive_more::From, uniffi::Object)]
 pub struct MultisigMemberPublicKey(pub iota_types::MultisigMemberPublicKey);
 

crates/iota-sdk-ffi/src/graphql.rs

@@ -215,6 +215,15 @@ impl ZkLoginProof {
     }
 }
 
+/// A claim of the iss in a zklogin proof
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// zklogin-claim = string u8
+/// ```
 #[uniffi::remote(Record)]
 pub struct ZkLoginClaim {
     pub value: String,

crates/iota-sdk-ffi/src/types/checkpoint.rs

@@ -574,19 +574,71 @@ impl From<MoveLocation> for iota_types::MoveLocation {
     }
 }
 
+/// An error with an argument to a command
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// command-argument-error =  type-mismatch
+///                        =/ invalid-bcs-bytes
+///                        =/ invalid-usage-of-pure-argument
+///                        =/ invalid-argument-to-private-entry-function
+///                        =/ index-out-of-bounds
+///                        =/ secondary-index-out-of-bound
+///                        =/ invalid-result-arity
+///                        =/ invalid-gas-coin-usage
+///                        =/ invalid-value-usage
+///                        =/ invalid-object-by-value
+///                        =/ invalid-object-by-mut-ref
+///                        =/ shared-object-operation-not-allowed
+///
+/// type-mismatch                               = %x00
+/// invalid-bcs-bytes                           = %x01
+/// invalid-usage-of-pure-argument              = %x02
+/// invalid-argument-to-private-entry-function  = %x03
+/// index-out-of-bounds                         = %x04 u16
+/// secondary-index-out-of-bound                = %x05 u16 u16
+/// invalid-result-arity                        = %x06 u16
+/// invalid-gas-coin-usage                      = %x07
+/// invalid-value-usage                         = %x08
+/// invalid-object-by-value                     = %x09
+/// invalid-object-by-mut-ref                   = %x0a
+/// shared-object-operation-not-allowed         = %x0b
+/// ```
 #[uniffi::remote(Enum)]
 pub enum CommandArgumentError {
+    /// The type of the value does not match the expected type
     TypeMismatch,
+    /// The argument cannot be deserialized into a value of the specified type
     InvalidBcsBytes,
+    /// The argument cannot be instantiated from raw bytes
     InvalidUsageOfPureArgument,
+    /// Invalid argument to private entry function.
+    /// Private entry functions cannot take arguments from other Move functions.
     InvalidArgumentToPrivateEntryFunction,
+    /// Out of bounds access to input or results
     IndexOutOfBounds { index: u16 },
+    /// Out of bounds access to subresult
     SecondaryIndexOutOfBounds { result: u16, subresult: u16 },
+    /// Invalid usage of result.
+    /// Expected a single result but found either no return value or multiple.
     InvalidResultArity { result: u16 },
+    /// Invalid usage of Gas coin.
+    /// The Gas coin can only be used by-value with a TransferObjects command.
     InvalidGasCoinUsage,
+    /// Invalid usage of move value.
+    //     Mutably borrowed values require unique usage.
+    //     Immutably borrowed values cannot be taken or borrowed mutably.
+    //     Taken values cannot be used again.
     InvalidValueUsage,
+    /// Immutable objects cannot be passed by-value.
     InvalidObjectByValue,
+    /// Immutable objects cannot be passed by mutable reference, &mut.
     InvalidObjectByMutRef,
+    /// Shared object operations such a wrapping, freezing, or converting to
+    /// owned are not allowed.
     SharedObjectOperationNotAllowed,
 }
 
@@ -695,8 +747,21 @@ impl From<PackageUpgradeError> for iota_types::PackageUpgradeError {
     }
 }
 
+/// An error with a type argument
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// type-argument-error = type-not-found / constraint-not-satisfied
+/// type-not-found = %x00
+/// constraint-not-satisfied = %x01
+/// ```
 #[uniffi::remote(Enum)]
 pub enum TypeArgumentError {
+    /// A type was not found in the module specified
     TypeNotFound,
+    /// A type provided did not match the specified constraint
     ConstraintNotSatisfied,
 }

crates/iota-sdk-ffi/src/types/crypto/multisig.rs

@@ -3,11 +3,55 @@
 
 use iota_types::GasCostSummary;
 
+/// Summary of gas charges.
+///
+/// Storage is charged independently of computation.
+/// There are 3 parts to the storage charges:
+/// `storage_cost`: it is the charge of storage at the time the transaction is
+/// executed.                 The cost of storage is the number of bytes of the
+/// objects being mutated                 multiplied by a variable storage cost
+/// per byte `storage_rebate`: this is the amount a user gets back when
+/// manipulating an object.                   The `storage_rebate` is the
+/// `storage_cost` for an object minus fees. `non_refundable_storage_fee`: not
+/// all the value of the object storage cost is                               
+/// given back to user and there is a small fraction that                       
+/// is kept by the system. This value tracks that charge.
+///
+/// When looking at a gas cost summary the amount charged to the user is
+/// `computation_cost + storage_cost - storage_rebate`
+/// and that is the amount that is deducted from the gas coins.
+/// `non_refundable_storage_fee` is collected from the objects being
+/// mutated/deleted and it is tracked by the system in storage funds.
+///
+/// Objects deleted, including the older versions of objects mutated, have the
+/// storage field on the objects added up to a pool of "potential rebate". This
+/// rebate then is reduced by the "nonrefundable rate" such that:
+/// `potential_rebate(storage cost of deleted/mutated objects) =
+/// storage_rebate + non_refundable_storage_fee`
+///
+/// # BCS
+///
+/// The BCS serialized form for this type is defined by the following ABNF:
+///
+/// ```text
+/// gas-cost-summary = u64 ; computation-cost
+///                    u64 ; storage-cost
+///                    u64 ; storage-rebate
+///                    u64 ; non-refundable-storage-fee
+/// ```
 #[uniffi::remote(Record)]
 pub struct GasCostSummary {
+    /// Cost of computation/execution
     pub computation_cost: u64,
+    /// The burned component of the computation/execution costs
     pub computation_cost_burned: u64,
+    /// Storage cost, it's the sum of all storage cost for all objects created
+    /// or mutated.
     pub storage_cost: u64,
+    /// The amount of storage cost refunded to the user for all objects deleted
+    /// or mutated in the transaction.
     pub storage_rebate: u64,
+    /// The fee for the rebate. The portion of the storage rebate kept by the
+    /// system.
     pub non_refundable_storage_fee: u64,
 }

crates/iota-sdk-ffi/src/types/crypto/zklogin.rs

@@ -507,6 +507,7 @@ impl From<Validator> for iota_graphql_client::query_types::Validator {
     }
 }
 
+/// The credentials related fields associated with a validator.
 #[uniffi::remote(Record)]
 pub struct ValidatorCredentials {
     pub authority_pub_key: Option<Base64>,