# Functions, Methods, and Data Structures ### CCL SDK {% hint style="info" %} The Secret Network CCL SDK can be forked [here](https://github.com/kromsten/secret-cosmos-abstraction). {% endhint %} ### Data Structures The essential parameters required for `chacha20poly1305`flow are defined in the following data structure: **EncryptedParams** *A data structure that is visible to all network participants and can be transmitted over non-secure channels* ```rust /// A data structure that is safe to be visible by all network participants and can be transmited over non-secure channels struct EncryptedParams { /// Encrypted payload containging hidden message pub payload : Binary, /// Sha256 hash of the payload pub payload_hash : Binary, /// Signed base64 digest of the payload_hash being wrapped /// in an cosmos arbitrary (036) object and rehashed again with sha256 pub payload_signature : Binary, /// Public key of wallet used for deriving a shared key for chacha20_poly1305 /// Not necessary the same as user's public key pub user_key : Binary, /// One-time nonce used for chacha20_poly1305 encryption pub nonce : Binary, } ``` #### EncryptedPayload *Data meant to be encrypted and stored in the payload field of EncryptedParams* ```rust /// Data meant to be encrypted and stored in the payload field of [EncryptedParams] #[cw_serde] pub struct EncryptedPayload { /// bech32 prefix address of a wallet used for signing hash of the payload pub user_address : String, /// Public key of a wallet used for signing hash of the payload pub user_pubkey : Binary, /// Human readable prefix for the bech32 address on the remote cosmos chain pub hrp : String, /// Plaintext message e.g. normal `ExecuteMsg` of your contract pub msg : Binary, } ``` ### Custom Contract Message Your contract must define an endpoint where a user can pass all the required fields of the `EncryptedParams`. E.g: ```rust pub enum ExecuteMsg { ... Encrypted { payload : Binary, payload_signature : Binary, payload_hash : Binary, user_key : Binary, nonce : Binary, } ... } ``` If you want to define a custom message, rename the fields, or add additional fields, there is a helpful trait `WithEncryption` that you can implement. It simply tells the compiler how to extract the essential parameters from your custom message and turn it into `EncryptedParams` ```rust trait WithEncryption : Serialize + Clone { fn encrypted(&self) -> EncryptedParams; fn is_encrypted(&self) -> bool; } ``` Implementing the trait for your message will allow you to use other useful methods of the SDK (like `handle_encrypted_wrapper`) that significantly simplify the development experience. Example of the implementation for the `ExecuteMsg` is as follows: ```rust impl WithEncryption for ExecuteMsg { fn encrypted(&self) -> EncryptedParams { match self.clone() { ExecuteMsg::Encrypted { payload, payload_signature, payload_hash, user_key, nonce, } => EncryptedParams { payload, payload_signature, payload_hash, user_key, nonce }, _ => panic!("Not encrypted") } } fn is_encrypted(&self) -> bool { if ExecuteMsg::Encrypted{..} = self { true } else { false } } } ``` ### Extending existing data structures The SDK has multiple data structures that already implement `WithEncryption` trait and also use the template engine of Rust to make them easily extendable. Take for example the following message: ```rust pub enum GatewayExecuteMsg> where E: JsonSchema { ResetEncryptionKey {} , Encrypted { payload : Binary, payload_signature : Binary, payload_hash : Binary, user_key : Binary, nonce : Binary, }, Extension { msg : E } } ``` You can define a new message that extends the `GatewayExecuteMsg` by simply providing a new type for the `Extension` instead of the default `Option` like this: ```rust // Degine your custom message #[cw_serde] pub enum MyCustomMessage { HandleFoo {} HandleBar {} } // Extend the GatewayExecuteMsg pub type MyGatewayExecuteMsg = GatewayExecuteMsg; ``` Your extended type in this case is available under `MyGatewayExecuteMsg::Extension` variant and you can use it in your contract like this: ```rust /// MyGatewayExecuteMsg match msg { ... ResetEncryptionKey => { ... }, MyGatewayExecuteMsg::Extension{msg} => { /// MyCustomMessage match msg { MyCustomMessage::HandleFoo{} => { // Do something } MyCustomMessage::HandleBar{} => { // Do something } } } ... } ``` ### Functions and methods **`handle_encrypted_wrapper`** The encryption logic, `handle_encrypted_wrapper`, **is where the encryption magic happens** ⭐ You can review the function in the SDK [here](https://github.com/writersblockchain/cosmos-ccl-sdk/blob/930732c9d0b11d6f394d9d99cccb96380e103881/packages/sdk/src/common/handle.rs#L52). It has the following functionality: 1. Check if Message is Encrypted: * If the message is encrypted (`msg.is_encrypted()`), it proceeds with decryption. 2. Extract Encryption Parameters: * Retrieves the encryption parameters from the message (`msg.encrypted()`). 3. Check Nonce: * Ensures the nonce has not been used before to prevent replay attacks. 4. Load Encryption Wallet: * Loads the encryption wallet from storage. 5. Decrypt Payload: * Decrypts the payload using the wallet and the provided parameters (`payload`, `user_key`, and `nonce`). ```rust let decrypted = wallet.decrypt_to_payload( ¶ms.payload, ¶ms.user_key, ¶ms.nonce, )?; ``` [decrypt\_to\_payload](https://github.com/writersblockchain/cosmos-ccl-sdk/blob/930732c9d0b11d6f394d9d99cccb96380e103881/packages/sdk/src/crypto/wallets.rs#L177) uses chacha20poly1305 algorithm 6. Verify Credentials: * Constructs a `CosmosCredential` from the decrypted data. * Inserts the nonce into storage to mark it as used. * Verifies the sender using the `verify_arbitrary` function with the credential. 7. Deserialize Inner Message: * Converts the decrypted payload into the original message type `E`. * Ensures the decrypted message is not encrypted (nested encryption is not allowed). 8. Return Decrypted Message and Updated Info: * Returns the decrypted message and updated `MessageInfo` with the verified sender. **`chacha20poly1305_decrypt`** The following function uses the following types for as the input parameters: * `cosmwasm_std::Binary`, * `std::vec::Vec`. * `[u8]` * and others that implement `Deref` trait ```rust pub fn chacha20poly1305_decrypt( ciphertext : &impl Deref, key : &impl Deref, nonce : &impl Deref, ) -> StdResult> { ... } ``` ### Various authentication utilities To verify a message that was was signed through a method `cosmos arbitrary (036)` message format, you can use the following function: ```rust fn verify_arbitrary(api: &dyn Api, cred: &CosmosCredential) -> StdResult ``` The method takes in a `CosmosCredential` struct as an argument which is a a helpful wrapper over essential required fields required for the verification: ```rust pub struct CosmosCredential where M: Display { /// public key matching the respective secret that was used to sign message pub pubkey : Binary, /// signed sha256 digest of a message wrapped in arbitary data (036) object pub signature : Binary, /// signed inner message before being wrapped with 036 pub message : M, /// prefix for the bech32 address on remote cosmos chain pub hrp : String } ``` Both `CosmosCredential` and `EncryptedParams` can be used with `String` or base64 encoded `Binary` types To generate a preamble message for the `cosmos arbitrary (036)` message format, you can use the following utility function: ```rust fn preamble_msg_arb_036(signer: &str, data: &str) -> String ``` The function uses a hardcoded JSON string with all the required keys present and sorted. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.scrt.network/secret-network-documentation/confidential-computing-layer/ibc/basics/cross-chain-messaging-with-ibc-hooks/functions-methods-and-data-structures.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.