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)