Add NonFungibleToken Docs

contracts/nonFungibleToken/src/NonFungibleToken.compact

@@ -6,7 +6,7 @@ pragma language_version >= 0.15.0;
  * @module NonFungibleToken
  * @description An unshielded Non-Fungible Token library.
  *
- * @notice One notable difference regarding this implementation and the EIP20 spec
+ * @notice One notable difference regarding this implementation and the EIP721 spec
  * consists of the token size. Uint<128> is used as the token size because Uint<256>
  * cannot be supported.
  * This is due to encoding limits on the midnight circuit backend:
@@ -96,8 +96,12 @@ module NonFungibleToken {
   /**
    * @description Initializes the contract by setting the name and symbol.
    *
+   * This MUST be called in the implementing contract's constructor.
+   * Failure to do so can lead to an irreparable contract.
+   *
    * Requirements:
-   * - The contract must not have been initialized.
+   *
+   * - Contract is not initialized.
    *
    * @param {Opaque<"string">} name_ - The name of the token.
    * @param {Opaque<"string">} symbol_ - The symbol of the token.
@@ -115,7 +119,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=309
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>)} owner - The account to query.
    * @return {Uint<128>} - The number of tokens in `owner`'s account.
@@ -135,7 +140,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=320
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - The `tokenId` must exist.
    *
    * @param {Uint<128>} tokenId - The identifier for a token.
@@ -152,7 +158,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=36
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * @return {Opaque<"string">} - The token name.
    */
@@ -167,7 +174,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=36
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * @return {Opaque<"string">} - The token symbol.
    */
@@ -183,13 +191,13 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=326
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - The `tokenId` must exist.
    *
-   * @notice Midnight does not support native strings and string operations
-   * within the Compact language, e.g. concatenating a base URI + token ID are not possible
-   * like in other NFT implementations. Therefore, we propose the URI storage
-   * approach; whereby, NFTs may or may not have unique "base" URIs.
+   * @notice Native strings and string operations aren't supported within the Compact language,
+   * e.g. concatenating a base URI + token ID is not possible like in other NFT implementations.
+   * Therefore, we propose the URI storage approach; whereby, NFTs may or may not have unique "base" URIs.
    * It's up to the implementation to decide on how to handle this.
    *
    * @param {Uint<128>} tokenId - The identifier for a token.
@@ -212,7 +220,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=283
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - The `tokenId` must exist.
    *
    * @notice The URI for a given NFT is usually set when the NFT is minted.
@@ -237,7 +246,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=993
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - The caller must either own the token or be an approved operator.
    * - `tokenId` must exist.
    *
@@ -264,7 +274,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=439
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - `tokenId` must exist.
    *
    * @param {Uint<128>} tokenId - The token an account may be approved to manage
@@ -284,7 +295,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=439
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - The `operator` cannot be the address zero.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} operator - An operator to manage the caller's tokens
@@ -310,7 +322,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=621
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} owner - The owner of a token
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} operator - An account that may operate on `owner`'s tokens
@@ -331,13 +344,18 @@ module NonFungibleToken {
   /**
    * @description Transfers `tokenId` token from `from` to `to`.
    *
+   * @notice Transfers to contract addresses are currently disallowed until contract-to-contract interactions
+   * are supported in Compact. This restriction prevents assets from being inadvertently locked in contracts that cannot
+   * currently handle token receipt.
+   *
    * @circuitInfo k=11, rows=2023
    *
    * Requirements:
-   * - The contract must have been initialized.
-   * - `from` cannot be the zero address.
-   * - `to` cannot be the zero address.
-   * - `to` cannot be ContractAddress.
+   *
+   * - The contract is initialized.
+   * - `from` is not the zero address.
+   * - `to` is not the zero address.
+   * - `to` is not a ContractAddress.
    * - `tokenId` token must be owned by `from`.
    * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.
    *
@@ -360,19 +378,20 @@ module NonFungibleToken {
   /**
    * @description Transfers `tokenId` token from `from` to `to`. It does NOT check if the recipient is a ContractAddress.
    *
+   * WARNING: Transfers to contract addresses are considered unsafe because contract-to-contract calls
+   * are not currently supported. Tokens sent to a contract address may become irretrievable.
+   * Once contract-to-contract calls are supported, this circuit may be deprecated.
+   *
    * @circuitInfo k=11, rows=2020
    *
    * Requirements:
-   * - The contract must have been initialized.
-   * - `from` cannot be the zero address.
-   * - `to` cannot be the zero address.
+   *
+   * - The contract is initialized.
+   * - `from` is not the zero address.
+   * - `to` is not the zero address.
    * - `tokenId` token must be owned by `from`.
    * - If the caller is not `from`, it must be approved to move this token by either {approve} or {setApprovalForAll}.
    *
-   * @notice External smart contracts cannot call the token contract at this time, so any transfers to external contracts
-   * may result in a permanent loss of the token. All transfers to external contracts will be permanently "stuck" at the
-   * ContractAddress
-   *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} from - The source account from which the token is being transfered
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} to - The target account to transfer token to
    * @param {Uint<128>} tokenId - The token being transfered
@@ -402,7 +421,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=253
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * @param {Uint<128>} tokenId - The target token of the owner query
    * @return {Either<ZswapCoinPublicKey, ContractAddress>} - The owner of the token
@@ -422,7 +442,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=253
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * @param {Uint<128>} tokenId - The token to query
    * @return {Either<ZswapCoinPublicKey, ContractAddress>} - An account approved to spend `tokenId`
@@ -442,7 +463,8 @@ module NonFungibleToken {
    * @circuitInfo k=11, rows=1128
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    *
    * WARNING: This function assumes that `owner` is the actual owner of `tokenId` and does not verify this
    * assumption.
@@ -470,7 +492,8 @@ module NonFungibleToken {
    * @circuitInfo k=11, rows=1181
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - `spender` has approval from `owner` for `tokenId` OR `spender` has approval to manage all of `owner`'s assets.
    *
    * WARNING: This function assumes that `owner` is the actual owner of `tokenId` and does not verify this
@@ -500,7 +523,8 @@ module NonFungibleToken {
    * @circuitInfo k=12, rows=2049
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - If `auth` is non 0, then this function will check that `auth` is either the owner of the token,
    * or approved to operate on the token (by the owner).
    *
@@ -549,10 +573,11 @@ module NonFungibleToken {
    * @circuitInfo k=11, rows=1073
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - `tokenId` must not exist.
-   * - `to` cannot be the zero address.
-   * - `to` cannot be ContractAddress.
+   * - `to` is not the zero address.
+   * - `to` is not a ContractAddress.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} to - The account receiving `tokenId`
    * @param {Uint<128>} tokenId - The token to transfer
@@ -574,12 +599,14 @@ module NonFungibleToken {
    * @circuitInfo k=11, rows=1070
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - `tokenId` must not exist.
-   * - `to` cannot be the zero address.
+   * - `to` is not the zero address.
    *
-   * @notice External smart contracts cannot call the token contract at this time, so any transfers to external contracts
-   * may result in a permanent loss of the token.
+   * WARNING: Transfers to contract addresses are considered unsafe because contract-to-contract
+   * calls are not currently supported. Tokens sent to a contract address may become irretrievable.
+   * Once contract-to-contract calls are supported, this circuit may be deprecated.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} to - The account receiving `tokenId`
    * @param {Uint<128>} tokenId - The token to transfer
@@ -605,7 +632,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=509
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - `tokenId` must exist.
    *
    * @param {Uint<128>} tokenId - The token to burn
@@ -621,13 +649,20 @@ module NonFungibleToken {
    * @description Transfers `tokenId` from `from` to `to`.
    *  As opposed to {transferFrom}, this imposes no restrictions on own_public_key().
    *
+   * @notice Transfers to contract addresses are currently disallowed until contract-to-contract
+   * interactions are supported in Compact. This restriction prevents assets from being inadvertently
+   * locked in contracts that cannot currently handle token receipt.
+   *
    * @circuitInfo k=11, rows=1284
    *
    * Requirements:
-   * - The contract must have been initialized.
-   * - `to` cannot be the zero address.
-   * - `to` cannot be ContractAddress.
+   *
+   * - The contract is initialized.
+   * - `to` is not the zero address.
+   * - `to` is not a ContractAddress.
    * - `tokenId` token must be owned by `from`.
+   *
+
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} from - The source account of the token transfer
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} to - The target account of the token transfer
@@ -653,13 +688,14 @@ module NonFungibleToken {
    * @circuitInfo k=11, rows=1281
    *
    * Requirements:
-   * - The contract must have been initialized.
-   * - `to` cannot be the zero address.
+   *
+   * - The contract is initialized.
+   * - `to` is not the zero address.
    * - `tokenId` token must be owned by `from`.
    *
-   * @notice External smart contracts cannot call the token contract at this time, so any transfers to external contracts
-   * may result in a permanent loss of the token. All transfers to external contracts will be permanently "stuck" at the
-   * ContractAddress
+   * WARNING: Transfers to contract addresses are considered unsafe because contract-to-contract
+   * calls are not currently supported. Tokens sent to a contract address may become irretrievable.
+   * Once contract-to-contract calls are supported, this circuit may be deprecated.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} from - The source account of the token transfer
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} to - The target account of the token transfer
@@ -686,7 +722,8 @@ module NonFungibleToken {
    * @circuitInfo k=11, rows=1169
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - If `auth` is non 0, then this function will check that `auth` is either the owner of the token,
    * or approved to operate on the token (by the owner).
    *
@@ -717,8 +754,9 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=554
    *
    * Requirements:
-   * - The contract must have been initialized.
-   * - `operator` can't be the address zero.
+   *
+   * - The contract is initialized.
+   * - `operator` is not the address zero.
    *
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} owner - Owner of a token
    * @param {Either<ZswapCoinPublicKey, ContractAddress>} operator - The account to approve
@@ -750,7 +788,8 @@ module NonFungibleToken {
    * @circuitInfo k=10, rows=318
    *
    * Requirements:
-   * - The contract must have been initialized.
+   *
+   * - The contract is initialized.
    * - `tokenId` must exist.
    *
    * @param {Uint<128>} tokenId - The token that should be owned

docs/antora.yml

@@ -5,4 +5,4 @@ nav:
   - modules/ROOT/nav.adoc
 asciidoc:
   attributes:
-    page-sidebar-collapse-default: 'Ownable'
+    page-sidebar-collapse-default: "Ownable, NonFungibleToken"

docs/modules/ROOT/nav.adoc

@@ -9,3 +9,6 @@
 
 ** xref:fungibleToken.adoc[FungibleToken]
 *** xref:/api/fungibleToken.adoc[API Reference]
+
+** xref:nonFungibleToken.adoc[NonFungibleToken]
+*** xref:/api/nonFungibleToken.adoc[API Reference]