HMIP-721Implementation

• Instantiating The Token Contract
• Messages
  • MintNft
  • BatchMintNft
  • MintNftClones
  • SetMetadata
  • SetRoyaltyInfo
  • Reveal
  • MakeOwnershipPrivate
  • SetGlobalApproval
  • SetWhitelistedApproval
  • Approve
  • Revoke
  • ApproveAll
  • RevokeAll
  • TransferNft
  • BatchTransferNft
  • SendNft
  • BatchSendNft
  • BurnNft
  • BatchBurnNft
  • CreateViewingKey
  • SetViewingKey
  • AddMinters
  • RemoveMinters
  • SetMinters
  • SetContractStatus
  • ChangeAdmin
  • RegisterReceiveNft
  • RevokePermit
• Queries
  • ContractInfo
  • ContractConfig
  • Minters
  • RegisteredCodeHash
  • NumTokens
  • AllTokens
  • IsUnwrapped
  • IsTransferable
  • OwnerOf
  • NftInfo
  • AllNftInfo
  • PrivateMetadata
  • NftDossier
  • RoyaltyInfo
  • TokenApprovals
  • ApprovedForAll
  • InventoryApprovals
  • Tokens
  • VerifyTransferApproval
  • ImplementsTokenSubtype
  • ImplementsNonTransferableTokens
  • TransactionHistory
  • WithPermit
• Receiver Interface
  • ReceiveNft
  • BatchReceiveNft

Instantiating The Token Contract

Request

{
	“name”: “name_of_the_token”,
	“symbol”: “token_symbol”,
	“admin”: “optional_admin_address”,
	“entropy”: “string_used_as_entropy_when_generating_random_viewing_keys”,
	"royalty_info": {
		"decimal_places_in_rates": 4,
		"royalties": [
			{
				"recipient": "address_that_should_be_paid_this_royalty",
				"rate": 100,
			},
			{
				"...": "..."
			}
		],
	},
	“config”: {
		“public_token_supply”: true | false,
		“public_owner”: true | false,
		“enable_sealed_metadata”: true | false,
		“unwrapped_metadata_is_private”: true | false,
		“minter_may_update_metadata”: true | false,
		“owner_may_update_metadata”: true | false,
		“enable_burn”: true | false
	},
	“post_init_callback”: {
		“msg”: “base64_encoded_Binary_representing_the_msg_to_perform_after_initialization”,
		“contract_address”: “address_of_the_contract_being_called_after_initialization”,
		“code_hash”: “code_hash_of_the_contract_being_called_after_initialization”,
		“send”: [
			{
				“denom”: “denom_string_for_native_coin_being_sent_with_this_message”,
				“amount”: “amount_of_native_coin_being_sent”
			},
			{
				"...": "..."
			}
		]
	}
}

The contract's default RoyaltyInfo is the RoyaltyInfo that will be assigned to any token that is minted without explicitly defining its own RoyaltyInfo. It should be noted that default RoyaltyInfo only applies to new tokens minted while the default is in effect, and will not alter the royalties for any existing NFTs. This is because a token creator should not be able to sell a token with only 1% advertised royalty, and then change it to 100% once it is purchased. If a SNIP-722 non-transferable token is minted, it will not inherit default royalties because non-transferable tokens can never be transferred as part of a sale, rendering royalties meaningless.

RoyaltyInfo

RoyaltyInfo is used to define royalties to be paid when an NFT is sold. This implementation will only display a token's royalty recipient addresses if the querier has permission to transfer the token, and it will only display the contract's default royalty recipient addresses if the querier is an authorized minter.

{
	"decimal_places_in_rates": 4,
	"royalties": [
		{
			"recipient": "address_that_should_be_paid_this_royalty_(optional_in_query_responses)",
			"rate": 100,
		},
		{
			"...": "..."
		}
	]
}

Royalty

Royalty defines a payment address and a royalty rate to be paid when an NFT is sold. This implementation will only display a token's royalty recipient addresses if the querier has permission to transfer the token, and it will only display the contract's default royalty recipient addresses if the querier is an authorized minter.

{
	"recipient": "address_that_should_be_paid_this_royalty_(optional_in_query_responses)",
	"rate": 100,
}

Config

Config is the privacy configuration for the contract.

• public_token_supply - This config value indicates whether the token IDs and the number of tokens controlled by the contract are public. If the token supply is private, only minters can view the token IDs and number of tokens controlled by the contract (default: False)
• public_owner - This config value indicates whether token ownership is public or private by default. Regardless of this setting a user has the ability to change whether the ownership of their tokens is public or private (default: False)
• enable_sealed_metadata - This config value indicates whether sealed metadata should be enabled. If sealed metadata is enabled, the private metadata of a newly minted token is not viewable by anyone, not even the owner, until the owner calls the Reveal message. When Reveal is called, the sealed metadata is irreversibly unwrapped and moved to the public metadata (as default). If unwrapped_metadata_is_private is set to true, the sealed metadata will remain as private metadata after unwrapping, but the owner (and anyone the owner has whitelisted) will now be able to see it. Anyone will be able to query the token to know whether it has been unwrapped. This simulates buying/selling a wrapped card that no one knows which card it is until it is unwrapped. If sealed metadata is not enabled, all tokens are considered unwrapped when minted (default: False)
• unwrapped_metadata_is_private - This config value indicates if the Reveal message should keep the sealed metadata private after unwrapping. This config value is ignored if sealed metadata is not enabled (default: False)
• minter_may_update_metadata - This config value indicates whether a minter is permitted to update a token's metadata (default: True)
• owner_may_update_metadata - This config value indicates whether the owner of a token is permitted to update a token's metadata (default: False)
• enable_burn - This config value indicates whether burn functionality is enabled. SNIP-722 non-transferable tokens can always be burned even when burning is disabled. This is because an owner must have a way to dispose of an unwanted, non-transferable token (default: False)

{
	“public_token_supply”: true | false,
	“public_owner”: true | false,
	“enable_sealed_metadata”: true | false,
	“unwrapped_metadata_is_private”: true | false,
	“minter_may_update_metadata”: true | false,
	“owner_may_update_metadata”: true | false,
	“enable_burn”: true | false
}

PostInitCallback

The PostInitCallback object is used to have the token contract execute an optional callback message after the contract has initialized. This can be useful if another contract is instantiating this token contract and needs the token contract to inform the creating contract of the address it has been given.

