ADO Submission - Cw721 Timelock

[mdjakovic0920]

Welcome to the ADO Submission Template. We will be walking through an example of an ADO and the required information to be able to submit for inclusion within the Andromeda Operating System (aOS).

Contact Information

• Name: Mitar
• Discord: mdjakovic0920
• Email Address: [email protected]
• Github: https://github.com/mdjakovic0920

ADO Repo (Provide a link to the repo the ADO is developed on)
https://github.com/mdjakovic0920/ado-database/tree/main/cw721-timelock

Contract Summary(Details of the contract and specific functionality to be included)
The goal of this ADO is to implement a CW721 Timelock smart contract that allows users to create time-locked NFTs. These NFTs will be transferable but can not be redeemed until a specified time has passed. This feature ensures that the NFTs serve as secure, time-based assets for various applications, such as vesting schedules, delayed rewards, or time-restricted access to content.

The CW721 Timelock contract functions by allowing users to mint NFTs with a specified unlock time. The contract will store the unlock time and ensure that the NFTs cannot be redeemed or used until the specified time has elapsed. Users can interact with the contract to check the remaining time until their NFT can be redeemed. Once the time has passed, the NFTs can be fully utilized or transferred without restrictions, providing a trustless way to manage time-based NFT assets.

This is solution for #7

External Reference Links(Link to something that might provide additional information about this ADO and its use cases if applicable)

• https://certik.medium.com/learn-about-crypto-what-is-a-timelock-ade497ec0bb9

Contract Flow Breakdown(Step by step explanation of how the ADO from start to finish. Workflow diagram is encouraged)

Instantiation - What is defined when instantiating the ADO:

• Define the owner of NFT.
  • The NFT owner is specified during instantiation, providing administrative control over the NFT's settings and operations.
  • This step ensures that there is a designated entity responsible for managing and updating the NFT as needed.
• Link to CW721
  Store the CW721 contract address that this timelock contract will interact with.
• Set Timelock Parameters
  • Define the default timelock duration or any specific conditions for the time-locked NFTs.
  • This configuration sets the foundation for how long the NFTs will be locked before they can be transferred.

Execution - After instantiation, what is the process for working with the ADO:

• Lock NFT
  Lock an NFT with a timelock. The NFT is locked for a specific duration, and the recipient is defined.
• Claim NFT
  After the timelock expires, anyone can call the claim function to send the NFT to the defined recipient.

Queries - What type of information will you need to include, search upon:

• Check Unlock Time
  Query the contract to check the unlock time of a specific NFT.
• Get NFT Details
  Retrieve detailed information about an NFT, including its unlock time and recipient.

Under what category would you include the ADO(non-fungible-tokens, finance, ecosystem etc..)
non-fungible-tokens

Messages

Instantiation (What is specified and stored at instantiation)

pub struct InstantiateMsg {
    pub kernel_address: String,
    pub owner: Option<String>,
    pub authorized_token_addresses: Option<Vec<AndrAddr>>,
}

authorized_token_addresses: An optional vector of addresses that are authorized to interact with the contract. If not specified, any address can interact.

Execute Messages (What are the messages that can be executed, what do they do, and who can call each message)

1. ReceiveNft: Handles the receipt of an NFT and locks it for a specified duration.

ReceiveNft(Cw721ReceiveMsg),

Cw721ReceiveMsg: The message received when an NFT is sent to this contract. This message includes the sender, the token ID, and a message for further handling.

2. ClaimNft: Allows the recipient to claim the NFT once the lock period has expired.

ClaimNft {
    cw721_contract: AndrAddr,
    token_id: String,
},

cw721_contract: The address of the CW721 contract.
token_id: The ID of the token to be claimed.

Query Messages (What are the messages that can be queried, what does each return)

1. UnlockTime: Returns the unlock time for a specified NFT.

UnlockTime {
    cw721_contract: AndrAddr,
    token_id: String,
},

