diff --git a/README.md b/README.md index 69d5000..7e7c3b9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,8 @@ -# documentation -ICON documentation +- howto + - [icon-development-network-on-aws-marketplace](./howto/icon-development-network-on-aws-marketplace.md) +- icon-key-concepts + - [accounts](./icon-key-concepts/accounts.md) + - [parallel-processing](./icon-key-concepts/parallel-processing.md) + - [transactions](./icon-key-concepts/transactions.md) +- introduction + - [about-this-guide](./introduction/about-this-guide.md) diff --git a/howto/icon-development-network-on-aws-marketplace.md b/howto/icon-development-network-on-aws-marketplace.md new file mode 100644 index 0000000..f2050c4 --- /dev/null +++ b/howto/icon-development-network-on-aws-marketplace.md @@ -0,0 +1,465 @@ +--- +title: "How to create own blockchain network from AWS marketplace" +excerpt: "" +--- + +This document is for anyone who wants to set up their own ICON Development Network on AWS. + +## Intended Audience +Someone who needs their own "ICON Development Network" for ICON SCORE or DApp. + +## Purpose +Following this document step-by-step will all reader to set up their own ICON Development Network on AWS. + +## Prerequisites +### Create an Amazon EC2 Key Pair +AWS uses public-key cryptography to secure the login information for your instance. A Linux instance has no password; you use a key pair to log in to your instance securely. You specify the name of the key pair when you launch your instance, then provide the private key when you log in using SSH. +If you haven't created a key pair already, you can create one using the Amazon EC2 console. Note that if you plan to launch instances in multiple regions, you'll need to create a key pair in each region. + +1. Sign in to AWS +2. From the AWS dashboard, choose **EC2** to open the Amazon EC2 console. +3. From the navigation bar, select a region for the key pair. You can select any region that's available to you, regardless of your location. However, key pairs are specific to a region; for example, if you plan to launch an instance in the US East (Ohio) Region, you must create a key pair for the instance in the US East (Ohio) Region. +4. In the navigation pane, under **NETWORK & SECURITY**, choose **Key Pairs**. +![Key_Pairs_01](./images/Key_Pairs_01.png) +5. Choose **Create Key Pair**. +6. Enter a name for the new key pair in the **Key pair name** field of the **Create Key Pair** dialog box, and then choose **Create**. Use a name that is easy for you to remember, such as your IAM user name, followed by -key-pair, plus the region name. For example, me-key-pair-useast2. +![Key_Pairs_02](./images/Key_Pairs_02.png) +7. The private key file is automatically downloaded by your browser. The base file name is the name you specified as the name of your key pair, and the file name extension is .pem. Save the private key file in a safe place. +8. If you are using an SSH client on a Mac or Linux computer to connect to your Linux instance, use the following command to set the permissions of your private key file so that only you can read it. If you do not set these permissions, then you cannot connect to your instance using this key pair. +``` +chmod 400 my-key-pair.pem +``` + +### EC2 instance limits + +**ICON Development Network** requires at least 7 EC2 instances. However, the default limit is 5 for each region, so you need to request extend EC2 instance limitation. You can request from the link below: + http://aws.amazon.com/contact-us/ec2-request + + + +## Steps of How-to + +### How to deploy on AWS + +1. Visit **AWS Marketplace** +https://console.aws.amazon.com/marketplace +![AWS Marketplace](./images/AWS_Marketplace.png) (LINK TO PICTURE IS BROKEN) +2. Search by keyword "ICON Development Network" or visit the URL below. Then, click **Continue to Subscribe** +https://aws.amazon.com/marketplace/pp/B07KBTZHZD?ref_=aws-mp-console-subscription-detail +![ICON Development Network](./images/ICON_Development_Network.png) +3. Click **Continue to Configuration** +![ICON Development Network2](./images/ICON_Development_Network_02.png) +4. Select options (must select a specific region that you want to deploy). Then, click **Continue to Launch** + - Fulfillment Option: Leave as default. + - Software Version: Leave as default. It will provide the latest stable version. + - Region: **(Required)** Please select a region to setup. +![ICON Development Network3](./images/ICON_Development_Network_03.png) +5. From **Choose Action**'s drop downmenu, select **Launch CloudFormation** and click **Launch** +![ICON Development Network5](./images/ICON_Development_Network_05.png) +![ICON Development Network6](./images/ICON_Development_Network_06.png) +6. The "CloudFormation" screen appears. Select **Next** +![AWS Cloudformation_01](./images/AWS_Cloudformation_01.png) +7. Step "Specify Details" + - Stack Name: **(Required)** Any stack name (must contain only letters, numbers, dashes and start with an alpha character) + - Instance Type: ICON EC2 instance type (t2.xlarge, m5.large, m5.xlarge, m5.2xlarge,c5.large, c5.xlarge). Default value is **m5.xlarge** + - Node Count: ICON Node Cluster size; must be between 4 and 12. Default value is **4**. + - InstanceName: EC2 Instance Name Prefix. Default value is **"ICON"**. + - VpcId: **(Required)** VpcId of your existing Virtual Private Cloud (VPC). Select any drop-down menu item. + - SubnetID: **(Required)** Subnet should be a public subnet. Select largest Subnet id (for example, \*.\*.0.0/32) + - Fee: Pay commission to execute the transaction by ICX or not. Default value is **false** + - Audit: Prevent to deploy SCORE by anybody or not. Default value is **false** + - KeyName: **(Required)** Name of an existing EC2 KeyPair to enable SSH access to the instance. You must select EC2 Keypair. You must make sure to create a "Keypair" before this setup process. + - SSHLocation: **(Required)** The IP address range that can be used to SSH to the EC2 instances. The setting with no limitation is "0.0.0.0/0". +![AWS Cloudformation_02](./images/AWS_Cloudformation_02.png) +8. Step "Options". Leave as default. Select **Next** +![AWS Cloudformation_03](./images/AWS_Cloudformation_03.png) +9. Step "Review". Select **Create** +![AWS Cloudformation_04](./images/AWS_Cloudformation_04.png) +10. The setup process is over. Just need to check the **Events** tab below. +![AWS Cloudformation_05](./images/AWS_Cloudformation_05.png) +11. After the network has been deployed successfully using the CloudFormation, you can get information for **ICON Development Network** from the **Outputs** tab. +![AWS Cloudformation_06](./images/AWS_Cloudformation_06.png) +12. From **Outputs**, select "LoopChainRadioGroupCheckURL" for peers status. + - "http://:9002/api/v1/peer/list", you can check the information of connected nodes. +![LoopChainRadioGroupCheckURL](./images/LoopChainRadioGroupCheckURL.png) + + +### EC2 instance connect & navigate +If you want to access each EC2 instance, you need public IP address of each EC2 Instance and private key selected during the CloudFormation process. +Get each EC2 instance Public IP address(**Peer\*PublicIP**. For Example, Peer1 PublicIP) information from Previous **Outputs**. + +``` +$ ssh -i yourkey.pem ec2-user@ +``` +You can see various configuration files and start.sh and stop.sh files in ec2-user's home directory. +``` +$ ls -l +total 8 +drwxrwxr-x 3 ec2-user ec2-user 194 Jan 3 01:54 conf +drwxrwxr-x 5 ec2-user ec2-user 43 Aug 10 01:18 elasticsearch +drwxrwxr-x 2 ec2-user ec2-user 25 Aug 10 01:33 fluentd_conf +drwxr-xr-x 3 root root 56 Oct 4 03:40 iconscore +drwxr-xr-x 3 root root 22 Oct 4 03:40 iconstate +drwxrwxr-x 3 ec2-user ec2-user 20 Aug 9 07:44 kibana +drwxrwxrwx 4 ec2-user ec2-user 55 Aug 9 08:06 log +drwxr-xr-x 2 root root 6 Oct 4 03:40 score +drwxrwxr-x 6 ec2-user ec2-user 79 Aug 21 05:08 scripts +-rwxrwxrwx 1 ec2-user ec2-user 268 Jan 3 01:54 start.sh +-rwxrwxrwx 1 ec2-user ec2-user 267 Jan 3 01:54 stop.sh +drwxr-xr-x 6 root root 124 Jan 3 01:55 storage +drwxr-xr-x 2 root root 6 Oct 4 03:21 storageRS +``` + +ICON's services use [Docker Compose](https://docs.docker.com/compose/ "Docker Compose"). You can check the current containers as follows. +``` +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +e144b9d76a6a 13.124.90.83:5000/loop-v1.2-rel/iconrpcserver:1810030300xbb2b02 "/bin/sh -c 'exec /e…" 22 minutes ago Up 22 minutes peer_loop_rpc1_1 +d2222b5f47ce 13.124.90.83:5000/loop-v1.2-rel/iconservice:1810030300xbb2b02 "/bin/sh -c 'exec /e…" 22 minutes ago Up 22 minutes peer_loop_iconservice1_1 +ec291c7b45c6 13.124.90.83:5000/loop-v1.2-rel/loop_queue:1810030300xbb2b02 "docker-entrypoint.s…" 22 minutes ago Up 22 minutes peer_loop_queue_1 +ab16726c94c6 13.124.90.83:5000/loop-v1.2-rel/loop_peer:1810030300xbb2b02 "/bin/sh -c 'exec /e…" 22 minutes ago Up 22 minutes peer_loop_peer1_1 + +``` +You can stop the services of the currently connected node and restart it by using stop.sh and start.sh. +``` +$ ./stop.sh +Stopping peer_loop_rpc1_1 ... done +Stopping peer_loop_iconservice1_1 ... done +Stopping peer_loop_queue_1 ... done +Stopping peer_loop_peer1_1 ... done +``` + +``` +$ ./start.sh +Starting peer_loop_iconservice1_1 ... done +Starting peer_loop_queue_1 ... done +Starting peer_loop_rpc1_1 ... done +Starting peer_loop_peer1_1 ... done + +``` + +### Distributing Smart Contract on Reliable Environment (SCORE) using T-bears + +T-bears is an ICON SCORE development suite. +The github address is: +https://github.com/icon-project/t-bears + +#### Step 1: Installation +Install the T-bears by referring to the following link: +https://github.com/icon-project/t-bears#installation + +#### Step 2: Block search & SCORE deploy + +T-bears can build an environment that can be deployed in a local SCORE without using the AWS-generated Development Network. See Github for details. + +We have already setup ICON Development Network with CloudFormation, we will deal with block search, Send Transaction & Get Transaction Result and SCORE distribution using this network. + +##### Block search +Block lookup is possible without any other setting. Use the address of the LoopChainPeer. + +###### lastblock +Retrieves the information of the last block in the current blockchain. +``` +$ tbears lastblock -u http://:9000/api/v3 +block info : { + "jsonrpc": "2.0", + "result": { + "version": "0.1a", + "prev_block_hash": "", + "merkle_tree_root_hash": "72722dad5bdb0adff8f5fbb061de07a2404b522d463b708d1a62071262616fb3", + "time_stamp": 0, + "confirmed_transaction_list": [ + { + "nid": "0x3", + "accounts": [ + { + "name": "god", + "address": "hx5a05b58a25a1e5ea0f1d5715e1f655dffc1fb30a", + "balance": "0x2961ffa20dd47f5c4700000" + }, + { + "name": "treasury", + "address": "hxd5775948cb745525d28ec8c1f0c84d73b38c78d4", + "balance": "0x0" + }, + { + "name": "test1", + "address": "hx670e692ffd3d5587c36c3a9d8442f6d2a8fcc795", + "balance": "0x2961ffa20dd47f5c4700000" + } + ], + "message": "ICONLOOP" + } + ], + "block_hash": "b3c99e161f8013b7dabc2ff8be56bacb3209853d139bb54f0a37384388a36505", + "height": 0, + "peer_id": "", + "signature": "" + }, + "id": 1 +} +``` + +###### blockbyheight +Set the height value of the block and get the information of the matching block. +``` +$ tbears blockbyheight -u http://:9000/api/v3 0 +block info : { + "jsonrpc": "2.0", + "result": { + "version": "0.1a", + "prev_block_hash": "", + "merkle_tree_root_hash": "72722dad5bdb0adff8f5fbb061de07a2404b522d463b708d1a62071262616fb3", + "time_stamp": 0, + "confirmed_transaction_list": [ + { + "nid": "0x3", + "accounts": [ + { + "name": "god", + "address": "hx5a05b58a25a1e5ea0f1d5715e1f655dffc1fb30a", + "balance": "0x2961ffa20dd47f5c4700000" + }, + { + "name": "treasury", + "address": "hxd5775948cb745525d28ec8c1f0c84d73b38c78d4", + "balance": "0x0" + }, + { + "name": "test1", + "address": "hx670e692ffd3d5587c36c3a9d8442f6d2a8fcc795", + "balance": "0x2961ffa20dd47f5c4700000" + } + ], + "message": "ICONLOOP" + } + ], + "block_hash": "b3c99e161f8013b7dabc2ff8be56bacb3209853d139bb54f0a37384388a36505", + "height": 0, + "peer_id": "", + "signature": "" + }, + "id": 1 +} +``` + +###### Send Transaction & Get Transaction Result +Keystore is needed when sending a transaction or when deploying a SCORE onto the network. You can generate a keystore file using T-Bears CLI. +First, create a keystore. +``` +$ tbears keystore +Input your keystore password: +Retype your keystore password: +Made keystore file successfully +``` + +When you open the keystore that you just created, you can see that the first keystore address is created in the address field. +``` +$ cat +{"address": "hx4d1042e98770dcbab06ae4b55d09b1215e6d3af8", "crypto": {"cipher": "aes-128-ctr", "cipherparams": {"iv": "2621384865fceeb2988767c64dfe274e"}, "ciphertext": "5505c45ff3dce6742aa4f1630ffbc154b090176716e06942ec67f9bd1549e48b", "kdf": "scrypt", "kdfparams": {"dklen": 32, "n": 16384, "r": 1, "p": 8, "salt": "716a3d1ea83d6e540caeba473bea155d"}, "mac": "a88bc55b881f8b6c74b18b2d73d153bea8d5e178b3d54ae0f500be5e627c0cf1"}, "id": "e1939d52-617e-4a18-96c0-aec1b1cdfbc1", "version": 3, "coinType": "icx"} +``` + +Before sending the transaction. You need to create a send.json file that file contains "from" and "to" information. "from" is the send address and "to" is the receive address (you can also use the address of the genesis block that you viewed with the lastblock or blockbyheight, since it is not a commission function because it is a development network). +``` +$ vi send.json +{ + "jsonrpc": "2.0", + "method": "icx_sendTransaction", + "params": { + "version": "0x3", + "from": "hx670e692ffd3d5587c36c3a9d8442f6d2a8fcc795", + "value": "0x0", + "stepLimit": "0x3000000", + "nid": "0x3", + "nonce": "0x1", + "to": "hx4d1042e98770dcbab06ae4b55d09b1215e6d3af8", + "dataType": "call", + "data": { + "method": "setValue", + "params": { + "value": "0x123" + } + } + }, + "id": 1 +} +``` +Now, let's send a Transaction. +``` +$ tbears sendtx -k -u http://:9000/api/v3 send.json +Input your keystore password: +Send transaction request successfully. +transaction hash: 0x2797cd29bd4f56ac82a732cd88d5269ed16739526dd37ccbdd23159c3610a464 +``` + +The confirmation of the sent transaction can be done as follows. +``` +$ tbears txresult -u http://:9000/api/v3 0x2797cd29bd4f56ac82a732cd88d5269ed16739526dd37ccbdd23159c3610a464 +Transaction result: { + "jsonrpc": "2.0", + "result": { + "txHash": "0x2797cd29bd4f56ac82a732cd88d5269ed16739526dd37ccbdd23159c3610a464", + "blockHeight": "0x3", + "blockHash": "0x9317c73b58a1d2d7838b4b7a40d164bc138c51eacbdaf3198d856b830a8a721f", + "txIndex": "0x0", + "to": "hx4d1042e98770dcbab06ae4b55d09b1215e6d3af8", + "stepUsed": "0xf4a10", + "stepPrice": "0x0", + "cumulativeStepUsed": "0xf4a10", + "eventLogs": [], + "logsBloom": "0x0000000000........0000000000", + "status": "0x1" + }, + "id": 1 +} +``` + +###### SCORE (Smart Contract on Reliable Environment) Deploy + +Now that you have a transaction send, let's deploy SCORE. +In T-bears, you can create a basic SCORE. Let's create a SCORE named ABCToken. +``` +(work) $ tbears init abc ABCToken +(work) $ ls abc +__init__.py abc.py package.json tests +``` +SCORE called ABCToken was created in the abc folder. Now distribute SCORE to the generated Develop Network. +``` +$ tbears deploy -u http://:9000/api/v3 -k abc +Input your keystore password: +Send deploy request successfully. +If you want to check SCORE deployed successfully, execute txresult command +transaction hash: 0x247ae6cfd8d321420dc93e94d56bdb9e30d8a4c194141f7876ae63f7f995a4db +``` +If "Send deploy request successfully" message appears, the distribution was successful. Now, let's check the SCORE address using txresult again with the resulting transaction hash value. + +``` +$ tbears txresult -u http://:9000/api/v3 0x247ae6cfd8d321420dc93e94d56bdb9e30d8a4c194141f7876ae63f7f995a4db +Transaction result: { + "jsonrpc": "2.0", + "result": { + "txHash": "0x247ae6cfd8d321420dc93e94d56bdb9e30d8a4c194141f7876ae63f7f995a4db", + "blockHeight": "0x4", + "blockHash": "0x6909b8bf9e280ef6f0b059850cd8c42078eeda96825ed38557e9ce74712c2cd4", + "txIndex": "0x0", + "to": "cx0000000000000000000000000000000000000000", + "scoreAddress": "cxe0b089a8b718037c537f877aff52ddb55724df21", + "stepUsed": "0x12eadf0", + "stepPrice": "0x0", + "cumulativeStepUsed": "0x12eadf0", + "eventLogs": [], + "logsBloom": "0x0000000000........0000000000", + "status": "0x1" + }, + "id": 1 +} +``` +The scoreAddress value from txresult is the address of the ABCToken that was released earlier. In this example, we can see that it is cxe0b089a8b718037c537f877aff52ddb55724df21. +Now, to check this SCORE API, we check the API of SCORE deployed using scoreapi. +``` +$ tbears scoreapi -u http://:9000/api/v3 cxe0b089a8b718037c537f877aff52ddb55724df21 +SCORE API: [ + { + "type": "fallback", + "name": "fallback", + "inputs": [] + }, + { + "type": "function", + "name": "hello", + "inputs": [], + "outputs": [ + { + "type": "str" + } + ], + "readonly": "0x1" + } +] +``` + +You can check the **hello** method of SCORE's API and call it. +First, create a config file called **call.json** and write it like this: + +``` +$ vi call.json +{ + "jsonrpc": "2.0", + "method": "icx_call", + "params": { + "from": "hx4d1042e98770dcbab06ae4b55d09b1215e6d3af8", + "to": "cxe0b089a8b718037c537f877aff52ddb55724df21", + "dataType": "call", + "data": { + "method": "hello" + } + }, + "id": 1 +} +``` + +"from" is the address of the previously created key, and "to" is the address of the previously SCORE deployed. +The method in the data section means that we will look up the hello method that we just looked up. +Let's call it using this file. +``` +$ tbears call -u http://:9000/api/v3 call.json +response : { + "jsonrpc": "2.0", + "result": "Hello", + "id": 1 +} +``` +If you get the above results, It is a success. + +## Extend the learning +Easy way to check **ICON Development Network** status. - Use Chrome extenstion program ([**POSTMAN**](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en)) + +From outputs. Get "LoopChainPeer\*CheckURL"(ex. LoopChainPeer1CheckURL. any LoopChainPeer\*CheckURL) information. +ex) http://ec2-54-180-148-115.ap-northeast-2.compute.amazonaws.com:9000/api/v3 +Send below JSON message to LoopchainPeer1CheckURL(POST method) + +``` +{ + "jsonrpc": "2.0", + "method": "icx_getLastBlock", + "id": 1234 +} +``` + +If you receive the following response, "ICON Development Network" status is normal. +![Postman](./images/Postman.png) + +## Summarize the learning +Congratulations on setting up your ICON Development Network on AWS! + +## Tips or FAQs + + + + + +## References + +**ICON JSON-RPC API v3** +https://github.com/icon-project/icon-rpc-server/blob/master/docs/icon-json-rpc-v3.md + +**Amazon EC2 Key Pairs** +https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html + +**Amazon EC2 Service Limits** +https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-resource-limits.html + + + +## Document History + + +Version | writer | Date +------------ | ------------- +v0.9 | Donghan Lee(Donghan.lee@icon.foundation) | 20th Feb 2019 + | | + + + + + diff --git a/icon-key-concepts/accounts.md b/icon-key-concepts/accounts.md new file mode 100644 index 0000000..58891c6 --- /dev/null +++ b/icon-key-concepts/accounts.md @@ -0,0 +1,26 @@ +--- +title: "Accounts" +excerpt: "" +--- + +## Account +Accounts represent identities of participants in the blockchain network, that is, users and contracts. Accounts are used to identify the owner of transactions and specify the destinations of transactions. All accounts can have an ICX balance. + +There are two types of accounts in ICON, accounts that are associated with users, often dubbed as Externally Owned Accounts (EOA), and Smart Contract (SCORE) Accounts. An EOA address starts with "hx" followed by a 20-byte hex string, while a Smart Contract Account address starts with "cx" followed by a 20-byte hex string. + +EOA has an associated private key, can sign and send a transaction, therefore can be the owner of transactions. However, a contract address does not have a private key, and cannot initiate a transaction. A contract address can only be the destination of transactions. + +There are some special, pre-defined accounts, such as: + - Governance contract + - Public Treasury + +In order to deploy a SCORE on the ICON network or make a transaction, one must hold a valid EOA. Furthermore, when we say account in this document, it means EOA. The terms of EOA, wallet, and keystore are not exactly the same, but are often used interchangeably. + +An account is cryptographically defined by a private-public key pair, and the account address can be derived from its public key by taking the last 20-bytes of the SHA3-256 hash of the public key. Creating an account is equivalent to creating a key pair, and the account can be exported as a file known as a keystore file. + +## Keystore file +A keystore file is a JSON text file containing your private key and address. The private key is encrypted with the password that you enter when you create an account or keystore file. If you lose your keystore file and password, there is no way to recover them. You will lose your account and the assets you own. + +A keystore file is used to authenticate a user. Every transaction must be signed with your private key. If your private key is leaked, anyone possessing the private key can access your account and sign the transaction on your behalf. Therefore, it is always recommended to use a keystore file instead of a plain private key. + + diff --git a/icon-key-concepts/parallel-processing.md b/icon-key-concepts/parallel-processing.md new file mode 100644 index 0000000..64401cb --- /dev/null +++ b/icon-key-concepts/parallel-processing.md @@ -0,0 +1,65 @@ +--- +title: "Parallel Processing" +excerpt: "Executing transactions in parallel" +--- + +Various factors affect blockchain performance. One of the major factors is the **execution time** of transactions. In this article, we illustrate our R&D approach to increase blockchain performance by reducing the transaction execution time. + +## Transaction Execution Time +Transactions Per Second (TPS) is the number of transactions that a network can process in a single second. TPS is a key metric of blockchain performance. +A transaction is measured from the submission to the network until it is included in the block. In ICON, the number of transactions included in a block are always guaranteed to be executed within one block generation time, so it is a good representation of transaction throughput and it is proportional to the TPS. + +TPS is mainly affected by following factors. +* Travel time of a transaction to the consensus node +* Communication time among consensus nodes +* Execution time of the transaction + +Travel and communication times are network bound, and there have been continuous attempts to optimize the network protocol in blockchain. Further optimizing the network protocol is not trivial as it involves the risk of breaking the liveness and safety properties of the blockchain network. +On the other hand, reducing the execution time has not been touched yet. If we can reduce the transaction execution time, we can improve the performance of a blockchain without risking network stability. + +## Parallel Execution + +The most straightforward approach to reduce transaction execution time is using stronger computing power. This is called scale-up or vertical scaling. However, increasing computing power is expensive and has physical limitations. Instead, in modern computing, a more common approach is increasing overall throughput with the parallel execution using multiple cores. + +That said, in blockchain, sequential execution of transactions has been the norm, because a blockchain network represents a world state - a collection of accounts and their states, and every consensus node must agree on the state change after a transaction. Since previous transactions can affect the execution of the current transaction, it is safer to execute transactions sequentially. + +On closer look, however, some transactions are disjoint or independent, meaning that they do not write on the same state variables during their execution. These independent transactions can be executed in parallel without any conflict with other transactions. In the subsequent sections, we will explain in more detail how this can be implemented in two different cases. + + +### Coin transfer + +Coin transfer can change the balance of at most three accounts at a time: 1) sender, 2) receiver, and 3) treasury accounts. +A treasury is a special account for deposit, and we can process all the deposit requests to the treasury in bulk after executing other transactions. Therefore, only two accounts (sender and receiver) are execution-order sensitive. + +Let's take a look at an example of the following transactions in a block in the order of submission. + +1) Transfer A to B: 100 +2) Transfer C to D: 100 +3) Transfer B to C: 100 + +Let T be the execution time for each coin transfer. +In sequential processing, total execution time is T x 3. +However, if we execute (1) and (2) in parallel, it takes T x 2. We know we can execute (1) and (2) at the same time, because they do not access the same accounts. + +![Parallel simple transfer](parallel-processing-1.png) + +We examined that if we can execute independent transactions in parallel, the total execution time of the transactions in a block can be effectively reduced. +The same approach can be applied to smart contract execution. + + +### Smart contract + +A transaction sent to a smart contract (SCORE) is a method call. +SCORE may change the state of any account, because it can make a call to other SCORE. In general, methods of SCORE need a write-permission to all accounts. +However, each specific method requires limited permission to the accounts. Thus, if we have extra information about which accounts the method needs an access, we can identify independent SCORE methods and execute them in parallel. + +With the extra information about the method, we can create a virtual world state (a partial view of the world) for each transaction. +The transaction can only change the world state when the method is designated to do so. Otherwise, any attempt to change the world state beyond its permission will result in a failed transaction. + +The diagram below illustrates how the parallel execution of two transactions are managed. + +![Parallel execution environment](parallel-processing-2.png) + +After executing transactions, each environment releases the locked accounts, then other transactions can create their own execution environments with the required accounts being locked. + +To enable parallel processing, SCORE methods should be annotated with the required accounts. Careful design, such as splitting database and code, will enhance the parallelism. diff --git a/icon-key-concepts/transactions.md b/icon-key-concepts/transactions.md new file mode 100644 index 0000000..f3ca078 --- /dev/null +++ b/icon-key-concepts/transactions.md @@ -0,0 +1,78 @@ +--- +title: "Transactions" +--- + +This article provides a basic understanding of what a transaction is in ICON. It defines what a transaction is and then describes its functionalities and specifications. + +## Transaction + +### Definition + +A “transaction” in ICON refers to a "signed" data package which is used for changing the states of a blockchain (e.g. deploying SCORE, ICX coin transfer, etc). A transaction always has to involve signature data. + +"States of a blockchain" refers to all states of accounts (e.g. EOA, SCORE accounts, etc.) which are recorded on the blockchain. + +### Purpose of Signature + +- A signature prevents transaction data from forgery or falsification. For example, if transaction data is falsified during propagation, the expected valid signature data also change. As no one can generate the valid signature except the owner of the account that generated the transaction, this transaction will fail during verification due to having an incorrect signature. +- A signature guarantees that the transaction data has been generated by the owner of the appropriate account. + +### Function of Transaction + +- ICX Coin transfer +- Record message(s) on the blockchain +- Deploy or update SCOREs +- Change SCORE's states + +### Data Model of Transaction + +The table below shows the data model of a transaction and the description of each component. + +| Component | **Description** | +| ---------------- | ------------------------------------------------------------ | +| from | EOA address that created the transaction. | +| to | EOA or SCORE address that receives ICX coins, or SCORE address that executes the transactions. When deploying a SCORE, "to" address is a zero SCORE address (i.e. `cx0000000000000000000000000000000000000000`) | +| value | Amount of ICX coins to be transferred. | +| step limit | The maximum amount of step that will be consumed when executing the transaction. Users can set this amount, and if the entire amount of step a user has set is consumed while executing the transaction, this transaction will fail. | +| time stamp | Transaction creation time. An outdated time will be rejected when validating the transaction. If you use the same time stamp when creating a transaction, that transaction can be rejected as the same transaction hash can be created (see the transaction hash description below). | +| nonce | An arbitrary number used to prevent transaction hash collision (optional). | +| nid | ICON network ID. Each ICON network has different rules and configurations (e.g. governance rules, fee policies, etc.), so even if you try to request the same transaction with the same state of the account, the result of the transaction can be different according to the network. | +| data type | Type of data for executing transaction. When executing a transaction, additional data may be required depending on the purpose of the transaction. For example, when you call a SCORE method, you have to specify which method you want to call, arguments of the method, etc. Depending on the purpose, there are three types: `call`, `deploy`, and `message`. In the case of a simple coin transfer, the data type is omitted because there is no need for additional data.
`call`: used when calling a function in SCORE
`deploy`: used when installing or updating a SCORE
`message`: used when transferring a message | +| data | The detailed content of the transaction. It varies depending on the data type. The maximum size of data is 512 KB. | +| signature | The signature generated by the transaction sender. Generate transaction signature using above data (from, to, value, etc). After generating the signature, if any of the above data is changed, it must be regenerated. The specifics of generating a transaction signature is defined in [How to Generate Transaction Signature](https://github.com/icon-project/documentation/blob/develop/howto/how-to-generate-a-transaction-signature.md). | +| transaction hash | Hash data returned after passing the validation process of the transaction (see the Life Cycle of Transaction's "Create Transaction" section below). Each transaction has a unique transaction hash. | + +For specific information on transaction data, see the JSON-RPC APIs "icx_sendTransaction" section of the [ICON JSON-RPC API v3 Specification](https://github.com/icon-project/documentation/blob/develop/references/json-rpc/icon-json-rpc-v3.md) documentation. + +### Life Cycle of Transaction + +![life_cycle_of_transaction](transactions-1.png) + +#### Create Transaction + +Create and propagate a transaction to the ICON network. Propagated transactions proceed with basic syntax and signature validation, and is put into the transaction pool to be recorded to a block if they are valid. At the same time, the ICON network returns the transaction hash data. If a transaction is invalid, that transaction is immediately rejected and the ICON network returns an error instead of a transaction hash. The word "rejected" refers to the transaction being removed because it can not be propagated on the ICON network. + +#### Transaction Pool + +In this stage, a transaction is waiting before being put into the block. + +#### Block Generation + +In this stage, a transaction is put into a generated block. If consensus is reached regarding the generated block (after the consensus process), that block is connected to the blockchain, and the transactions in the block are recorded permanently. If the consensus on the block fails, all transactions in that block are removed after a certain period of time. The word "removed" refers to ceasing to exist on the ICON network entirely. Therefore, the user who created and propagated the transaction needs to track the transaction until it is recorded on the blockchain (i.e. confirmed). + +#### Confirmed + +The block which contains a transaction is connected to the blockchain after the consensus process. This state of the transaction is called "confirmed". A transaction in a confirmed block is recorded permanently regardless of the transaction processing result (success or failure). + +### How to Check Transaction State + +#### Check the Transaction Validation + +If you get the transaction hash as a response to sending a transaction to the ICON network, this means that your transaction has passed the validation. ICON network returns the transaction hash only when a transaction is valid. For specific information about this process, see the JSON-RPC APIs "icx_sendTransaction" section of the [ICON JSON-RPC API v3 Specification] documentation. + +#### Check the Transaction Confirmation + +You can check if a transaction is confirmed or pending using "icx_getTransactionResult" JSON-RPC API. "Pending" means that a transaction is in the transaction pool or block generation stage (except in the case of consensus failure on the block, it can be temporarily marked as "pending"). For specific information about this process, see the JSON-RPC APIs "icx_getTransactionResult" section of the [ICON JSON-RPC API v3 Specification] documentation. + + +[ICON JSON-RPC API v3 Specification]: json-rpc-specification diff --git a/introduction/about-this-guide.md b/introduction/about-this-guide.md new file mode 100644 index 0000000..a71edb4 --- /dev/null +++ b/introduction/about-this-guide.md @@ -0,0 +1,91 @@ +--- +title: "About this Guide" +excerpt: "" +--- +This guide is ICON's primary developer documentation and answers the questions that most developers have when learning to develop on ICON. You will find step-by-step instructions, examples, guidelines, and a comprehensive reference. This guide is continually updated with new topics, edits to existing material, and improvements in how the material is presented. After learning the basics on ICON, you can use this guide as a springboard into more advanced topics. + +How to use this guide : + +- Are you curious why ICON matters? Start with [Introduction](#introduction). +- Do you want to develop a Smart Contract? Go to [SCORE](#score). +- DApp developers, you will definitely need to interact with your Smart Contract and send transactions to the ICON network from your DApp. Read [ICON SDKs](#icon-sdks). ICON wallet (ICONex) also exposes a couple of useful APIs to sign your transaction on your behalf. [ICONex Connect](#iconex-connect) is for that. +- Interested in being a P-Rep? Everything about operating a P-Rep node is here, [Running an ICON Node](#running-an-icon-node). +- Curious about ICONLOOP's enterprise solution? [Enterprise Solution - loopchain](#enterprise-solution---loopchain) +- [References](#references) - Want to go deeper? A comprehensive collection of how-to guides, protocol specifications, design specifications, and user manuals. + +## Documentation Structure + +The ICON technical documentation is organized as follows. + +### Introduction + +If you are new to ICON, this is a good starting point. You will learn the motivation and the design goals of the ICON project. We will convince you why ICON is technically different from other blockchain networks. + +- **What is ICON** +- **ICON Key Concepts**: Account, transaction, transaction fees, different types of ICON nodes, parallel processing, P-Rep election, ICON incentive scoring system, and the interchain protocol are explained here. +- **The ICON Network**: Will show how the ICON network is logically structured across the world. + +### ICON Application Services + +No platform is complete without supporting services. + +- **ICONest**: Token creation and Crowdsale platform. +- **ICONex**: ICONex is the official ICON wallet application. Chrome, Android, and iOS applications are available. +- **Tracker**: ICON block and transaction explorer. +- **ICON ID**: Decentralized ID on the blockchain. +- **User Manuals**: Reference manuals for detailed functions of the above applications. + +### SCORE + +This is where the fun begins. Smart Contracts are the core building blocks of every blockchain application. In this section, you will get everything you need to know to write, test and deploy a Smart Contract (SCORE) on ICON. + +- **SCORE Quickstart**: No previous ICON knowledge or experience required. As long as you are a developer and proficient with Python, Docker, and Linux, following this guideline will lead you to deploy and run your first SCORE on the ICON testnet. +- **SCORE Development Guide**: All the SCORE development tools and syntax are explained here. +- **SCORE Audit**: Please make sure you comprehend the audit checklist. This is the SCORE coding patterns that the platform mandates. +- **Sample SCOREs**: Reference implementation and explanation. + +### T-Bears + +T-Bears is a SCORE development suite. In order to write a Smart Contract on ICON, you need to install T-Bears first. T-Bears installs the `iconservice` python package which is required to write a SCORE, CLI tools to create, run, test, and deploy a SCORE, and the emulated node environment that runs on your local machine. + +### ICON SDKs + +ICON SDK is a library that implements the JSON-RPC v3 protocol to interact with the ICON nodes and execute the SCORE functions. ICON officially supports Java, Python, JavaScript, and Swift. + +### ICONex Connect + +ICONex Connect is a protocol that signs and sends a transaction on behalf of an application. The ICONex app will prompt the user to enter a password. + +### Running an ICON node + +- **P-Rep**: If you are a P-Rep or a P-Rep candidate, please read this section. This section contains all the guidelines from node installation to troubleshooting. +- **Citizen Node**: Sometimes you need to run your own citizen node for various reasons, e.g. security or performance. This section explains the installation and configuration of the citizen node. + +### Enterprise Solution - loopchain + +We will briefly introduce loopchain, ICONLOOP's enterprise blockchain solution. Inter-connecting ICON mainnet with the private loopchain networks is one of ICON's big milestones. The loopchain engine contains all the technical components of ICON with the addition of enterprise-specific features. + +### References + +- **How-to** : How-to guidelines to achieve frequently-questioned tasks. +- **Reference Manuals** : References and technical specifications. +- **User Manuals** : ICON applications' user manuals + +
+ +Besides technical documentation, the ICON Developers Portal includes the following resources: +## Announcement + +Developer-related news such as workshops, meetups, ICON's key milestones, and new specification proposals will be announced here. + +## Forum + +A code-level discussion forum. We hope the ICON developer community will grow. You don't need to sign up to post a question or share an idea, and your email is not visible to the public. Please be respectful to the community. Any irrelevant or offensive posts can be removed by the forum moderators without notice. + +## Support + +Various channels where you can send your feedback, report a bug, and speak to the ICON team. + +## Resources + +Tutorials, presentation decks, and community developed tools.