19 |
20 | TYPE ${this.props.category}
21 |
22 |
23 | 
26 |
26 | 
38 | 
121 | ${date}
122 | List for Sale 
Auction
Collateralise
List for Hire
14 |
34 |
14 |
22 | 
](https://github.com/AlphaWallet/TokenScript/blob/master/doc/img/iconified-view.jpeg)
20 |
21 |
22 |
23 | The regular view is displayed after a user clicks on a particular token and it shows all the
24 | functions available to the user as well as a more in depth view of the token. It looks something like this:
25 |
26 | [
](https://github.com/AlphaWallet/TokenScript/blob/master/doc/img/regular-view.jpeg)
27 |
--------------------------------------------------------------------------------
/tutorial/step-2-assembling-the-XML-file.md:
--------------------------------------------------------------------------------
1 | ## Assembling the XML File
2 |
3 | So, now that you have your token.en.shtml, enter.en.shtml and shared.css file, we are now ready to continue on to the XML file. This file will define the function calls, how we define the meaning of our tokens, off chain functionality of the token (in our example, it would be entering a building with a token via a challenge response) and plugging in the layout.
4 |
5 | Since NFTs can encode information inside their 32 bytes such as genes or what time the event is supposed to be held, we can use TokenScript to interpret the meaning of such tokens so that the user is given context. Furthermore, it is also possible to define logic which queries the smart contract for additional information, within the context of the token id itself.
6 |
7 | To inspect the example EntryToken.xml file we have for you, simply:
8 |
9 | $ cd examples/EntryToken && cat EntryToken.xml
10 |
11 | We have set up contracts on mainnet, ropsten, kovan & rinkeby that will always return a balance of two NFTs. You can use these to test against the sample TokenScript provided in the tutorial examples.
12 |
13 | ### Creating your own XML file or editing ours
14 |
15 | You can make your own changes to the sample XML file in the examples directory and change it to match whatever you like. Once you drag and drop it in the next step, you will be able to see the changes reload and since there is a hardcoded balance of two NFTs, you will be able to play around with it.
16 |
--------------------------------------------------------------------------------
/tutorial/step-3-debugging-and-testing.md:
--------------------------------------------------------------------------------
1 | ## Debugging and testing on iOS and Android
2 | So you now have your completed .xml and .shtml files, excellent! You can now merge the files together and drop them for testing in AlphaWallet iOS and Android. To merge the files together run 'make EntryToken.canonicalized.xml' which will validate the files and put them all together. Since we have hardcoded the balances for this contract, you will be able to see them immediately in your wallet after you add them by clicking the + button in the top-right of the wallet tab, and entering the contract address.
3 |
4 | For Ethereum mainnet:
5 |
6 | 
7 | '0x63cCEF733a093E5Bd773b41C96D3eCE361464942'
8 |
9 | Or your choice of testnet (see the `ts:address` tag in EntryToken.xml for each available network's address).
10 |
11 | ** We have uploaded this example xml file to our repo server, this means you do not have to drag and drop it to the device unless you are planning to edit it or create your own **
12 |
13 | ### Get AlphaWallet iOS or Android
14 | [
](https://itunes.apple.com/us/app/alphawallet/id1358230430?ls=1&mt=8) [
](https://play.google.com/store/apps/details?id=io.stormbird.wallet&hl=en_US)
15 |
16 | ### Clone the source
17 | Go to either [iOS](https://github.com/AlphaWallet/alpha-wallet-ios) or [Android](https://github.com/AlphaWallet/alpha-wallet-android) source repo
18 |
19 | ### Debugging on iOS
20 | After cloning the source code you can run it with either the emulator or your own phone via xcode or AppCode. If you are using the emulator, simply copy the path it prints when loading up in xcode and cd into it. Once there you shoud see a directory called 'assetDefinitionsOverrides', simply drop the file into this directory.
21 |
22 | If you are using your real device, simply airdrop the canonicalized.xml file or drop the xml file with its three layout files (shared.css, enter.en.shtml & token.en.shtml).
23 |
24 | ### Debugging on Android
25 | As with iOS you can either use your own device or the emulator. Run on Android Studio/Intellij and use your device or the emulator. In the AlphaWallet settings choose 'enable dev override', allow the app access to file structure then drag and drop the file into the AlphaWallet directory at root or upload to sdcard/AlphaWallet using the Device File Explorer. If the 'enable dev override' is not chosen inside the app, it will not be able to pick up files in this directory.
26 |
27 |
--------------------------------------------------------------------------------
/tutorial/step-4-signing-and-publishing.md:
--------------------------------------------------------------------------------
1 | ## Signing and publishing your TokenScript file
2 |
3 | To publish your Tokenscript, it has to be signed.
4 |
5 | Currently, a TokenScript is signed by an SSL key. For example, a TokenScript signed by the SSL key for the domain name shong.wang is displayed as "reputation relies on shong.wang" when rendered. To make your first signing easy, we provided both the signing key and needed SSL certificates.
6 |
7 | ** Dapps like DAI will have a signature from MakerDAO.com's SSL certificate; this gives the user peace of mind that the TokenScript is actually intended by the issuer. The file includes all the relevant code and therefore cannot be tampered with, as that would break the signature verification. **
8 |
9 | ### Install the tools
10 |
11 | All XML signing tools should work, but we will we demonstrate here with xmlsectool.
12 |
13 | First, check that you have the right tool installed. Say, in OS X with brew installed:
14 |
15 | $ brew install xmlsectool
16 |
17 | If your package manager doesn't provide xmlsectool, you can download from its [home page](https://wiki.shibboleth.net/confluence/display/XSTJ2/xmlsectool+V2+Home) and install it manually.
18 |
19 | From here I'll assume your system supports make. If not, it's easier to wait for the tutorial on how to sign with GUI, which we will produce based on [Oxygen's document](https://www.oxygenxml.com/doc/versions/21.0/ug-editor/topics/signing-files.html#signing-files) by late 2019.
20 |
21 | If you installed xmlsectool manually, for example to `/opt/xmlsectool-2.0.0/`, you will need to change the first line of the MakeFile to this:
22 |
23 | XMLSECTOOL=/opt/xmlsectool-2.0.0/xmlsectool.sh
24 |
25 | Having that sorted out, please also install xmlstarlet and xmllint
26 |
27 | $ brew install xmlstarlet xmllint
28 |
29 | Now we have all the tools ready.
30 |
31 | ### Validate the test TokenScript
32 |
33 | Do a `make`. It will validate EntryToken.xml. It should pass if you haven't changed it.
34 |
35 | $ make EntryToken.canonicalized.xml
36 | # XML Canonicalization
37 | xmlstarlet c14n EntryToken.xml > EntryToken.canonicalized.xml
38 | # XML Validation
39 | -xmlstarlet val --xsd http://tokenscript.org/2019/10/tokenscript/tokenscript.xsd $@ || (mv $@ $@.INVALID; xmllint --noout --schema http://tokenscript.org/2019/10/tokenscript/tokenscript.xsd $@.INVALID)
40 |
41 | ** If the file has errors, it will produce a file named EntryToken.canonicalized.xml.FAILED which you can use for debugging **
42 |
43 | ### Using your SSL key
44 | To sign a TokenScript file you must retrieve the relevant SSL key that corresponds to the Token you are making a TokenScript for. e.g. `cdp.makerdao.com` for DAI related TokenScripts.
45 |
46 | This file must be converted to .p12 for signing and since most services will give you your file in .pem, here are the steps using OpenSSL to convert it from pem to p12.
47 |
48 | $ openssl pkcs12 -export -out keystore.p12 -inkey pathToYourPrivateKey.pem -in pathToYourCert.pem -certfile pathToYourChain.pem
49 |
50 | This command will ask for you to provide a password to encrypt the .p12, you will need to use this password again for the step below. The output of this command will be `keystore.p12`.
51 |
52 | If you do not want to use your own key for this tutorial, simply skip this step and go to the next which uses the sample key `shong.wang`.
53 |
54 | ### Sign the test TokenScript
55 |
56 | We prepared the signing key and SSL certificates in ssl directory. If you use yours, remember to replace their references in the Makefile or use the command below with your encrypted .p12.
57 |
58 | Run `make` with `EntryToken.tsml`
59 |
60 | $ make EntryToken.tsml
61 | /opt/xmlsectool-2.0.0/xmlsectool.sh --sign --keyInfoKeyName 'Shong Wang' --digest SHA-256 --signatureAlgorithm http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 --inFile EntryToken.canonicalized.xml --outFile EntryToken.tsml --key ssl/shong.wang.key --certificate ssl/shong.wang.certs
62 | INFO XMLSecTool - Reading XML document from file 'EntryToken.canonicalized.xml'
63 | INFO XMLSecTool - XML document parsed and is well-formed.
64 | INFO XMLSecTool - XML document successfully signed
65 | INFO XMLSecTool - XML document written to file /home/weiwu/IdeaProjects/TokenScript/examples/ticket/EntryToken.tsml
66 | # removing the canonicalized created for validation
67 | rm EntryToken.canonicalized.xml
68 |
69 | And now you get a signed TokenScript EntryToken.tsml which is ready to be published. This file can also be dropped to the iOS or Android app as described in the previous step.
70 |
71 | If you are signing with your own key from the step above, run:
72 |
73 | $ make EntryToken.tsml KEYSTORE=keystore.p12 KEYPASSWORD=YourPassword
74 |
75 | ### Publishing your TokenScript
76 |
77 | To test your current .tsml file, you can simply drop in onto your device with the instructions provided by step 3. As of now, we are serving signed tsml files from a server that the device can pull from to load into it's corresponding token card.
78 |
79 | If you would like to publish your own tsml file to run on this server, create a PR in this [repo](https://github.com/AlphaWallet/TokenScript-Repo) and we will review it.
80 |
--------------------------------------------------------------------------------
/tutorial/tutorial-files/Coin.sol:
--------------------------------------------------------------------------------
1 |
2 | // Specifies that the source code is for a version
3 | // of Solidity greater than 0.5.0
4 | pragma solidity >=0.5.0 <0.7.0;
5 |
6 | // A contract is a collection of functions and data (its state)
7 | // that resides at a specific address on the Ethereum blockchain.
8 | contract Coin {
9 | // The keyword "public" makes variables accessible from outside a contract
10 | // and creates a function that other contracts or SDKs can call to access the value
11 |
12 | string public name = "Coin"; //fancy name: eg Simon Bucks
13 | uint256 public decimals = 18; //How many decimals to show.
14 | string public symbol = "COIN"; //An identifier: eg SBX
15 |
16 | // Returns balance of an address
17 | function balanceOf(address addr) public view returns (uint) {
18 | return balances[addr];
19 | }
20 |
21 | // An address stores addresses of contracts or external (user) accounts
22 | address public minter;
23 |
24 | // A mapping lets you create complex custom data types.
25 | // This mapping assigns an unsigned integer to an address
26 | // and is also a public variable.
27 | mapping (address => uint) public balances;
28 |
29 | // Events allow Ethereum clients to react to specific
30 | // contract changes you declare.
31 | // This defines the event and it is sent later
32 | event Sent(address from, address to, uint amount);
33 |
34 | // A special function only run during the creation of the contract
35 | constructor() public {
36 | // Uses the special msg global variable to store the
37 | // address of the contract creator
38 | minter = msg.sender;
39 | }
40 |
41 | // Sends an amount of newly created coins to an address
42 | function mint(address receiver, uint amount) public {
43 | // require statements define conditions that must pass
44 | // before state is changed.
45 | // If it fails (equals false), an exception is triggered
46 | // and reverts all modifications to state from the current call
47 |
48 | // Can only be called by the contract creator
49 | require(msg.sender == minter);
50 |
51 | // Ensures a maximum amount of tokens
52 | require(amount < 1e60);
53 | balances[receiver] += amount;
54 | }
55 |
56 | // Sends an amount of existing coins
57 | // from any caller to an address
58 | function transfer(address receiver, uint amount) public {
59 | // The sender must have enough coins to send
60 | require(amount <= balances[msg.sender], "Insufficient balance.");
61 | // Adjust balances
62 | balances[msg.sender] -= amount;
63 | balances[receiver] += amount;
64 | // Emit event defined earlier
65 | emit Sent(msg.sender, receiver, amount);
66 | }
67 | }
68 |
--------------------------------------------------------------------------------
/tutorial/tutorial-files/Coin.xml:
--------------------------------------------------------------------------------
1 |
2 |
4 |
5 | ]>
6 |