Merge pull request #4 from mobilecoinofficial/main

update to v0.16.0 (fixes per functional review)
mobilecoinofficial · Sep 11, 2023 · 474cb05 · 474cb05
2 parents 6003c9d + 2257f9a
commit 474cb05
Show file tree

Hide file tree

Showing 30 changed files with 224 additions and 114 deletions.
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -487,7 +487,7 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: doc
-          args: --no-deps
+          args: --no-deps --workspace
 
       - name: Deploy to GitHub Pages
         uses: crazy-max/ghaction-github-pages@v3

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Makefile b/Makefile
@@ -33,7 +33,7 @@ nanox-test: nanox
 
 # Build docs
 docs:
-	cargo doc --no-deps
+	cargo doc --no-deps --workspace
 
 # Build nanosplus firmware
 nanosplus: 
@@ -129,4 +129,4 @@ miri:
 clean:
 	rm -rf target fw/target
 
-.PHONY: fw lib core nanosplus nanox fmt clippy clean
+.PHONY: fw lib core nanosplus nanox fmt clippy clean docs
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 A [MobileCoin][1] NanoApp for [Ledger][2] `nanosplus` and `nanox` devices.
 You can grab the latest (unsigned) firmware and tooling [here](https://github.com/mobilecoinofficial/ledger-mob/releases), or follow the [Getting Started](#Getting-Started) instructions to build your own.
 
-For application interaction or integration see the [library](https://mobilecoinofficial.github.io/ledger-mob/ledger_mob/index.html) and [APDU](https://mobilecoinofficial.github.io/ledger-mob/ledger_mob_apdu/index.html) documentation.
+For application interaction or integration see the [library](https://mobilecoinofficial.github.io/ledger-mob/ledger_mob/index.html), [Engine](https://mobilecoinofficial.github.io/ledger-mob/ledger_mob_core/index.html) and [APDU](https://mobilecoinofficial.github.io/ledger-mob/ledger_mob_apdu/index.html) documentation.
 
 ## Status
 

diff --git a/apdu/Cargo.toml b/apdu/Cargo.toml
@@ -4,7 +4,7 @@ cargo-features = ["per-package-target"]
 name = "ledger-mob-apdu"
 description = "MobileCoin hardware wallet protocol / APDU definitions"
 repository = "https://github.com/mobilecoinofficial/ledger-mob.git"
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 license = "Apache-2.0"
 publish = false

diff --git a/apdu/src/digest.rs b/apdu/src/digest.rs
@@ -1,6 +1,6 @@
 //! Helpers for computing APDU / event digests
 //!
-//! This is used instead of [Digestible] as the same digest must be computed over [ledger_mob_core::engine::Event]s and APDUs.
+//! This is used in place of `Digestible` as the same digest must be computed over engine events and APDUs.
 
 use sha2::{Digest as _, Sha512_256};
 

diff --git a/apdu/src/ident.rs b/apdu/src/ident.rs
@@ -62,7 +62,7 @@ impl<'a> ApduStatic for IdentSignReq<'a> {
 impl<'a> Encode for IdentSignReq<'a> {
     type Error = ApduError;
 
-    /// Encode an [`IdentReq`] APDU into the provided buffer
+    /// Encode an [`IdentSignReq`] APDU into the provided buffer
     #[inline]
     fn encode(&self, buff: &mut [u8]) -> Result<usize, ApduError> {
         let mut index = 0;
@@ -108,7 +108,7 @@ impl<'a> Decode<'a> for IdentSignReq<'a> {
     type Output = Self;
     type Error = ApduError;
 
-    /// Decode a [`IdentReq`] APDU from the provided buffer
+    /// Decode a [`IdentSignReq`] APDU from the provided buffer
     #[inline]
     fn decode(buff: &'a [u8]) -> Result<(Self, usize), ApduError> {
         let mut index = 0;
@@ -198,7 +198,7 @@ pub struct IdentResp {
 }
 
 impl IdentResp {
-    /// Create a new [`KeyImage`] APDU
+    /// Create a new [`IdentResp`] APDU
     pub fn new(public_key: [u8; 32], signature: [u8; 64]) -> Self {
         Self {
             public_key,

diff --git a/apdu/src/lib.rs b/apdu/src/lib.rs
@@ -13,6 +13,7 @@
 //! 32-bit field alignment to reduce the need for unaligned access on constrained platforms.
 //! All field encodings are little-endian, because most of the world is these days.
 //!
+//! See [Instruction] for APDU instruction codes.
 //!
 
 #![no_std]

diff --git a/apdu/src/state.rs b/apdu/src/state.rs
@@ -11,7 +11,7 @@ use sha2::{Digest as _, Sha512_256};
 use strum::{Display, EnumIter, EnumString, EnumVariantNames};
 
 /// Engine state enumeration
-/// used in [`TxInfo`] to communicate transaction progress
+/// used in [crate::tx::TxInfo] to communicate transaction progress
 #[derive(
     Copy, Clone, PartialEq, Debug, EnumString, Display, EnumVariantNames, EnumIter, TryFromPrimitive,
 )]

diff --git a/apdu/src/tx/mod.rs b/apdu/src/tx/mod.rs
@@ -2,7 +2,7 @@
 
 //! Transaction related APDUs, used to execute a transaction via the hardware wallet.
 //!
-//! See [crate::engine] for interaction and state machines
+//! See [ledger_mob_core::engine] for interaction and state machines
 
 use encdec::{Decode, Encode};
 use ledger_proto::ApduStatic;

diff --git a/apdu/src/tx/summary.rs b/apdu/src/tx/summary.rs
@@ -67,7 +67,37 @@ impl TxSummaryInit {
 
 /// Add TxOutSummary to the summary
 ///
-/// See [mc_transaction_core::tx_summary::TxOutSummary] for equivalence
+/// See [mc_transaction_core::tx_summary::TxOutSummary] for an equivalent MobileCoin core object.
+///
+/// ## Encoding:
+/// ```text
+///  0                   1                   2                   3
+///  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |     FLAGS     |    INDEX      |            RESERVED           |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                         MASKED_VALUE                          |
+/// |                        (u64, 8-byte)                          |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                        MASKED_TOKEN_ID                        |
+/// |                        (u64, 8-byte)                          |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                           COMMITMENT                          /
+/// /                 (32-byte Compressed Ristretto Point)          /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                        TXOUT_TARGET_KEY                       /
+/// /           (32-byte Compressed Ristretto Public Key)           /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                           PUBLIC_KEY                          /
+/// /           (32-byte Compressed Ristretto Public Key)           /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// ```
 #[derive(Clone, PartialEq, Debug, Encode, Decode)]
 #[encdec(error = "ApduError")]
 pub struct TxSummaryAddTxOut {
@@ -192,7 +222,50 @@ impl TxSummaryAddTxOut {
 
 /// Add TxOutSummaryUnblinding to the summary
 ///
-///
+/// ## Encoding:
+/// ```text
+///  0                   1                   2                   3
+///  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |     FLAGS     |    INDEX      |    FOG_ID     |   RESERVED    |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                        UNMASKED_VALUE                         |
+/// |                        (u64, 8-byte)                          |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                            TOKEN_ID                           |
+/// |                        (u64, 8-byte)                          |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                            BLINDING                           /
+/// /                   (32-byte Ristretto Scalar)                  /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /      TARGET_SPEND_PUBLIC_KEY (Optional, see HAS_ADDRESS)      /
+/// /                (32-byte Ristretto Public Key)                 /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /      TARGET_VIEW_PUBLIC_KEY (Optional, see HAS_ADDRESS)       /
+/// /                 (32-byte Ristretto Public Key)                /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                        TXOUT_TARGET_KEY                       /
+/// /           (32-byte Compressed Ristretto Public Key)           /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /       TXOUT_PRIVATE_KEY (optional, see HAS_PRIVATE_KEY)       /
+/// /          (32-byte Compressed Ristretto Private Key)           /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /    FOG_AUTHORITY_SIG (optional, see HAS_FOG_AUTHORITY_SIG)    /
+/// /               (64-byte Fog Authority Signature)               /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// ```
 #[derive(Clone, PartialEq, Debug, Encode, Decode)]
 #[encdec(error = "ApduError")]
 pub struct TxSummaryAddTxOutUnblinding {
@@ -488,7 +561,35 @@ impl TxSummaryAddTxOutUnblinding {
 
 /// Add TxInSummary for a transaction
 ///
-///
+/// ## Encoding:
+/// ```text
+///  0                   1                   2                   3
+///  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |     FLAGS     |    INDEX      |            RESERVED           |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                    PSEUDO_OUTPUT_COMMITMENT                   /
+/// /              (32-byte Compressed Ristretto Point)             /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                        UNMASKED_VALUE                         |
+/// |                        (u64, 8-byte)                          |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                           TOKEN_ID                            |
+/// |                         (u64, 8-byte)                         |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /                           BLINDING                            /
+/// /                   (32-byte Ristretto Scalar)                  /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                                                               |
+/// /      INPUT_RULES_DIGEST (optional, see HAS_INPUT_RULES)       /
+/// /                 (32-byte Input Rules Digest)                  /
+/// |                                                               |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// ```
 #[derive(Clone, PartialEq, Debug, Encode, Decode)]
 #[encdec(error = "ApduError")]
 pub struct TxSummaryAddTxIn {
@@ -582,7 +683,21 @@ impl TxSummaryAddTxIn {
 
 /// Complete TxSummary building
 ///
-///
+/// ## Encoding:
+/// ```text
+///  0                   1                   2                   3
+///  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                           FEE_VALUE                           |
+/// |                         (u64, 8-byte)                         |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                         FEE_TOKEN_ID                          |
+/// |                         (u64, 8-byte)                         |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// |                        TOMBSTONE_BLOCK                        |
+/// |                         (u64, 8-byte)                         |
+/// +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+/// ```
 #[derive(Clone, PartialEq, Debug, Encode, Decode)]
 #[encdec(error = "ApduError")]
 pub struct TxSummaryBuild {

diff --git a/core/Cargo.toml b/core/Cargo.toml
@@ -4,7 +4,7 @@ cargo-features = ["per-package-target"]
 name = "ledger-mob-core"
 description = "MobileCoin hardware wallet engine"
 repository = "https://github.com/mobilecoinofficial/ledger-mob.git"
-version = "0.15.0"
+version = "0.16.0"
 edition = "2021"
 license = "GPL-3.0"
 publish = false

diff --git a/core/src/engine/error.rs b/core/src/engine/error.rs
@@ -1,6 +1,6 @@
 // Copyright (c) 2022-2023 The MobileCoin Foundation
 
-/// [Engine] errors
+/// [super::Engine] errors
 #[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "thiserror", derive(thiserror::Error))]
 #[repr(u8)]

diff --git a/core/src/engine/function.rs b/core/src/engine/function.rs
@@ -66,7 +66,7 @@ impl Function {
     /// Setup ring-signer context
     ///
     /// this uses out-pointer based init to avoid stack allocation
-    /// see: https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#out-pointers
+    /// see: <https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#out-pointers>
     #[cfg(feature = "mlsag")]
     #[allow(clippy::too_many_arguments)]
     #[cfg_attr(feature = "noinline", inline(never))]
@@ -138,7 +138,7 @@ impl Function {
     /// Setup summarizer context
     ///
     /// this uses out-pointer based init to avoid stack allocation
-    /// see: https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#out-pointers
+    /// see: <https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#out-pointers>
     #[cfg(feature = "summary")]
     #[cfg_attr(feature = "noinline", inline(never))]
     pub fn summarizer_init(

diff --git a/core/src/engine/output.rs b/core/src/engine/output.rs
@@ -18,7 +18,7 @@ use super::summary::SummaryState;
 #[cfg(feature = "ident")]
 use super::ident::IdentState;
 
-/// [`Engine`][super::Engine] outputs (in response to events), typically encoded to response [APDUs][crate::apdu]
+/// [`Engine`][super::Engine] outputs (in response to events), typically encoded to response [APDUs][ledger_mob_apdu]
 #[derive(Clone, PartialEq, Debug)]
 pub enum Output {
     None,
@@ -93,7 +93,7 @@ impl Output {
         ptr.write(Output::None);
     }
 
-    /// Encode an [`Output`] object to a response [APDU]
+    /// Encode an [`Output`] object to a response [APDU][ledger_mob_apdu]
     #[cfg_attr(feature = "noinline", inline(never))]
     pub fn encode(&self, buff: &mut [u8]) -> Result<usize, ApduError> {
         match self.clone() {
@@ -204,7 +204,7 @@ impl From<(crate::engine::State, TxDigest)> for apdu::tx::TxInfo {
 }
 
 impl crate::engine::State {
-    /// Map [engine](crate::engine) states to [apdu][apdu::state::TxState] states for transmission
+    /// Map [engine](crate::engine) states to [apdu][ledger_mob_apdu::state::TxState] states for transmission
     pub fn state(&self) -> apdu::state::TxState {
         use crate::{apdu::state::TxState, engine::State};
 

diff --git a/core/src/engine/summary.rs b/core/src/engine/summary.rs
@@ -37,7 +37,7 @@ pub struct Summarizer<const MAX_RECORDS: usize = 16> {
     num_inputs: usize,
 }
 
-/// [Summarizer] state enumeration
+/// Summarizer state enumeration
 #[derive(
     Copy, Clone, PartialEq, Debug, Default, EnumString, Display, EnumVariantNames, EnumIter,
 )]