CW721

Introduction

The CW721 ADO is a smart contract to allow users to launch their own custom NFT projects. In addition to the standard CW721 messages, we have added some custom logic to further extend the utility and function of the contract.

The CW721 ADO is one of the base ADOs meaning it can interact with a large number of other ADOs such as the marketplace, crowdfund, auction, CW721 timelock and many more.

The contract has implemented a custom TransferAgreement message to allow the buying/selling of tokens between two parties throught the CW721 ADO itself.

Ado_type: cw721

Version: 2.0.3-beta.1

InstantiateMsg

Rust

pub struct InstantiateMsg {
    pub name: String,
    pub symbol: String,
    pub minter: AndrAddr,
    pub kernel_address: String,
    pub owner: Option<String>,
}

JSON

{
"name": "Example Token",
"symbol": "ET",
"minter":"andr1...",
"kernel_address":"andr1..."
}
        

Name	Type	Description
name	String	The name of the NFT collection.
symbol	String	The symbol of the NFT collection.
minter	AndrAddr	The address allowed to mint NFTs.
kernel_address	String	Contract address of the kernel contract to be used for AMP messaging. Kernel contract address can be found in our deployed contracts.
owner	Option<String>	Optional address to specify as the owner of the ADO being created. Defaults to the sender if not specified.

ExecuteMsg

Mint

Mints a new NFT.

Only available to the defined minter in the InstantiateMsg.

Rust

pub enum ExecuteMsg  {
   Mint {
    pub token_id: String,
    pub owner: String,
    pub token_uri: Option<String>,
    pub extension: TokenExtension,
   }
}

JSON

{
"mint": {                                                                                                                             
    "token_id": "1",
    "owner": "andr1...",
    "token_uri":"https://gateway.pinata.cloud/ipfs...",
    "extension": {
            "publisher": "Andromeda"
        }
    }
}

Name	Type	Description
token_id	String	Unique Id of the NFT.
owner	String	The address of the NFT owner.
token_uri	Option<String>	URI pointing to the NFT metadata. You can read more about the NFT token URI and metadata standards here.
extension	TokenExtension	Any custom extension used by this contract. Here we use TokenExtension.

TokenExtension

Extension that can be added to an NFT when minting.

pub struct TokenExtension {
   pub publisher: String,
}

Name	Type	Description
publisher	String	The entity to assign as the publisher of the NFT e.g. "Andromeda" or "Bob". (Immutable).

BatchMint

Mint several NFTs at once.

Rust

pub enum ExecuteMsg {
   BatchMint {
        tokens: Vec<MintMsg>,
    }
}

JSON

{
  "batch_mint": {
    "tokens": [
      {
        "token_id": "1",
        "owner": "andr1...",
        "token_uri":"https://gateway.pinata.cloud/ipfs...",
        "extension": {
          "publisher": "Andromeda"
        }
      },
      {
        "token_id": "2",
        "owner": "andr1...",
        "token_uri":"https://gateway.pinata.cloud/ipfs...",
        "extension": {
          "publisher": "Andromeda"
        }
      },
      {
        "token_id": "3",
        "owner": "andr1...",
        "token_uri":"https://gateway.pinata.cloud/ipfs...",
        "extension": {
          "publisher": "Andromeda"
        }
      }
    ]
  }
}

Name	Type	Description
tokens	Vec<MintMsg>	Vector of MintMsg. Similar to minting one token, but allows minting of many tokens in one go.

TransferAgreement

Assigns a TransferAgreement for a token. If the agreement field is not set, the message will remove any previously set agreements on the token (Instead of making a new RemoveAgreement message).

Only available to the token owner.

Rust

pub enum ExecuteMsg {
       TransferAgreement {
           token_id: String,
           agreement: Option<TransferAgreement>,
        }
  }

JSON

{
"transfer_agreement":{
    "token_id":"1",
    "agreement":{
        "amount":{
            "raw":{
                "denom":"uandr",
                "amount":"1000000"
                }
            },
         "purchaser":"andr1..."
         }
   }
 }

