surface merkle distributor

Author: brozorec

content/stellar-contracts/utils/crypto.mdx

@@ -0,0 +1,109 @@
+---
+title: Cryptography Utilities
+---
+
+[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/contract-utils/src/crypto)
+
+## Overview
+
+The Cryptography Utilities provide a set of cryptographic tools for Soroban smart contracts,
+including hash functions, Merkle tree verification, and Merkle-based distribution systems.
+These utilities enable secure data verification and efficient token distribution mechanisms.
+The Cryptography Utilities consist of two main packages:
+
+* Crypto: A set of cryptographic primitives and utilities for Soroban contracts.
+* [Merkle Distributor](./merkle-distributor): A system for distributing tokens or other assets using Merkle proofs for verification.
+
+## Crypto Package
+
+The crypto package provides fundamental cryptographic primitives and utilities for Soroban contracts,
+with a focus on hashing and Merkle tree operations.
+
+### Key Components
+
+#### Hashers
+
+Provides a generic `Hasher` trait and implementations for common hash functions:
+
+* `Sha256`: Implementation of the SHA-256 hash function
+* `Keccak256`: Implementation of the Keccak-256 hash function (used in Ethereum)
+
+Each hasher follows the same interface:
+
+```rust
+pub trait Hasher {
+    type Output;
+
+    fn new(e: &Env) -> Self;
+    fn update(&mut self, input: Bytes);
+    fn finalize(self) -> Self::Output;
+}
+```
+
+#### Hashable
+
+The `Hashable` trait allows types to be hashed with any `Hasher` implementation:
+
+```rust
+pub trait Hashable {
+    fn hash<H: Hasher>(&self, hasher: &mut H);
+}
+```
+
+Built-in implementations are provided for `BytesN<32>` and `Bytes`.
+
+#### Utility Functions
+
+* `hash_pair`: Hashes two values together
+* `commutative_hash_pair`: Hashes two values in a deterministic order (important for Merkle trees)
+
+#### Merkle Tree Verification
+
+The `Verifier` struct provides functionality to verify Merkle proofs:
+
+```rust
+impl<H> Verifier<H>
+where
+    H: Hasher<Output = Bytes32>,
+{
+    pub fn verify(e: &Env, proof: Vec<Bytes32>, root: Bytes32, leaf: Bytes32) -> bool {
+        // Implementation verifies that the leaf is part of the tree defined by root
+    }
+}
+```
+
+### Usage Examples
+
+#### Hashing Data
+
+```rust
+use soroban_sdk::{Bytes, Env};
+use stellar_contract_utils::crypto::keccak::Keccak256;
+use stellar_contract_utils::crypto::hasher::Hasher;
+
+// Hash some data with Keccak256
+let e = Env::default();
+let data = Bytes::from_slice(&e, "Hello, world!".as_bytes());
+
+let mut hasher = Keccak256::new(&e);
+hasher.update(data);
+let hash = hasher.finalize();
+```
+
+#### Verifying a Merkle Proof
+
+```rust
+use soroban_sdk::{BytesN, Env, Vec};
+use stellar_crypto::keccak::Keccak256;
+use stellar_crypto::merkle::Verifier;
+
+// Verify that a leaf is part of a Merkle tree
+let e = Env::default();
+let root = /* merkle root as BytesN<32> */;
+let leaf = /* leaf to verify as BytesN<32> */;
+let proof = /* proof as Vec<BytesN<32>> */;
+
+let is_valid = Verifier::<Keccak256>::verify(&e, proof, root, leaf);
+```
+
+