diff --git a/pallets/asset/src/lib.rs b/pallets/asset/src/lib.rs index e8445d21..751b2ac4 100644 --- a/pallets/asset/src/lib.rs +++ b/pallets/asset/src/lib.rs @@ -252,6 +252,33 @@ pub mod pallet { impl Pallet { #[pallet::call_index(0)] #[pallet::weight(::WeightInfo::create())] + /// Creates a new asset entry within a specified space. + /// + /// This function is responsible for creating a new asset entry in the blockchain. + /// It verifies the caller's authorization, validates the asset entry, and then + /// generates a unique identifier for the asset. If all checks pass, it records the + /// asset entry in the storage and emits a creation event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the creator. + /// - `entry`: The details of the asset being created, including quantity, value, and type. + /// - `digest`: The hash of the entry data. + /// - `authorization`: The authorization ID used to validate the creation. + /// + /// # Returns + /// Returns `Ok(())` if the asset was successfully created, or an `Err` with an appropriate + /// error if the operation fails. + /// + /// # Errors + /// - `InvalidAssetValue`: If the asset quantity or value is non-positive. + /// - `InvalidAssetType`: If the asset type is invalid. + /// - `InvalidIdentifierLength`: If the generated identifier is of invalid length. + /// - `AssetIdAlreadyExists`: If an asset with the generated identifier already exists. + /// - Propagates errors from `pallet_chain_space::Pallet::ensure_authorization_origin` and + /// `Self::update_activity` if they fail. + /// + /// # Events + /// - `Event::Create`: Emitted when an asset is successfully created. pub fn create( origin: OriginFor, entry: AssetInputEntryOf, @@ -301,6 +328,37 @@ pub mod pallet { Ok(()) } + /// Issues new instances of an existing asset. + /// + /// This function is responsible for issuing new instances of an existing asset. + /// It verifies the caller's authorization and ensures the asset is active and has + /// sufficient quantity for issuance. If all checks pass, it generates a unique + /// identifier for each new asset instance, records the issuance in the storage, + /// and emits an issuance event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the issuer. + /// - `entry`: The details of the asset issuance, including asset ID, owner, and issuance + /// quantity. + /// - `digest`: The hash of the entry data. + /// - `authorization`: The authorization ID used to validate the issuance. + /// + /// # Returns + /// Returns `Ok(())` if the asset instances were successfully issued, or an `Err` with an + /// appropriate error if the operation fails. + /// + /// # Errors + /// - `AssetIdNotFound`: If the asset with the given ID does not exist. + /// - `UnauthorizedOperation`: If the caller is not the issuer of the asset. + /// - `AssetNotActive`: If the asset is not active. + /// - `OverIssuanceLimit`: If the issuance quantity exceeds the asset's total quantity. + /// - `InvalidIdentifierLength`: If the generated identifier is of invalid length. + /// - `DistributionLimitExceeded`: If the distribution limit is exceeded. + /// - Propagates errors from `pallet_chain_space::Pallet::ensure_authorization_origin` and + /// `Self::update_activity` if they fail. + /// + /// # Events + /// - `Event::Issue`: Emitted when asset instances are successfully issued. #[pallet::call_index(1)] #[pallet::weight(::WeightInfo::issue())] pub fn issue( @@ -384,6 +442,34 @@ pub mod pallet { Ok(()) } + /// Transfers ownership of an asset instance. + /// + /// This function is responsible for transferring ownership of a specific asset instance. + /// It verifies the caller's authorization, ensures the asset and its instance are active, + /// and then updates the ownership record. If all checks pass, it records the transfer + /// in the storage and emits a transfer event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the current owner. + /// - `entry`: The details of the asset transfer, including asset ID, instance ID, current + /// owner, and new owner. + /// - `_digest`: The hash of the entry data (unused in this function). + /// + /// # Returns + /// Returns `Ok(())` if the asset instance was successfully transferred, or an `Err` with an + /// appropriate error if the operation fails. + /// + /// # Errors + /// - `AssetIdNotFound`: If the asset with the given ID does not exist. + /// - `AssetInstanceNotFound`: If the asset instance with the given ID does not exist. + /// - `UnauthorizedOperation`: If the caller or the specified current owner is not the owner + /// of the asset instance. + /// - `AssetNotActive`: If the asset is not active. + /// - `InstanceNotActive`: If the asset instance is not active. + /// - Propagates errors from `Self::update_activity` if it fails. + /// + /// # Events + /// - `Event::Transfer`: Emitted when an asset instance is successfully transferred. #[pallet::call_index(2)] #[pallet::weight(::WeightInfo::transfer())] pub fn transfer( @@ -434,6 +520,36 @@ pub mod pallet { Ok(()) } + /// Changes the status of an asset or an asset instance. + /// + /// This function is responsible for changing the status of an asset or a specific asset + /// instance. It verifies the caller's authorization, ensures the new status is valid, and + /// then updates the status in storage. If all checks pass, it records the status change + /// and emits a status change event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the issuer. + /// - `asset_id`: The identifier of the asset whose status is being changed. + /// - `instance_id`: An optional identifier of the specific asset instance whose status is + /// being changed. + /// - `new_status`: The new status to be assigned to the asset or asset instance. + /// + /// # Returns + /// Returns `Ok(())` if the status was successfully changed, or an `Err` with an appropriate + /// error if the operation fails. + /// + /// # Errors + /// - `AssetIdNotFound`: If the asset with the given ID does not exist. + /// - `AssetInstanceNotFound`: If the asset instance with the given ID does not exist (if + /// `instance_id` is provided). + /// - `UnauthorizedOperation`: If the caller is not the issuer of the asset. + /// - `InvalidAssetStatus`: If the new status is invalid. + /// - `AssetInSameState`: If the new status is the same as the current status. + /// - Propagates errors from `Self::update_activity` if it fails. + /// + /// # Events + /// - `Event::StatusChange`: Emitted when the status of an asset or asset instance is + /// successfully changed. #[pallet::call_index(3)] #[pallet::weight(::WeightInfo::status_change())] pub fn status_change( @@ -487,6 +603,30 @@ pub mod pallet { Ok(()) } + /// Creates a new VC (Verifiable Credential) asset. + /// + /// This function is responsible for creating a new VC asset. It verifies the caller's + /// authorization, ensures the provided asset quantity is valid, and then records the new + /// asset in storage. If all checks pass, it emits a creation event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the creator. + /// - `asset_qty`: The quantity of the asset to be created. + /// - `digest`: The hash of the entry data. + /// - `authorization`: The authorization ID used to validate the creation. + /// + /// # Returns + /// Returns `Ok(())` if the asset was successfully created, or an `Err` with an appropriate + /// error if the operation fails. + /// + /// # Errors + /// - `InvalidAssetQty`: If the provided asset quantity is zero or negative. + /// - `InvalidIdentifierLength`: If the generated identifier length is invalid. + /// - `AssetIdAlreadyExists`: If an asset with the generated identifier already exists. + /// - Propagates errors from `Self::update_activity` if it fails. + /// + /// # Events + /// - `Event::Create`: Emitted when a VC asset is successfully created. // TODO: Set actual weights #[pallet::call_index(4)] #[pallet::weight({0})] @@ -539,6 +679,35 @@ pub mod pallet { Ok(()) } + /// Issues a new instance of a VC (Verifiable Credential) asset. + /// + /// This function is responsible for issuing a new instance of a VC asset. It verifies the + /// caller's authorization, ensures the provided issuance quantity is valid, and then + /// records the new asset instance in storage. If all checks pass, it emits an issuance + /// event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the issuer. + /// - `entry`: The details of the asset issuance entry, including the asset ID, owner, and + /// issuance quantity. + /// - `digest`: The hash of the entry data. + /// - `authorization`: The authorization ID used to validate the issuance. + /// + /// # Returns + /// Returns `Ok(())` if the asset instance was successfully issued, or an `Err` with an + /// appropriate error if the operation fails. + /// + /// # Errors + /// - `AssetIdNotFound`: If the asset with the given ID does not exist. + /// - `UnauthorizedOperation`: If the caller is not the issuer of the asset. + /// - `AssetNotActive`: If the asset is not in an active state. + /// - `OverIssuanceLimit`: If the issuance quantity exceeds the asset's available quantity. + /// - `InvalidIdentifierLength`: If the generated identifier length is invalid. + /// - `DistributionLimitExceeded`: If the distribution limit is exceeded. + /// - Propagates errors from `Self::update_activity` if it fails. + /// + /// # Events + /// - `Event::Issue`: Emitted when a VC asset instance is successfully issued. #[pallet::call_index(5)] #[pallet::weight({0})] pub fn vc_issue( @@ -621,6 +790,34 @@ pub mod pallet { Ok(()) } + /// Transfers ownership of a VC (Verifiable Credential) asset instance. + /// + /// This function facilitates the transfer of ownership of a VC asset instance. It verifies + /// that the caller is the current owner of the asset instance, checks the asset and + /// instance status, and updates the ownership record in storage. If all checks pass, it + /// emits a transfer event. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the current owner of the + /// asset instance. + /// - `entry`: The details of the asset transfer entry, including the asset ID, instance ID, + /// current owner, and new owner. + /// - `digest`: The hash of the entry data. + /// + /// # Returns + /// Returns `Ok(())` if the asset instance ownership was successfully transferred, or an + /// `Err` with an appropriate error if the operation fails. + /// + /// # Errors + /// - `AssetIdNotFound`: If the asset with the given ID does not exist. + /// - `AssetInstanceNotFound`: If the asset instance with the given ID does not exist. + /// - `UnauthorizedOperation`: If the caller is not the current owner of the asset instance. + /// - `AssetNotActive`: If the asset is not in an active state. + /// - `InstanceNotActive`: If the asset instance is not in an active state. + /// - Propagates errors from `Self::update_activity` if it fails. + /// + /// # Events + /// - `Event::Transfer`: Emitted when a VC asset instance is successfully transferred. #[pallet::call_index(6)] #[pallet::weight({0})] pub fn vc_transfer( @@ -672,6 +869,35 @@ pub mod pallet { Ok(()) } + /// Changes the status of a VC (Verifiable Credential) asset or asset instance. + /// + /// This function allows the issuer of an asset to change the status of either the entire + /// asset or a specific asset instance. It checks that the caller is the issuer of the + /// asset, verifies the new status, and updates the status in storage. If the status + /// change is successful, an event is emitted. + /// + /// # Parameters + /// - `origin`: The origin of the call, which must be signed by the issuer of the asset. + /// - `asset_id`: The identifier of the asset whose status is being changed. + /// - `instance_id`: An optional identifier of the specific asset instance whose status is + /// being changed. If `None`, the status of the entire asset is changed. + /// - `new_status`: The new status to be assigned to the asset or asset instance. + /// + /// # Returns + /// Returns `Ok(())` if the status was successfully changed, or an `Err` with an appropriate + /// error if the operation fails. + /// + /// # Errors + /// - `AssetIdNotFound`: If the asset with the given ID does not exist. + /// - `UnauthorizedOperation`: If the caller is not the issuer of the asset. + /// - `InvalidAssetStatus`: If the provided status is not a valid status type. + /// - `AssetInstanceNotFound`: If the specific asset instance does not exist. + /// - `AssetInSameState`: If the asset or asset instance is already in the provided status. + /// - Propagates errors from `Self::update_activity` if it fails. + /// + /// # Events + /// - `Event::StatusChange`: Emitted when the status of an asset or asset instance is + /// successfully changed. #[pallet::call_index(7)] #[pallet::weight({0})] pub fn vc_status_change(