Name	Type	Description
token_id	String	The token Id of the NFT we want to add an agreement for.
agreement	Option<TransferAgreement>	The agreement for the token containing the selling price and the address allowed to purchase the token. If not specified then any previously set agreement is removed from the token.

TransferAgreement

The purchaser may use the TransferNft message for this token as long as funds are provided equaling the amount defined in the agreement.

If the purchaser is set to "*" then anyone can complete the TransferAgreement (Anyone can buy the NFT).

pub struct TransferAgreement {
    pub amount: Coin,
    pub purchaser: String,
}

Name	Type	Description
amount	Coin	The amount required for the purchaser to transfer ownership of the token.
purchaser	String	The address of the purchaser that is allowed to purchase the token.

TransferNft

A CW721 compliant transfer method. Transfers ownership of a minted token.

Archived tokens cannot be transferred.

Only available to the contract owner, an approved operator, or a purchaser in a TransferAgreement for the given token.

Rust

pub enum ExecuteMsg {
    TransferNft {
        recipient: AndrAddr,
        token_id: String,
    }
}

JSON

{
    "transfer_nft": {
        "recipient": "andr1...",
        "token_id": "anewtoken"
    }
}

Name	Type	Description
recipient	AndrAddr	The address to receive the NFT.
token_id	String	The token Id of the token to be transferred.

SendNft

A CW721 compliant send method. Sends ownership of a minted token to an external contract.

Only available to the token owner/operator/approved address.

Rust

pub enum ExecuteMsg {
    SendNft {
        contract: AndrAddr,
        token_id: String,
        msg: Binary,
    }
}

JSON

{
    "send_nft": {
        "contract": "andr1...",
        "token_id": "anewtoken",
        "msg":"eyJzdGFydF9hdWN0aW9uIjogeyJzdGFydF90aW1lIjogMTY2MzMzNDk3MDIxMSwiZHVyYXRpb24iOiA5MDAwMDAsImNvaW5fZGVub20iOiAidWFuZHIiLCJtaW5fYmlkIjoiMzAwIiwid2hpdGVsaXN0IjogWyJhbmRyMS4uLiIsICJhbmRyMS4uLiIsIC4uLl19fQ=="
    }
}

Name	Type	Description
contract	AndrAddr	The address of the receiving contract.
token_id	String	The Id of the token to be sent.
msg	Binary	A message to be sent to the receiving contract.

Burn

Destroys any token data related to an token Id. The Id of the token is still reserved.

Cannot be undone.

Only available to the token owner.

Rust

pub enum ExecuteMsg {
    Burn {
        token_id: String,
    },
}

JSON

{
    "burn": {
        "token_id": "1"
    }
}

Name	Type	Description
token_id	String	The Id of the token to burn.

Archive

Archives an token, making it immutable in any respect. Once an token is archived it cannot be edited, transferred or burnt.

Cannot be undone.

Only available to the token owner.

Rust

pub enum ExecuteMsg {
    Archive {
        token_id: String,
    }
}

JSON

{
    "archive": {
        "token_id": "1"
    }
}

Name	Type	Description
token_id	String	The Id of the token to archive.

Approve

A CW721 compliant approve method. Approves a given address as an operator for the token, allowing them to transfer, burn or archive the token.

Only available to the token owner/operator.

Rust

pub enum ExecuteMsg {
    Approve {
        spender: String,
        token_id: String,
        expires: Option<Expiration>,
    }
}

JSON

{
    "approve": {
        "spender": "andr1...",
        "token_id": "1"
    }
}

Name	Type	Description
spender	String	The address to be authorised as an operator.
token_id	String	The id of the token for which to assign the spender as an operator.
expires	Option<Expiration>	An optional expiration for the approval. Defaults to never.

Revoke

A CW721 compliant revoke method. Revokes operator privileges for a given address.

Only available to the token owner/operator.

Rust

pub enum ExecuteMsg {
    Revoke {
        spender: String,
        token_id: String,
    }
}

