Merge pull request #120 from ultraio/feature/BLOCK-2016-update-user-g…

…roup-and-subjective-queue-consolidation-documentation-for-testnet

Feature/block 2016 update user group and subjective queue consolidation documentation for testnet

README.md

@@ -25,14 +25,22 @@ Always use `experimental` for general document writing. The files update instant
 -   If you create any new pages you will need to stop vitepress, and restart the preview.
 -   You can actively preview changes to a single document in the browser while a dev command is running, meaning the page auto-refreshes.
 
-### Experimental
+### All Files
 
-**This Has Live Updates**
+**This has live updates, and renders all files.**
 
 ```
 npm run dev
 ```
 
+### Experimental
+
+**This does not update live**
+
+```
+npm run dev:experimental
+```
+
 ### Staging
 
 **This does not update live**
@@ -57,45 +65,34 @@ Builds a static version of the website that can be deployed anywhere.
 npm run build:all
 ```
 
-## File Deployment Guide
-
-Deployments are based on the name.
-
-Any file without the extension `.mainnet.md` or `.staging.md` will be available in all versions.
+# Extended Functionality
 
-If you want to only deploy a specific file version on mainnet, append `.mainnet.md` to the file name.
+## File Environment Extension Guide
 
-## File Order Guide
-
-`order` is an optional property in the front matter at the top.
+Deployments are based on the name.
 
-Specifying the order as a lesser number ensures it is higher up in the sidebar.
+Any file without the extension `.experimental.md` or `.mainnet.md` or `.staging.md` will only be deployed to their respective environments.
 
-ie.
-- -99999999 - Highest
-- 1 - High
-- 2 - Medium
-- 3 - Low
-- 99 - Lowest
+If the file **does not contain** any of the above extensions, it will be deployed to all environments.
 
-```md
----
-title: 'Example Markdown File'
-order: -999
+### A Note About Links
 
----
+When you are linking an `environment extension` file, **DO NOT APPEND** `staging`, `mainnet`, or `experimental`.
 
-# Example Markdown File
+This means if you have a file named `test.experimental.md`, you should link it as the following:
 
-Placeholder
+```
+[My Test File](./test.md);
 ```
 
 ## Environment Sections
 
-If you need one file in `docs` to have specific content for a specific `environment` you can use these tags.
+If you need one file in `docs` to have specific content for a specific `environment` you can use these tags as long as the changes **do not include** an `environment extension link`.
 
 They support `inline` as well.
 
+**You cannot use links inside of these sections, they are meant for small text edits.**
+
 ```html
 <Experimental>
 Only shows in experimental
@@ -109,3 +106,27 @@ Only shows in staging
 Only shows in mainnet
 </Mainnet>
 ```
+
+## File Order Guide
+
+`order` is an optional property in the front matter at the top.
+
+Specifying the order as a lesser number ensures it is higher up in the sidebar.
+
+ie.
+- -99999999 - Highest
+- 1 - High
+- 2 - Medium
+- 3 - Low
+- 99 - Lowest
+
+```md
+---
+title: 'Example Markdown File'
+order: -999
+---
+
+# Example Markdown File
+
+Placeholder
+```

docs/.vitepress/sidebars/helper.ts

