Expand asset library docs (#322)

## Type of change

- Documentation

## Changes

The following changes have been made:

- Add examples and expand documentation

## Checklist

- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
- [x] I have updated the changelog to reflect the changes on this PR.

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - [#318](https://github.com/FuelLabs/sway-libs/pull/318) Adds further documentation and examples for the `signed_integers` library.
 - [#319](https://github.com/FuelLabs/sway-libs/pull/319) Adds further documentation and examples for the ownership library.
+- [#322](https://github.com/FuelLabs/sway-libs/pull/320) Adds further documentation and examples for the asset metadata library.
 
 ### Changed
 

docs/book/src/asset/metadata.md

@@ -36,7 +36,14 @@ Once imported, the Asset Library's metadata functionality should be available. T
 
 ### Setting Metadata
 
-To set some metadata for an Asset, use the `SetAssetMetadata` ABI provided by the Asset Library with the `_set_metadata()` function. Be sure to follow the [SRC-9](https://docs.fuel.network/docs/sway-standards/src-9-metadata-keys/) standard for your `key`. It is recommended that the [Ownership Library](../ownership/index.md) is used in conjunction with the `SetAssetMetadata` ABI to ensure only a single user has permissions to set an Asset's metadata.
+As described in the [SRC-7](https://docs.fuel.network/docs/sway-standards/src-7-asset-metadata/) standard, the metadata type is a simple enum of the following types:
+
+- `b256`
+- `Bytes`
+- `u64`
+- `String`
+
+To set some metadata of any of the above types for an Asset, you can use the `SetAssetMetadata` ABI provided by the Asset Library with the `_set_metadata()` function. Be sure to follow the [SRC-9](https://docs.fuel.network/docs/sway-standards/src-9-metadata-keys/) standard for your `key`. It is recommended that the [Ownership Library](../ownership/index.md) is used in conjunction with the `SetAssetMetadata` ABI to ensure only a single user has permissions to set an Asset's metadata.
 
 The `_set_metadata()` function follows the SRC-7 standard for logging and will emit the `SetMetadataEvent` when called.
 
@@ -46,10 +53,40 @@ The `_set_metadata()` function follows the SRC-7 standard for logging and will e
 
 > **NOTE** The `_set_metadata()` function will set the metadata of an asset *unconditionally*. External checks should be applied to restrict the setting of metadata.
 
+To set the metadata of an Asset, using only one of the above types, you can define a custom ABI and use it as such:
+
+```sway
+{{#include ../../../../examples/asset/setting_src7_attributes/src/main.sw:setting_src7_attributes_custom_abi}}
+```
+
+> **NOTE** The `_set_metadata()` function will set the metadata of an asset *unconditionally*. External checks should be applied to restrict the setting of metadata.
+
 ### Implementing the SRC-7 Standard with StorageMetadata
 
 To use the `StorageMetadata` type, simply get the stored metadata with the associated `key` and `AssetId` using the provided `_metadata()` convenience function. The example below shows the implementation of the [SRC-7](https://docs.fuel.network/docs/sway-standards/src-7-asset-metadata/) standard in combination with the Asset Library's `StorageMetadata` type and the `_metadata()` function with no user defined restrictions or custom functionality.
 
 ```sway
 {{#include ../../../../examples/asset/basic_src7/src/main.sw:basic_src7}}
 ```
+
+### Getting Metadata
+
+To get the metadata for an asset, apart from the above mentioned `_metadata()` convenience function, you can also use the `get()` method on the `StorageMetadata` type, which returns the `Metadata` type.
+
+```sway
+{{#include ../../../../examples/asset/metadata_docs/src/main.sw:get_metadata}}
+```
+
+This results an `Option` type as the metadata may not be set for the asset and key combination.
+
+If you know that the metadata is set, but you don't know the type, you can use a match statement to access the metadata.
+
+```sway
+{{#include ../../../../examples/asset/metadata_docs/src/main.sw:get_metadata_match}}
+```
+
+If you know that the metadata is set and you know the type, you can use the `as_*` methods to access the metadata. We also provide `is_*` methods to check if the metadata is of a specific type.
+
+```sway
+{{#include ../../../../examples/asset/metadata_docs/src/main.sw:get_metadata_as}}
+```

examples/asset/metadata_docs/src/main.sw

@@ -33,7 +33,52 @@ impl SRC7 for Contract {
 impl SetAssetMetadata for Contract {
     #[storage(read, write)]
     fn set_metadata(asset: AssetId, key: String, metadata: Metadata) {
+        // add your authentication logic here
+        // eg. only_owner()
         _set_metadata(storage.metadata, asset, key, metadata);
     }
 }
 // ANCHOR_END: src7_set_metadata
+
+#[storage(read)]
+fn get_metadata(asset: AssetId, key: String) {
+    // ANCHOR: get_metadata
+    use sway_libs::asset::metadata::*; // To access trait implementations you must import everything using the glob operator.
+    let metadata: Option<Metadata> = storage.metadata.get(asset, key);
+    // ANCHOR_END: get_metadata
+
+    // ANCHOR: get_metadata_match
+    match metadata.unwrap() {
+        Metadata::B256(b256) => {
+        // do something with b256
+},
+        Metadata::Bytes(bytes) => {
+        // do something with bytes
+},
+        Metadata::Int(int) => {
+        // do something with int
+},
+        Metadata::String(string) => {
+        // do something with string
+},
+    }
+    // ANCHOR_END: get_metadata_match
+
+    // ANCHOR: get_metadata_as
+    let metadata: Metadata = storage.metadata.get(asset, key).unwrap();
+
+    if metadata.is_b256() {
+        let b256: b256 = metadata.as_b256().unwrap();
+        // do something with b256
+    } else if metadata.is_bytes() {
+        let bytes: Bytes = metadata.as_bytes().unwrap();
+        // do something with bytes
+    } else if metadata.is_u64() {
+        let int: u64 = metadata.as_u64().unwrap();
+        // do something with int
+    } else if metadata.is_string() {
+        let string: String = metadata.as_string().unwrap();
+        // do something with string
+    }
+    // ANCHOR_END: get_metadata_as
+}

examples/asset/setting_src7_attributes/src/main.sw

@@ -1,6 +1,7 @@
 contract;
 
 use std::string::String;
+use std::bytes::Bytes;
 
 // ANCHOR: setting_src7_attributes
 use sway_libs::asset::metadata::*;
@@ -13,7 +14,45 @@ storage {
 impl SetAssetMetadata for Contract {
     #[storage(read, write)]
     fn set_metadata(asset: AssetId, key: String, metadata: Metadata) {
+        // add your authentication logic here
+        // eg. only_owner()
         _set_metadata(storage.metadata, asset, key, metadata);
     }
 }
 // ANCHOR_END: setting_src7_attributes
+
+// ANCHOR: setting_src7_attributes_custom_abi
+abi CustomSetAssetMetadata {
+    #[storage(read, write)]
+    fn custom_set_metadata(
+        asset: AssetId,
+        key: String,
+        bits256: b256,
+        bytes: Bytes,
+        int: u64,
+        string: String,
+    );
+}
+
+impl CustomSetAssetMetadata for Contract {
+    #[storage(read, write)]
+    fn custom_set_metadata(
+        asset: AssetId,
+        key: String,
+        bits256: b256,
+        bytes: Bytes,
+        int: u64,
+        string: String,
+    ) {
+        let b256_metadata = Metadata::B256(bits256);
+        let bytes_metadata = Metadata::Bytes(bytes);
+        let int_metadata = Metadata::Int(int);
+        let string_metadata = Metadata::String(string);
+
+        // your authentication logic here
+
+        // set whichever metadata you want
+        storage.metadata.insert(asset, key, string_metadata);
+    }
+}
+// ANCHOR_END: setting_src7_attributes_custom_abi