JSON

{
    "revoke": {
        "spender": "andr1...",
        "token_id": "1"
    }
}

Name	Type	Description
spender	String	The address of the operator for which to revoke privileges.
token_id	String	The Id of the token for which to revoke operator privileges.

ApproveAll

A CW721 compliant approve all method. Approves a given address as an operator for all tokens owned by the sender.

Will overwrite any approval currently assigned to the operator's address.

Rust

pub enum ExecuteMsg {
    ApproveAll {
        operator: String,
        expires: Option<Expiration>,
    }
}

JSON

{
    "approve_all": {
        "operator": "andr1..."
    }
}

Name	Type	Description
operator	String	The address to be authorised as an operator.
expires	Option<Expiration>	An optional expiration for the approval. Defaults to never.

RevokeAll

A CW721 compliant revoke all method. Revokes an operator's privileges for any tokens owned by the sender.

Rust

pub enum ExecuteMsg {
    RevokeAll {
        operator: String,
    }
}

JSON

{
    "revoke_all": {
        "operator": "andr1..."
    }
}

Name	Type	Description
operator	String	The address of the operator for which to revoke privileges.

Base Executes

The rest of the execute messages can be found in the ADO Base section.

QueryMsg

Minter

Queries the current minter of the contract.

Rust

pub enum QueryMsg{
    #[returns(MinterResponse)]
    Minter{},
 }

JSON

{
"minter":{}
}

MinterResponse

Rust

pub struct MinterResponse{
        minter: Option<String>,
 }

JSON

{
"minter":"andr1..."
}

OwnerOf

A CW721 compliant "owner of" query. Queries the current owner of a given token Id.

Rust

pub enum QueryMsg {
    #[returns(OwnerOfResponse)]
    OwnerOf {
        token_id: String,
        include_expired:bool,
    }
}

JSON

{
    "owner_of": {
        "token_id": "1",
        "include_expired": false
    }
}

Name	Type	Description
token_id	String	The Id of the token to query.
include_expired	bool	Whether to include any expired owners.

OwnerOfResponse

Rust

pub struct OwnerOfResponse {
    pub owner: String,
    pub approvals: Vec<Approval>,
}

JSON

{
    "owner": "andr1...",
    "approvals": [
        {
            "spender": "andr1...",
            "expires": "never"
        }
    ]
}

Name	Type	Description
owner	String	The owner of the queried token.
approvals	Vec<Approval>	An array of all approvals for the token.

Approval

pub struct Approval {
    pub spender: String,
    pub expires: Expiration,
}

Name	Type	Description
spender	String	The address that is approved.
expires	Expiration	The expiration for the approval.

Operator

Returns the approval of a given operator for all tokens of an owner. Errors if no approvals are set.

Rust

pub enum QueryMsg {
   #[returns(cw721::OperatorResponse)]
   Operator {
        owner: String,
        operator: String,
        include_expired: Option<bool>,
    }
 }

JSON

// Some code

Name	Type	Description
owner	String	The address of the NFTs owner.
operator	String	The address of the operator that has approvals over the specified owner NFTs.
include_expired	Option<bool>	Whether to include any expired approvals.

OperatorResponse

Rust

#[cw_serde]
pub struct OperatorResponse {
    pub approval: Approval,
}

JSON

{
"approval":{
    "spender": "andr1...",
    "expires":{
            "at_time": "16705100749238434832"
        }
    }
 }

Returns an Approval struct.

AllOperators

List all operators that can access all of the owner's tokens.

Rust