cw721_contract: The address of the CW721 contract.
token_id: The ID of the token.

Returns:

pub struct UnlockTimeResponse {
    pub unlock_time: u64,
}

unlock_time: The time at which the NFT can be claimed.

2. NftDetails: Returns the details of a locked NFT including the unlock time and the recipient address.

NftDetails {
    cw721_contract: AndrAddr,
    token_id: String,
},

cw721_contract: The address of the CW721 contract.
token_id: The ID of the token.

Returns:

pub struct NftDetailsResponse {
    pub unlock_time: u64,
    pub recipient: Addr,
}

unlock_time: The time at which the NFT can be claimed.
recipient: The address of the recipient who can claim the NFT after the unlock time.

---

Possible Next Iterations/Future Work
A potential future iteration of the CW721 Timelock ADO could involve introducing more sophisticated timelocking mechanisms. For example, an enhancement could include a "flexible timelock" feature where multiple unlock periods could be set for a single NFT. This would allow for staggered unlocking, which could be particularly useful in scenarios like vesting schedules where portions of the NFT become available over time. Additionally, integrating advanced permissioning features, such as allowing only certain actions during the lock period, could add even more versatility to the ADO.

Possible Concers/Risks (Security,speed,safety,logic)

• Lock Duration Validations: To prevent potential misuse, it's essential to ensure that the lock duration remains within sensible limits. While the current contract enforces a minimum and maximum lock period, careful consideration should be given to any future changes in these limits to maintain security and usability.
• Simulating Unlock Scenarios: Before NFTs are timelocked, it might be beneficial to introduce a feature that simulates the lock and unlock process. This would help users understand how and when their NFTs will become available, preventing confusion or errors. It would also ensure that the specified unlock times align with the user's intentions, reducing the risk of unintentional asset inaccessibility.

Other ADO’s to Pair With (Does this ADO work with another existing ADO? If so, which and how? Does it need to be part of an App?)
This ADO can work with Cw721 ADO and it is necessary to have a part of an App.

Credits/Associations(Is this ADO inspired by another from the ecosystem? Was it prepared with another partnering group or developers?)
This ADO is based on the Cw721 Timelock of Andromeda Hackerboard .

Dependencies

Cargo Dependencies Used
The dependencies are listed in the Cargo.toml file under the dependencies section.

Third Pary Dependencies(Does this ADO require any third party integrations such as oracles,protocols,specific wallet, or anything off chain)
No third party integrations needed.

Compatibility(To which chains is the ADO compatable. List the included and excluded chains. Does it require a specific sdk module? If so specify.)
Compatible with all chains.

---

Additional Sections/Material Needed

Make sure you have the following in your Repo:

1. Clear and neat ReadMe file that includes a summary of the ADO and documentation on how to use it
2. ADO should contain unit tests. Testing should cover both positive and negative testing with 90% coverage. Any additional testing (on-chain or other) is also encouraged but not required.
3. ADO should contain an updated schema file (Schema generation crate)

Usage Guide

Provide a full exmample of the ADO usage. Include the messages called and the JSON used to call these messages.

Example: Users have NFTs to set timelock. They will use this ADO to do so.

Instantiating the ADO:

{"authorized_token_addresses":[],"owner":"andr1f9q5dhg5q434jyjes002fvkcuk062tnt0wdzl8","kernel_address":"andr12h2acqz3r92e8dg9t3p3r76lueqymuzjga0f3crv7l2f6k9qwjvs65lut0"}

User can set the timelock duration with sending NFT to this ADO.
So have to call SendNft function of cw721.

{"send_nft":{"contract":"./cw721-timelock","token_id":"token1","msg":{"timelock_nft":{"lock_duration":1000000,"recipient":"andr1cp9vxvplgjf508thtacvxeh6qxqsx67gseqcd5"}}}}

After the lock duration user can claim the NFT.

{"claim_nft":{"cw721_contract":"./cw721","token_id":"token1"}}