commit fb6b7cde2e07ec16f09949a5f9b6d31125ae7dd7
parent 758e9a0ae815ebb20d1bd7b33a51aaeaa247c0d4
Author: lash <dev@holbrook.no>
Date: Sat, 24 Dec 2022 12:28:55 +0000
Convert docs to texinfo and build docs
Diffstat:
6 files changed, 141 insertions(+), 0 deletions(-)
diff --git a/Makefile b/Makefile
@@ -20,3 +20,6 @@ aux: wala
test:
make -C python test
+
+doc:
+ makeinfo -o html_docs --html doc/texinfo/index.texi
diff --git a/doc/texinfo/contract.texi b/doc/texinfo/contract.texi
@@ -0,0 +1,47 @@
+@chapter Smart contract
+
+There are primarily two distinct representations, one for the unique token and one for the batch. Both are expressed within the same data structure.
+
+All serialized representations of numbers mentioned in the below are expressed in big-endian format.
+
+
+@section Relational structure
+
+At the highest level, a token is unambiguously identified by the sha256 hash of the json structure that describes it.
+
+This is true regardless whether the token is a Unique Token or a Batched Token.
+
+
+@subsection Token array
+
+The tokens array contains every distinct token ever added to the contract.
+
+The content of each entry is the sha256 content address of the token specification.
+
+
+@subsection Token Allocation mapping
+
+The token mapping defines the parameters for individual tokens allocations.
+
+For a Unique Token there will only ever be one Token Allocation.
+
+Every entry in the array defines how many tokens were issued for the batch, and a current count of how many individual tokens have been minted from that batch.
+
+For a Token Batch, it also keeps track of whether or not sparse token minting has occurred. See below for more details on sparse minting.
+
+
+@subsubsection Minted Token mapping
+
+The mintedToken mapping defines the state of a minted token, e.g. the ownership and its position in the token issuance hierarchy. A minted token can be either unique or one of a batch.
+
+For unique tokens, the key of this mapping will always be the same as the sha256 content address of the token specification.
+
+For a batched token, the key will be the first 48 bytes of the content address, then 2 bytes describing the batch of the token, and 6 bytes describing its index within the batch.
+
+The value of this mapping contains the remainder of the hash that has been supplanted by the batch and index in the key (bytes 2 through 10), as well as the owner address (bytes 12 through 32.
+
+The first byte of the value is reserved for control bits.
+
+The first bit, if set, disambiguates an actually set value from an empty value.
+
+The second bit, if set, indicates a unique token.
diff --git a/doc/texinfo/index.texi b/doc/texinfo/index.texi
@@ -0,0 +1,7 @@
+@node craft-nft
+@top Craft NFT
+
+@include overview.texi
+@include terminology.texi
+@include contract.texi
+@include tools.texi
diff --git a/doc/texinfo/overview.texi b/doc/texinfo/overview.texi
@@ -0,0 +1,21 @@
+@chapter Overview
+
+The CraftNFT code is designed to provide a sovereign and standalone registry for certificates of real-world arts and crafts assets.
+
+Tokens may be issued for unique works, aswell as works that span multiple units or copies. The latter, termed as ``batched'' tokens, may be issued in sequential or arbitrary order.
+
+
+@section Unique token
+
+A unique token represents a unique piece of work. Most unique works are hand-crafted, or at least represent some result of work that is bound to a combination of either of individual(s), time and place.
+
+A unique work never usually retains its value when copied.
+
+
+@section Batched token
+
+A batched token represents a work that is designed to be copied. Examples include limited edition prints, perhaps numbered, and signed digital assets.
+
+Every issuance of new batched tokens is clearly identitiable by the batch number it inherits. This is analogous to serial edition numbers used in book publishing.
+
+Thus, it is not possible to inflate the supply of an existing token issuance. Or, in other words, if 10 tokens are issued first, and 20 issued later, the 20 latter tokens will be irreversibly marked as ``second edition''.
diff --git a/doc/texinfo/terminology.texi b/doc/texinfo/terminology.texi
@@ -0,0 +1,43 @@
+@chapter Terminology
+
+@table @samp
+@item Content Address
+A data string representing a deterministic fingerprint of data.
+
+@item Token Contract
+A smart contract that enables creation of multiple NFT tokens.
+
+@item Contract Declaration
+A Content Address of a human-readable resource that describes all tokens created in a single Token Contract.
+
+@item Token Batch
+A collection of units that were issued at a particular moment in time to represent a unique work, for example limited edition printed copies. A token may have multiple batches, for example to represents reprints.
+
+@item Token Id
+The unique identifier for a work. In the context of Token Batches, the Token Id points to the work that the units in the batches represent, for example the original print medium resource. The Token Id is the Content Address of the file
+
+@item Token Declaration
+A Content Address of a machine-readable resource that describes a single Token Id
+
+@item Minted Token
+A token that has been minted.
+
+@item Token Owner
+A public/private key pair holder that owns a Minted Token.
+
+@item Token Key
+The identifier for a single minted token. The token may be unique or may be part of a Token Batch. In case of the latter, the Token Key contains the batch number and the minted token's index within that batch.
+
+@item Batch Token
+A minted token which is part of a batch.
+
+@item Unique Token
+A single Minted Token which
+
+@item Token Allocation
+Defines the nature and behavior of a token. A Token Allocation is done once for a Unique Token, or per-batch for a Batch Token.
+
+@item Token Spec
+Data structure describing the current state of token minting.
+
+@end table
diff --git a/doc/texinfo/tools.texi b/doc/texinfo/tools.texi
@@ -0,0 +1,20 @@
+@chapter Tooling
+
+The smart contract tests are implemented using a convenience library based on the chainlib-eth python module.
+
+It also provides two CLI tools:
+
+@itemize @var
+@item craftnft-publish
+Create a new token.
+@item craftnft-dump
+List all minted tokens and their ownership status.
+@item craftnft-allocate
+Allocate a new set of tokens for a particular token definition.
+@item craftnft-mint
+Mint a new token from an existing allocation.
+@end itemize
+
+The tooling is itself provided as a python module. It can be installed from pypi.org under the name craft\_nft, e.g. pip install craft\_nft. If your executables path are correctly set, the tools will be directly executable in the shell.
+
+