@@ -13,6 +13,20 @@ import { DefaultTheme } from 'vitepress';
  * @return {(string[] | null)}
  */
 export function getMarkdownFiles(folderPath: string, basePath = '/docs'): DefaultTheme.SidebarItem[] {
+    if (__filename.includes('docs-')) {
+        if (__filename.includes('docs-experimental')) {
+            basePath = '/docs-experimental'
+        }
+
+        if (__filename.includes('docs-staging')) {
+            basePath = '/docs-staging'
+        }
+
+        if (__filename.includes('docs-mainnet')) {
+            basePath = '/docs-mainnet'
+        }
+    }
+
     // Example: /home/stuyk/ultra/docs-blockchain + basePath + folderPath
     const baseFolderPath = process.cwd().replace(/\\/gm, '/') + basePath;
     const folderToRead = baseFolderPath + folderPath;

docs/blockchain/contracts/nft-contract/index.experimental.md

@@ -0,0 +1,152 @@
+---
+title: 'NFT Contract Overview'
+order: -99
+
+---
+
+# NFT Overview
+
+The abbreviation ‘NFT’ stands for Non-Fungible Token which means that NFT is a unit of data stored on a blockchain that can be sold or traded like other tokens. Unlike other tokens all NFTs are unique and one NFT cannot be replaced with another. That is why NFTs are often called `Uniqs`. In this document the NFTs can also be referred to as tokens.
+
+The Ultra's `eosio.nft.ft` smart contract defines a set of data structures (multi index tables, singletons) and a set of blockchain actions to manipulate the data structures. Both the data structures and the actions implement the supported set of NFT Use cases.
+
+## Info
+
+NFT use cases describe what different users can do with NFTs. The text in **bold** represents actions, the text in _italic_ represents blockchain accounts and the `highlighted` text represents the related data structures or data structure elements. Please refer to the action description or data structure overview to obtain more information.
+
+## Token Factory Creation
+
+**PLEASE NOTE:** _Recall and Lockup feature will be disabled by default which means when creating new token factory, action will fail if you put any value for recall window or lockup time. This note will be removed when these features are enabled again._
+
+The _Asset Creator_ and the _Asset Manager_ can **create.b** a token factory.
+
+To issue a token, a token factory should be created first. For this version of `eosio.nft.ft` only _Ultra_ can be the _Asset Creator_ and the _Asset Manager_. A token factory is a set of blockchain data which provides settings for the NFTs issued with the factory. During the creation process it is required to set up several token parameters which control the NFTs parameters and the lifecycle - the NFTs off-chain metadata, minimum prices, reselling timeframes etc. All these data is stored in the `factory.b` table.
+
+-   [create.b - create token factory](./nft-actions/create.b.md)
+-   [factory.b](./nft-tables.md#factory-b)
+
+## Issuing
+
+The _Asset Manager_ can **issue.b** a token either to the _Asset Manager_ or to another _Account_.
+
+The NFT issuance requires setting several parameters like the receiving _Account_ and the amount of tokens. The issued NFTs receive a global unique ID and a token factory recorded serial (ordinal) number. The issued token is recorded into the _Account_'s `token.b` table. The **issue.b** action reads and updates the data in the `factory.b` table.
+
+-   [issue.b - issue tokens with token factory](./nft-actions/issue.b.md)
+-   [factory.b](./nft-tables.md#factory-b)
+-   [token.b](./nft-tables.md#token-b)
+
+## Transferring
+
+The token _Owner_ can **transfer** tokens to another _Account_.
+
+An NFT _Owner_ can **transfer** their tokens to another _Account_. If the _Account_ is listed on the `conditionless_receivers` array of the token factory, no transfer checks are done. Otherwise the action is checked against the trading window and lock time limitations. The tables affected are `token.b` scoped to the sender and receiver accounts. The `factory.b` is read to obtain limitations.
+
+-   [transfer - hand tokens over to another user](./nft-actions/transfer.md)
+-   [token.b](./nft-tables.md#token-b)
+
+## Selling
+
+The token _Owner_ can **resell** tokens.
+
+An NFT _Owner_ can **resell** their tokens on the resale marketplace specifying the desirable price. A resale promoter fee can be specified, the resale promoter will receive a fraction of the received funds. This action is a subject to the trading window, minimal resale price and the lockup checks. The token ownership is verified using the `token.b` table. The resale marketplace table is `resale.a`.
+
+-   [resell - place tokens for sale on resell marketplace](./nft-actions/resell.md)
+-   [token.b](./nft-tables.md#token-b)
+-   [resale.b](./nft-tables.md#resale-a)
+
+## Buying
+
+An _Account_ can **buy** a token ownership.
+
+A blockchain _Account_ can **buy** a token from the resale marketplace. This action is a subject to the trading window checks. The global and the token factory specific resale shares as well as the resale promoter are dealt with when the paid funds are transferred from the buer to the seller. The token is deduced from the _Seller_'s `token.b` and added to the _Buyer_'s `token.b`. The `factory.b` and `resale.a` are read to obtain the tradeable window, promoter and the shares info.
+
+-   [buy - purchase token on resale marketplace](./nft-actions/buy.md)
+-   [factory.b](./nft-tables.md#factory-b)
+-   [token.b](./nft-tables.md#token-b)
+-   [resale.a](./nft-tables.md#resale-a)
+
+## Cancelling resell
+
+The token _Owner_ can **cancelresell** tokens.
+
+This action is only removes the token from the resale marketplace. The resale marketplace table is `resale.a`.
+
+-   [cancelresell - cancel token resell](./nft-actions/cancelresell.md)
+-   [resale.a](./nft-tables.md#resale-a)
+
+## Burning
+
+The token _Owner_ can **burn** tokens.
+
+An NFT _Owner_ can execute the **burn** action which removes the token from the resale marketplace (`resale.a`), removes the token from the _Owner_ account (`token.b`) and updates the token factory `existing_tokens_no` field (`factory.b`).
+
+-   [burn - erase tokens from owners and uniq factories](./nft-actions/burn.md)
+-   [factory.b](./nft-tables.md#factory-b)
+-   [token.b](./nft-tables.md#token-b)
+-   [resale.a](./nft-tables.md#resale-a)
+
+## NFT Service Use Cases
+
+## Recalling
+
+The _Asset Manager_ can **recall** tokens from an _Account_ in case of fraudulent action or erroneous issue.
+
+During the recall time window the _Asset Manager_ can recall tokens from an _Account_ in case of fraudulent action or erroneous issue or other cases that require tokens ownership be returned to the _Asset Manager_. If the token being recalled has entered the resell marketplace, the reselling of such token is canceled. The **recall** action affects `factory.b`, `resale.a` and `token.b` tables.
+
+-   [recall - cancel resell, return tokens to factory manager](./nft-actions/recall.md)
+-   [factory.b](./nft-tables.md#factory-b)
+-   [token.b](./nft-tables.md#token-b)
+-   [resale.a](./nft-tables.md#resale-a)
+
+## Authorizing Another Minter
+
+The _Asset Manager_ or an _Authorized Minter_ can authorize another _Minter_ to issue tokens with a token factory with the **authminter** action.
+
+Initially the _Asset Manager_ can delegate their ability to issue NFTs to some other account _Authorized Minter_ limited to issue up to the quantity of tokens. An _Authorized Minter_ can re-delegate a part of their quantity to another _Authorized Minter_. The `factory.a` table is read and `authmintr.a` table is modified during this action.
+
+-   [authmint.b - authorize an account to be able to mint tokens](./nft-actions/authmint.b.md)
+-   [factory.b](./nft-tables.md#factory-b)
+-   [authmintr.a](./nft-tables.md#authmintrs-a)
+
+## Controlling Token Factory Lifecycle
+
+The _Asset Manager_ can stop issuing with or decommission a token factory.
+
+The **setstatus** action lets the _Asset Manager_ to control the lifecycle of the token factory. Only the `factory.b` table is involved.
+
+-   [setstatus - set token factory state](./nft-actions/setstatus.md)
+-   [factory.b](./nft-tables.md#factory-b)
+
+## Updating the Token Factory Metadata
+
+The _Asset Manager_ can update the token factory metadata.
+
+The **setmeta.b** action lets the _Asset Manager_ to set the token factory metadata updating the `factory.b` table.
+
+-   [setmeta.b - set token factory metadata uri and hash](./nft-actions/setmeta.b.md.md)
+-   [factory.b](./nft-tables.md#factory-b)
+
+## Setting the conditionless receivers
+
+The _Asset Manager_ can set the token factory conditionless receivers.
+
+The **setconrecv** action allows the _Asset Manager_ to set the token factory conditional receivers - the accounts that can receive NFTs without checking for mintable window, lockup and other limitations. The action updates the `factory.b` table.
+
+-   [setconrecv - set conditionless receivers](./nft-actions/setconrecv.md)
+-   [factory.b](./nft-tables.md#factory-b)
+
+## Adding factory purchase options
+
+The _Asset Manager_ can add the factory first-hand purchase requirements
+
+The **setprchsreq.a**/**setprchsreq.b** action allows the _Asset Manager_ to set a purchase requirement for the factory which can then be used by any user to purchase a token from the factory directly using **purchase.a** action.
+
+**setprchsreq.a** action is deprecated, we recommend using **setprchsreq.b** action.
+
+Multiple purchase requirements can be specified for a single factory. In addition to a simple fungible token price (UOS or USD) asset manager can specify the price for an individual purchase option using uniqs from other factories. Those uniqs can be either burnt or transferred to a specified account or simply verify their presence.
+
+-   [setprchsreq.a - set purchase requirement](./nft-actions/setprchsreq.a.md)
+-   [setprchsreq.b - set purchase requirement](./nft-actions/setprchsreq.b.md)
+-   [delprchsreq.a - delete purchase requirement](./nft-actions/delprchsreq.a.md)
+-   [purchase.a - purchase a token](./nft-actions/purchase.a.md)
+-   [fctrprchs.a - table of factory purchase options](./nft-tables.md#fctrprchs-a)