feat: algo25 module (#335)

Co-authored-by: Copilot <[email protected]>

Author: joe-p

.github/workflows/swift_ci.yml

@@ -57,8 +57,43 @@ jobs:
         run: cargo pkg ${{ env.CRATE }} swift
 
       # Ideally we'd use a matrix for the platforms, but due to the limitations of Mac runners on GitHub it's probably better to just have a single job with multiple steps
+      - name: Detect iOS simulator
+        id: ios_sim
+        run: |
+          DEST_ID="$(python3 - <<'PY'
+          import json, subprocess, re
+
+          data = json.loads(subprocess.check_output(
+              ["xcrun", "simctl", "list", "devices", "available", "-j"],
+              text=True
+          ))
+
+          def runtime_version(key: str):
+              # Example key: com.apple.CoreSimulator.SimRuntime.iOS-18-2
+              m = re.search(r"iOS-(\d+)-(\d+)", key)
+              return (int(m.group(1)), int(m.group(2))) if m else (-1, -1)
+
+          ios_runtimes = [k for k in data["devices"].keys() if "SimRuntime.iOS-" in k]
+          ios_runtimes.sort(key=runtime_version, reverse=True)
+
+          udid = None
+          for runtime in ios_runtimes:
+              devices = data["devices"][runtime]
+              iphones = [d for d in devices if d.get("isAvailable") and d.get("name", "").startswith("iPhone")]
+              if iphones:
+                  udid = iphones[0]["udid"]
+                  break
+
+          if not udid:
+              raise SystemExit("No available iPhone simulator found")
+
+          print(udid)
+          PY
+          )"
+          echo "destination=id=${DEST_ID}" >> "$GITHUB_OUTPUT"
+
       - name: Test (iOS)
-        run: cd packages/swift/${{ env.PACKAGE }} && xcodebuild -scheme ${{ env.PACKAGE }} test -destination "platform=iOS Simulator,name=iPhone 17,OS=latest"
+        run: cd packages/swift/${{ env.PACKAGE }} && xcodebuild -scheme ${{ env.PACKAGE }} test -destination "${{ steps.ios_sim.outputs.destination }}"
       - name: Test (macOS)
         run: cd packages/swift/${{ env.PACKAGE }} && xcodebuild -scheme ${{ env.PACKAGE }} test -destination "platform=macOS"
       - name: Test (Catalyst)
@@ -74,4 +109,3 @@ jobs:
         with:
           name: ${{ env.PACKAGE }}
           path: packages/swift/${{ env.PACKAGE }}.zip
-

Cargo.lock

@@ -16,6 +16,7 @@ zeroize = { version = "1.8", features = ["derive"] }
 # Used random seed generation for ed25519
 getrandom = "0.4.1"
 async-trait = "0.1.89"
+sha2.workspace = true
 
 [dev-dependencies]
 tokio = { version = "1.49.0", features = ["macros", "rt"] }

crates/algokit_crypto/Cargo.toml