{
	“msg”: “base64_encoded_Binary_representing_the_msg_to_perform_after_initialization”,
	“contract_address”: “address_of_the_contract_being_called_after_initialization”,
	“code_hash”: “code_hash_of_the_contract_being_called_after_initialization”,
	“send”: [
		{
			“denom”: “denom_string_for_native_coin_being_sent_with_this_message”,
			“amount”: “amount_of_native_coin_being_sent”
		},
		{
			"...": "..."
		}
	]
}

Coin

Coin is the payment to send with the post-init callback message. Although send is not an optional field of the PostInitCallback, because it is an array, you can just use [] to not send any payment with the callback message

{
	“denom”: “denom_string_for_native_coin_being_sent_with_this_message”,
	“amount”: “amount_of_native_coin_being_sent”
}

Messages

MintNft

MintNft mints a single token. Only an authorized minting address my execute MintNft.

SNIP-722 adds the ability to optionally mint non-transferable tokens, which are NFTs that can never have a different owner than the address it was minted to.

Request

{
	"mint_nft": {
		"token_id": "optional_ID_of_new_token",
		"owner": "optional_address_the_new_token_will_be_minted_to",
		"public_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"private_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"serial_number": {
			"mint_run": 3,
			"serial_number": 67,
			"quantity_minted_this_run": 1000,
		},
		"royalty_info": {
			"decimal_places_in_rates": 4,
			"royalties": [
				{
					"recipient": "address_that_should_be_paid_this_royalty",
					"rate": 100,
				},
				{
					"...": "..."
				}
			],
		},
		"transferable": true | false,
		"memo": "optional_memo_for_the_mint_tx",
		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Setting royalties for a non-transferable token has no purpose, because it can never be transferred as part of a sale, so this implementation will not store any RoyaltyInfo for non-transferable tokens.

Response

{
	"mint_nft": {
		"token_id": "ID_of_minted_token",
	}
}

The ID of the minted token will also be returned in a LogAttribute with the key minted.

Metadata

This is the metadata for a token that follows CW-721 metadata specification, which is based on ERC721 Metadata JSON Schema. This implementation will throw an error if both token_uri and extension are provided.

{
	"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
	"extension": {
		"...": "..."
	}
}

Extension

This is an on-chain metadata extension struct that conforms to the Stashh metadata standard (which in turn implements https://docs.opensea.io/docs/metadata-standards). Urls should be prefixed with http://, https://, ipfs://, or ar://. Feel free to add/delete any fields as necessary.

SNIP-722 adds an optional token_subtype field in Extension to be used for Badges/POAPs. This field is intended to be used by applications in order to differentiate NFTs that are used as Badges/POAPs so that they can be displayed as such because they will be used for things like trophies, achievements, proof of attendence, etc...

{
	"image": "optional_image_url",
	"image_data": "optional_raw_svg_image_data",
	"external_url": "optional_url_to_view_token_on_your_site",
	"description": "optional_token_description",
	"name": "optional_token_name",
	"attributes": [
		{
			"display_type": "optional_display_format_for_numerical_traits",
			"trait_type": "optional_name_of_the_trait",
			"value": "trait value",
			"max_value": "optional_max_value_for_numerical_traits"
		},
		{
			"...": "...",
		},
	],
	"background_color": "optional_six-character_hexadecimal_background_color_(without_pre-pended_`#`)",
	"animation_url": "optional_url_to_multimedia_file",
	"youtube_url": "optional_url_to_a_YouTube_video",
	"media": [
		{
			"file_type": "optional_file_type",
			"extension": "optional_file_extension",
			"authentication": {
				"key": "optional_decryption_key_or_password",
				"user": "optional_username_for_authentication"
			},
			"url": "url_pointing_to_the_multimedia_file"
		},
		{
			"...": "...",
		},
	],
	"protected_attributes": [ "list", "of_attributes", "whose_types", "are_public", "but_values", "are_private" ],
	"token_subtype": "badge"
}

Trait

Trait describes a token attribute as defined in https://docs.opensea.io/docs/metadata-standards.

{
	"display_type": "optional_display_format_for_numerical_traits",
	"trait_type": "optional_name_of_the_trait",
	"value": "trait value",
	"max_value": "optional_max_value_for_numerical_traits"
}

MediaFile

MediaFile is the data structure used by Stashh to reference off-chain multimedia files. It allows for hosted files to be encrypted or authenticated with basic authentication, and for the decryption key or username/password to also be included in the on-chain private metadata. Urls should be prefixed with http://, https://, ipfs://, or ar://.

{
	"file_type": "optional_file_type",
	"extension": "optional_file_extension",
	"authentication": {
		"key": "optional_decryption_key_or_password",
		"user": "optional_username_for_authentication"
	},
	"url": "url_pointing_to_the_multimedia_file"
}

Authentication

Authentication is used to provide the decryption key or username/password for protected files.

{
	"key": "optional_decryption_key_or_password",
	"user": "optional_username_for_authentication"
}

SerialNumber

SerialNumber is used to serialize identical NFTs.

{
	"mint_run": 3,
	"serial_number": 67,
	"quantity_minted_this_run": 1000,
}

A mint run is a group of NFTs released at the same time. So, for example, if a creator decided to make 100 copies, they would all be part of mint run number 1. If they sell well and the creator wants to rerelease that NFT, he could make 100 more copies that would all be part of mint run number 2. The combination of mint_run, serial_number, and quantity_minted_this_run is used to indicate, for example, that this token was number 67 of 1000 minted in mint run number 3.

BatchMintNft

BatchMintNft mints a list of tokens. Only an authorized minting address my execute BatchMintNft.

SNIP-722 adds the ability to optionally mint non-transferable tokens, which are NFTs that can never have a different owner than the address it was minted to.

Request

{
	"batch_mint_nft": {
		"mints": [
			{
				"token_id": "optional_ID_of_new_token",
				"owner": "optional_address_the_new_token_will_be_minted_to",
				"public_metadata": {
					"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
					"extension": {
						"...": "..."
					}
				},
				"private_metadata": {
					"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
					"extension": {
						"...": "..."
					}
				},
				"serial_number": {
					"mint_run": 3,
					"serial_number": 67,
					"quantity_minted_this_run": 1000,
				},
				"royalty_info": {
					"decimal_places_in_rates": 4,
					"royalties": [
						{
							"recipient": "address_that_should_be_paid_this_royalty",
							"rate": 100,
						},
						{
							"...": "..."
						}
					],
				},
				"transferable": true | false,
				"memo": "optional_memo_for_the_mint_tx"
			},
			{
				"...": "..."
			}
		],
		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"batch_mint_nft": {
		"token_ids": [
			"IDs", "of", "tokens", "that", "were", "minted", "..."
		]
	}
}

The IDs of the minted tokens will also be returned in a LogAttribute with the key minted.

Mint

The Mint object defines the data necessary to mint one token.

{
	"token_id": "optional_ID_of_new_token",
	"owner": "optional_address_the_new_token_will_be_minted_to",
	"public_metadata": {
		"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
		"extension": {
			"...": "..."
		}
	},
	"private_metadata": {
		"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
		"extension": {
			"...": "..."
		}
	},
	"serial_number": {
		"mint_run": 3,
		"serial_number": 67,
		"quantity_minted_this_run": 1000,
	},
	"royalty_info": {
		"decimal_places_in_rates": 4,
		"royalties": [
			{
				"recipient": "address_that_should_be_paid_this_royalty",
				"rate": 100,
			},
			{
				"...": "..."
			}
		],
	},
	"transferable": true | false,
	"memo": "optional_memo_for_the_mint_tx"
}

Setting royalties for a non-transferable token has no purpose, because it can never be transferred as part of a sale, so this implementation will not store any RoyaltyInfo for non-transferable tokens.

MintNftClones

MintNftClones mints copies of an NFT, giving each one a MintRunInfo that indicates its serial number and the number of identical NFTs minted with it. If the optional mint_run_id is provided, the contract will also indicate which mint run these tokens were minted in, where the first use of the mint_run_id will be mint run number 1, the second time MintNftClones is called with that mint_run_id will be mint run number 2, etc... If no mint_run_id is provided, the MintRunInfo will not include a mint_run.

SNIP-722 adds the ability to optionally mint non-transferable tokens, which are NFTs that can never have a different owner than the address it was minted to.

Request

{
	"mint_nft_clones": {
		"mint_run_id": "optional_ID_used_to_track_mint_run_numbers_over_multiple_calls",
		"quantity": 100,
		"owner": "optional_address_the_new_tokens_will_be_minted_to",
		"public_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"private_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"royalty_info": {
			"decimal_places_in_rates": 4,
			"royalties": [
				{
					"recipient": "address_that_should_be_paid_this_royalty",
					"rate": 100,
				},
				{
					"...": "..."
				}
			],
		},
		"transferable": true | false,
		"memo": "optional_memo_for_the_mint_tx",
		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Setting royalties for a non-transferable token has no purpose, because it can never be transferred as part of a sale, so this implementation will not store any RoyaltyInfo for non-transferable tokens.

Response

{
	"mint_nft_clones": {
		"first_minted": "token_id_of_the_first_minted_token",
		"last_minted": "token_id_of_the_last_minted_token"
	}
}

The IDs of the minted tokens will also be returned in LogAttributes with the keys first_minted and last_minted. Because the token IDs are sequential, the IDs of the other minted tokens are easily inferred.

SetMetadata

SetMetadata will set the public and/or private metadata to the corresponding input if the message sender is either the token owner or an approved minter and they have been given this power by the configuration value chosen during instantiation. The private metadata of a sealed token may not be altered until after it has been unwrapped.

Request

{
	"set_metadata": {
		"token_id": "ID_of_token_whose_metadata_should_be_updated",
		"public_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"private_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"set_metadata": {
		"status": "success"
	}
}

SetRoyaltyInfo

If a token_id is supplied, SetRoyaltyInfo will update the specified token's RoyaltyInfo to the input. If no RoyaltyInfo is provided, it will delete the RoyaltyInfo and replace it with the contract's default RoyaltyInfo (if there is one). If no token_id is provided, SetRoyaltyInfo will update the contract's default RoyaltyInfo to the input, or delete it if no RoyaltyInfo is provided.
Only an authorized minter may update the contract's default RoyaltyInfo.
Only a token's creator may update its RoyaltyInfo, and only if they are also the current owner.

This implementation will throw an error if trying to set the royalty of a SNIP-722 non-transferable token, because they can never be transferred as part of a sale.

Request

{
	"set_royalty_info": {
		"token_id": "optional_ID_of_token_whose_royalty_info_should_be_updated",
		"royalty_info": {
			"decimal_places_in_rates": 4,
			"royalties": [
				{
					"recipient": "address_that_should_be_paid_this_royalty",
					"rate": 100,
				},
				{
					"...": "..."
				}
			],
		},
		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"set_royalty_info": {
		"status": "success"
	}
}

Reveal

Reveal unwraps the sealed private metadata, irreversibly marking the token as unwrapped. If the unwrapped_metadata_is_private configuration value is true, the formerly sealed metadata will remain private, otherwise it will be made public.

Request

{
	"reveal": {
		"token_id": "ID_of_the_token_to_unwrap",
		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"reveal": {
		"status": "success"
	}
}

MakeOwnershipPrivate

MakeOwnershipPrivate is used when the token contract was instantiated with the public_owner configuration value set to true. It allows an address to make all of its tokens have private ownership by default. The owner may still use SetGlobalApproval or SetWhitelistedApproval to make ownership public as desired.

Request

{
	"make_ownership_private": {
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"make_ownership_private": {
		"status": "success"
	}
}

SetGlobalApproval

The owner of a token can use SetGlobalApproval to make ownership and/or private metadata viewable by everyone. This can be set for a single token or for an owner's entire inventory of tokens by choosing the appropriate AccessLevel. SetGlobalApproval can also be used to revoke any global approval previously granted.

Request

{
	"set_global_approval": {
		"token_id": "optional_ID_of_the_token_to_grant_or_revoke_approval_on",
		"view_owner": "approve_token" | "all" | "revoke_token" | "none",
		"view_private_metadata": "approve_token" | "all" | "revoke_token" | "none",
		"expires": "never" | {"at_height": 999999} | {"at_time":999999},
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"set_global_approval": {
		"status": "success"
	}
}

AccessLevel

AccessLevel determines the type of access being granted or revoked to the specified address in a SetWhitelistedApproval message or to everyone in a SetGlobalApproval message. Inventory-wide approval and token-specific approval are mutually exclusive levels of access. The levels are:

• "approve_token" - grant approval only on the token specified in the message
• "revoke_token" - revoke a previous approval on the specified token
• "all" - grant approval for all tokens in the message signer's inventory. This approval will also apply to any tokens the signer acquires after granting all approval
• "none" - revoke any approval (both token and inventory-wide) previously granted to the specified address (or for everyone if using SetGlobalApproval)

If the message signer grants an address (or everyone in the case of SetGlobalApproval) all (inventory-wide) approval, it will remove any individual token approvals previously granted to that address (or granted to everyone in the case of SetGlobalApproval), and grant that address all (inventory-wide) approval. If an address (or everyone in the case of SetGlobalApproval) already has all approval, and the message signer grants it approve_token approval, if the expiration of the new approve_token approval is the same as the expiration of the previous all approval, it will just leave the all approval in place. If the expirations are different, it will grant approve_token approval with the specified expiration for the input token, and all other tokens will be changed to approve_token approvals with the expiration of the previous all approval, and the all (inventory-wide) approval will be removed. If the message signer applies revoke_token access to an address that currently has inventory-wide approval, it will remove the inventory-wide approval, and create approve_token approvals for that address on every token in the signer's inventory EXCEPT the token specified with the revoke_token message. In other words, it will only revoke the approval on that single token.

Expiration

The Expiration object is used to set an expiration for any approvals granted in the message. Expiration can be set to a specified blockheight, a time in seconds since epoch 01/01/1970, or "never". Values for blockheight and time are specified as a u64. If no expiration is given, it will default to "never".

One should be aware that the current blockheight and time is not available to a query on Secret Network at this moment, but there are plans to make the BlockInfo available to queries in a future hardfork. To get around this limitation, the contract saves the BlockInfo every time a message is executed, and uses the blockheight and time of the last message execution to check viewing permission expiration during a query. Therefore it is possible that a whitelisted address may be able to view the owner or metadata of a token past its approval expiration if no one executed any contract message since before the expiration. However, because transferring/burning a token is executing a message, it does have the current blockheight and time available and can not occur if transfer approval has expired.

• "never" - the approval will never expire
• {"at_time": 1700000000} - the approval will expire 1700000000 seconds after 01/01/1970 (time value is u64)
• {"at_height": 3000000} - the approval will expire at blockheight 3000000 (height value is u64)

SetWhitelistedApproval

The owner of a token can use SetWhitelistedApproval to grant an address permission to view ownership, view private metadata, and/or to transfer a single token or every token in the owner's inventory. SetWhitelistedApproval can also be used to revoke any approval previously granted to the address.

Request

{
	"set_whitelisted_approval": {
		"address": "address_being_granted_or_revoked_approval",
		"token_id": "optional_ID_of_the_token_to_grant_or_revoke_approval_on",
		"view_owner": "approve_token" | "all" | "revoke_token" | "none",
		"view_private_metadata": "approve_token" | "all" | "revoke_token" | "none",
		"transfer": "approve_token" | "all" | "revoke_token" | "none",
		"expires": "never" | {"at_height": 999999} | {"at_time":999999},
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"set_whitelisted_approval": {
		"status": "success"
	}
}

Approve

Approve is used to grant an address permission to transfer a single token. This can only be performed by the token's owner or, in compliance with CW-721, an address that has inventory-wide approval to transfer the owner's tokens. Approve is provided to maintain compliance with CW-721, but the owner can use SetWhitelistedApproval to accomplish the same thing if specifying a token_id and approve_token AccessLevel for transfer.

Request

{
	"approve": {
		"spender": "address_being_granted_approval_to_transfer_the_specified_token",
		"token_id": "ID_of_the_token_that_can_now_be_transferred_by_the_spender",
		"expires": "never" | {"at_height": 999999} | {"at_time":999999},
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"approve": {
		"status": "success"
	}
}

Revoke

Revoke is used to revoke from an address the permission to transfer this single token. This can only be performed by the token's owner or, in compliance with CW-721, an address that has inventory-wide approval to transfer the owner's tokens (referred to as an operator later). However, one operator may not revoke transfer permission of even one single token away from another operator. Revoke is provided to maintain compliance with CW-721, but the owner can use SetWhitelistedApproval to accomplish the same thing if specifying a token_id and revoke_token AccessLevel for transfer.

Request

{
	"revoke": {
		"spender": "address_being_revoked_approval_to_transfer_the_specified_token",
		"token_id": "ID_of_the_token_that_can_no_longer_be_transferred_by_the_spender",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"revoke": {
		"status": "success"
	}
}

ApproveAll

ApproveAll is used to grant an address permission to transfer all the tokens in the message sender's inventory. This will include the ability to transfer any tokens the sender acquires after granting this inventory-wide approval. This also gives the address the ability to grant another address the approval to transfer a single token. ApproveAll is provided to maintain compliance with CW-721, but the message sender can use SetWhitelistedApproval to accomplish the same thing by using all AccessLevel for transfer.

Request

{
	"approve_all": {
		"operator": "address_being_granted_inventory-wide_approval_to_transfer_tokens",
		"expires": "never" | {"at_height": 999999} | {"at_time":999999},
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"approve_all": {
		"status": "success"
	}
}

RevokeAll

RevokeAll is used to revoke all transfer approvals granted to an address. RevokeAll is provided to maintain compliance with CW-721, but the message sender can use SetWhitelistedApproval to accomplish the same thing by using none AccessLevel for transfer.

Request

{
	"revoke_all": {
		"operator": "address_being_revoked_all_approvals_to_transfer_tokens",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"revoke_all": {
		"status": "success"
	}
}

TransferNft

TransferNft is used to transfer ownership of the token to the recipient address. This requires a valid token_id and the message sender must either be the owner or an address with valid transfer approval. If the recipient address is the same as the current owner, the contract will throw an error. If the token is transferred to a new owner, its single-token approvals will be cleared.

This implementation will throw an error if trying to transfer a SNIP-722 non-transferable token.

Request

{
	"transfer_nft": {
		"recipient": "address_receiving_the_token",
		"token_id": "ID_of_the_token_being_transferred",
		"memo": "optional_memo_for_the_transfer_tx",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"transfer_nft": {
		"status": "success"
	}
}

BatchTransferNft

BatchTransferNft is used to perform multiple token transfers. The message sender may specify a list of tokens to transfer to one recipient address in each Transfer object, and any memo provided will be applied to every token transferred in that one Transfer object. The message sender may provide multiple Transfer objects to perform transfers to multiple addresses, providing a different memo for each address if desired. Each individual transfer of a token will show separately in transaction histories. The message sender must have permission to transfer all the tokens listed (either by being the owner or being granted transfer approval) and every listed token_id must be valid. A contract may use the VerifyTransferApproval query to verify that it has permission to transfer all the tokens.

If the message sender does not have permission to transfer any one of the listed tokens, the entire message will fail (no tokens will be transferred) and the error will provide the ID of the first token encountered in which the sender does not have the required permission. If any token transfer involves a recipient address that is the same as its current owner, the contract will throw an error. Any token that is transferred to a new owner will have its single-token approvals cleared.

This implementation will throw an error if trying to transfer a SNIP-722 non-transferable token.

Request

{
	"batch_transfer_nft": {
		"transfers": [
			{
				"recipient": "address_receiving_the_tokens",
				"token_ids": [
					"list", "of", "token", "IDs", "to", "transfer"
				],
				"memo": "optional_memo_applied_to_the_transfer_tx_for_every_token_listed_in_this_Transfer_object"
			},
			{
				"...": "..."
			}
		],
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"batch_transfer_nft": {
		"status": "success"
	}
}

Transfer

The Transfer object provides a list of tokens to transfer to one recipient address, as well as an optional memo that would be included with every logged token transfer.

{
	"recipient": "address_receiving_the_tokens",
	"token_ids": [
		"list", "of", "token", "IDs", "to", "transfer", "..."
	],
	"memo": "optional_memo_applied_to_the_transfer_tx_for_every_token_listed_in_this_Transfer_object"
}

SendNft

SendNft is used to transfer ownership of the token to the contract address, and then call the recipient's BatchReceiveNft (or ReceiveNft) if the recipient contract has registered its receiver interface with the NFT contract or if its ReceiverInfo is provided. If the recipient contract registered (or if the ReceiverInfo indicates) that it implements BatchReceiveNft, a BatchReceiveNft callback will be performed with only the single token ID in the token_ids array.

While SendNft keeps the contract field name in order to maintain CW-721 compliance, Secret Network does not have the same limitations as Cosmos, and it is possible to use SendNft to transfer token ownership to a personal address (not a contract) or to a contract that does not implement any Receiver Interface.

SendNft requires a valid token_id and the message sender must either be the owner or an address with valid transfer approval. If the recipient address is the same as the current owner, the contract will throw an error. If the token is transferred to a new owner, its single-token approvals will be cleared. If the BatchReceiveNft (or ReceiveNft) callback fails, the entire transaction will be reverted (even the transfer will not take place).

This implementation will throw an error if trying to send a SNIP-722 non-transferable token.

Request

{
	"send_nft": {
		"contract": "address_receiving_the_token",
		"receiver_info": {
			"recipient_code_hash": "code_hash_of_the_recipient_contract",
			"also_implements_batch_receive_nft": true | false,
		},
		"token_id": "ID_of_the_token_being_transferred",
		"msg": "optional_base64_encoded_Binary_message_sent_with_the_BatchReceiveNft_callback",
		"memo": "optional_memo_for_the_transfer_tx",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"send_nft": {
		"status": "success"
	}
}

ReceiverInfo

The optional ReceiverInfo object may be used to provide the code hash of the contract receiving tokens from either SendNft or BatchSendNft. It may also optionally indicate whether the recipient contract implements BatchReceiveNft in addition to ReceiveNft. If the also_implements_batch_receive_nft field is not provided, it defaults to false.

{
	"recipient_code_hash": "code_hash_of_the_recipient_contract",
	"also_implements_batch_receive_nft": true | false,
}

BatchSendNft

BatchSendNft is used to perform multiple token transfers, and then call the recipient contracts' BatchReceiveNft (or ReceiveNft) if they have registered their receiver interface with the NFT contract or if their ReceiverInfo is provided. The message sender may specify a list of tokens to send to one recipient address in each Send object, and any memo or msg provided will be applied to every token transferred in that one Send object. If the list of transferred tokens belonged to multiple previous owners, a separate BatchReceiveNft callback will be performed for each of the previous owners. If the contract only implements ReceiveNft, one ReceiveNft will be performed for every sent token. Therefore it is highly recommended to implement BatchReceiveNft if there is the possibility of being sent multiple tokens at one time. This will significantly reduce gas costs.

The message sender may provide multiple Send objects to perform sends to multiple addresses, providing a different memo and msg for each address if desired. Each individual transfer of a token will show separately in transaction histories. The message sender must have permission to transfer all the tokens listed (either by being the owner or being granted transfer approval) and every token ID must be valid. A contract may use the VerifyTransferApproval query to verify that it has permission to transfer all the tokens. If the message sender does not have permission to transfer any one of the listed tokens, the entire message will fail (no tokens will be transferred) and the error will provide the ID of the first token encountered in which the sender does not have the required permission. If any token transfer involves a recipient address that is the same as its current owner, the contract will throw an error. Any token that is transferred to a new owner will have its single-token approvals cleared. If any BatchReceiveNft (or ReceiveNft) callback fails, the entire transaction will be reverted (even the transfers will not take place).

This implementation will throw an error if trying to send a SNIP-722 non-transferable token.

Request

{
	"batch_send_nft": {
		"sends": [
			{
				"contract": "address_receiving_the_tokens",
				"receiver_info": {
					"recipient_code_hash": "code_hash_of_the_recipient_contract",
					"also_implements_batch_receive_nft": true | false,
				},
				"token_ids": [
					"list", "of", "token", "IDs", "to", "transfer", "..."
				],
				"msg": "optional_base64_encoded_Binary_message_sent_with_every_BatchReceiveNft_callback_made_for_this_one_Send_object",
				"memo": "optional_memo_applied_to_the_transfer_tx_for_every_token_listed_in_this_Send_object"
			},
			{
				"...": "..."
			}
		],
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"batch_send_nft": {
		"status": "success"
	}
}

Send

The Send object provides a list of tokens to transfer to one recipient address, optionally provides the ReceiverInfo of the recipient contract, as well as an optional memo that would be included with every logged token transfer, and an optional msg that would be included with every BatchReceiveNft or ReceiveNft callback made as a result of this Send object. While Send keeps the contract field name in order be consistent with CW-721 specification, Secret Network does not have the same limitations as Cosmos, and it is possible to use BatchSendNft to transfer token ownership to a personal address (not a contract) or to a contract that does not implement any Receiver Interface.

{
	"contract": "address_receiving_the_tokens",
	"receiver_info": {
		"recipient_code_hash": "code_hash_of_the_recipient_contract",
		"also_implements_batch_receive_nft": true | false,
	},
	"token_ids": [
		"list", "of", "token", "IDs", "to", "transfer", "..."
	],
	"msg": "optional_base64_encoded_Binary_message_sent_with_every_BatchReceiveNft_callback_made_for_this_one_Send_object",
	"memo": "optional_memo_applied_to_the_transfer_tx_for_every_token_listed_in_this_Send_object"
}

BurnNft

BurnNft is used to burn a single token, providing an optional memo to include in the burn's transaction history if desired. If the contract has not enabled burn functionality using the init configuration enable_burn, BurnNft will result in an error, unless the token being burned is a SNIP-722 non-transferable token. This is because an owner should always be able to dispose of an unwanted, non-transferable token. Only the token owner and anyone else with valid transfer approval may burn this token.

Request

{
	"burn_nft": {
		"token_id": "ID_of_the_token_to_burn",
		"memo": "optional_memo_for_the_burn_tx",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"burn_nft": {
		"status": "success"
	}
}

BatchBurnNft

BatchBurnNft is used to burn multiple tokens. The message sender may specify a list of tokens to burn in each Burn object, and any memo provided will be applied to every token burned in that one Burn object. The message sender will usually list every token to be burned in one Burn object, but if a different memo is needed for different tokens being burned, multiple Burn objects may be listed. Each individual burning of a token will show separately in transaction histories. The message sender must have permission to transfer/burn all the tokens listed (either by being the owner or being granted transfer approval). A contract may use the VerifyTransferApproval query to verify that it has permission to transfer/burn all the tokens. If the message sender does not have permission to transfer/burn any one of the listed tokens, the entire message will fail (no tokens will be burned) and the error will provide the ID of the first token encountered in which the sender does not have the required permission.

A SNIP-722 non-transferable token can always be burned even if burn functionality has been disabled using the init configuration. This is because an owner should always be able to dispose of an unwanted, non-transferable token.

Request

{
	"batch_burn_nft": {
		"burns": [
			{
				"token_ids": [
					"list", "of", "token", "IDs", "to", "burn"
				],
				"memo": "optional_memo_applied_to_the_burn_tx_for_every_token_listed_in_this_Burn_object"
			},
			{
				"...": "..."
			}
		],
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"batch_burn_nft": {
		"status": "success"
	}
}

Burn

The Burn object provides a list of tokens to burn, as well as an optional memo that would be included with every token burn transaction history.

{
	"token_ids": [
		"list", "of", "token", "IDs", "to", "burn", "..."
	],
	"memo": "optional_memo_applied_to_the_burn_tx_for_every_token_listed_in_this_Burn_object"
}

CreateViewingKey

CreateViewingKey is used to generate a random viewing key to be used to authenticate account-specific queries. The entropy field is a client-supplied string used as part of the entropy supplied to the rng that creates the viewing key.

Request

{
	"create_viewing_key": {
		"entropy": "string_used_as_part_of_the_entropy_supplied_to_the_rng",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"viewing_key": {
		"key": "the_created_viewing_key"
	}
}

SetViewingKey

SetViewingKey is used to set the viewing key to a predefined string. It will replace any key that currently exists. It would be best for users to call CreateViewingKey to ensure a strong key, but this function is provided so that contracts can also utilize viewing keys.

Request

{
	"set_viewing_key": {
		"key": "the_new_viewing_key",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"viewing_key": {
		"key": "the_message_sender's_viewing_key"
	}
}

AddMinters

AddMinters will add the provided addresses to the list of authorized minters. This can only be called by the admin address.

Request

{
	"add_minters": {
		"minters": [
			"list", "of", "addresses", "to", "add", "to", "the", "list", "of", "minters", "..."
		],
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"add_minters": {
		"status": "success"
	}
}

RemoveMinters

RemoveMinters will remove the provided addresses from the list of authorized minters. This can only be called by the admin address.

Request

{
	"remove_minters": {
		"minters": [
			"list", "of", "addresses", "to", "remove", "from", "the", "list", "of", "minters", "..."
		],
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"remove_minters": {
		"status": "success"
	}
}

SetMinters

SetMinters will precisely define the list of authorized minters. This can only be called by the admin address.

Request

{
	"set_minters": {
		"minters": [
			"list", "of", "addresses", "that", "have", "minting", "authority", "..."
		],
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"set_minters": {
		"status": "success"
	}
}

SetContractStatus

SetContractStatus allows the contract admin to define which messages the contract will execute. This can only be called by the admin address.

Request

{
	"set_contract_status": {
		"level": "normal" | "stop_transactions" | "stop_all",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"set_contract_status": {
		"status": "success"
	}
}

ContractStatus

ContractStatus indicates which messages the contract will execute. The possible values are:

• "normal" - the contract will execute all messages
• "stop_transactions" - the contract will not allow any minting, burning, sending, or transferring of tokens
• "stop_all" - the contract will only execute a SetContractStatus message

ChangeAdmin

ChangeAdmin will allow the current admin to transfer admin privileges to another address (which will be the only admin address). This can only be called by the current admin address.

Request

{
	"change_admin": {
		"address": "address_of_the_new_contract_admin",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"change_admin": {
		"status": "success"
	}
}

RegisterReceiveNft

A contract will use RegisterReceiveNft to notify the NFT contract that it implements ReceiveNft and possibly also BatchReceiveNft (see below). This enables the NFT contract to call the registered contract whenever it is Sent a token (or tokens). In order to comply with CW-721, ReceiveNft only informs the recipient contract that it has been sent a single token, and it only informs the recipient contract who the token's previous owner was, not who sent the token (which may be different addresses) despite calling the previous owner sender (see below). BatchReceiveNft, on the other hand, can be used to inform a contract that it was sent multiple tokens, and notifies the recipient of both, the token's previous owner and the sender. If a contract implements BatchReceiveNft, the NFT contract will always call BatchReceiveNft even if there is only one token being sent, in which case the token_ids array will only have one element.

Request

{
	"register_receive_nft": {
		"code_hash": "code_hash_of_the_contract_implementing_a_receiver_interface",
		"also_implements_batch_receive_nft": true | false,
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"register_receive_nft": {
		"status": "success"
	}
}

RevokePermit

RevokePermit allows a user to disable the use of a permit for authenticated queries.

Request

{
	"revoke_permit": {
		"permit_name": "name_of_the_permit_that_is_no_longer_valid",
 		"padding": "optional_ignored_string_that_can_be_used_to_maintain_constant_message_length"
	}
}

Response

{
	"revoke_permit": {
		"status": "success"
	}
}

Queries

Queries are off-chain requests, that are not cryptographically validated; therefore, this contract utilizes viewing keys to authenticate address-specific queries. It makes viewing key validation resource intensive in order to combat offline brute-force attempts to guess viewing keys. Also, even if a user has not set a viewing key, it will perform the same resource intensive processing to prevent an attacker from knowing that a key has not been set and provides the same error response whether there is no viewing key or if the input key does not match.

Any query that inquires about a specific token will return an error if the input token ID does not exist. If the token supply is public, the error will indicate that the token does not exist. If the token supply is private, the query will return the same error response whether the token does not exist or the querier does not have permission to view the requested information.

One should be aware that the current blockheight and time is not available to a query on Secret Network at this moment, but there are plans to make the BlockInfo available to queries in a future hardfork. To get around this limitation, the contract saves the BlockInfo every time a message is executed, and uses the blockheight and time of the last message execution to check viewing approval expiration during a query. Therefore it is possible that a whitelisted address may be able to view the owner or metadata of a token past its approval expiration if no one executed any contract message since before the expiration. However, because transferring/burning a token is executing a message, it does have the current blockheight and time available and can enforce exact expiration.

ContractInfo

ContractInfo returns the contract's name and symbol. This query is not authenticated.

Request

{
	"contract_info": {}
}

Response

{
	"contract_info": {
		"name": "contract_name",
		"symbol": "contract_symbol"
	}
}

ContractConfig

ContractConfig returns the configuration values that were selected when the contract was instantiated. See Config for an explanation of the configuration options. This query is not authenticated.

Request

{
	"contract_config": {}
}

Response

{
	"contract_config": {
		“token_supply_is_public”: true | false,
		“owner_is_public”: true | false,
		“sealed_metadata_is_enabled”: true | false,
		“unwrapped_metadata_is_private”: true | false,
		“minter_may_update_metadata”: true | false,
		“owner_may_update_metadata”: true | false,
		“burn_is_enabled”: true | false
	}
}

Minters

Minters returns the list of addresses that are authorized to mint tokens. This query is not authenticated.

Request

{
	"minters": {}
}

Response

{
	"minters": {
		“minters”: [
			"list", "of", "authorized", "minters", "..."
		]
	}
}

RegisteredCodeHash

RegisteredCodeHash will display the code hash of the specified contract if it has registered its receiver interface and will indicate whether the contract implements BatchReceiveNft.

Request

{
	"registered_code_hash": {
		"contract": "address_of_the_contract_whose_registration_is_being_queried"
	}
}

Response

{
	"registered_code_hash": {
		"code_hash": "code_hash_of_the_registered_contract",
		"also_implements_batch_receive_nft": true | false
	}
}

NumTokens

NumTokens returns the number of tokens controlled by the contract. If the contract's token supply is private, only an authenticated minter's address will be allowed to perform this query.

Request

{
	"num_tokens": {
		"viewer": {
			"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
			"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
		}
	}
}

Response

{
	"num_tokens": {
		"count": 99999
	}
}

ViewerInfo

The ViewerInfo object provides the address and viewing key of the querier. It is optionally provided in queries where public responses and address-specific responses will differ.

{
	"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
	"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
}

AllTokens

AllTokens returns an optionally paginated list of all the token IDs controlled by the contract. If the contract's token supply is private, only an authenticated minter's address will be allowed to perform this query. When paginating, supply the last token ID received in a response as the start_after token ID of the next query to continue listing where the previous query stopped.

Request

{
	"all_tokens": {
		"viewer": {
			"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
			"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
		},
		"start_after": "optionally_display_only_token_ids_that_come_after_this_one_in_the_list",
		"limit": 10
	}
}

Response

{
	"token_list": {
		"tokens": [
			"list", "of", "token", "IDs", "controlled", "by", "the", "contract", "..."
		]
	}
}

IsUnwrapped

IsUnwrapped indicates whether the token has been unwrapped. If sealed metadata is not enabled, all tokens are considered to be unwrapped. This query is not authenticated.

Request

{
	"is_unwrapped": {
		"token_id": "ID_of_the_token_whose_unwrapped_status_is_being_queried"
	}
}

Response

{
	"is_unwrapped": {
		"token_is_unwrapped": true | false
	}
}

IsTransferable

IsTransferable is a SNIP-722 query that indicates whether the token is transferable. This query is not authenticated.

Request

{
	"is_transferable": {
		"token_id": "ID_of_the_token_whose_transferability_is_being_queried"
	}
}

Response

{
	"is_transferable": {
		"token_is_transferable": true | false
	}
}

OwnerOf

OwnerOf returns the owner of the specified token if the querier is the owner or has been granted permission to view the owner. If the querier is the owner, OwnerOf will also display all the addresses that have been given transfer permission. The transfer approval list is provided as part of CW-721 compliance; however, the token owner is advised to use NftDossier for a more complete list that includes view_owner and view_private_metadata approvals (which CW-721 is not capable of keeping private). If no viewer is provided, OwnerOf will only display the owner if ownership is public for this token.

Request

{
	"owner_of": {
		"token_id": "ID_of_the_token_being_queried",
		"viewer": {
			"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
			"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
		},
		"include_expired": true | false
	}
}

Response

{
	"owner_of": {
		"owner": "address_of_the_token_owner",
		"approvals": [
			{
				"spender": "address_with_transfer_approval",
				"expires": "never" | {"at_height": 999999} | {"at_time":999999}
			},
			{
				"...": "..."
			}
		]
	}
}

Cw721Approval

The Cw721Approval object is used to display CW-721-style approvals which are limited to only permission to transfer, as CW-721 does not enable ownership or metadata privacy.

{
	"spender": "address_with_transfer_approval",
	"expires": "never" | {"at_height": 999999} | {"at_time":999999}
}

NftInfo

NftInfo returns the public metadata of a token. It follows CW-721 specification, which is based on ERC-721 Metadata JSON Schema. At most, one of the fields token_uri OR extension will be defined.

Request

{
	"nft_info": {
		"token_id": "ID_of_the_token_being_queried"
	}
}

Response

{
	"nft_info": {
		"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
		"extension": {
			"...": "..."
		}
	}
}

AllNftInfo

AllNftInfo displays the result of both OwnerOf and NftInfo in a single query. This is provided for CW-721 compliance, but for more complete information about a token, use NftDossier, which will include private metadata and view_owner and view_private_metadata approvals if the querier is permitted to view this information.

Request

{
	"all_nft_info": {
		"token_id": "ID_of_the_token_being_queried",
		"viewer": {
			"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
			"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
		},
		"include_expired": true | false
	}
}

Response

{
	"all_nft_info": {
		"access": {
			"owner": "address_of_the_token_owner",
			"approvals": [
				{
					"spender": "address_with_transfer_approval",
					"expires": "never" | {"at_height": 999999} | {"at_time":999999}
				},
				{
					"...": "..."
				}
			]
		},
		"info": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		}
	}
}

Cw721OwnerOfResponse

The Cw721OwnerOfResponse object is used to display a token's owner if the querier has view_owner permission, and the token's transfer approvals if the querier is the token's owner.

{
	"owner": "address_of_the_token_owner",
	"approvals": [
		{
			"spender": "address_with_transfer_approval",
			"expires": "never" | {"at_height": 999999} | {"at_time":999999}
		},
		{
			"...": "..."
		}
	]
}

PrivateMetadata

PrivateMetadata returns the private metadata of a token if the querier is permitted to view it. It follows CW-721 metadata specification, which is based on ERC-721 Metadata JSON Schema. At most, one of the fields token_uri OR extension will be defined. If the metadata is sealed, no one is permitted to view it until it has been unwrapped with Reveal. If no viewer is provided, PrivateMetadata will only display the private metadata if the private metadata is public for this token.

Request

{
	"private_metadata": {
		"token_id": "ID_of_the_token_being_queried",
		"viewer": {
			"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
			"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
		},
	}
}

Response

{
	"private_metadata": {
		"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
		"extension": {
			"...": "..."
		}
	}
}

NftDossier

NftDossier returns all the information about a token that the viewer is permitted to view. If no viewer is provided, NftDossier will only display the information that has been made public. The response may include the owner, the public metadata, the private metadata, the reason the private metadata is not viewable, the royalty information, the mint run information, whether the token is transferable, whether ownership is public, whether the private metadata is public, and (if the querier is the owner,) the approvals for this token as well as the inventory-wide approvals for the owner. This implementation will only display a token's royalty recipient addresses if the querier has permission to transfer the token.

SNIP-722 adds a transferable field to the NftDossier response.

SNIP-723 (specification to be written) adds an unwrapped field which is false if private metadata for this token is sealed.

Request

{
	"nft_dossier": {
		"token_id": "ID_of_the_token_being_queried",
		"viewer": {
			"address": "address_of_the_querier_if_supplying_optional_ViewerInfo",
			"viewing_key": "viewer's_key_if_supplying_optional_ViewerInfo"
		},
		"include_expired": true | false
	}
}

Response

{
	"nft_dossier": {
		"owner": "address_of_the_token_owner",
		"public_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"private_metadata": {
			"token_uri": "optional_uri_pointing_to_off-chain_JSON_metadata",
			"extension": {
				"...": "..."
			}
		},
		"display_private_metadata_error": "optional_error_describing_why_private_metadata_is_not_viewable_if_applicable",
		"royalty_info": {
			"decimal_places_in_rates": 4,
			"royalties": [
				{
					"recipient": "optional_address_that_should_be_paid_this_royalty",
					"rate": 100,
				},
				{
					"...": "..."
				}
			],
		},
		"mint_run_info": {
			"collection_creator": "optional_address_that_instantiated_this_contract",
			"token_creator": "optional_address_that_minted_this_token",
			"time_of_minting": 999999,
			"mint_run": 3,
			"serial_number": 67,
			"quantity_minted_this_run": 1000,
		},
		"transferable": true | false,
		"unwrapped": true | false,
		"owner_is_public": true | false,
		"public_ownership_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
		"private_metadata_is_public": true | false,
		"private_metadata_is_public_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
		"token_approvals": [
			{
				"address": "whitelisted_address",
				"view_owner_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
				"view_private_metadata_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
				"transfer_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
			},
			{
				"...": "..."
			}
		],
		"inventory_approvals": [
			{
				"address": "whitelisted_address",
				"view_owner_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
				"view_private_metadata_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
				"transfer_expiration": "never" | {"at_height": 999999} | {"at_time":999999},
			},
			{
				"...": "..."
			}
		]
	}
}

The transferable field is mandatory for SNIP-722 compliant contracts, but because SNIP-722 is an optional extension to SNIP-721, any NftDossier response that does not include the field can be considered to come from a contract that only implements transferable tokens (considered equivalent to transferable = true). The unwrapped field is mandatory for SNIP-723 (specification to be written) compliant contracts, but because SNIP-723 is an optional extension to SNIP-721, an NftDossier response might not include the field. In this case, the display_private_metadata_error field might indicate that the private metadata is sealed if the querier has permission to normally view private metadata. Or an IsUnwrapped query may be performed to learn the token's sealed status.

MintRunInfo

MintRunInfo contains information aout the minting of this token.

{
	"collection_creator": "optional_address_that_instantiated_this_contract",
	"token_creator": "optional_address_that_minted_this_token",
	"time_of_minting": 999999,
	"mint_run": 3,
	"serial_number": 67,
	"quantity_minted_this_run": 1000,
}

A mint run is a group of NFTs released at the same time. So, for example, if a creator decided to make 100 copies, they would all be part of mint run number 1. If they sell well and the creator wants to rerelease that NFT, he could make 100 more copies that would all be part of mint run number 2. The combination of mint_run, serial_number, and quantity_minted_this_run is used to indicate, for example, that this token was number 67 of 1000 minted in mint run number 3.