pub enum QueryMsg {
    #[returns(OperatorsResponse)]
    AllOperators {
        owner: String,
        include_expired: Option<bool>,
        start_after: Option<String>,
        limit: Option<u32>,
    },

JSON

{
    "all_operators": {
        "owner": "andr1...",
        "include_expired": true,
        "start_after":"andr1...",
        "limit": 10
    }
}

Name	Type	Description
owner	String	The address of the owner for which to query operators.
include_expired	Option<bool>	Whether to include any expired approvals.
limit	Option<u32>	An optional limit on how many approvals are returned. The default limit is 10 and the maximum limit allowed is 100.
start_after	Option<String>	An optional address for which to start after, used for pagination.

OperatorsResponse

Rust

pub struct OperatorsResponse {
    pub operators: Vec<Approval>,
}

JSON

{
    "operators": [
        {
            "spender": "andr1...",
            "expires":{
                "at_time": "16705100749238434832"
            }
        },
      ...
    ]
}

Name	Type	Description
approvals	Vec<Approval>	An array of all approvals for the given owner address.

NumTokens

A CW721 compliant "num tokens" query. Queries the amount of tokens minted by the contract.

Rust

pub enum QueryMsg {
    #[returns(NumTokensResponse)]
    NumTokens {}
}

JSON

{
"num_tokens": {}
}

NumTokensResponse

Rust

pub struct NumTokensResponse {
    pub count: u64,
}

JSON

{
    "count": 1
}

Name	Type	Description
count	u64	The amount of tokens minted by the contract.

NftInfo

A CW721 compliant "nft info" query. Queries the stored info of a token.

Rust

pub enum QueryMsg {
    #[returns(NftInfoResponse<TokenExtension>)]
    NftInfo {
        token_id: String,
    }
}

JSON

{
    "nft_info": {
        "token_id": "1"
    }
}

Name	Type	Description
token_id	String	The id of the token.

NftInfoResponse

Rust

pub struct NftInfoResponse<T> {
    pub token_uri: Option<String>,
    pub extension: T,
}

JSON

{
   "extension":{
         "name":"mytoken",
         "publisher":"publisher",
         "description":"This token ....",
         "archived": false
        }
 }

Name	Type	Description
token_uri	String	Universal resource identifier for this token.
extension	T (Generic type)	Any extension being used by the contract to add custom metadata to the tokens.

AllNftInfo

A CW721 compliant "all nft info" query. Queries all stored info of an token.

Rust

pub enum QueryMsg {
    #[returns(AllNftInfoResponse<TokenExtension>)]
    AllNftInfo {
        token_id: String,
        include_expired: Option<bool>
    }
}

JSON

{
    "all_nft_info": {
        "token_id": "1",
        "include_expired": false
    }
}

Name	Type	Description
token_id	String	The token id of the NFT.
include_expired	Option<bool>	Whether to include any expired approvals.

AllNftInfoResponse

Rust

pub struct AllNftInfoResponse<T> {
    pub access: OwnerOfResponse,
    pub info: NftInfoResponse<T>,
}

JSON

{
    "access": {
        "owner": "andr1...",
        "approvals": [
            {
                "spender": "andr1...",
                "expires": "never"
            }
        ]
    },
    "info": {
        "name": "A New Token",
        "description": "A newly minted token",
        "extension": {
            "archived": false,
            "metadata": "{ \"some_json_field\": \"some_json_value\" }",
            "agreement": {
                "purchaser": "andr1...",
                "amount": "100uandr"
            }
        }
    }
}

Name	Type	Description
access	OwnerOfResponse	The address that can transfer the token.
info	NFtInfoResponse	Data on the token itself.

IsArchived

Checks if the token with the specified token_id is archived.

Rust

pub enum QueryMsg {
   #[returns(bool)]
   IsArchived {
         token_id: String,
        }
 }

JSON

{
"is_archived":{
    "token_id":"3"
    }
}

Name	Type	Description
token_id	String	The token_id of the NFT we want to check.

Returns a bool value.

TransferAgreement

Checks if the token has a TransferAgreement .

Rust

pub enum QueryMsg {
      #[returns(Option<TransferAgreement>)]
      TransferAgreement {
        token_id: String,
    }
}

JSON

{
"transfer_agreement":{
    "token_id":"3"
    }
}

Name	Type	Description
token_id	String	The token_id of the nft we want to check.

Returns None if no TransferAgreement is found, and the TransferAgreement struct otherwise.

Tokens

Queries all the tokens of a particular owner.

Rust

pub enum QueryMsg {
    #[returns(TokensResponse)]
    Tokens {
        owner: String,
        start_after: Option<String>,
        limit: Option<u32>,
    }
}

JSON

{
"tokens": {
            "owner":"andr1...",
            "start_after":"3",
            "limit": 25
            }
    }

Name	Type	Description
owner	String	The address that we want to check the tokens of
start_after	Option<String>	An optional address for which to start after, used for pagination.
limit	Option<u32>	Optional limit to the number of tokens queried. It is set by default as 10 and can be set up to 30.

TokensResponse

Contains all token_ids in lexicographical ordering. If there are more than limit, use start_from in future queries to achieve pagination.

pub struct TokensResponse {
    pub tokens: Vec<String>,
}

AllTokens

Queries the tokens minted by the contract.

Rust

