lsp-ducky-1 v1.0.0

DynamicMetadata Smart Contract

The DynamicMetadata contract provides a dynamic way to manage metadata attributes for tokens. Each token, identified by its unique ID, can have multiple attributes. These attributes are key-value pairs where both the key and the value are strings.

Features

• Dynamic Attributes: This contract allows you to add, update, and retrieve attributes for a given token dynamically.
• Event Notification: When an attribute of a token is updated, the contract emits a RefreshRequired event, indicating that clients should refresh the metadata for that token.

Contract Details

Data Structures

• tokenAttributes: A mapping from token ID to another mapping that maps attribute names to their values.
• attributeNames: A mapping from token ID to a list of its attribute names.

Functions

• getAttributeNames(uint256 tokenId): Returns a list of attribute names for a given token ID.
• getAttribute(uint256 tokenId, string memory attribute): Returns the value of a specific attribute for a given token ID.
• getAttributes(uint256 tokenId): Returns all attributes (name-value pairs) for a given token ID.

Events

• RefreshRequired: Notifies that metadata for a specific token ID needs to be refreshed. Contains the token ID, attribute name, and the new value.

For Smart contract Developers: Internal/Private Method

These functions are meant for contract developers and are not directly callable by end users:

• _emitRefresh(uint256 ID, string memory attribute, string memory newValue): Internal function to trigger the RefreshRequired event.
• _updateMetadata(uint256 ID, string memory attribute, string memory newValue): Internal function to update or add a new attribute.
• _updateAttribute(uint256 ID, string memory attribute, string memory newValue): Private helper function to handle attribute-specific logic.

Usage

To use this contract through inheritance:

1. Inherit the DynamicMetadata contract.
2. Update the Attributes
   1. Emits RefreshRequired event
3. Access the Attributes
   1. Listen to the RefreshRequired event to update metadata in your application as required.
   2. Call the public functions to retrieve attributes for tokens.

License

SPDX-License-Identifier: UNLICENSED

Extended Usage

1. Inherit the DynamicMetadata Contract

contract Asset is DynamicMetadata (){
    // ...
}

2. update the Attributes - using updateMetadata() to emit event

• Call the _updateMetadata function with the token ID you want to update, the attribute name, and the value.
  • Alternatively _updateAttributes() can be used as a lower level feature that allows to update attributes without events being emitted, useful for batch updates, etc.
• Example: To add or update an attribute for a token with ID 12345, set the attribute name as color and the value as red:

_updateMetadata(12345, "color", "red");

3. Retrieve Token Attributes

a) Retrieve All Attribute Names

To get a list of all attribute names associated with a token:

string[] memory names = getAttributeNames(12345);

b) Fetch a Specific Attribute

To fetch the value of the color attribute for token ID 12345:

string memory colorValue = getAttribute(12345, "color");

c) Fetch All Attributes

To get all attributes associated with a token:

mapping(string => string) memory attributes = getAttributes(12345);

4. Listen to Contract Events

Keep your application's metadata up-to-date by listening to the RefreshRequired event. This event is emitted every time an attribute is updated.

a) Using web3.js

dynamicMetadataInstance.events.RefreshRequired({
    filter: {tokenId: 12345},
    fromBlock: 'latest'
}, function(error, event) {
    console.log(event.returnValues);
});

This will print the token ID, updated attribute's name, and its new value.

5. Extending Functionality

The contract's internal and private functions can be utilized in extended contracts to further customize behavior. For instance, you can introduce attribute constraints, or tie metadata updates to specific on-chain activities.

More Examples

Adding or Updating an Attribute

To add or update an attribute for a token with ID 12345, set the attribute name as color and the value as red:

_updateMetadata(12345, "color", "red");

This will add or update the color attribute of the token 12345 to red.

Retrieving an Attribute

To retrieve the value of the color attribute for a token with ID 12345:

string memory colorValue = dynamicMetadataInstance.getAttribute(12345, "color");

This will return the value of the color attribute, which in this case would be red.

Listening to the RefreshRequired Event

To ensure that your application stays updated, you can listen to the RefreshRequired event. Here's how you might do it in a web3.js context:

dynamicMetadataInstance.events.RefreshRequired({
    filter: {tokenId: 12345},
    fromBlock: 'latest'
}, function(error, event) {
    console.log(event.returnValues);
});

This will log the updated attribute's name and new value for the token with ID 12345 whenever the RefreshRequired event is emitted.

Including such examples in the README will help users get a better understanding of how to interact with the contract and its functions. It will also serve as a quick reference guide for developers looking to integrate the contract into their applications.

Versioning https://semver.org/