lsp-ducky-1/README.md

The DynamicMetadata Smart Contract is a robust solution for managing metadata attributes of tokens in a dynamic manner. It allows users to add, update, and retrieve attributes associated with unique token IDs, with attributes being represented as key-valu

# 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

```solidity
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`:

```solidity
_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:

```solidity
string[] memory names = getAttributeNames(12345);
```

#### b) Fetch a Specific Attribute

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

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

#### c) Fetch All Attributes

To get all attributes associated with a token:

```solidity
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

```javascript
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`:

```solidity
_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`:

```solidity
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:

```javascript
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/>