diff --git a/docs/api/http.md b/docs/api/http.md index 457c56704..196c1895f 100644 --- a/docs/api/http.md +++ b/docs/api/http.md @@ -8,7 +8,10 @@ 请务必为来自 API 的所有数据实施 XSS 防护，以确保用户数据的安全。我们了解您可能需要有关 XSS 防护的更多信息。建议您参考以下资源：[OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)。 -首先，对HTTP API中地址格式的选择进行说明：TRON网络账户地址格式有两种：HexString格式和Base58格式。节点HTTP API支持地址格式选择，用户可以通过visible参数设置地址格式，默认值为false，参数及返回值中的地址格式均为hex格式，当visible设置为true时，参数及返回值中的地址格式均为Base58格式。如果参数格式与visible设置不匹配，将会报错。设置方式： +首先，对HTTP API中地址格式的选择进行说明：TRON网络账户地址格式有两种：HexString格式和Base58格式。 +像TronLink钱包地址`TUXAoxQ8PwFAtfQet7Akc8HaV5ciC6WkjY`就是Base58格式。可以使用[TranScan](https://nile.tronscan.org/#/tools/code-converter/base58check)工具方便格式之间的转换。 + +节点HTTP API支持地址格式选择，用户可以通过visible参数设置地址格式，默认值为false，参数及返回值中的地址格式均为hex格式，当visible设置为true时，参数及返回值中的地址格式均为Base58格式。如果参数格式与visible设置不匹配，将会报错。设置方式： - 对于GET方式请求接口或者不需要参数的查询接口，通过在url中增加参数`visible=true` ```text @@ -16,8 +19,9 @@ http://127.0.0.1:8090/wallet/listexchanges?visible=true ``` - 对于POST方式请求接口，通过在json结构体最外层中增加参数`"visible": true` ```json -curl -X POST http://127.0.0.1:8090/wallet/createtransaction -d -'{ +curl --location 'http://127.0.0.1:8090/wallet/createtransaction' \ +--header 'Content-Type: application/json' \ +--data '{ "owner_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", "to_address": "TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW", "amount": 1000000, @@ -63,16 +67,29 @@ FullNode HTTP API分类如下: #### wallet/validateaddress 作用：检查地址是否正确 ``` -curl -X POST http://127.0.0.1:8090/wallet/validateaddress -d '{"address": "4189139CB1387AF85E3D24E212A008AC974967E561"}' +curl -X POST http://127.0.0.1:8090/wallet/validateaddress +--header 'Content-Type: application/json' +-d '{"address": "4189139CB1387AF85E3D24E212A008AC974967E561"}' ``` 参数说明：地址，可以是base58checksum、hexString、base64格式 返回值：地址正确或者错误 +``` +{ + "result": true, + "message": "Hex string format" +} +``` #### wallet/createaccount 作用：创建账号，一个已经激活的账号创建一个新账号。如果创建者账号有足够的通过质押TRX获得的带宽，那么创建账户只会消耗带宽，否则，会烧掉0.1个TRX来支付带宽费用，同时需要额外支付 1 TRX的创建费用 ``` -curl -X POST http://127.0.0.1:8090/wallet/createaccount -d '{"owner_address":"41d1e7a6bc354106cb410e65ff8b181c600ff14292", "account_address": "41e552f6487585c2b58bc2c9bb4492bc1f17132cd0"}' +curl -X POST http://127.0.0.1:8090/wallet/createaccount +--header 'Content-Type: application/json' +-d '{ + "owner_address":"41d1e7a6bc354106cb410e65ff8b181c600ff14292", + "account_address": "41e552f6487585c2b58bc2c9bb4492bc1f17132cd0" + }' ``` 参数： @@ -85,7 +102,9 @@ curl -X POST http://127.0.0.1:8090/wallet/createaccount -d '{"owner_address":"4 #### wallet/getaccount 作用：查询一个账户的信息 ``` -curl -X POST http://127.0.0.1:8090/wallet/getaccount -d '{"address": "41E552F6487585C2B58BC2C9BB4492BC1F17132CD0"}' +curl -X POST http://127.0.0.1:8090/wallet/getaccount +--header 'Content-Type: application/json' +-d '{"address": "41E552F6487585C2B58BC2C9BB4492BC1F17132CD0"}' ``` 参数：`address` 账户地址 @@ -94,7 +113,12 @@ curl -X POST http://127.0.0.1:8090/wallet/getaccount -d '{"address": "41E552F64 #### wallet/updateaccount 作用：修改账号名称 ``` -curl -X POST http://127.0.0.1:8090/wallet/updateaccount -d '{"account_name": "0x7570646174654e616d6531353330383933343635353139" ,"owner_address":"41d1e7a6bc354106cb410e65ff8b181c600ff14292"}' +curl -X POST http://127.0.0.1:8090/wallet/updateaccount +--header 'Content-Type: application/json' +-d '{ +"account_name": "0x7570646174654e616d6531353330383933343635353139" , +"owner_address":"41d1e7a6bc354106cb410e65ff8b181c600ff14292" +}' ``` 参数： @@ -108,8 +132,9 @@ curl -X POST http://127.0.0.1:8090/wallet/updateaccount -d '{"account_name": "0 #### wallet/accountpermissionupdate 作用：修改账户权限 ``` -curl -X POST http://127.0.0.1:8090/wallet/accountpermissionupdate -d -'{ +curl -X POST http://127.0.0.1:8090/wallet/accountpermissionupdate +--header 'Content-Type: application/json' +-d '{ "owner_address": "TRGhNNfnmgLegT4zHNjEqDSADjgmnHvubJ", "owner": { "type": 0, @@ -343,7 +368,9 @@ curl -X POST http://127.0.0.1:8090/wallet/getapprovedlist -d '{ #### wallet/getaccountresource 作用：查询账户的资源信息 ``` -curl -X POST http://127.0.0.1:8090/wallet/getaccountresource -d {"address" : "419844f7600e018fd0d710e2145351d607b3316ce9"} +curl -X POST http://127.0.0.1:8090/wallet/getaccountresource +--header 'Content-Type: application/json' +-d {"address" : "419844f7600e018fd0d710e2145351d607b3316ce9"} ``` 参数： @@ -429,7 +456,7 @@ curl -X POST http://127.0.0.1:8090/wallet/freezebalancev2 -d }' ``` -参数： +参数： - `owner_address`: 质押TRX 账号的地址, HEX 格式或 Base58check 格式 - `frozen_balance`: 质押TRX 的数量, 单位为sun diff --git a/docs/architecture/event.md b/docs/architecture/event.md index d33a202bf..bf3f32588 100644 --- a/docs/architecture/event.md +++ b/docs/architecture/event.md @@ -7,7 +7,7 @@ TIP: [https://github.com/tronprotocol/TIPs/issues/12](https://github.com/tronprotocol/TIPs/issues/12) ### 事件类型 -波场事件订阅支持四种类型的事件： +当交易被打包进区块后，波场会对外发送四种类型的事件： - 交易相关事件 diff --git a/docs/clients/wallet-cli.md b/docs/clients/wallet-cli.md index c635f2304..8b98fd91c 100644 --- a/docs/clients/wallet-cli.md +++ b/docs/clients/wallet-cli.md @@ -1,6 +1,6 @@ # 什么是Wallet-Cli？ -Wallet-Cli是一个支持TRON网络的交互式命令行钱包，用于在安全的本地环境中签名和广播交易，也可以获取链上数据。Wallet-Cli支持密钥管理，您可以将私钥导入钱包中，Wallet-Cli会使用对称加密算法加密您的私钥，并存储到一个keystore文件中。Wallet-Cli本地不存储链上数据，它采用gRPC的方式与某一个Java-tron节点进行通信，您需要在配置文件中配置需要链接的Java-tron节点，下图是使用Wallet-Cli签名和广播TRX转账交易的流程： +Wallet-Cli是一个支持TRON网络的交互式命令行钱包，用于在安全的本地环境中签名和广播交易，也可以获取链上数据。Wallet-Cli支持密钥创建和管理，您可以将私钥导入钱包中，Wallet-Cli会使用对称加密算法加密您的私钥，并存储到一个keystore文件中。Wallet-Cli本地不存储链上数据，它采用gRPC的方式与某一个Java-tron节点进行通信，您需要在配置文件中配置需要链接的Java-tron节点，下图是使用Wallet-Cli签名和广播TRX转账交易的流程： ![](https://i.imgur.com/NRKmZmE.png) 用户首先运行`Login`命令解锁钱包，然后运行`SendCoin`命令发送TRX，Wallet-Cli会本地构建和签名交易，然后将调用Java-tron节点的BroadcastTransaction gRPC API将交易广播的网络中，广播成功后Java-tron节点会返回交易hash给Wallet-Cli，Wallet-Cli将交易hash展示给用户。 diff --git a/docs/getting_started/getting_started_with_javatron.md b/docs/getting_started/getting_started_with_javatron.md index 23823304f..c7f383421 100644 --- a/docs/getting_started/getting_started_with_javatron.md +++ b/docs/getting_started/getting_started_with_javatron.md @@ -5,11 +5,11 @@ 本文涵盖了使用Java-tron的基础，这包括生成帐户、加入TRON nile测试网络、在帐户之间发送TRX。文档中也使用了wallet-cli，wallet-cli是TRON网络的一个命令行工具，该工具提供用户交互式命令，使用它可以更方便的与Java-tron进行交互。 -Java-tron是用Java编写的TRON网络客户端，这意味着运行Java-tron的计算机会变成一个TRON网络节点。TRON网络是一个分布式网络，信息在节点之间共享，而不是由中央服务器管理。超级代表的节点在生成新的区块后，会将区块发送给其它节点。每个节点在接收到一个新的区块时，都会对其进行校验，校验通过后将其添加到自己的数据库中。Java-tron使用每个区块提供的信息来更新其“状态”——TRON网络上每个账户的余额。TRON网络上有两种类型的帐户:外部拥有的帐户和合约帐户。合约帐户在收到交易时执行合约代码。外部账户是用户在本地管理的帐户，以便签署和提交交易。每个外部账户都是一个公私密钥对，其中公钥用于为用户派生一个唯一的地址，而私钥用于保护帐户和安全签署消息。因此，为了使用TRON网络，首先需要生成外部账户(以下简称“帐户”)。本教程将指导用户如何创建一个帐户，存入TRX代币，并转账TRX。 +Java-tron是用Java编写的TRON网络客户端，这意味着运行Java-tron的计算机会变成一个TRON网络节点。TRON网络是一个分布式网络，信息在节点之间共享，而不是由中央服务器管理。超级代表的节点在生成新的区块后，会将区块发送给其它节点。每个节点在接收到一个新的区块时，都会对其进行校验，校验通过后将其添加到自己的数据库中。Java-tron使用每个区块提供的信息来更新其“状态”——TRON网络上每个账户的余额。TRON网络上有两种类型的帐户:外部拥有的帐户和合约帐户。合约帐户在收到交易时执行合约代码。外部账户是用户在本地管理的帐户，以便签署和提交交易，比如通过TronLink钱包创建的账户。每个外部账户都是一个公私密钥对，其中公钥用于为用户派生一个唯一的地址，而私钥用于保护帐户和安全签署消息。因此，为了使用TRON网络，首先需要生成外部账户(以下简称“帐户”)。本教程将指导用户如何创建一个帐户，存入TRX代币，并转账TRX。 # 生成账户 -有多种方法来生成TRON网络帐户，这里将演示如何使用wallet-cli生成帐户。帐户是一对密钥(公钥和私钥)。 +有多种方法来生成TRON网络帐户，这里将演示如何使用wallet-cli生成帐户, 参考[安装和部署](../clients/wallet-cli.md)章节。帐户是一对密钥(公钥和私钥)。 在终端中通过命令`java -jar wallet-cli.jar`来启动一个wallet-cli： ``` @@ -18,23 +18,23 @@ $ java -jar wallet-cli.jar Welcome to Tron Wallet-Cli Please type one of the following commands to proceed. Login, RegisterWallet or ImportWallet - + You may also use the Help command at anytime to display a full list of commands. - -wallet> + +wallet> ``` 输入命令：registerwallet，然后根据提示输入密码。该命令会生成TRON网络账户,并注册到wallet-cli，也就是wallet-cli会保存此账户的私钥，之后就可以使用该私钥对交易进行签名了。 ``` wallet> registerwallet Please input password. -password: +password: user defined config file doesn't exists, use default config file in jar WalletApi getRpcVsersion: 2 Please input password again. -password: +password: Register a wallet successful, keystore file name is UTC--2022-07-04T06-35-35.304000000Z--TQXjm2J8K2DKTV49MdfT2anjUehbU3WDJz.json -wallet> +wallet> ``` # 登录wallet-cli @@ -49,9 +49,9 @@ wallet> login Please choose between 1 and 3 2 Please input your password. -password: +password: Login successful !!! -wallet> +wallet> ``` 登录后，可以通过getaddress命令查看登录的账户地址： @@ -59,7 +59,7 @@ wallet> wallet> getaddress GetAddress successful !! address = TQXjm2J8K2DKTV49MdfT2anjUehbU3WDJz -wallet> +wallet> ``` 然后可以通过backupwallet命令，根据提示输入密码后，查看账户的私钥，建议保存好私钥。 @@ -92,14 +92,14 @@ Java-tron启动后，日志将包括以下内容： 11:08:42.567 INFO [TronJClientWorker-1] [DB](Manager.java:1642) solidBlockNumber:23113849 11:08:42.567 INFO [TronJClientWorker-1] [net](SyncService.java:179) Get block chain summary, low: 23113867, highNoFork: 23113867, high: 23113867, realHigh: 23113867 11:08:42.572 INFO [TronJClientWorker-1] [net](MessageQueue.java:106) Send to /123.56.3.74:18888, type: SYNC_BLOCK_CHAIN -size: 1, start block: Num:23113867,ID:000000000160b08b510b6c501c980a2567bff1229eed62ca79874c9ca7828e9c +size: 1, start block: Num:23113867,ID:000000000160b08b510b6c501c980a2567bff1229eed62ca79874c9ca7828e9c 11:08:42.631 INFO [TronJClientWorker-1] [net](MessageQueue.java:121) Receive from /123.56.3.74:18888, type: BLOCK_CHAIN_INVENTORY size: 2001, first blockId: Num:23113867,ID:000000000160b08b510b6c501c980a2567bff1229eed62ca79874c9ca7828e9c, end blockId: Num:23115867,ID:000000000160b85b587ef18d00a1905d8022ec0a8fd174f3980b78f6aacf0ede ...... 11:08:43.478 INFO [pool-49-thread-1] [net](MessageQueue.java:106) Send to /123.56.3.74:18888, type: FETCH_INV_DATA -invType: BLOCK, size: 100, First hash: 000000000160b08c6eeba60eced4fb13d7c56e46a3c5220a67bb2801a05e5679, End hash: 000000000160b0efd90560e389d1f6e5b3c8d3877709ce375a8e063f5db73af9 +invType: BLOCK, size: 100, First hash: 000000000160b08c6eeba60eced4fb13d7c56e46a3c5220a67bb2801a05e5679, End hash: 000000000160b0efd90560e389d1f6e5b3c8d3877709ce375a8e063f5db73af9 11:08:43.502 INFO [TronJClientWorker-1] [net](MessageQueue.java:121) Receive from /123.56.3.74:18888, type: BLOCK Num:23113868,ID:000000000160b08c6eeba60eced4fb13d7c56e46a3c5220a67bb2801a05e5679, trx size: 1 @@ -119,14 +119,16 @@ $ curl http://127.0.0.1:16887/wallet/getnodeinfo 如果要关闭Java-tron，请通过`kill -15 进程id`来暂停节点。 # 获取Nile测试网TRX -为了能够发送交易，用户的账户中需要持有TRX。在TRON网络主网上，只能通过三种方式获得TRX: -1. 超级代表生产区块/为超级代表投票的奖励; -2. 另一个TRON网络账户向其转账TRX; +为了能够发送交易，用户的账户中需要持有TRX。在TRON网络主网上，只能通过三种方式获得TRX: +1. 超级代表生产区块/为超级代表投票的奖励; +2. 另一个TRON网络账户向其转账TRX; 3. 从交易所获得。 在TRON测试网中，TRX没有实际价值, 可以通过 [水龙头](https://nileex.io/join/getJoinPage) 免费获得。 # 与Java-tron交互 +如果本地不便运行节点，或者节点要长时间同步数据才能获取最新的数据，可以使用TronGrid。TronGrid提供负载均衡的，安全的，可靠的的节点访问API，参考[TronGrid](../clients/tron-grid.md)。 +Nile测试网的TronGrid地址为 https://nile.trongrid.io。其他网络节点或者grpc连接参考[Networks](https://developers.tron.network/docs/networks)。 ## 使用wallet-cli与Java-tron节点进行交互 Java-tron对外提供http接口和grpc接口，方便用户与TRON网络进行交互。wallet-cli使用的是grpc接口。 @@ -148,7 +150,7 @@ wallet> getaccount TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM "account_resource": { "latest_consume_time_for_energy": 1655358327000 }, - + ...... } @@ -158,7 +160,7 @@ wallet> getaccount TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM ``` wallet> getbalance Balance = 93642857919 -wallet> +wallet> ``` ### 转账TRX @@ -202,11 +204,11 @@ The 3th keystore file name is UTC--2022-06-21T09-51-26.367000000Z--TUoHaVjx7n5xz Please choose between 1 and 3 3 Please input your password. -password: +password: after sign transaction hex string is 0a85010a02cbc322088581ae7e29258a5240dbfc91ca9c305a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541ce8a0cf0c16d48bcf22825f6053248df653c89ca121541d0b69631440f0a494bb51f7eee68ff5c593c00f018c0843d7098cfebbf9c301241241a3ce4797ccc2fedf49ae41af28b49df1e15a476e4948af4df5aadf23a1e940ad5cc2133f501c08f2bab6a2231cdc82a745fed0fc6a012dc19310532d9138600 txid is 21851bcf1faf22c99a7a49c4f246d709cf9f54db2f264ca145adcd464ea155a4 Send 1000000 Sun to TUznHJfHe6gdYY7gvWmf6bNZHuPHDZtowf successful !! -wallet> +wallet> ``` ### 根据交易id查询交易 @@ -245,7 +247,7 @@ wallet> gettransactionbyid 21851bcf1faf22c99a7a49c4f246d709cf9f54db2f264ca145adc }, "raw_data_hex":"0a02cbc322088581ae7e29258a5240dbfc91ca9c305a67080112630a2d747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5472616e73666572436f6e747261637412320a1541ce8a0cf0c16d48bcf22825f6053248df653c89ca121541d0b69631440f0a494bb51f7eee68ff5c593c00f018c0843d7098cfebbf9c30" } -wallet> +wallet> ``` @@ -262,26 +264,41 @@ wallet> gettransactioninfobyid 21851bcf1faf22c99a7a49c4f246d709cf9f54db2f264ca14 "net_usage": 267 } } -wallet> +wallet> ``` ## 使用Curl与Java-tron节点进行交互 -上文介绍了如何使用wallet-cli与Java-tron进行交互。与直接发送grpc/http命令相比，该工具提供更友好的交互式命令，使用户可以更方便的向Java-tron发送指令。但是，如何直接发送HTTP请求到Java-tron节点呢？ Curl是一个发送HTTP请求的命令行工具。本章节将说明如何通过Curl检查帐户余额，并发送交易。 +上文介绍了如何使用wallet-cli与Java-tron进行交互。与直接发送grpc/http命令相比，该工具提供更友好的交互式命令，使用户可以更方便的向Java-tron发送指令。但是，如何直接发送HTTP请求到Java-tron节点呢？ Curl是一个发送HTTP请求的命令行工具, 可以把curl命令复制到Postman工具里使用。本章节将说明如何通过Curl检查帐户余额，并发送交易。如果本地节点无法访问，请使用TranGrid API. ### 查询账户余额 -可以通过节点HTTP接口`wallet/getaccount`来查询账户的TRX余额信息，返回结果中的balance即为TRX余额，以sun为单位： +可以通过节点HTTP接口`wallet/getaccount`来查询账户的TRX余额信息，返回结果中的balance即为TRX余额，以sun为单位。 + +访问本地节点，注意本地节点如果同步中则可能数据不准确: ``` - curl -X POST http://127.0.0.1:16887/wallet/getaccount -d - '{"address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM", - "visible": true - }' +curl --location 'http://127.0.0.1:16887/wallet/getaccount' \ +--header 'Content-Type: application/json' \ +--data '{ + "address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM", + "visible": true +}' ``` -结果为： +参考返回结果数据： ``` {"account_name": "testacc2","address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM","balance": 1000000000000000,"account_resource": {}} ``` +也可以通过TranGrid访问其他远端节点: +``` + curl --location 'https://nile.trongrid.io/wallet/getaccount' \ +--header 'Content-Type: application/json' \ +--data '{ + "address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM", + "visible":"true" +}' +``` + + ### 发送交易 通过http接口发送交易，总共需要三步： @@ -293,13 +310,14 @@ wallet> 通过fullnode HTTP接口`wallet/createtransaction`创建一个未签名的TRX转账交易： ``` -curl -X POST http://127.0.0.1:16887/wallet/createtransaction -d - '{ - "to_address": "TUznHJfHe6gdYY7gvWmf6bNZHuPHDZtowf", - "owner_address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM", - "amount": 10000000, - "visible":true - }' +curl --location 'http://127.0.0.1:16887/wallet/createtransaction' \ +--header 'Content-Type: application/json' \ +--data '{ + "to_address": "TUznHJfHe6gdYY7gvWmf6bNZHuPHDZtowf", + "owner_address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM", + "amount": 10000000, + "visible":true +}' ``` 返回一个未签名的TRX转账交易： ``` @@ -312,7 +330,7 @@ curl -X POST http://127.0.0.1:16887/wallet/createtransaction -d "parameter": { "value": { "amount": 10000000, - "owner_address": "TPswDDCAWhJAZGdHPidFg5nEf8TkNToDX1", + "owner_address": "TUoHaVjx7n5xz8LwPRDckgFrDWhMhuSuJM", "to_address": "TUznHJfHe6gdYY7gvWmf6bNZHuPHDZtowf" }, "type_url": "type.googleapis.com/protocol.TransferContract" @@ -376,14 +394,14 @@ curl --location --request POST 'http://127.0.0.1:16887/wallet/broadcasttransacti ### 根据交易id查询交易 通过http接口 `wallet/gettransactionbyid`来查询交易的内容： ``` -curl --location --request POST 'http://127.0.0.1:16887/wallet/gettransactionbyid' \ +curl --location 'http://127.0.0.1:16887/wallet/gettransactionbyid' \ --header 'Content-Type: application/json' \ ---data-raw '{ - "value": "c558bd35978267d8999baf6148703cbc94786f3f2e22893637588ca05437d7f0" +--data '{ + "value": "f51f427344460ea484e92a90dc8701a4bbdb57f8b29ce1d7a7dca1bd74a5e1f2", + "visible": true }' ``` -查询结果为： - +参考查询结果为： ``` { "ret": [ diff --git a/docs/introduction/dpos.md b/docs/introduction/dpos.md index 4f0f67560..4c420e487 100644 --- a/docs/introduction/dpos.md +++ b/docs/introduction/dpos.md @@ -24,7 +24,7 @@ DPOS共识在区块链系统中根据节点获取选票的多少确定出部分 * 波场币：指由波场区块链系统发行并在系统中流转的权益通证，代号是TRX。 -* 记账候选人：指波场中有成为记账人资格的节点。 +* 记账候选人Witness：指波场中有成为记账人资格的节点, 在波场中统称为Witness。 * 记账人：指波场中获得记账资格的节点，通常DPOS共识中将记账人称为witness，波场也将记账人称为super node（简称SR），波场设定记账人的数量是27个。下文不区分记账人、witness、supernode、SR等概念。 @@ -48,7 +48,7 @@ DPOS共识在区块链系统中根据节点获取选票的多少确定出部分 2、投票过程 -波场中设定对候选人的投票过程是一笔特殊类型的交易，节点可以通过生成一笔投票交易对候选人进行投票。 +波场中设定对候选人的投票过程是一笔特殊类型的交易，节点可以通过生成一笔投票交易对候选人进行投票。投票交易接口参考[API说明](../api/http.md/#walletvotewitnessaccount)。 3、统计票 @@ -75,7 +75,10 @@ DPOS共识在区块链系统中根据节点获取选票的多少确定出部分 ### 固化块原则 -刚生产出来的区块处于未确认状态，只有被27个Witness中70%以上（即27 * 70% = 19, 向下取整）的witness"认可"的区块才被认为是不可逆区块，一般称为固化块，此时固化块中包含的交易已经被整个区块链网络确认。此处对未确认状态区块"认可"的方式是Witness在其之后生产后继区块，如图d中Witness C生产的第103块，Witness E在第103块的基础上生产了104‘,Witness G、A、B分别生产的第105‘、106’、107‘实质上也是103块的后继区块，故也是对C生产的第103块的认可。可知，当高度为121的区块被生产出来的时候，第103块就成为固化块，因为此时103区块已经有了19个后继区块，此处需要强调的一点是：生产这19个区块的Witness互不相同，并且和生产第103个区块的Witness也不同。 +刚生产出来的区块处于未确认状态，只有被27个Witness中70%以上（即27 * 70% = 19, 向下取整）的witness"认可"的区块才被认为是不可逆区块，一般称为固化块，此时固化块中包含的交易已经被整个区块链网络确认。 +对未确认状态区块"认可"的方式是Witness在其之后生产后继区块，如图下中节点0的记账人生产第100块，节点1的记账人在第100块的基础上生产了101，其它节点的记账人分别生产的第102、103、104个区块实质上也是100块的后继区块，故也是对第100区块的认可。 +![image](https://raw.githubusercontent.com/dongdongsunny/documentation-zh/master/images/solidate_blocks.png) +可知，当高度为119的区块被生产出来的时候，第101块就成为固化块，因为此时119区块已经有了19个后继区块等于被19个记账节点认可了。此处需要强调的一点是：生产这19个区块的Witness互不相同，并且和生产第103个区块的Witness也不同。Tron节点在接受到广播新的区块时会检查区块的有效性，其中一个就是记账人是否正确。 ### 最长链原则 @@ -84,6 +87,7 @@ DPOS共识在区块链系统中根据节点获取选票的多少确定出部分 ## 激励模型 为了保证区块链系统安全高效地运行，TRON设定激励模型，用于鼓励更多的节点加入到波场网络，从而扩大网络规模。波场网络每生成一个区块，都会授予16个TRX的区块奖励给生产该区块的超级代表，还会授予160个TRX的投票奖励给所有超级代表和超级合伙人(票数排名第28～127名的超级代表候选人也叫超级代表合伙人)，他们根据获得的投票数按比例瓜分投票奖励。同时，超级代表及合伙人还会将获得的奖励按照其设定的佣金比例扣除后，将剩余部分按照选民投票比例分发给选民。 +具体计算规则参考下一章[超级代表的奖励](../mechanism-algorithm/sr.md/#3)。 ## 基于提案对参数进行调整 diff --git a/docs/mechanism-algorithm/account.md b/docs/mechanism-algorithm/account.md index 5da690157..19827fd8b 100644 --- a/docs/mechanism-algorithm/account.md +++ b/docs/mechanism-algorithm/account.md @@ -4,14 +4,19 @@ TRON采用账户模型，账户的唯一标识为地址（address），对账户操作需要私钥签名。每个账户可以拥有TRX、TRC10 Token、带宽、能量等各种资源。通过发送交易可以增减TRX或者TRC10 Token余额,可以发布并拥有智能合约，也可以调用自己或者他人发布的智能合约。可以申请成为超级代表并被投票，也可以对超级代表进行投票等等。TRON所有的活动都围绕账户进行。 -## 创建账号的方式 +## 创建波场账号的方式 -1. 首先用钱包或者浏览器生成私钥和地址，公钥可以丢弃。由已有老账户往目标地址发送TRX或者Token，并广播到网络后将完成账户创建的流程。 +1. 首先用钱包或者浏览器生成私钥和地址，然后由已有老账户往目标地址发送TRX或者TRC10 Token，并广播到网络后将完成账户创建的流程。 -2. 通过调用CreateAccount内置合约，完成创建账户 +2. 通过调用[wallet/createaccount](../api/http.md/#walletcreateaccount)系统合约，完成创建账户。 如果账户有足够的通过质押TRX获得的带宽，那么创建账户只会消耗带宽，否则，创建账户会烧掉0.1个TRX。 +### 未激活状态 +注意：由上述第一种方式创建的私钥和地址，比如TranLink钱包创建的账户，对于波场来说属于未激活的状态，也就是在java-tron逻辑中没有创建这个地址对应的账户对象。 +如果此时往该地址发送智能合约交易，交易会成功，但是从新创建的账户查询交易记录会返回空，从调用方可以正常查询记录。当然新创建的地址发起交易也会失败，因为没有对应的账户对象，对应的带宽和能量也是为0。 +激活一个已经创建的地址就通过往改地址发送TRX或TRC10系统专属合约token。 + ## 生成密钥对算法 Tron的签名算法为ECDSA，选用曲线为SECP256K1。其私钥为一个随机数，公钥为椭圆曲线上一个点。生成过程为，首先生成一个随机数d作为私钥，再计算P = d * G作为公钥；其中G为椭圆曲线的基点。 @@ -31,7 +36,7 @@ ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz" 1. 取交易的rawdata，转成byte[]格式。 2. 对rawdata进行sha256运算。 -3. 用交易每个合约中地址对应的私钥（现在一般就是一个合约，一个私钥），对sha256的结果进行签名。 +3. 用交易发起账户的私钥，对sha256的结果进行签名。 4. 把签名结果添加到交易中。 ### 算法 @@ -50,7 +55,7 @@ ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz" 注意：签名结果应该是65字节。 r 32字节， s 32字节，v 1个字节。 -3. fullnode节点收到交易后会进行验签，由hash 和 r、s、v计算出一个地址，与合约中的地址进行比较，相同则为验签通过。 +3. fullnode节点收到交易后会进行验签，由hash 和 r、s、v计算出一个地址，与交易rawData中的发起交易地址进行比较，相同则为验签通过。 ### 示例 diff --git a/docs/mechanism-algorithm/resource.md b/docs/mechanism-algorithm/resource.md index 49e48c500..b0241ca00 100644 --- a/docs/mechanism-algorithm/resource.md +++ b/docs/mechanism-algorithm/resource.md @@ -4,7 +4,7 @@ 投票权、带宽和能量是TRON网络中的重要系统资源。其中投票权用于给超级代表投票；带宽是衡量保存在区块链数据库中的交易字节大小的单位，交易越大，消耗的带宽资源会越多。能量是衡量在TRON网络上TVM虚拟机执行特定操作所需的计算量的单位,由于智能合约交易都需要计算资源来执行，因此每笔智能合约交易都需要付费。 -下文我们把投票权也称为TP、带宽也称为Bandwidth Points，能量也称为Energy。 +下文我们把投票权也称为TRON Power(TP)、带宽也称为Bandwidth Points，能量也称为Energy。 !!! note - 普通交易仅消耗Bandwidth points @@ -14,7 +14,29 @@ 任何账户在给超级代表投票前，都需要先获得投票权，即TRON Power(TP)。投票权可以通过质押TRX来获取。质押TRX除了可以获得带宽或者能量外，还将同时获得投票权，选民质押1TRX，将获得1TP。关于如何质押请参考[在TRON网络上质押](#tron)章节。 -选民可以分批多次质押，多次质押获取到的投票权会被累加到选民账户内，选民可以通过`wallet/getaccountresource`接口查询账户拥有的投票权总数以及已使用的投票权数量。 +选民可以分批多次质押，多次质押获取到的投票权会被累加到选民账户内，选民可以通过[wallet/getaccount](../api/http.md/#walletgetaccount)接口查询账户拥有的投票权总数以及已使用的投票权数量。 + ++ 示例接口结果： +``` +{ + "address": "TBEJewE3MWBbW9t7F4s875yvMHrhqBAZfB", + "votes": [ + { + "vote_address": "TFMehqCGCei9RrJLdM5eRFuwHY4CrYy6Xt", + "vote_count": 7003 + }, + { + "vote_address": "TE8dLwHkMrutMKULTZE41knERrT5XiLVeN", + "vote_count": 7003 + }, + { + "vote_address": "TYcvQx7rFuDgyauJmfxBxj7ppkAsSa3sJe", + "vote_count": 7003 + } + ], +... +} +``` ## 带宽 @@ -22,15 +44,25 @@ 如一条交易的字节数为200，那么该交易需要消耗 200 Bandwidth Points。 -!!! note - 由于网络中总质押资金以及账户的质押资金随时可能发生变化，因此账户拥有的 Bandwidth Points 不是固定值。 - ### 1. Bandwidth Points的来源 Bandwidth Points的获取分两种： -- 通过质押TRX获取的Bandwidth Points， 额度 = 为获取Bandwidth Points质押的TRX / 整个网络为获取Bandwidth Points质押的TRX 总额 * 43_200_000_000，也就是所有用户按质押的TRX数量平分固定额度的Bandwidth Points. -- 每个账号每天有固定免费额度的带宽，为600。 +- 通过质押TRX获取的Bandwidth Points。 +- 每个账号每天有固定免费额度的带宽，目前为600，由61号提案控制。 + +其中质押获取的带宽计算公式为: + +`NetLimit = FrozenBandwidthAmount / TotalNetWeight * TotalNetLimit` + +- FrozenBandwidthAmount: 为获取Bandwidth Points质押的TRX +- TotalNetWeight: 整个网络为获取Bandwidth Points质押的TRX 总额 +- TotalNetLimit = 43_200_000_000 + +也就是所有用户按质押的TRX数量平分固定额度的Bandwidth Points。 + +!!! note + 由于网络中总质押资金以及账户的质押资金随时可能发生变化，因此账户拥有的 Bandwidth Points 不是固定值。 ### 2. Bandwith Points的消耗 @@ -46,14 +78,14 @@ Bandwidth Points是一个账户1天内能够使用的总字节数。一定时间 1. 尝试消耗交易发起者质押获取的Bandwidth Points。如果交易发起者Bandwidth Points不足，则进入下一步 2. 尝试消耗交易发起者的TRX，这部分烧掉0.1TRX -如果交易是Token转账，Bandwidth Points消耗如下： +如果交易是TRC-10 Token转账，Bandwidth Points消耗如下： -1. 依次验证 发行Token资产总的免费Bandwidth Points是否足够消耗，转账发起者的Token剩余免费Bandwidth Points是否足够消耗，Token发行者质押TRX获取Bandwidth Points剩余量是否足够消耗。如果满足则扣除Token发行者质押获取的Bandwidth Points，任意一个不满足则进入下一步 +1. 依次验证发行Token资产总的免费Bandwidth Points是否足够消耗，转账发起者的Token剩余免费Bandwidth Points是否足够消耗，Token发行者质押TRX获取Bandwidth Points剩余量是否足够消耗。如果满足则扣除Token发行者质押获取的Bandwidth Points，任意一个不满足则进入下一步 2. 尝试消耗交易发起者质押获取的Bandwidth Points。如果交易发起者Bandwidth Points不足，则进入下一步 3. 尝试消耗交易发起者的免费Bandwidth Points。如果免费Bandwidth Points也不足，则进入下一步 4. 尝试消耗交易发起者的TRX，交易的字节数 * 1000 sun -如果交易普通交易，Bandwidth Points消耗如下： +如果是其它交易，Bandwidth Points消耗如下： 1. 尝试消耗交易发起者质押获取的Bandwidth Points。如果交易发起者Bandwidth Points不足，则进入下一步 2. 尝试消耗交易发起者的免费Bandwidth Points。如果免费Bandwidth Points也不足，则进入下一步 @@ -61,7 +93,16 @@ Bandwidth Points是一个账户1天内能够使用的总字节数。一定时间 ### 4. 带宽的自动恢复 -账户的免费带宽和质押TRX获取的带宽消耗后， 会在24小时内逐步恢复。 +账户的免费带宽和质押TRX获取的带宽消耗后，会在24小时内逐步恢复。 +其中每次计算质押剩余可用带宽的等价公式为： + +`AvailableNetUsage = NetLimit - LastUsage * (CurrentTime - LastUseTime) / RecoveryWindow(24h)` + +当 `CurrentTime - LastUseTime >= 24h` 时 `AvailableNetUsage = NetLimit`， +其中NetLimit的公式就是上面质押获取带宽的计算公式。通过这个公式实现24小时的质押带宽恢复。 + +如果交易需要消耗质押带宽，当 `AvailableNetUsage >= NewCost `则可顺利消耗质押带宽，并设置新的 +`LastUsage = AvailableNetUsage - NewCost， LastUseTime = CurrentTime`。 ### 5. 账户带宽余额查询 @@ -80,17 +121,56 @@ Bandwidth Points是一个账户1天内能够使用的总字节数。一定时间 ### 1. Energy的获取与消耗 -质押获取Energy，即将持有的trx锁定，无法进行交易，作为抵押，并以此获得免费使用Energy的权利。具体计算与全网所有账户质押有关，可参考相关部分计算。 +质押获取Energy，即将持有的TRX锁定，无法进行交易，作为抵押，并以此获得免费使用Energy的权利。具体计算与全网所有账户质押有关，可参考下面计算逻辑。 #### 质押获得能量 +通过调用接口[wallet/freezebalancev2](../api/http.md/#walletfreezebalancev2)，或下面Wallet-cli指令: + ```text freezeBalanceV2 frozen_balance [ResourceCode:0 BANDWIDTH,1 ENERGY] ``` -通过质押TRX获取的Energy 额度 = 为获取Energy质押的TRX / 整个网络为获取Energy质押的TRX 总额 * 180_000_000_000。 +接口[wallet/getaccount](../api/http.md/#walletgetaccount)可以查询账户当前为获取Energy质押的TRX，示例返回： +``` +{ + "address": "TBEJewE3MWBbW9t7F4s875yvMHrhqBAZfB", + "balance": 26795494669, + "frozenV2": [ + { + "amount": 1002000000 // Bandwith + }, + { + "type": "ENERGY", + "amount": 20001000000 + }, + { + "type": "TRON_POWER" + } + ], + ... ... +} +``` + +##### 质押获得的能量计算 +通过质押TRX获取的能量公式为： +`Energy_Limit = 为获取Energy质押的TRX / TotalEnergyWeight * TotalEnergyLimit` +。 +TotalEnergyWeight：整个网络为获取Energy质押的TRX总额 +其中Total_Energy_Limit = 180000000000，由#19号提议决定，后续数值变动可以查看[Network Parameters](https://tronscan.org/#/sr/committee)。 +也就是所有用户按质押的TRX数量平分固定额度的Energy。 + +具体账户的能量数值，可以调用接口[wallet/getaccountresource](../api/http.md/#walletgetaccountresource)查看，示例返回： +``` +{ + ... + "EnergyLimit": 1459402, // Dynamic changed as TotalEnergyWeight changes + "TotalEnergyLimit": 180000000000, // Static value follow propsal #19 + "TotalEnergyWeight": 2466887064 +} +``` -也就是所有用户按质押的TRX数量平分固定额度的Energy，示例： +账户获得的Energy Limit是会动态调整的，示例： ```text 如全网只有两个人A，B分别质押2TRX，2TRX。 @@ -128,6 +208,12 @@ B: 30_000_000_000 且energy_limit 为36_000_000_000 账户的能量资源消耗后，会在24小时内逐步恢复。 +其中每次计算质押剩余可用能量的等价公式为： + +`EnergyLimit - LastUsage * (CurrentTime - LastUseTime) / RecoveryWindow(24h)` +当 `CurrentTime - LastUseTime >= 24h` 时 `Account_Left_Energy = EnergyLimit`， +其中EnergyLimit的公式就是上面质押获取EnergyLimit的计算公式。通过这个公式实现24小时的质押能量恢复。 + #### 账户能量余额查询 首先调用节点HTTP接口wallet/getaccountresource来获取账户当前的资源状态，然后通过如下公式计算能量余额： diff --git a/docs/mechanism-algorithm/sr.md b/docs/mechanism-algorithm/sr.md index a06f2b4a4..2c2822daa 100644 --- a/docs/mechanism-algorithm/sr.md +++ b/docs/mechanism-algorithm/sr.md @@ -31,45 +31,71 @@ votewitness witness1 3 witness2 7 # 同时给witness1投了3票，给witness2投 ### Witnesses分红 -默认比例是20%，超级代表和超级代表合伙人可以通过wallet/getBrokerage接口查询佣金比例, 也可以通过wallet/updateBrokerage接口修改佣金比例。 +默认比例是20%，超级代表和超级代表合伙人可以通过[wallet/getBrokerage](../api/http.md/#walletgetbrokerage)接口查询佣金比例, 也可以通过[wallet/updateBrokerage](../api/http.md/#walletupdatebrokerage)接口修改佣金比例。 如果一个witness获得20%的奖励，那么剩余的80%奖励会被分配给投票者。如果分红比例设置为100%，那么只有witness可以获得奖励；相反，如果设置为0，那么只有投票者会获得奖励。 -## 3. 超级代表的奖励 +## 3. 超级代表和合伙人的奖励 -### 投票奖励 +### 票数奖励 -票数奖励是每生成一个区块奖励160TRX，总奖励数是4,608,000 TRX / 天。 +票数奖励是每生成一个区块奖励160TRX，分给SR和Partner。 -对每一个SR与Partner，每天获得的票数奖励 = 4,608,000 * ( 获得的票数 / 总票数) x 20% TRX +`每天总票数奖励数 = (24h/出块时间3s) * 160 = 4,608,000 TRX / 天` + +对每一个SR与Partner，每天获得的票数奖励TRX = 总奖励数 * ( 获得的票数 / SR与Partner的总票数) x 分红比例 ### 出块奖励 -波场协议网络每3秒中会出一个区块，每个区块将给予超级代表16个TRX奖励，每年总计168,192,000 TRX将会被奖励给超级代表。 +波场协议网络每3秒中会出一个区块，每个区块将给予超级代表16个TRX奖励，每年总计 365 * 24 * 3600 * 16TRX / 3 = 168,192,000 TRX将会被奖励给超级代表。 -超级代表每次出块完成后，出块奖励都会发到超级代表的子账号当中，超级代表不能直接使用这部分资产，但可以查询。 每24h允许一次提取操作。从该子账号转移到超级代表的账户中。 +超级代表每次出块完成后，出块奖励都会发到超级代表的账号当中，超级代表不能直接使用这部分资产，但可以查询。 -16 (TRX/区块) * 28,800 (总区块数/day) = 460,800 (TRX/天) +`每天总出块奖励 = (24h/出块时间3s) * 16 = 460,800 (TRX/天)` -对每一个SR，每天获得的出块奖励 = (460,800 / 27) x 20% TRX +单个SR每天获得的出块奖励 = (460,800 / 27) x Witness分红 TRX 实际奖励可能会比理论上的奖励少，因为出块失败或者维护期切换。 +### 奖励领取 +SR与Partner的票数奖励以Allowance的方式记录在账户里面，每次新的区块生成之后会随即更新，通过[wallet/getaccount](../api/http.md/#walletgetaccount)可以查询。 +统一通过[wallet/withdrawbalance](../api/http.md/#withdrawbalance)把账户相关的票数, 出块以及结算的投票奖励领取到账户余额，每24小时限领一次。 + ## 4. 投票者的奖励 -如果投票给Super Representative： +每次出块时，投票者都会根据Witness分红比例获取所投SR或Partner对应的奖励：从SR分成出块和票数奖励，和从Partner分成票数奖励。 +我们根据下面的参数公式，计算投票奖励： + +- `总投票比例 = 你的投票数 / SR和Partner获取的总票数` +- `选民抽成 = (1 - Witness分红)` -每日获得奖励 = (((你投给一个witness的票数) *4,608,000 / 总票数)* 80%) + ((460,800 / 27) *80%)* (你投给一个witness的票数) / (一个witness获得的总票数) TRX +如果投票给SR： + +- 如果轮到该SR出块 `每次出块获得的Reward =（SR投票比例 * 16 + 总投票比例 * 160）* 选民抽成 TRX` +- 如果不是该SR出块 `每次出块获得的Reward =（总投票比例 * 160）* 选民抽成 TRX` +- `每日获得总奖励 = （SR投票比例 * 每天总出块奖励 / 27 + 总投票比例 * 每天总票数奖励数）* 选民抽成 TRX` +- `SR投票比例 = 你的投票数 / 该SR获取的总票数` 如果你投票给Partner： -每日获得奖励 = (((你投给一个witness的票数) *4,608,000 / 总票数)* 80%) TRX +- `每次出块获得的Reward =（总投票比例 * 160）* 选民抽成 TRX` +- `每日获得总奖励 = 总投票比例 * 每天总票数奖励数 * 选民抽成 TRX` + +注意：上面的每日获得总奖励是理论上获取的奖励上限，实际情况每6个小时维护期后SR和Partner可能有变动，或者出块失败，或者账户重新投票，奖励应该会变小。 + +每次产块后波场的具体计算逻辑是：java-tron会以SR和Partner的账户地址+维护期Cycle为key累加新的分成Reward到代理存储delegationStore。 +然后在维护期结束时，对每个witness计算本维护期Cycle的累积witnessVi = lastCycle witnessVi + (currentCycle reward)/voteCount， +即把每轮每个选票分得的reward累加一起。投票账户获得的奖励计算是从上次领取过的Cycle到上个维护期Cycle的witnessVi的差值，然后更新领取过的Cycle。 +接口[wallet/getreward](../api/http.md/#walletgetreward)会返回结算过的可领的投票奖励+Allowance（见上面章节）。 + +### 奖励领取 +统一通过[wallet/withdrawbalance](../api/http.md/#walletwithdrawbalance)把账户相关的票数, 出块以及投票的奖励领取到账户余额，每24小时限领一次。 ## 5. 委员会 ### 5.1 什么是委员会 -委员会用于修改Tron网络动态参数，如出块奖励、交易费用等等。委员会由当前的27个超级代表组成。每个超级代表都具有提议权、对提议的投票权， +委员会用于修改Tron网络动态参数，如出块奖励、交易费用等等。委员会由当前的27个超级代表组成。每个超级代表都具有提议权、对提议的投票权。从提议创建时间开始，3天时间内为提议的有效期。 当提议获得18个代表及以上的赞成票时，该提议获得通过，并在下个维护期内进行网络参数修改。 ### 5.2 创建提议 @@ -78,7 +104,7 @@ votewitness witness1 3 witness2 7 # 同时给witness1投了3票，给witness2投 TRON网络动态参数及其编号请参考[这里](https://tronscan.org/#/sr/committee)。 -+ 示例： ++ Wallet-Cli指令示例： ```text createproposal id0 value0 ... idN valueN @@ -92,7 +118,7 @@ value0_N: 新参数值 提议仅支持投赞成票，不投票代表不赞同。从提议创建时间开始，3天时间内为提议的有效期。超过该时间范围，该提议如果没有获得足够的 赞成票，该提议失效。允许取消之前投的赞成票。 -+ 示例： ++ Wallet-Cli指令示例： ```shell approveProposal id is_or_not_add_approval @@ -104,7 +130,7 @@ is_or_not_add_approval: 赞成或取消赞成 提议创建者，能够在提议生效前，取消提议。 -+ 示例： ++ Wallet-Cli指令示例： ```shell deleteProposal proposalId @@ -115,8 +141,9 @@ id: 提议Id，根据提议创建时间递增 以下接口可以查询提议，包括： -+ 查询所有提议信息（ListProposals） -+ 分页查询提议信息（GetPaginatedProposalList） -+ 查询指定提议信息（GetProposalById） ++ 查询所有提议信息[wallet/listproposals](../api/http.md/#walletlistproposals) ++ 分页查询提议信息[wallet/getpaginatedproposallist](../api/http.md/#walletgetpaginatedproposallist) ++ 查询指定提议信息[wallet/getproposalbyid](../api/http.md/#walletgetproposalbyid) -相关api详情，请查询[Tron HTTP API](../api/http.md). +相关api详情，请查询[Tron HTTP API](../api/http.md/#_6)。 +其他相关参考文档[super-representatives](https://developers.tron.network/docs/super-representatives). diff --git a/docs/using_javatron/backup_restore.md b/docs/using_javatron/backup_restore.md index 14b6c4a1b..e4faf7b44 100644 --- a/docs/using_javatron/backup_restore.md +++ b/docs/using_javatron/backup_restore.md @@ -58,6 +58,7 @@ $ tar xzvf output-directory.20220628152402.etgz 注意：LevelDB和RocksDB的数据不允许混用。FullNode的数据库类型通过配置文件的配置项`db.engine` 进行指定，可选值为`LEVELDB`或者`ROCKSDB`。 +Nile测试网数据下载地址：https://database.nileex.io ### Lite FullNode数据快照 diff --git a/docs/using_javatron/installing_javatron.md b/docs/using_javatron/installing_javatron.md index 094afdd3c..b9d29231f 100644 --- a/docs/using_javatron/installing_javatron.md +++ b/docs/using_javatron/installing_javatron.md @@ -12,13 +12,13 @@ $ git checkout -t origin/master ``` 然后，通过执行如下命令编译Java-tron源代码。参数`-x test`表示跳过执行测试用例，您也可以去掉这个参数，以在编译的过程中执行测试代码，这将使编译时间更长。编译完成之后，FullNode.jar会生成在 `java-tron/build/libs/`目录下。 - + ``` $ cd java-tron $ ./gradlew clean build -x test ``` - - + + # 运行Java-tron节点 @@ -31,29 +31,47 @@ Fullnode作为TRON网络的入口点，拥有完整的历史数据，并提供 ```` $ java -Xmx24g -XX:+UseConcMarkSweepGC -jar FullNode.jar -c main_net_config.conf ```` - + * -XX:+UseConcMarkSweepGC ：指定并行垃圾回收。要放在 -jar 参数前面，不能放在最后面。 -* -Xmx ：JVM堆的最大值，可以设置成物理内存的80%。 +* -Xmx ：JVM堆所占内存的最大值，可以设置成物理内存的80%。 + +main_net_config.conf里面的部分配置参考[网络配置](./connecting_to_tron.md)章节。 + +Java-tron启动后，日志会输出在文件java-tron/logs/tron.log中，查看文件可以看到以下内容显示网络层建立P2P连接，之后节点开始区块同步： +``` +16:41:11.229 INFO [main] [app](Args.java:1143) ************************ Net config ************************ +16:41:11.229 INFO [main] [app](Args.java:1144) P2P version: 201910292 +16:41:11.229 INFO [main] [app](Args.java:1145) Bind IP: 192.168.20.101 +16:41:11.229 INFO [main] [app](Args.java:1146) External IP: 203.12.203.3 +16:41:11.229 INFO [main] [app](Args.java:1147) Listen port: 18888 +16:41:11.229 INFO [main] [app](Args.java:1148) Discover enable: true +... ... +16:41:32.838 INFO [peerClient-13] [DB](Manager.java:1936) HeadNumber: 52347923, syncBeginNumber: 52347923, solidBlockNumber: 52347905. +16:41:32.839 INFO [peerClient-13] [net](SyncService.java:197) Get block chain summary, low: 52347923, highNoFork: 52347923, high: 52347923, realHigh: 52347923 +16:41:32.839 INFO [peerClient-13] [net](PeerConnection.java:184) Send peer /182.125.127.201:18888 message type: SYNC_BLOCK_CHAIN +size: 1, start block: Num:52347923,ID:00000000031ec413b7d75adeb141cfb6acf01127436dcd02eafbaf58df07f9e5 +``` +如果节点启动异常，该日志也会输出错误信息。 ### 启动出块的全节点 将`--witness`参数添加到启动命令中，fullnode将作为出块的全节点运行。出块全节点除了支持fullnode的所有功能，它还支持区块生产和交易打包。请确保您拥有一个超级代表账户，并获得他人的投票，如果票数排在前27名，您需要启动一个出块的全节点参与区块生产。 - -将超级代表地址的私钥填写到main_net_config.conf的localwitness列表中，示例如下。但如果不希望使用这种以明文的方式进行私钥指定，可以使用keystore + 密码的方式，请参考[其它说明](#_2) + +将超级代表地址的私钥填写到main_net_config.conf的localwitness列表中，示例如下。但如果不希望使用这种以明文的方式进行私钥指定，可以使用keystore + 密码的方式，请参考下面[其它说明](#_3)。 ``` localwitness = [ 650950B193DDDDB35B6E48912DD28F7AB0E7140C1BFDEFD493348F02295BD812 ] ``` - + 然后执行如下命令来启动节点: - + ``` $ java -Xmx24g -XX:+UseConcMarkSweepGC -jar FullNode.jar --witness -c main_net_config.conf ``` -**注意**：对于主网和nile测试网，由于新节点启动后，需要同步的数据量较大，因此同步数据需要较长的时间。可以使用 [数据快照](../backup_restore/#_5) 来加快节点同步速度。首先下载最新的数据快照，并将其解压至tron项目的output-directory目录下，然后再启动节点，这样节点将在数据快照的基础上进行同步。 +**注意**：对于主网和nile测试网，由于新节点启动后，需要同步的数据量较大，因此同步数据需要较长的时间。可以使用 [数据快照](../backup_restore/#_5) 来加快节点同步速度，Nile测试网[下载](https://database.nileex.io)。首先下载最新的数据快照，并将其解压至tron项目的output-directory目录下，然后再启动节点，这样节点将在数据快照的基础上进行同步。 # 其它说明 ### 如何使用keystore+密码的方式指定witness账户私钥 @@ -80,10 +98,10 @@ $ java -Xmx24g -XX:+UseConcMarkSweepGC -jar FullNode.jar --witness -c main_net_c 安装tcmalloc，然后在启动脚本中添加以下两行，不同的linux发行版tcmalloc的路径略有差异。 ``` #!/bin/bash - + export LD_PRELOAD="/usr/lib/libtcmalloc.so.4" export TCMALLOC_RELEASE_RATE=10 - + # original start command java -jar ..... ``` @@ -121,4 +139,4 @@ java -jar ..... ``` export LD_PRELOAD="/usr/lib64/libtcmalloc.so.4" export TCMALLOC_RELEASE_RATE=10 - ``` \ No newline at end of file + ``` diff --git a/docs/using_javatron/metrics.md b/docs/using_javatron/metrics.md index 4a7152908..ecb43f9a8 100644 --- a/docs/using_javatron/metrics.md +++ b/docs/using_javatron/metrics.md @@ -21,7 +21,7 @@ node { ``` ## 启动Java-tron节点 -您可以通过如下命令启动Java-tron节点： +您可以通过如下命令启动Java-tron节点, 参考[部署Java-tron](./installing_javatron.md)章节。 ``` $ java -Xmx24g -XX:+UseConcMarkSweepGC -jar FullNode.jar -c main_net_config.conf ``` diff --git a/docs/using_javatron/private_network.md b/docs/using_javatron/private_network.md index de6142efa..4d3287cae 100644 --- a/docs/using_javatron/private_network.md +++ b/docs/using_javatron/private_network.md @@ -31,29 +31,46 @@ ``` 4. 修改各节点的配置文件 - - 请根据如下表格中的说明，依次修改节点的各个配置项： - - | 配置项名称 | SR Fullnode配置内容 | FullNode配置内容 | 说明 | - | :-------- | :-------- | :-------- | :-------- | - | localwitness | witness账户私钥 | 不需填值 | 生成区块需要使用私钥签名 | - | genesis.block.witnesses | 上面私钥对应的地址 | 与SR配置值相同 | 创世块相关的配置，genesis.block需要与SR节点的一样 | - | genesis.block.Assets | 给特定账户预置TRX。将预先准备的账户地址写入并随意指定其TRX的余额。可以直接修改原来已有账户的address字段，其它字段不需要修改；或者在末尾添加新账户信息 | 与SR配置值相同 | 创世块相关的配置 | - | p2p.version | 11111之外的任意正整数 | 与SR配置值相同 | SR 和fullnode需相同，只有相同version的节点才能握手成功 | - | seed.node | 不需填值 | 将ip.list设置为SR的ip地址和SR配置文件中的`listen.port`端口号 | 能够让fullnode与SR node建立连接并同步数据 | - | needSyncCheck | false | true | 第1个SR设置needSyncCheck为false，其他设置为true | - | node.discovery.enable | true | true | 如果配置成false，则当前节点不会被其他节点发现 | - |block.proposalExpireTime|600000 |与SR配置值相同 |默认提议生效时间是3天：259200000(ms)，如需快速通过提议，可将该项设置为更小的值，如10分钟，即600000ms| - |block.maintenanceTimeInterval|300000| 与SR配置值相同 | 维护期时间间隔，默认是6小时: 21600000(ms),如需快速通过提议，可将该项设置为更小的值，如五分钟，即300000ms。| - |committee.allowSameTokenName |1|1|允许相同的token name| - |committee.allowTvmTransferTrc10 | 1|1|允许智能合约转账TRC10代币| - + 请根据如下表格中的说明，依次修改节点的各个配置项，**滑动向右**查看不同节点配置： + + | 配置项名称 | SR Fullnode配置内容 | FullNode配置内容 | 说明 | + | :-------- |:-------------------------------------------------------------------------------------| :-------- | :-------- | + | localwitness | witness账户私钥 | 不需填值 | 生成区块需要使用私钥签名 | + | genesis.block.witnesses | 上面私钥对应的地址 | 与SR配置值相同 | 创世块相关的配置，genesis.block需要与SR节点的一样 | + | genesis.block.Assets | 给特定账户预置TRX。
将预先准备的账户地址写入并随意指定其TRX的余额。
可以直接修改原来已有账户的address字段，其它字段不需要修改；或者在末尾添加新账户信息 | 与SR配置值相同 | 创世块相关的配置 | + | p2p.version | 11111之外的任意正整数 | 与SR配置值相同 | SR 和fullnode需相同，只有相同version的节点才能握手成功 | + | seed.node | 不需填值 | 将ip.list设置为SR的ip地址和SR配置文件中的`listen.port`端口号 | 能够让fullnode与SR node建立连接并同步数据 | + | needSyncCheck | false | true | 第1个SR设置needSyncCheck为false，其他设置为true | + | node.discovery.enable | true | true | 如果配置成false，则当前节点不会被其他节点发现 | + |block.proposalExpireTime| 600000 |与SR配置值相同 |默认提议生效时间是3天：259200000(ms)，如需快速通过提议，可将该项设置为更小的值，如10分钟，即600000ms| + |block.maintenanceTimeInterval| 300000 | 与SR配置值相同 | 维护期时间间隔，默认是6小时: 21600000(ms),如需快速通过提议，可将该项设置为更小的值，如五分钟，即300000ms。| + |committee.allowSameTokenName | 1 |1|允许相同的token name| + |committee.allowTvmTransferTrc10 | 1 |1|允许智能合约转账TRC10代币| + + 5. 修改配置文件中的端口号，将SR和FullNode的配置成不相同的端口号。注意，如果SR和FullNode运行在一台机器上，此步骤是必须的，否则，可跳过此步。 + 在配置文件的node结构下面修改下列参数： * `listen.port` ： p2p的监听端口 * `http`端口： Http监听端口 * `rpc` 端口： rpc 监听端口 +``` +node { + listen.port = 16666 + + http { + fullNodePort = 16667 + solidityPort = 16668 + } + + rpc { + port = 16669 + ... + } + ... + } +``` 6. 启动节点 产块的全节点和非产块的全节点，启动命令不同： @@ -114,4 +131,4 @@ modifyChainParameters(parametersForProposal2, 2) ``` - 等待该提议生效后，私链的动态参数与主网就一致了，您可以通过/wallet/getchainparameters接口查询链参数。 \ No newline at end of file + 等待该提议生效后，私链的动态参数与主网就一致了，您可以通过/wallet/getchainparameters接口查询链参数。 diff --git a/docs/using_javatron/toolkit.md b/docs/using_javatron/toolkit.md index d42c6fbe2..a9a2c34dc 100644 --- a/docs/using_javatron/toolkit.md +++ b/docs/using_javatron/toolkit.md @@ -131,12 +131,17 @@ Toolkit提供数据剪裁工具，主要用于轻节点数据的生成以及轻 数据剪裁工具根据当前`最新区块高度`(latest_block_number)可将完整数据切分成快照数据集（Snapshot dataset）或历史数据集（History dataset），快照数据集用于启动轻节点，历史数据集用于历史数据查询。通过快照数据集启动的轻节点不支持查询剪裁时的最新区块高度之前的历史数据。数据剪裁工具还提供了将历史数据集同快照数据集合并的功能，使用场景如下： * 将全节点数据切分成轻节点数据 - 轻节点只基于快照数据集启动，使用数据剪裁工具将全节点数据切分成快照数据集，即得到轻节点数据 + +轻节点只基于快照数据集启动，使用数据剪裁工具将全节点数据切分成快照数据集，即得到轻节点数据。 + * 定期剪裁轻节点数据 - 由于轻节点启动后，会保存与全节点同样的数据，所以轻节点虽然在启动时数据量非常小，但是后期的数据膨胀速度与全节点相同，因此可能需要定期剪裁数据。裁剪轻节点数据也是使用数据剪裁工具将轻节点数据切分成快照数据集，即得到裁剪后的轻节点数据 + +由于轻节点启动后，会保存与全节点同样的数据，所以轻节点虽然在启动时数据量非常小，但是后期的数据膨胀速度与全节点相同，因此可能需要定期剪裁数据。裁剪轻节点数据也是使用数据剪裁工具将轻节点数据切分成快照数据集，即得到裁剪后的轻节点数据。 + * 将轻节点数据转回全节点数据 - 由于轻节点不支持历史数据查询，如果要支持，则需要将轻节点数据变为全节点数据，那么该节点也就从轻节点变成了全节点。可以直接下载全节点数据库快照实现，也可以使用数据剪裁工具：首先将全节点数据切分成历史数据集，再合并历史数据集与轻节点的快照数据集，得到全节点数据。 - + +由于轻节点不支持历史数据查询，如果要支持，则需要将轻节点数据变为全节点数据，那么该节点也就从轻节点变成了全节点。可以直接下载全节点数据库快照实现，也可以使用数据剪裁工具：首先将全节点数据切分成历史数据集，再合并历史数据集与轻节点的快照数据集，得到全节点数据。 + 注意：使用本工具进行任何操作之前，需要首先停止当前运行的节点。 diff --git a/images/solidate_blocks.png b/images/solidate_blocks.png new file mode 100644 index 000000000..ea1c90ef7 Binary files /dev/null and b/images/solidate_blocks.png differ diff --git a/mkdocs.yml b/mkdocs.yml index aafbe37d2..32db40a4e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,19 +5,6 @@ repo_url: https://github.com/tronprotocol/documentation-zh nav: - 入门: - Java-tron入门: 'getting_started/getting_started_with_javatron.md' - - 使用Java-tron: - - 部署Java-tron: using_javatron/installing_javatron.md - - 备份和恢复: using_javatron/backup_restore.md - - 轻节点: developers/litefullnode.md - - 私链网络: using_javatron/private_network.md - - 事件订阅: architecture/event.md - - 数据库配置: architecture/database.md - - 网络配置: using_javatron/connecting_to_tron.md - - 节点监控: using_javatron/metrics.md - - 节点维护工具: using_javatron/toolkit.md - - API 接口: - - HTTP 接口: api/http.md - - gRPC 接口: api/rpc.md - 核心协议: - 波场共识: introduction/dpos.md - 超级代表: mechanism-algorithm/sr.md @@ -27,7 +14,20 @@ nav: - 系统合约: mechanism-algorithm/system-contracts.md - 去中心化交易所: mechanism-algorithm/dex.md - 多重签名: mechanism-algorithm/multi-signatures.md - - Java-tron开发: + - 使用Java-tron: + - 部署Java-tron: using_javatron/installing_javatron.md + - 备份和恢复: using_javatron/backup_restore.md + - 轻节点: developers/litefullnode.md + - 私链网络: using_javatron/private_network.md + - 事件订阅: architecture/event.md + - 数据库配置: architecture/database.md + - 网络配置: using_javatron/connecting_to_tron.md + - 节点监控: using_javatron/metrics.md + - 节点维护工具: using_javatron/toolkit.md + - API 接口: + - HTTP 接口: api/http.md + - gRPC 接口: api/rpc.md + - Java-tron开发: - 开发者指南: developers/java-tron.md - TIPs工作流程: developers/tips.md - Issue工作流程: developers/issue-workflow.md @@ -35,11 +35,11 @@ nav: - 配置IDE开发环境: developers/run-in-idea.md - 开发示例: developers/demo.md - 核心模块: developers/code-structure.md - - Dapp开发: - - Dapp开发工具: contracts/compiler.md - - Wallet-cli: + - Wallet-cli: - 什么是Wallet-Cli: clients/wallet-cli.md - Wallet命令: clients/wallet-cli-command.md + - Dapp开发: + - Dapp开发工具: contracts/compiler.md - 版本发布: - 新版本部署手册: releases/upgrade-instruction.md - 一致性检验: releases/signature_verification.md