diff --git a/contracts/commitment-pool/src/lib.rs b/contracts/commitment-pool/src/lib.rs index b835a61..50ae40d 100644 --- a/contracts/commitment-pool/src/lib.rs +++ b/contracts/commitment-pool/src/lib.rs @@ -25,7 +25,22 @@ pub struct CommitmentPool; #[contractimpl] impl CommitmentPool { - /// Initialize the commitment pool with admin, token, and verifier contract addresses. + /// Initializes the commitment pool with admin, token, and verifier contract addresses. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `admin` - The address of the contract administrator. + /// * `token_id` - The address of the underlying token contract. + /// * `verifier_id` - The address of the Groth16 verifier contract. + /// + /// # Returns + /// + /// Returns `Ok(())` on successful initialization. + /// + /// # Errors + /// + /// Returns `Error::Unauthorized` if the contract is already initialized. pub fn initialize( env: Env, admin: Address, @@ -43,10 +58,25 @@ impl CommitmentPool { Ok(()) } - /// Deposit a commitment into the shielded pool. + /// Deposits a commitment into the shielded pool. /// /// The commitment is a hash of (secret, nullifier, amount, token). - /// The encrypted_note allows the recipient to decrypt the note details. + /// The encrypted_note allows the recipient to decrypt the note details off-chain. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `commitment` - A 32-byte hash representing the user's deposit commitment. + /// * `encrypted_note` - The encrypted details of the deposit for the recipient. + /// + /// # Returns + /// + /// Returns `Ok(())` on a successful deposit. + /// + /// # Errors + /// + /// * Returns `Error::ContractPaused` if the contract is currently paused. + /// * Returns `Error::DuplicateCommitment` if the commitment already exists in the tree. pub fn deposit( env: Env, commitment: BytesN<32>, @@ -71,10 +101,28 @@ impl CommitmentPool { Ok(()) } - /// Withdraw from the pool by providing a valid ZK proof. + /// Withdraws tokens from the pool by providing a valid ZK proof. /// /// The proof demonstrates knowledge of a valid commitment in the Merkle tree /// without revealing which commitment is being spent. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `nullifier` - A unique 32-byte hash derived from the secret to prevent double-spending. + /// * `proof` - The serialized ZK proof proving ownership of a commitment. + /// * `recipient` - The address that will receive the withdrawn tokens. + /// * `amount` - The amount of tokens to withdraw. + /// + /// # Returns + /// + /// Returns `Ok(())` on a successful withdrawal. + /// + /// # Errors + /// + /// * Returns `Error::ContractPaused` if the contract is currently paused. + /// * Returns `Error::NullifierAlreadySpent` if the nullifier has been seen before. + /// * Returns `Error::InvalidProof` if the proof verification fails. pub fn withdraw( env: Env, nullifier: BytesN<32>, @@ -131,16 +179,47 @@ impl CommitmentPool { } /// Returns the current Merkle root of the commitment tree. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// + /// # Returns + /// + /// Returns a 32-byte array representing the current Merkle root. pub fn get_root(env: Env) -> BytesN<32> { MerkleTree::root(&env) } /// Checks whether a nullifier has already been spent. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `nullifier` - The 32-byte nullifier hash to check. + /// + /// # Returns + /// + /// Returns `true` if the nullifier has been spent, otherwise `false`. pub fn is_nullifier_spent(env: Env, nullifier: BytesN<32>) -> bool { NullifierSet::is_spent(&env, &nullifier) } - /// Pause the contract. Only the admin can call this. + /// Pauses the contract, suspending deposits and withdrawals. + /// + /// Only the contract administrator can call this function. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successfully pausing the contract. + /// + /// # Errors + /// + /// Returns `Error::Unauthorized` if the caller is not the admin. pub fn pause(env: Env) -> Result<(), Error> { let admin: Address = env.storage().instance() .get(&DataKey::Admin).ok_or(Error::Unauthorized)?; @@ -150,7 +229,21 @@ impl CommitmentPool { Ok(()) } - /// Unpause the contract. Only the admin can call this. + /// Unpauses the contract, resuming deposits and withdrawals. + /// + /// Only the contract administrator can call this function. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successfully unpausing the contract. + /// + /// # Errors + /// + /// Returns `Error::Unauthorized` if the caller is not the admin. pub fn unpause(env: Env) -> Result<(), Error> { let admin: Address = env.storage().instance() .get(&DataKey::Admin).ok_or(Error::Unauthorized)?; diff --git a/contracts/compliance-registry/src/lib.rs b/contracts/compliance-registry/src/lib.rs index 775dd9b..bef09bd 100644 --- a/contracts/compliance-registry/src/lib.rs +++ b/contracts/compliance-registry/src/lib.rs @@ -22,7 +22,20 @@ pub struct ComplianceRegistry; #[contractimpl] impl ComplianceRegistry { - /// Initialize the registry with an admin address. + /// Initializes the registry with an admin address. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `admin` - The address of the contract administrator. + /// + /// # Returns + /// + /// Returns `Ok(())` on successful initialization. + /// + /// # Errors + /// + /// Returns `ComplianceError::Unauthorized` if the contract is already initialized. pub fn initialize(env: Env, admin: Address) -> Result<(), ComplianceError> { if env.storage().instance().has(&RegistryKey::Admin) { return Err(ComplianceError::Unauthorized); @@ -32,7 +45,20 @@ impl ComplianceRegistry { Ok(()) } - /// Set the auditor address. Only admin can call this. + /// Sets the auditor address. Only the admin can call this function. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `auditor` - The address of the designated auditor. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successful update of the auditor address. + /// + /// # Errors + /// + /// Returns `ComplianceError::Unauthorized` if the caller is not the admin. pub fn set_auditor(env: Env, auditor: Address) -> Result<(), ComplianceError> { let admin: Address = env.storage().instance() .get(&RegistryKey::Admin).ok_or(ComplianceError::Unauthorized)?; @@ -41,10 +67,24 @@ impl ComplianceRegistry { Ok(()) } - /// Register an encrypted viewing key for a commitment. + /// Registers an encrypted viewing key for a commitment. /// /// The viewing key is encrypted with the auditor's public key, /// allowing only the auditor to decrypt transaction details. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `commitment` - The 32-byte hash of the commitment. + /// * `encrypted_key` - The encrypted viewing key. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successful registration. + /// + /// # Errors + /// + /// Returns `ComplianceError::AlreadyRegistered` if a key is already registered for this commitment. pub fn register_viewing_key( env: Env, commitment: BytesN<32>, @@ -58,8 +98,23 @@ impl ComplianceRegistry { Ok(()) } - /// Get the encrypted viewing key for a commitment. + /// Gets the encrypted viewing key for a commitment. + /// /// Only the auditor can retrieve viewing keys. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `commitment` - The 32-byte hash of the commitment. + /// + /// # Returns + /// + /// Returns the encrypted viewing key as `Bytes`. + /// + /// # Errors + /// + /// * Returns `ComplianceError::NotAuditor` if the caller is not the registered auditor. + /// * Returns `ComplianceError::NotFound` if no viewing key exists for the given commitment. pub fn get_viewing_key( env: Env, commitment: BytesN<32>, diff --git a/contracts/groth16-verifier/src/lib.rs b/contracts/groth16-verifier/src/lib.rs index 919056b..8590c3b 100644 --- a/contracts/groth16-verifier/src/lib.rs +++ b/contracts/groth16-verifier/src/lib.rs @@ -50,7 +50,20 @@ pub struct Groth16Verifier; #[contractimpl] impl Groth16Verifier { - /// Initialize the verifier with an admin address. + /// Initializes the verifier with an admin address. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `admin` - The address of the contract administrator. + /// + /// # Returns + /// + /// Returns `Ok(())` on successful initialization. + /// + /// # Errors + /// + /// Returns `VerifierError::Unauthorized` if the contract is already initialized. pub fn initialize(env: Env, admin: Address) -> Result<(), VerifierError> { if env.storage().instance().has(&VkKey::Admin) { return Err(VerifierError::Unauthorized); @@ -60,9 +73,23 @@ impl Groth16Verifier { Ok(()) } - /// Register a verification key by storing its serialized form. + /// Registers a verification key by storing its serialized form. /// /// Only the admin can register verification keys. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `vk_hash` - The 32-byte hash of the verification key. + /// * `vk_data` - The serialized verification key data. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successful registration. + /// + /// # Errors + /// + /// Returns `VerifierError::Unauthorized` if the caller is not the admin. pub fn register_vk( env: Env, vk_hash: BytesN<32>, @@ -81,22 +108,40 @@ impl Groth16Verifier { Ok(()) } - /// Check if a verification key is registered. + /// Checks if a verification key is registered. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `vk_hash` - The 32-byte hash of the verification key to check. + /// + /// # Returns + /// + /// Returns `true` if the verification key is registered, otherwise `false`. pub fn is_vk_registered(env: Env, vk_hash: BytesN<32>) -> bool { env.storage() .persistent() .has(&VkKey::Vk(vk_hash)) } - /// Verify a Groth16 proof against registered verification key. + /// Verifies a Groth16 proof against a registered verification key. /// /// # Arguments - /// * `proof` - Serialized proof bytes (A, B, C points) - /// * `public_inputs` - Vector of 32-byte public input scalars - /// * `vk_hash` - Hash of the verification key to use + /// + /// * `env` - The execution environment. + /// * `proof` - Serialized proof bytes (A, B, C points). + /// * `public_inputs` - Vector of 32-byte public input scalars. + /// * `vk_hash` - Hash of the verification key to use. /// /// # Returns - /// `true` if the proof is valid, `false` otherwise + /// + /// Returns `Ok(true)` if the proof is valid, `Ok(false)` if invalid. + /// + /// # Errors + /// + /// * Returns `VerifierError::VkNotRegistered` if the given `vk_hash` is not found. + /// * Returns `VerifierError::InvalidProofFormat` if the proof length is incorrect. + /// * Returns `VerifierError::InvalidPublicInputs` if the public inputs vector is empty. pub fn verify( env: Env, proof: Bytes, diff --git a/contracts/proxy-blend/src/lib.rs b/contracts/proxy-blend/src/lib.rs index f692c5c..2a56943 100644 --- a/contracts/proxy-blend/src/lib.rs +++ b/contracts/proxy-blend/src/lib.rs @@ -24,7 +24,22 @@ pub struct ProxyBlend; #[contractimpl] impl ProxyBlend { - /// Initialize the proxy with admin and pool addresses. + /// Initializes the proxy with admin and pool addresses. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `admin` - The address of the contract administrator. + /// * `commitment_pool_id` - The address of the shielded commitment pool. + /// * `blend_pool_id` - The address of the Blend lending pool. + /// + /// # Returns + /// + /// Returns `Ok(())` on successful initialization. + /// + /// # Errors + /// + /// Returns `ProxyBlendError::Unauthorized` if the contract is already initialized. pub fn initialize( env: Env, admin: Address, @@ -42,10 +57,25 @@ impl ProxyBlend { Ok(()) } - /// Deposit into Blend lending pool using a shielded withdrawal proof. + /// Deposits into the Blend lending pool using a shielded withdrawal proof. /// /// Flow: User proves ownership of shielded funds → proxy withdraws /// from commitment pool → deposits into Blend pool. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `nullifier` - The nullifier corresponding to the shielded commitment being spent. + /// * `proof` - The ZK proof proving ownership of the commitment. + /// * `amount` - The amount of tokens to deposit. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successful deposit. + /// + /// # Errors + /// + /// Returns `ProxyBlendError::ContractPaused` if the proxy contract is paused. pub fn shielded_deposit( env: Env, nullifier: BytesN<32>, @@ -61,10 +91,24 @@ impl ProxyBlend { Ok(()) } - /// Withdraw from Blend lending pool into a new shielded commitment. + /// Withdraws from the Blend lending pool into a new shielded commitment. /// /// Flow: Proxy withdraws from Blend → creates new commitment /// in the shielded pool. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `commitment` - The 32-byte hash of the new commitment to create. + /// * `amount` - The amount of tokens to withdraw. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successful withdrawal. + /// + /// # Errors + /// + /// Returns `ProxyBlendError::ContractPaused` if the proxy contract is paused. pub fn shielded_withdraw( env: Env, commitment: BytesN<32>, @@ -79,7 +123,23 @@ impl ProxyBlend { Ok(()) } - /// Borrow from Blend lending pool using shielded collateral. + /// Borrows from the Blend lending pool using shielded collateral. + /// + /// # Arguments + /// + /// * `env` - The execution environment. + /// * `collateral_nullifier` - The nullifier corresponding to the collateral commitment. + /// * `collateral_proof` - The ZK proof proving ownership of the collateral. + /// * `borrow_amount` - The amount of tokens to borrow. + /// * `borrow_commitment` - The new commitment hash for the borrowed funds. + /// + /// # Returns + /// + /// Returns `Ok(())` upon successful borrow operation. + /// + /// # Errors + /// + /// Returns `ProxyBlendError::ContractPaused` if the proxy contract is paused. pub fn shielded_borrow( env: Env, collateral_nullifier: BytesN<32>,