craft-nft

A standalone NFT implementation for real-world arts and crafts assets
Info | Log | Files | Refs | README

README.md (7987B)


      1 # Craft NFT
      2 
      3 The CraftNFT code is designed to provide a sovereign and standalone registry for certificates of real-world arts and crafts assets.
      4 
      5 It is implemented on the Ethereum Virtual Machine and the web3 JSON-RPC protocol.
      6 
      7 
      8 ## Dependencies
      9 
     10 Version numbers in dependencies are not absolute, but only detail what has been used by the author during development.
     11 
     12 * `make >= 4.x`
     13 * `solc >= 0.8.x`
     14 * `python >= 3.7.x`
     15 * `node >= 19.2.x (npm >= 8.19.x)`
     16 * An `evm` service endpoint that speaks web3 JSON-RPC. Some examples for development are:
     17     - [ganache](https://trufflesuite.com/ganache/) (probably the simplest to set up)
     18     - A private network with [geth](https://github.com/ethereum/go-ethereum)
     19     - An `evm` network using valueless tokens (e.g. [Görli](https://blog.infura.io/post/infura-supports-goerli-and-sepolia-as-ethereums-long-lived-testnets) or [Bloxberg](https://bloxberg.org))
     20 
     21 For `python` and `node` requirements, please consult the respective `*requirements.txt` and `package.json` files. Usage of `virtualenv` for python and `nvm` for nodejs is recommended.
     22 
     23 The example browser application currently only works with Metamask as wallet. The dependencies used in development are:
     24 
     25 * `chromium 108.0.5359.98` 
     26 * `metamask (chromium extension) 10.23.1`
     27 
     28 To use the contract address storage service in the example browser application, you also need:
     29 
     30 * `rust >= 1.60 (cargo => 1.60)`
     31 
     32 
     33 ## Quickstart
     34 
     35 ```
     36 git clone git://defalsify.org/craft-nft
     37 cd craft-nft
     38 make
     39 ```
     40 
     41 The above will compile the smart contract, and copy it to the python and js environments. It will also download dependencies for python and javascript, compile the python package, and build the javascript browser library.
     42 
     43 
     44 ## Publishing the token contract
     45 
     46 ```
     47 $ pip install $REPO_ROOT/dist/craft-nft-x.x.x.tar.gz 
     48 ```
     49 
     50 ```
     51 craftnft-publish \
     52     --name <token name> \
     53     --symbol <token symbol> \
     54     -p <evm rpc node provider> \
     55     -s -w
     56 ```
     57 
     58 If successful, the `craftnft-publish` command will output the address of the token.
     59 
     60 You can also run the script directly from the python directory without installing anything. The same argumnents apply as above. Make sure that you include the directory in python's path.
     61 
     62 ```
     63 cd python
     64 PYTHONPATH=. python craft_nft/runnable/publish.py <args>
     65 ```
     66 
     67 ## Allocating and minting tokens
     68 
     69 There are CLI tools for allocating, minting and listing tokens. Here is a full example for tokens based on nonsensical token data:
     70 
     71 ```
     72 set +e
     73 # chainlib required settings, edit as needed.
     74 export RPC_PROVIDER=http://localhost:8545
     75 # The chain spec 3rd field MUST match the chain id of the newtork
     76 export CHAIN_SPEC=evm:kitabu:5050:test
     77 # this file will be used to sign all transcations below
     78 # it must have sufficient gas token balance
     79 export WALLET_KEY_FILE=${WALLET_KEY_FILE:-alice.json}
     80 
     81 # eth-keyfile is provided by the funga-eth module, a dependency of craft-nft
     82 >&2 echo generating keys...
     83 eth-keyfile -z > bob.json
     84 eth-keyfile -z > carol.json
     85 eth-keyfile -z > dave.json
     86 export ALICE=$(eth-keyfile -z -d $WALLET_KEY_FILE)
     87 >&2 echo "Alice has key $ALICE. This key will be used for signing"
     88 export BOB=$(eth-keyfile -z -d bob.json)
     89 >&2 echo Bob has key $BOB
     90 export CAROL=$(eth-keyfile -z -d carol.json)
     91 >&2 echo Carol has key $CAROL
     92 export DAVE=$(eth-keyfile -z -d dave.json)
     93 >&2 echo Dave has key $DAVE
     94 
     95 # publish contract
     96 >&2 echo publishing token ...
     97 echo "description missing" > description.txt
     98 craftnft-publish --name "Test Token" --symbol "TEST" -s -w > token.txt
     99 export TOKEN_ADDRESS=$(cat token.txt | eth-checksum)
    100 >&2 echo published token $TOKEN_ADDRESS
    101 
    102 token_foo=$(echo -n foo | sha256sum | awk '{print $1;}')
    103 >&2 echo allocating unique token "foo" ...
    104 craftnft-allocate -e $TOKEN_ADDRESS -s -w $token_foo >> txs.txt
    105 token_bar=$(echo -n bar | sha256sum | awk '{print $1;}')
    106 >&2 echo allocating batched token "bar" ...
    107 craftnft-allocate -e $TOKEN_ADDRESS -s -w --count 10 $token_bar  >> txs.txt
    108 
    109 >&2 echo minting the "foo" token to Alice ...
    110 craftnft-mint -e $TOKEN_ADDRESS --token-id $token_foo -s -w $ALICE >> txs.txt
    111 >&2 echo minting a "bar" token to Bob ...
    112 craftnft-mint -e $TOKEN_ADDRESS --token-id $token_bar -s -w $BOB >> txs.txt
    113 >&2 echo minting a "bar" token to Carol ...
    114 craftnft-mint -e $TOKEN_ADDRESS --token-id $token_bar -s -w $CAROL >> txs.txt
    115 >&2 echo minting a "bar" token to Alice ...
    116 craftnft-mint -e $TOKEN_ADDRESS --token-id $token_bar -s -w $ALICE >> txs.txt
    117 
    118 # erc721-tranfser is provided by the eth-erc721 module, a dependency of craft-nft
    119 # It is a generic tool, so we need to specify the gas budget manually
    120 >&2 echo "transfer Alice's bar token to Dave ..."
    121 erc721-transfer -e $TOKEN_ADDRESS -a $DAVE -s -w --fee-limit 100000 0xfcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04f0000000000000002 >> txs.txt
    122 
    123 craftnft-dump $TOKEN_ADDRESS
    124 set -e
    125 ```
    126 
    127 The above code is stored in demo.sh. A bit of editing is needed to set up according to your environment and signing keys.
    128 
    129 The outputs of a sample run should look something like this:
    130 
    131 ```
    132 sh /home/lash/src/home/eth/craft-nft/python/demo.sh 
    133 generating keys...
    134 Alice has key Eb3907eCad74a0013c259D5874AE7f22DcBcC95C. This key will be used for signing
    135 Bob has key e5E6656181108cCCB222243e1896bC0D0328af3B
    136 Carol has key 9aB2C0f01CA7135a106829EFfBb2B303191352b3
    137 Dave has key A952a6e57A45744a924B7bA5cC4Fbb42438EaEA5
    138 publishing token ...
    139 published token 7115070486ce22004D63D70f62F52175cedB3bAd
    140 allocating unique token foo ...
    141 allocating batched token bar ...
    142 minting the foo token to Alice ...
    143 minting a bar token to Bob ...
    144 minting a bar token to Carol ...
    145 minting a bar token to Alice ...
    146 transfer Alice's bar token to Dave ...
    147 token 2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae owned by Eb3907eCad74a0013c259D5874AE7f22DcBcC95C
    148 token fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04f0000000000000000 owned by e5E6656181108cCCB222243e1896bC0D0328af3B - (id fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9 batch 0 index 0)
    149 token fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04f0000000000000001 owned by 9aB2C0f01CA7135a106829EFfBb2B303191352b3 - (id fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9 batch 0 index 1)
    150 token fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04f0000000000000002 owned by A952a6e57A45744a924B7bA5cC4Fbb42438EaEA5 - (id fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9 batch 0 index 2)
    151 ```
    152 
    153 
    154 ## Using the javascript browser UI example.
    155 
    156 In the `js` directory, create a file called `settings.json` with the following contents (replace the address with the one output from `craftnft-publish`):
    157 
    158 ```
    159 {
    160     "contract": "<address of published contract>"
    161     "contentGatewayUrl": null
    162 }
    163 ```
    164 
    165 Then serve the `js` folder using a web server. For example:
    166 
    167 ```
    168 cd js
    169 # add -d to enable debugging output
    170 webfsd -F -d -p <port>
    171 ```
    172 
    173 ## Content addressed storage
    174 
    175 The example browser application uses the Wala service for content addressed storage and retrieval. The application will still work without the service, but some data will not be available for display.
    176 
    177 Wala can currently only be provisioned through its git repository:
    178 
    179 ```
    180 git clone git://defalsify.org/wala.git
    181 cd wala
    182 cargo build --release
    183 
    184 # to see whats going on behind the scenes, add debug logging
    185 export RUST_LOG=debug
    186 target/release/wala -p <port>
    187 ```
    188 
    189 For the example browser application to use the service, the `wala` url needs to be added to the `contentGatewayUrl` field of the settings.json file in the `js` directory.
    190 
    191 ### Data published to storage
    192 
    193 The data in content-addressed storage used by the application is:
    194 
    195 * Token metadata (read/write)
    196 
    197 See the `$REPO_ROOT/doc/latex/terminology.latex` document for a terminology overview.
    198 
    199 
    200 ## Further reading
    201 
    202 For more details on the chainlib/chaintool contents, please refer to the [chaintool documentation repository](https://git.defalsify.org/chaintool-doc).
    203 
    204 All chaintool related code repositories are hosted on [https://git.defalsify.org](https://git.defalsify.org)