@@ -0,0 +1,244 @@
+mod english;
+
+use english::ENGLISH;
+use sha2::{Digest, Sha512_256};
+
+pub const FAIL_TO_DECODE_MNEMONIC_ERROR_MSG: &str = "failed to decode mnemonic";
+pub const NOT_IN_WORDS_LIST_ERROR_MSG: &str =
+    "the mnemonic contains a word that is not in the wordlist";
+
+const SEED_BYTES_LENGTH: usize = 32;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum MnemonicError {
+    InvalidSeedLength { expected: usize, found: usize },
+    NotInWordsList,
+    FailedToDecodeMnemonic,
+}
+
+impl core::fmt::Display for MnemonicError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            MnemonicError::InvalidSeedLength { expected, .. } => {
+                write!(f, "Seed length must be {expected}")
+            }
+            MnemonicError::NotInWordsList => write!(f, "{NOT_IN_WORDS_LIST_ERROR_MSG}"),
+            MnemonicError::FailedToDecodeMnemonic => {
+                write!(f, "{FAIL_TO_DECODE_MNEMONIC_ERROR_MSG}")
+            }
+        }
+    }
+}
+
+impl std::error::Error for MnemonicError {}
+
+fn to_uint11_array(buffer8: &[u8]) -> Vec<u16> {
+    let mut buffer11 = Vec::new();
+    let mut acc: u32 = 0;
+    let mut acc_bits: u32 = 0;
+
+    for octet in buffer8 {
+        acc |= u32::from(*octet) << acc_bits;
+        acc_bits += 8;
+
+        if acc_bits >= 11 {
+            buffer11.push((acc & 0x7ff) as u16);
+            acc >>= 11;
+            acc_bits -= 11;
+        }
+    }
+
+    if acc_bits != 0 {
+        buffer11.push(acc as u16);
+    }
+
+    buffer11
+}
+
+fn to_uint8_array(buffer11: &[u16]) -> Vec<u8> {
+    let mut buffer8 = Vec::new();
+    let mut acc: u32 = 0;
+    let mut acc_bits: u32 = 0;
+
+    for ui11 in buffer11 {
+        acc |= u32::from(*ui11) << acc_bits;
+        acc_bits += 11;
+
+        while acc_bits >= 8 {
+            buffer8.push((acc & 0xff) as u8);
+            acc >>= 8;
+            acc_bits -= 8;
+        }
+    }
+
+    if acc_bits != 0 {
+        buffer8.push(acc as u8);
+    }
+
+    buffer8
+}
+
+fn apply_words(nums: &[u16]) -> Vec<&'static str> {
+    nums.iter().map(|n| ENGLISH[*n as usize]).collect()
+}
+
+fn english_index(word: &str) -> Option<usize> {
+    ENGLISH.iter().position(|candidate| *candidate == word)
+}
+
+fn compute_checksum(seed: &[u8; SEED_BYTES_LENGTH]) -> &'static str {
+    let mut hasher = Sha512_256::new();
+    hasher.update(seed);
+    let hash = hasher.finalize();
+
+    let uint11_hash = to_uint11_array(hash.as_ref());
+    let words = apply_words(&uint11_hash);
+    words[0]
+}
+
+/// Converts a 32-byte key into a 25-word mnemonic including checksum.
+pub fn mnemonic_from_seed(seed: &[u8]) -> Result<String, MnemonicError> {
+    if seed.len() != SEED_BYTES_LENGTH {
+        return Err(MnemonicError::InvalidSeedLength {
+            expected: SEED_BYTES_LENGTH,
+            found: seed.len(),
+        });
+    }
+
+    let seed: [u8; SEED_BYTES_LENGTH] =
+        seed.try_into()
+            .map_err(|_| MnemonicError::InvalidSeedLength {
+                expected: SEED_BYTES_LENGTH,
+                found: seed.len(),
+            })?;
+
+    let uint11_array = to_uint11_array(&seed);
+    let words = apply_words(&uint11_array);
+    let checksum_word = compute_checksum(&seed);
+
+    Ok(format!("{} {checksum_word}", words.join(" ")))
+}
+
+/// Converts a mnemonic generated by this library back to the source 32-byte seed.
+pub fn seed_from_mnemonic(mnemonic: &str) -> Result<[u8; SEED_BYTES_LENGTH], MnemonicError> {
+    let words: Vec<&str> = mnemonic.split_whitespace().collect();
+
+    // Expect exactly 25 words: 24 data words + 1 checksum word.
+    if words.len() != 25 {
+        return Err(MnemonicError::FailedToDecodeMnemonic);
+    }
+
+    let key_words = &words[..24];
+
+    for w in key_words {
+        if english_index(w).is_none() {
+            return Err(MnemonicError::NotInWordsList);
+        }
+    }
+
+    let checksum = words[24];
+    let uint11_array: Vec<u16> = key_words
+        .iter()
+        .map(|word| english_index(word).expect("checked above") as u16)
+        .collect();
+
+    let mut uint8_array = to_uint8_array(&uint11_array);
+
+    if uint8_array.len() != 33 {
+        return Err(MnemonicError::FailedToDecodeMnemonic);
+    }
+
+    if uint8_array[uint8_array.len() - 1] != 0x0 {
+        return Err(MnemonicError::FailedToDecodeMnemonic);
+    }
+
+    uint8_array.pop();
+
+    let seed: [u8; SEED_BYTES_LENGTH] = uint8_array
+        .try_into()
+        .map_err(|_| MnemonicError::FailedToDecodeMnemonic)?;
+
+    if compute_checksum(&seed) == checksum {
+        return Ok(seed);
+    }
+
+    Err(MnemonicError::FailedToDecodeMnemonic)
+}
+
+/// Takes an Algorand secret key and returns its associated mnemonic.
+pub fn secret_key_to_mnemonic(sk: &[u8]) -> Result<String, MnemonicError> {
+    let seed = sk
+        .get(..SEED_BYTES_LENGTH)
+        .ok_or(MnemonicError::InvalidSeedLength {
+            expected: SEED_BYTES_LENGTH,
+            found: sk.len(),
+        })?;
+    mnemonic_from_seed(seed)
+}
+
+/// Takes a mnemonic and returns the corresponding master derivation key.
+pub fn mnemonic_to_master_derivation_key(
+    mn: &str,
+) -> Result<[u8; SEED_BYTES_LENGTH], MnemonicError> {
+    seed_from_mnemonic(mn)
+}
+
+/// Takes a master derivation key and returns the corresponding mnemonic.
+pub fn master_derivation_key_to_mnemonic(mdk: &[u8]) -> Result<String, MnemonicError> {
+    mnemonic_from_seed(mdk)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn seed_round_trip() {
+        let seed = [7u8; SEED_BYTES_LENGTH];
+        let mnemonic = mnemonic_from_seed(&seed).expect("mnemonic should encode");
+        let decoded = seed_from_mnemonic(&mnemonic).expect("mnemonic should decode");
+        assert_eq!(decoded, seed);
+    }
+
+    #[test]
+    fn rejects_non_wordlist_words() {
+        let seed = [3u8; SEED_BYTES_LENGTH];
+        let mnemonic = mnemonic_from_seed(&seed).expect("mnemonic should encode");
+        let mut words: Vec<&str> = mnemonic.split(' ').collect();
+        words[0] = "notaword";
+        let broken = words.join(" ");
+
+        let err = seed_from_mnemonic(&broken).expect_err("should fail");
+        assert_eq!(err, MnemonicError::NotInWordsList);
+        assert_eq!(err.to_string(), NOT_IN_WORDS_LIST_ERROR_MSG);
+    }
+
+    #[test]
+    fn rejects_bad_checksum() {
+        let seed = [11u8; SEED_BYTES_LENGTH];
+        let mnemonic = mnemonic_from_seed(&seed).expect("mnemonic should encode");
+        let mut words: Vec<&str> = mnemonic.split(' ').collect();
+        words[24] = if words[24] == "abandon" {
+            "ability"
+        } else {
+            "abandon"
+        };
+        let broken = words.join(" ");
+
+        let err = seed_from_mnemonic(&broken).expect_err("should fail checksum");
+        assert_eq!(err, MnemonicError::FailedToDecodeMnemonic);
+        assert_eq!(err.to_string(), FAIL_TO_DECODE_MNEMONIC_ERROR_MSG);
+    }
+
+    #[test]
+    fn rejects_wrong_seed_length() {
+        let err = mnemonic_from_seed(&[1u8; 31]).expect_err("length mismatch should fail");
+        assert_eq!(
+            err,
+            MnemonicError::InvalidSeedLength {
+                expected: SEED_BYTES_LENGTH,
+                found: 31
+            }
+        );
+    }
+}

crates/algokit_crypto/src/algo25/english.rs

@@ -1,3 +1,3 @@
+pub mod algo25;
 pub mod ed25519;
-
 pub use signature::{Keypair, Signer};

crates/algokit_crypto/src/algo25/mod.rs

@@ -18,6 +18,7 @@ uniffi = { workspace = true, features = [
 async-trait = "0.1.89"
 signature = "2.2.0"
 tokio = { version = "1.49.0", features = ["rt", "time", "net", "io-util", "sync"] }
+getrandom = "0.4.1"
 
 [dev-dependencies]
 tokio = { version = "1.49.0", features = ["macros", "rt"] }