 pub enum QueryMsg {
    #[returns(TokensResponse)]
    AllTokens {
        start_after: Option<String>,
        limit: Option<u32>,
        }
 }

JSON

{
  "all_tokens": {
          "limit": 5
          }
  }

Name	Type	Description
start_after	Option<String>	An optional address for which to start after, used for pagination.
limit	Option<u32>	Optional limit to the number of tokens queried. It is set by default as 10 and can be set up to 30.

TokensResponse

Contains all token_ids in lexicographical ordering. If there are more than limit, use start_from in future queries to achieve pagination.

pub struct TokensResponse {
    pub tokens: Vec<String>,
}

ContractInfo

Queries the name and symbol of the token collection.

Rust

pub enum QueryMsg {
    #[returns(ContractInfoResponse)]
    ContractInfo {}
}

JSON

{
    "contract_info": {}
}

ContractInfoResponse

Rust

pub struct CotractInfoResponse {
    pub name: String,
    pub symbol: String,
}

JSON

{
    "name": "Example Token",
    "symbol": "ET"
}

Name	Type	Description
name	String	The name of the contract.
symbol	String	The assigned symbol of the contract.

Approval

Queries the spender's approval to check for the expiration.

Rust

 pub enum QueryMsg {
 Approval {
        token_id: String,
        spender: String,
        include_expired: Option<bool>,
    }
 }

JSON

{
"approval":{
    "token_id":"my_token";
    "spender":"andr1...";
    "include_expired": true
    }
} 

Name	Type	Description
token_id	String	The token Id of the NFT to check.
spender	String	The address to check the approvals.
include_expired	Option<bool>	Optional flag to include the expired approvals. Defaults to false.

ApprovalResponse

Rust

pub struct ApprovalResponse {
    pub approval: Approval,
}

JSON

{
"spender":"andr1...";
"expires":{
    "at_height": 500
    }
}

Name	Type	Description
approval	Approval	The approved spender and the expiration for the approval.

pub struct Approval {
    pub spender: String,
    pub expires: Expiration,
}

Name	Type	Description
spender	String	Account that can transfer/send the token
expires	Expiration	When the Approval expires. Might be Expiration::never.

Approvals

Returns all the approvals a token has.

Rust

pub enum QueryMsg{
  Approvals {
        token_id: String,
        include_expired: Option<bool>,
    }
 }

JSON

{
"approval":{
    "token_id":"my_token";
    "include_expired": true
    }
}

Name	Type	Description
token_id	String	The token Id of the NFT to get approvals for.
include_expired	Option<bool>	Optional flag to include the expired approvals. Defaults to false.

ApprovalsResponse

Rust

pub struct ApprovalsResponse {
    pub approvals: Vec<Approval>,
}

JSON

{
"approvals":[    
                {
                    "spender":"andr1...";
                    "expires":{
                        "at_height": 500
                         }
                    },
                    {
                    "spender":"andr1...";
                    "expires":{
                        "at_height": 500
                        }
                    },
                    ...
            ]
}

Return a vector of Approval.

Base Queries

The rest of the query messages can be found in the ADO Base section.