From 66e83b62a197d4b2f6557d7962bf0b14e29fd777 Mon Sep 17 00:00:00 2001 From: byounggul kwon <49632556+kwon528@users.noreply.github.com> Date: Fri, 27 Oct 2023 15:38:25 +0900 Subject: [PATCH] Update document and docker compose for relay --- doc/bmc.md | 231 ------ doc/bmr.md | 82 +- doc/bmv.md | 47 -- doc/bsh.md | 65 -- doc/btp.md | 297 ------- doc/btpsimple_cli.md | 204 ----- doc/build.md | 48 -- doc/icon.md | 353 --------- doc/iconee.md | 354 --------- doc/iip-draft_btp.md | 715 ----------------- doc/img/btp_components.svg | 1 - doc/relay_cli.md | 182 +++++ doc/tutorial.md | 741 ------------------ doc/tutorial_pyscore.md | 677 ---------------- .../relay/config/icon_to_hardhat_config.json | 36 + .../relay/config/icon_to_icon_config.json | 38 + docker-compose/relay/config/relay_config.json | 34 - docker-compose/relay/docker-compose.yml | 2 +- docker-compose/relay/keystore/icon1/keysecret | 1 + .../relay/keystore/icon1/keystore.json | 22 + 20 files changed, 351 insertions(+), 3779 deletions(-) delete mode 100644 doc/bmc.md delete mode 100644 doc/bmv.md delete mode 100644 doc/bsh.md delete mode 100644 doc/btp.md delete mode 100644 doc/btpsimple_cli.md delete mode 100644 doc/build.md delete mode 100644 doc/icon.md delete mode 100644 doc/iconee.md delete mode 100644 doc/iip-draft_btp.md delete mode 100644 doc/img/btp_components.svg create mode 100644 doc/relay_cli.md delete mode 100644 doc/tutorial.md delete mode 100644 doc/tutorial_pyscore.md create mode 100644 docker-compose/relay/config/icon_to_hardhat_config.json create mode 100644 docker-compose/relay/config/icon_to_icon_config.json delete mode 100644 docker-compose/relay/config/relay_config.json create mode 100644 docker-compose/relay/keystore/icon1/keysecret create mode 100644 docker-compose/relay/keystore/icon1/keystore.json diff --git a/doc/bmc.md b/doc/bmc.md deleted file mode 100644 index 471dc9d..0000000 --- a/doc/bmc.md +++ /dev/null @@ -1,231 +0,0 @@ -# BTP Message Center(BMC) - -## Introduction - -BTP Message Center is a smart contract which builds BTP Message and -sends it to BTP Message Relay and handles Relay Message from the other. - -## Setup - -1. Registers [BSH](bsh.md)s for the services. - (BSH should be deployed before the registration) -2. Registers [BMV](bmv.md)s for the directly connected blockchains. - (BMV should be deployed before the registration) -3. Add links, BMCs of directly connected blockchains -4. Add routes to other BMCs of in-directly connected blockchains - -## Send a message - -BSH sends a message through [BMC.sendMessage](bmc.md#sendmessage). -It accepts the requests from the registered BTP Service Handler(BSH). -Of course, if service name of those requests is different from -registration, then they will be rejected. - -Then it builds a BTP Message from the request. -1. Decide destination BMC from given Network Address -2. Fill in other information from parameters. -3. Serialize them for sending. - -Then it tries to send the BTP Message. -1. Decide next BMC from the destination referring routing information. -2. Get sequence number corresponding to the next. -3. Emit the event, [Message](#message) including the information. - -The event will be monitored by the Relay, it will build Relay Message -for next BMC. - -## Receive a message - -It receives the Relay Message, then it tries to decode it with registered -BMV. It may contain multiple BTP Messages. -It dispatches received BTP Messages one-by-one in the sequence. - -If it is the destination, then it tries to find the BSH for the -service, and then calls [BSH.handleBTPMessage](bsh.md#handlebtpmessage). -It calls [BSH.handleBTPError](bsh.md#handlebtperror) if it's an error. - -If it's not the destination, then it tries to send the message to -the next route. - -If it fails, then it replies an error. -BTP Message for error reply is composed of followings. -* sn : negated serial number of the message. -* dst : BTP Address of the source. -* src : BTP Address of the BMC. -* msg : Error Message including error code and message. - -## Interface - -### Writable methods - -#### handleRelayMessage -* Params - - _prev: String ( BTP Address of the BMC generates the message ) - - _msg: String ( base64 encoded string of serialized bytes of Relay Message ) -* Description: - - It verify and decode RelayMessage with BMV, and dispatch BTP Messages - to registered BSHs - - It's allowed to be called by registered Relay. - -#### handleFragment -* Params - - _prev: String ( BTP Address of the BMC generates the message ) - - _msg: String ( base64 encoded string of serialized bytes of Relay Message ) - - _idx: Integer ( Index of fragment ) -* Description: - - Assemble fragments of the Relay Message and call BMC.handleRelayMessage - - It's allowed to be called by registered Relay. - -#### sendMessage -* Params - - _to: String ( Network Address of destination network ) - - _svc: String ( name of the service ) - - _sn: Integer ( serial number of the message, it should be positive ) - - _msg: Bytes ( serialized bytes of Service Message ) -* Description: - - It sends the message to specific network. - - It's allowed to be called by registered BSHs. - -#### addService -* Params - - _svc: String (the name of the service) - - _addr: Address (the address of the smart contract handling the service) -* Description: - - It registers the smart contract for the service. - - It's called by the operator to manage the BTP network. - -#### removeService -* Params - - _svc: String (the name of the service) -* Description: - - It de-registers the smart contract for the service. - - It's called by the operator to manage the BTP network. - -#### addVerifier -* Params - - _net: String (Network Address of the blockchain ) - - _addr: Address (the address of BMV) -* Description - - Registers BMV for the network. - - It's called by the operator to manage the BTP network. - -#### removeVerifier -* Params - - _net: String (Network Address of the blockchain ) -* Description - - De-registers BMV for the network. - - It may fail if it's referred by the link. - - It's called by the operator to manage the BTP network. - -#### addLink -* Params - - _link: String (BTP Address of connected BMC) -* Description - - If it generates the event related with the link, the relay shall - handle the event to deliver BTP Message to the BMC. - - If the link is already registered, or its network is already - registered then it fails. - - If there is no verifier related with the network of the link, - then it fails. - - It initializes status information for the link. - - It's called by the operator to manage the BTP network. - -#### removeLink -* Params - - _link: String (BTP Address of connected BMC) -* Description - - It removes the link and status information. - - It's called by the operator to manage the BTP network. - -#### addRoute -* Params - - _dst: String ( BTP Address of the destination BMC ) - - _link: String ( BTP Address of the next BMC for the destination ) -* Description: - - Add route to the BMC. - - It may fail if there more than one BMC for the network. - - It's called by the operator to manage the BTP network. - -#### removeRoute -* Params - - _dst: String ( BTP Address of the destination BMC ) -* Description: - - Remove route to the BMC. - - It's called by the operator to manage the BTP network. - -### Read-only methods - -#### getServices -* Description - - Get registered services. -* Returns - - A dictionary with the name of the service as key and address of the BSH - related with the service as value. - ```json - { - "token": "cx72eaed466599ca5ea377637c6fa2c5c0978537da" - } - ``` - -#### getVerifiers -* Description - - Get registered verifiers. -* Returns - - A dictionary with the Network Address as a key and smart contract - address of the BMV as a value. - ```json - { - "0x1.iconee": "cx72eaed466599ca5ea377637c6fa2c5c0978537da" - } - ``` - -#### getLinks -* Description - - Get registered links. -* Returns - - A list of links ( BTP Addresses of the BMCs ) - ```json - [ "btp://0x1.iconee/cx9f8a75111fd611710702e76440ba9adaffef8656" ] - ``` - -#### getRoutes -* Description: - - Get routing information. -* Return - - A dictionary with the BTP Address of the destination BMC as key and - the BTP Address of the next as value. - ```json - { - "btp://0x2.iconee/cx1d6e4decae8160386f4ecbfc7e97a1bc5f74d35b": "btp://0x1.iconee/cx9f8a75111fd611710702e76440ba9adaffef8656" - } - ``` - -#### getStatus -* Params - - _link: String ( BTP Address of the connected BMC ) -* Description: - - Get status of BMC. - - It's used by the relay to resolve next BTP Message to send. - - If target is not registered, it will fail. -* Return - - The object contains followings fields. - - | Field | Type | Description | - |:---------|:--------|:-------------------------------------------------| - | tx_seq | Integer | next sequence number of the next sending message | - | rx_seq | Integer | next sequence number of the message to receive | - | verifier | Object | status information of the BMV | - - -### Events - -#### Message -* Indexed: 1 -* Params - - _next: String ( BTP Address of the BMC to handle the message ) - - _seq: Integer ( sequence number of the message from current BMC to the next ) - - _msg: Bytes ( serialized bytes of BTP Message ) -* Description - - It sends the message to the next BMC. - - The relay monitors this event. - diff --git a/doc/bmr.md b/doc/bmr.md index c1beb31..61415aa 100644 --- a/doc/bmr.md +++ b/doc/bmr.md @@ -1,18 +1,78 @@ # BMR (BTP Message Relay) ## Introduction - -* Unidirectional relay -* Monitor BTP events +* Relay direction setting ( both,front,reverse ) +* Monitor BTP events +* Send BTP Relay Message * Gather proofs for the events -## Integrated blockchain -* [ICON](icon.md) -* [ICON Enterprise Edition](iconee.md) +## Platform preparation + +* GoLang 1.19 + + **Mac OSX** + ``` + brew install go + ``` + +## Source checkout +First of all, you need to check out the source. + +```bash +git clone https://github.com/icon-project/btp2.git --recurse-submodules +``` + +## Build + +```bash +cd ${PROJECT_ROOT} +make relay +``` + +Output binaries are placed under `bin/` directory. + +## Docker Image Build +```bash +cd ${PROJECT_ROOT} +make relay-image +``` +* [Docker Compose example](../docker-compose) + +## Relay CLI +* [Relay command line](relay_cli.md) + +## Tutorial +* [End-to-End Testing Demo](../e2edemo/README.md) + +## Relay start + +### Create network configuration + +```bash +${PROJECT_ROOT}/bin/relay save ./config/relay_config.json +``` +* Configuration example + * [Icon to Icon configuration](../docker-compose/relay/config/icon_to_icon_config.json) + * [Icon to Eth-Bridge configuration](../docker-compose/relay/config/icon_to_hardhat_config.json) + +#### Configuration setting +1. 'relay_config' setting +[[Relay config]](relay_cli.md#options) + +2. 'chains_config' setting + +| Key | Description | +|:-------------|:-----------------------------------------------| +| address | BTPAddress ( btp://${Network}/${BMC Address} ) | +| endpoint | Network endpoint | +| key_store | Relay keystore | +| key_password | Relay keystore password | +| type | BTP2 contract type | + +#### Relay Start +```bash +${PROJECT_ROOT}/bin/relay start --config ./config/relay_config.json +``` + -## General -* [Build Guide](build.md) -* [Tutorial](tutorial.md) -## Management -* [btpsimple command line](btpsimple_cli.md) \ No newline at end of file diff --git a/doc/bmv.md b/doc/bmv.md deleted file mode 100644 index 7ece284..0000000 --- a/doc/bmv.md +++ /dev/null @@ -1,47 +0,0 @@ -# BTP Message Verifier(BMV) - -## Introduction - -BTP Message Verifier verify and decode Relay Message to -[BTP Message](btp.md#btp-message)s. -Relay Message is composed of both BTP Messages and with proof of -existence of BTP Messages. - -For easy verification, it may update trust information for the -followed events. Most of implementations may track the hashes of block -headers. - -If the blockchain system provide proof of absence of the BTP Messages, -then it just sustains latest one. It updates the hash only if it sees -proof of absence of further BTP Messages in the block. - -But most blockchain system doesn't provide the proof of absence of data. -So, they need to provide the method to verify any of old hashes. - -Merkle Accumulator can be used for verifying old hashes. -BMV sustains roots of Merkle Tree Accumulator, and the relay -will sustain all elements of Merkle Tree Accumulator. The relay -may make the proof of any one of old hashes. -So, even if byzantine relay updated the trust information with the -proof of new block, normal relay can send BTP Messages in -the past block with the proof. - -## Interface - -### Writable methods - -#### handleRelayMessage - -* Description - - Decodes Relay Message and process BTP Messages - - If there is an error, then it sends a BTP Message containing - Error Message - - It ignores BTP Messages with old sequence numbers. But if it - sees a BTP Message with future sequence number, it should fail. -* Params - - _bmc: String ( BTP Address of the BMC handles the message ) - - _prev: String ( BTP Address of the BMC generates the message ) - - _seq: Integer ( next sequence number to get a message ) - - _msg: Bytes ( serialized bytes of Relay Message ) -* Returns - - List of serialized bytes of a [BTP Message](btp.md#btp-message) diff --git a/doc/bsh.md b/doc/bsh.md deleted file mode 100644 index cc8c4b1..0000000 --- a/doc/bsh.md +++ /dev/null @@ -1,65 +0,0 @@ -# BTP Service Handler(BSH) - -## Introduction - -It may send messages through BTP Message Center(BMC) from any user -request. Of course, the request may come from other smart contracts. -It also have responsibility to handle the message from other BSHs. - -BSH can communicate other BSHs with same service name. -If there is already the service using same name, then it should choose -other name for the service when it registers a new service. -Of course, if it wants to be a part of the service, then it should -use same name. And also it follows the protocol of the service. - -Before it's registered to the BMC, it can't send an message, and also -it won't handle the message from others. -To be BSH, followings are required. - -1. Implements the interface -2. Registered to the BMC through [BMC.addService](bmc.md#addservice) - -After the registration, it may send messages through -[BMC.sendMessage](bmc.md#sendmessage). -If there is an error while it delivers the message, then it will -return error information though [handleBTPError](#handlebtperror). -If it's successfully delivered, then BMC will call -[handleBTPMessage](#handlebtpmessage) of the target BSH. -While it processes the message, it may reply though -[BMC.sendMessage](bmc.md#sendmessage). - -## Security - -It should not handle messages or errors from other contract -except the BMC. -BMC also accepts only the service messages from registered BSH. -Of course, BSH may have other APIs, but APIs related with BMC are -only called by BMC. - -## Interface - -### Writable methods - -#### handleBTPMessage -* Description - - Handle BTP Message from other blockchain. - - Accept the message only from the BMC. - - If it fails, then BMC will generate BTP Message including - error information, then it would be delivered to the source. -* Params - - _from: String ( Network Address of source network ) - - _svc: String ( name of the service ) - - _sn: Integer ( serial number of the message ) - - _msg: Bytes ( serialized bytes of ServiceMessage ) - -#### handleBTPError -* Description - - Handle the error on delivering the message. - - Accept the error only from the BMC. -* Params - - _src: String ( BTP Address of BMC generates the error ) - - _svc: String ( name of the service ) - - _sn: Integer ( serial number of the original message ) - - _code: Integer ( code of the error ) - - _msg: String ( message of the error ) - diff --git a/doc/btp.md b/doc/btp.md deleted file mode 100644 index 1e7232d..0000000 --- a/doc/btp.md +++ /dev/null @@ -1,297 +0,0 @@ -# Blockchain Transmission Protocol - -## Introduction - -Blockchain records lots of verifiable data. -With this verifiable data, we may construct a network communicatingBTP Message -verifiable messages between blockchains without direct connection. - -The relay delivers messages between blockchains. Each messages are verified -by smart contract, and also it sends messages for the reply. - -Blockchain Transmission Protocol is used to deliver messages between blockchains. -A Relay delivers BTP messages between blockchains and smart contracts will verify and decode the delivered messages according to the services. -Complex and heavy functions of smart contracts can be shared if they are implemented according to standardized interfaces. Smart contracts are also more extensible staying compliant to the standards. - - -## Motivation - -BTP Messages from multiple services are delivered to multiple blockchains. -BTP smart contracts to support multiple services and blockchains. -BTP Message Center(BMC) is the center of smart contracts. - -For each blockchain, BTP Message Verifier(BMV) verifies the relay message and decodes it into standardized messages (BTP Messages). - -For each service, BTP Message Handler(BSH) handles received messages of the service and sends messages through the BTP Message Center(BMC). - - -## Terminology - -* [Network Address](#network-address) - - A string to identify blockchain network - -* [BTP Address](#btp-address) - - A string of URL for locating an account of the blockchain network - -* [Relay Message](#relay-message) - - A message that a relay sends to the blockchain. - -* [BTP Message](#btp-message) - - Standardized messages delivered between different blockchains - -* [BTP Message Center(BMC)](bmc.md) - - BMC accepts messages from a relay (Relay Messages). - A Relay Message contains standardized messages(BTP Messages) and proof of existence for these messages. - Corresponding BMV will verify and decode the Relay Message, then the BMC will process the BTP Messages. - - If the destination of the message isn't current BMC, then it's sent to the next BMC to reach its destination. - If current BMC is the destination, then it's dispatched to the corresponding BSH. - If the message cannot be processed, then it sends an error back to the source. - - -* [BTP Message Verifier(BMV)](bmv.md) - - BMV verifies a Relay Message and decodes it into BTP Messages. - - -* [BTP Service Handler(BSH)](bsh.md) - - BSH handles BTP Messages of the service. It also sends messages according to different service scenarios. - - -* [BTP Message Relay(BMR)](bmr.md) - - The software relays Relay Message between blockchains - - -### Network Address - -A string to identify blockchain network - -``` -. -``` - -**Network System**: -Short name of the blockchain network system. - -| Name | Description | -|:-------|:---------------------| -| icon | Loopchain for ICON | -| iconee | Loopchain Enterprise | - -**NID**: -ID of the network in the blockchain network system. - -> Example - -| Network Address | Description | -|:----------------|:---------------------------------------------| -| `0x1.icon` | ICON Network with nid="0x1" <- ICON Main-Net | -| `0x1.iconee` | Loopchain Enterprise network with nid="0x1" | - -### BTP Address - -A string of URL for locating an account of the blockchain network - -> Example -``` -btp:/// -``` -**Account Identifier**: -Identifier of the account including smart contract. -It should be composed of URL safe characters except "."(dot). - -> Example -``` -btp://0x1.icon/hxc0007b426f8880f9afbab72fd8c7817f0d3fd5c0 -btp://0x1.iconee/cx429731644462ebcfd22185df38727273f16f9b87 -``` - -It could be expanded to other resources. - -### BTP Message - -A message delivered across blockchains. - -| Name | Type | Description | -|:-----|:--------|:-----------------------------------------------------| -| src | String | BTP Address of source BMC | -| dst | String | BTP Address of destination BMC | -| svc | String | name of the service | -| sn | Integer | serial number of the message | -| msg | Bytes | serialized bytes of Service Message or Error Message | - -if **sn** is negative, **msg** should be Error Message. -It would be serialized in [RLP serialization](#rlp-serialization). - - -### Error Message - -A message for delivering error information. - -| Name | Type | Description | -|:-----|:--------|:--------------| -| code | Integer | error code | -| msg | String | error message | - -It would be serialized in [RLP serialization](#rlp-serialization). - - -### RLP serialization - -For encoding [BTP Message](#btp-message) and [Error Message](#error-message), it uses Recursive Length Prefix (RLP). -RLP supports bytes and list naturally. -Here are some descriptions about other types. - -#### String - -It uses UTF-8 encoded bytes of the string. -There is no termination bytes. - -#### Integer - -It uses the shortest form of two's complemented bytes representations. -If it's negative, the highest bit of the first byte should be 1. - -> Example - -| Value | Encoded bytes | -|:------|:--------------| -| 0 | 0x00 | -| -1 | 0xff | -| -128 | 0x80 | - -### Relay Message - -It's used to deliver BTP Messages along with other required contents. Normally, it contains the following. - -* BTP Messages along with their proof of existence -* Trust information updates along with their proof of consensus - -The relay gathers the information through APIs of a source blockchain system and its internal database. The actual content of the message is decided according to the blockchain system and BMV implementation. - - -## Components - -Following diagram shows an example, delivering a message from left -blockchain to the other blockchain. - -![btp_components](./img/btp_components.svg) - -In the diagram, there are a few components. - -* [BTP Service Handler(BSH)](bsh.md) -* [BTP Message Center(BMC)](bmc.md) -* [BTP Message Verifier(BMV)](bmv.md) - -### Message delivery. - -1. BSH sends an Service Message through BMC. - - * BSH calls [BMC.sendMessage](bmc.md#sendmessage) with followings. - - | Name | Type | Description | - |:--------|:--------|:----------------------------------------------| - | _to | String | Network Address of the destination blockchain | - | _svc | String | Name of the service. | - | _sn | Integer | Serial number of the message. | - | _msg | Bytes | Service message to be delivered. | - - * BMC lookup the destination BMC belonging to *_to*. - If there is no known BMC to the network, then it fails. - - * BMC builds an BTP Message. - - | Name | Type | Description | - |:-----|:--------|:----------------------------------------------| - | src | String | BTP Address of current BMC | - | dst | String | BTP Address of destination BMC in the network | - | svc | String | Given service name | - | sn | Integer | Given serial number | - | msg | Bytes | Given service message | - - * BMC decide the next BMC according to the destination. - If there is no route to the destination BMC. - - * BMC generates an event with BTP Message. - - | Name | Type | Description | - |:------|:--------|:-------------------------------------------| - | _next | String | BTP Address of the next BMC | - | _seq | Integer | Sequence number of the msg to the next BMC | - | _msg | Bytes | Serialized BTP Message | - -2. The BTP Message Relay(BMR) detects events. - * The relay detects [BMC.Message](bmc.md#message) through various ways. - * The relay can confirm that it occurs and it's finalized. - -3. BMR gathers proofs - * Relay gathers proofs of the event(POE)s - - Proof for the new block - - Proof for the event in the block - * Relay builds Relay Message including followings. - - Proof of the new events - - New events including the BTP Message. - * Relay calls [BMC.handleRelayMessage](bmc.md#handlerelaymessage) - with built Relay Message. - - | Name | Type | Description | - |:------|:-------|:------------------------------------------------| - | _prev | String | BTP Address of the previous BMC | - | _msg | Bytes | serialized Relay Message including BTP Messages | - -4. BMC handles Relay Message - - * It finds BMV for the network address of the previous BMC. - * It gets the sequence number of the next message from the source network. - * BMC calls [BMV.handleRelayMessage](bmv.md#handlerelaymessage) - to decode Relay Message and get a list of BTP Messages. - - | Name | Type | Description | - |:------|:--------|:----------------------------------------------------------| - | _bmc | String | BTP Address of the current BMC | - | _prev | String | BTP Address of given previous BMC | - | _seq | Integer | Next sequence number of the BTP Message from previous BMC | - | _msg | Bytes | The Relay Message | - -5. BMV decodes Relay Message - - * It verifies and decodes Relay Message, then returns a list of - BTP Messages. - * If it fails to verify the message, then it fails. - * The events from the previous BMC to the current BMC will be processed. - * The events should have proper sequence number, otherwise it fails. - -6. BSH handles Service Messages - - * BMC dispatches BTP Messages. - * If the destination BMC isn't current one, then it locates - the next BMC and generates the event. - * If the destination BMC is the current one, then it locates BSH - for the service of the BTP Message. - * Calls [BSH.handleBTPMessage](bsh.md#handlebtpmessage) if - the message has a positive value as *_sn*. - - | Name | Type | Description | - |:------|:--------|:--------------------------------------| - | _from | String | Network Address of the source network | - | _svc | String | Given service name | - | _sn | Integer | Given serial number | - | _msg | Bytes | Given service message | - - * Otherwise, it calls [BSH.handleBTPError](bsh.md#handlebtperror). - - | Name | Type | Description | - |:------|:--------|:-----------------------------------------------| - | _src | String | BTP Address of the BMC that generated the error| - | _svc | String | Given service name | - | _sn | Integer | Given serial number | - | _code | Integer | Given error code | - | _msg | String | Given error message | - diff --git a/doc/btpsimple_cli.md b/doc/btpsimple_cli.md deleted file mode 100644 index 849a9e8..0000000 --- a/doc/btpsimple_cli.md +++ /dev/null @@ -1,204 +0,0 @@ -# Btpsimple - -## btpsimple - -### Description -Command Line Interface of Relay for Blockchain Transmission Protocol - -### Usage -` btpsimple [flags] ` - -### Options -|Name,shorthand | Environment Variable | Required | Default | Description| -|---|---|---|---|---| -| --base_dir | BTPSIMPLE_BASE_DIR | false | | Base directory for data | -| --config, -c | BTPSIMPLE_CONFIG | false | | Parsing configuration file | -| --console_level | BTPSIMPLE_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | -| --dst.address | BTPSIMPLE_DST_ADDRESS | true | | BTP Address of destination blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --dst.endpoint | BTPSIMPLE_DST_ENDPOINT | true | | Endpoint of destination blockchain | -| --dst.options | BTPSIMPLE_DST_OPTIONS | false | [] | Options, comma-separated 'key=value' | -| --key_password | BTPSIMPLE_KEY_PASSWORD | false | | Password of KeyStore | -| --key_secret | BTPSIMPLE_KEY_SECRET | false | | Secret(password) file for KeyStore | -| --key_store | BTPSIMPLE_KEY_STORE | false | | KeyStore | -| --log_forwarder.address | BTPSIMPLE_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | -| --log_forwarder.level | BTPSIMPLE_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | -| --log_forwarder.name | BTPSIMPLE_LOG_FORWARDER_NAME | false | | LogForwarder name | -| --log_forwarder.options | BTPSIMPLE_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | -| --log_forwarder.vendor | BTPSIMPLE_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | -| --log_level | BTPSIMPLE_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | -| --log_writer.compress | BTPSIMPLE_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | -| --log_writer.filename | BTPSIMPLE_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | -| --log_writer.localtime | BTPSIMPLE_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | -| --log_writer.maxage | BTPSIMPLE_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | -| --log_writer.maxbackups | BTPSIMPLE_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | -| --log_writer.maxsize | BTPSIMPLE_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | -| --offset | BTPSIMPLE_OFFSET | false | 0 | Offset of MTA | -| --src.address | BTPSIMPLE_SRC_ADDRESS | true | | BTP Address of source blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --src.endpoint | BTPSIMPLE_SRC_ENDPOINT | true | | Endpoint of source blockchain | -| --src.options | BTPSIMPLE_SRC_OPTIONS | false | [] | Options, comma-separated 'key=value' | - -### Child commands -|Command | Description| -|---|---| -| [btpsimple save](#btpsimple-save) | Save configuration | -| [btpsimple start](#btpsimple-start) | Start server | -| [btpsimple version](#btpsimple-version) | Print btpsimple version | - -## btpsimple save - -### Description -Save configuration - -### Usage -` btpsimple save [file] [flags] ` - -### Options -|Name,shorthand | Environment Variable | Required | Default | Description| -|---|---|---|---|---| -| --save_key_store | | false | | KeyStore File path to save | - -### Inherited Options -|Name,shorthand | Environment Variable | Required | Default | Description| -|---|---|---|---|---| -| --base_dir | BTPSIMPLE_BASE_DIR | false | | Base directory for data | -| --config, -c | BTPSIMPLE_CONFIG | false | | Parsing configuration file | -| --console_level | BTPSIMPLE_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | -| --dst.address | BTPSIMPLE_DST_ADDRESS | true | | BTP Address of destination blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --dst.endpoint | BTPSIMPLE_DST_ENDPOINT | true | | Endpoint of destination blockchain | -| --dst.options | BTPSIMPLE_DST_OPTIONS | false | [] | Options, comma-separated 'key=value' | -| --key_password | BTPSIMPLE_KEY_PASSWORD | false | | Password of KeyStore | -| --key_secret | BTPSIMPLE_KEY_SECRET | false | | Secret(password) file for KeyStore | -| --key_store | BTPSIMPLE_KEY_STORE | false | | KeyStore | -| --log_forwarder.address | BTPSIMPLE_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | -| --log_forwarder.level | BTPSIMPLE_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | -| --log_forwarder.name | BTPSIMPLE_LOG_FORWARDER_NAME | false | | LogForwarder name | -| --log_forwarder.options | BTPSIMPLE_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | -| --log_forwarder.vendor | BTPSIMPLE_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | -| --log_level | BTPSIMPLE_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | -| --log_writer.compress | BTPSIMPLE_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | -| --log_writer.filename | BTPSIMPLE_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | -| --log_writer.localtime | BTPSIMPLE_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | -| --log_writer.maxage | BTPSIMPLE_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | -| --log_writer.maxbackups | BTPSIMPLE_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | -| --log_writer.maxsize | BTPSIMPLE_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | -| --offset | BTPSIMPLE_OFFSET | false | 0 | Offset of MTA | -| --src.address | BTPSIMPLE_SRC_ADDRESS | true | | BTP Address of source blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --src.endpoint | BTPSIMPLE_SRC_ENDPOINT | true | | Endpoint of source blockchain | -| --src.options | BTPSIMPLE_SRC_OPTIONS | false | [] | Options, comma-separated 'key=value' | - -### Parent command -|Command | Description| -|---|---| -| [btpsimple](#btpsimple) | BTP Relay CLI | - -### Related commands -|Command | Description| -|---|---| -| [btpsimple save](#btpsimple-save) | Save configuration | -| [btpsimple start](#btpsimple-start) | Start server | -| [btpsimple version](#btpsimple-version) | Print btpsimple version | - -## btpsimple start - -### Description -Start server - -### Usage -` btpsimple start [flags] ` - -### Options -|Name,shorthand | Environment Variable | Required | Default | Description| -|---|---|---|---|---| -| --cpuprofile | | false | | CPU Profiling data file | -| --memprofile | | false | | Memory Profiling data file | - -### Inherited Options -|Name,shorthand | Environment Variable | Required | Default | Description| -|---|---|---|---|---| -| --base_dir | BTPSIMPLE_BASE_DIR | false | | Base directory for data | -| --config, -c | BTPSIMPLE_CONFIG | false | | Parsing configuration file | -| --console_level | BTPSIMPLE_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | -| --dst.address | BTPSIMPLE_DST_ADDRESS | true | | BTP Address of destination blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --dst.endpoint | BTPSIMPLE_DST_ENDPOINT | true | | Endpoint of destination blockchain | -| --dst.options | BTPSIMPLE_DST_OPTIONS | false | [] | Options, comma-separated 'key=value' | -| --key_password | BTPSIMPLE_KEY_PASSWORD | false | | Password of KeyStore | -| --key_secret | BTPSIMPLE_KEY_SECRET | false | | Secret(password) file for KeyStore | -| --key_store | BTPSIMPLE_KEY_STORE | false | | KeyStore | -| --log_forwarder.address | BTPSIMPLE_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | -| --log_forwarder.level | BTPSIMPLE_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | -| --log_forwarder.name | BTPSIMPLE_LOG_FORWARDER_NAME | false | | LogForwarder name | -| --log_forwarder.options | BTPSIMPLE_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | -| --log_forwarder.vendor | BTPSIMPLE_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | -| --log_level | BTPSIMPLE_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | -| --log_writer.compress | BTPSIMPLE_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | -| --log_writer.filename | BTPSIMPLE_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | -| --log_writer.localtime | BTPSIMPLE_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | -| --log_writer.maxage | BTPSIMPLE_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | -| --log_writer.maxbackups | BTPSIMPLE_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | -| --log_writer.maxsize | BTPSIMPLE_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | -| --offset | BTPSIMPLE_OFFSET | false | 0 | Offset of MTA | -| --src.address | BTPSIMPLE_SRC_ADDRESS | true | | BTP Address of source blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --src.endpoint | BTPSIMPLE_SRC_ENDPOINT | true | | Endpoint of source blockchain | -| --src.options | BTPSIMPLE_SRC_OPTIONS | false | [] | Options, comma-separated 'key=value' | - -### Parent command -|Command | Description| -|---|---| -| [btpsimple](#btpsimple) | BTP Relay CLI | - -### Related commands -|Command | Description| -|---|---| -| [btpsimple save](#btpsimple-save) | Save configuration | -| [btpsimple start](#btpsimple-start) | Start server | -| [btpsimple version](#btpsimple-version) | Print btpsimple version | - -## btpsimple version - -### Description -Print btpsimple version - -### Usage -` btpsimple version ` - -### Inherited Options -|Name,shorthand | Environment Variable | Required | Default | Description| -|---|---|---|---|---| -| --base_dir | BTPSIMPLE_BASE_DIR | false | | Base directory for data | -| --config, -c | BTPSIMPLE_CONFIG | false | | Parsing configuration file | -| --console_level | BTPSIMPLE_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | -| --dst.address | BTPSIMPLE_DST_ADDRESS | true | | BTP Address of destination blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --dst.endpoint | BTPSIMPLE_DST_ENDPOINT | true | | Endpoint of destination blockchain | -| --dst.options | BTPSIMPLE_DST_OPTIONS | false | [] | Options, comma-separated 'key=value' | -| --key_password | BTPSIMPLE_KEY_PASSWORD | false | | Password of KeyStore | -| --key_secret | BTPSIMPLE_KEY_SECRET | false | | Secret(password) file for KeyStore | -| --key_store | BTPSIMPLE_KEY_STORE | false | | KeyStore | -| --log_forwarder.address | BTPSIMPLE_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | -| --log_forwarder.level | BTPSIMPLE_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | -| --log_forwarder.name | BTPSIMPLE_LOG_FORWARDER_NAME | false | | LogForwarder name | -| --log_forwarder.options | BTPSIMPLE_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | -| --log_forwarder.vendor | BTPSIMPLE_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | -| --log_level | BTPSIMPLE_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | -| --log_writer.compress | BTPSIMPLE_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | -| --log_writer.filename | BTPSIMPLE_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | -| --log_writer.localtime | BTPSIMPLE_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | -| --log_writer.maxage | BTPSIMPLE_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | -| --log_writer.maxbackups | BTPSIMPLE_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | -| --log_writer.maxsize | BTPSIMPLE_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | -| --offset | BTPSIMPLE_OFFSET | false | 0 | Offset of MTA | -| --src.address | BTPSIMPLE_SRC_ADDRESS | true | | BTP Address of source blockchain (PROTOCOL://NID.BLOCKCHAIN/BMC) | -| --src.endpoint | BTPSIMPLE_SRC_ENDPOINT | true | | Endpoint of source blockchain | -| --src.options | BTPSIMPLE_SRC_OPTIONS | false | [] | Options, comma-separated 'key=value' | - -### Parent command -|Command | Description| -|---|---| -| [btpsimple](#btpsimple) | BTP Relay CLI | - -### Related commands -|Command | Description| -|---|---| -| [btpsimple save](#btpsimple-save) | Save configuration | -| [btpsimple start](#btpsimple-start) | Start server | -| [btpsimple version](#btpsimple-version) | Print btpsimple version | - diff --git a/doc/build.md b/doc/build.md deleted file mode 100644 index 6ddfe6f..0000000 --- a/doc/build.md +++ /dev/null @@ -1,48 +0,0 @@ -# Build guide - -## Platform preparation - -* GoLang 1.13+ - - **Mac OSX** - ``` - brew install go - ``` - -### ICON SCORE(Smart Contract On Reliable Environment) - -* Python 3.7+ Virtual Environment - - **Mac OSX** - ``` - brew install python - pip install virtualenv setuptools wheel - ``` - -## Environment - -### Source checkout - -First of all, you need to check out the source. -```bash -git clone $REPOSITORY_URL btp -``` - -## Build - -### Build executables - -```bash -make -``` - -Output binaries are placed under `bin/` directory. - - -### Build ICON SCORE - -```bash -make dist-py -``` - -Output files are placed under `build/pyscore/` directory. diff --git a/doc/icon.md b/doc/icon.md deleted file mode 100644 index 4de6608..0000000 --- a/doc/icon.md +++ /dev/null @@ -1,353 +0,0 @@ -# ICON - -## Introduction - -***TODO*** - -## BMV Trust - -| Name | Type | Description | -|:------------|:----------------|:------------| -| NextHeight | Integer | | -| MerkleRoots | List of Bytes | | -| Validators | List of Address | | - - -## BMV Prove - -| Name | Type | Description | -|:--------------------|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------| -| BlockHeader | Bytes | fips-sha3-256(BlockHeader) → *BlockID*
BlockHeader.Result.ReceiptRootHash → *ReceiptRootHash*
BlockHeader.Height → *BlockHeight*
| -| Votes | Bytes | [Prove with Votes](#prove-with-votes) | -| NextVaidators | Bytes | Validators = decode(NextValidators).ToAddress() | -| *BlockHeight* | Integer | Check BlockHeight == LastHeight | -| *BlockID* | Bytes | [Prove with MTA](#prove-with-mta) | -| BlockProof | List of Bytes | [Prove with MTA](#prove-with-mta) | -| ReceiptProofs | List of Bytes | [Prove with MPT](#prove-with-mpt) | -| *ReceiptRootHash* | Bytes | [Prove with MPT](#prove-with-mpt) | - -### Prove with Votes -```` -for VoteItem in Votes.Items { - VoteMessage = encode({ - Height: BlockHeader.Height - Round: Votes.Round - Type: 1 - BlockPartSetID: Votes.BlockPartSetID - BlockID: BlockID - Timestamp: VoteItem.Timestamp - }) - PublicKey = DeducePublicKey( - VoteItem.Signature, - fips-sha3-256(VoteMessage)) - ) - Check ToAddress(PublicKey) in Validators -} -```` - -### Prove with MTA -```` -MTA.Prove( - roots=MerkleRoots, - witness=BlockProof -) -```` - -### Prove with MPT -```` -for ReceiptProof in ReceiptProofs { - MPT.Prove( - key=encode(ReceiptProof.Index), - root=ReceiptRootHash - proofs=ReceiptProof.Proofs - ) → Receipt - - for EventProof in ReceiptProof.EventProofs { - MPT.Prove( - key=encode(EventProof.Index), - root=Receipt.EventLogHash - proofs=EventProof.Proofs - ) → EventLog - } -} -```` - -## Binary format - -ICON uses RLP with Null(RLPn) for binary encoding and decoding. - -* RLPn is [RLP](https://github.com/ethereum/wiki/wiki/RLP) with Null ( `[ 0xF8 0x00]` ) - -| Type | RLPn | Description | -|:----------|:---------|:----------------------------------------------------------------------------------------------------------------------------------| -| B_LIST | List | List of items | -| B_BYTES | Bytes | Raw bytes | -| B_BIGINT | Bytes | N bytes of integer representation.
ex)
0x00 → [ 0x00 ]
0x80 → [ 0x00 0x80 ]
-0x01 → [ 0xff ]
-0x80 → [ 0x80 ] | -| B_INT | B_BIGINT | 64bits signed integer | -| B_ADDRESS | Bytes | 1 byte
- 0x00 ← EOA
- 0x01 ← SCORE
20 bytes : Identifier | -| B_NULL | Null | B_BYTES(N), B_ADDRESS(N) or B_LIST(N) can be Null | - -Suffixed `(N)` means a nullable value. - -## RelayMessage - -> B_LIST of followings - -| Field | Type | Description | -|:--------------|:-----------|:---------------------------------------------------------------------------------------------------------------------------------------| -| BlockUpdates | B_LIST(N) | List of encoded bytes of the [BlockUpdate](#blockupdate). If there is no updates, it would be empty, then BlockProof must not be Null. | -| BlockProof | B_BYTES(N) | Encoded bytes of the [BlockProof](#blockproof). If it’s not Null, then BlockUpdates must be empty. | -| ReceiptProofs | B_LIST(N) | List of encoded bytes of the [ReceiptProof](#receiptproof). | - - -### BlockUpdate - -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:----------|:--------------------------------------------------------------------------| -| Header | B_BYTES | Encoded bytes of the [BlockHeader](#blockheader) | -| Votes | B_BYTES | Encoded bytes of the [Votes](#votes) | -| NextValidators | B_BYTES(N) | Encoded bytes of the [Validators](#validators). Null if it’s not changed. | - - -### BlockProof - -> B_LIST of followings - -| Field | Type | Description | -|:-------------|:--------|:-------------------------------------------------| -| Header | B_BYTES | Encoded bytes of the [BlockHeader](#blockheader) | -| BlockWitness | - | [BlockWitness](#blockwitness) | - - -### BlockWitness - -> B_LIST of followings - -| Field | Type | Description | -|:--------|:--------|:-------------------------------------------------------------------------------------------------| -| Height | B_BYTES | Encoded bytes of the [BlockHeader](#blockheader) | -| Witness | B_LIST | List of bytes. Only hashes of witness.Directions can be recovered by height of the block header. | - - -### ReceiptProof - -> B_LIST of followings - -| Field | Type | Description | -|:------------|:-------|:----------------------------------------------------------------------------------------------------------------------------| -| Index | B_INT | Index to the Receipt. | -| Proofs | B_LIST | List of [Merkle Proof](#merkle-proof) of receipt. [MPT Node](#mpt-node) including encoded bytes of the [Receipt](#receipt). | -| EventProofs | B_LIST | List of [EventProof](#eventproof). | - - -### EventProof - -> B_LIST of followings - -| Field | Type | Description | -|:-------|:-------|:----------------------------------------------------------------------------------------------------------------------------| -| Index | B_INT | Index to the EventLog. | -| Proofs | B_LIST | List of [Merkle Proof](#merkle-proof) of event. [MPT Node](#mpt-node) including encoded bytes of the [EventLog](#eventlog). | - - -### Block Header - -> B_LIST of followings - -| Field | Type | Description | -|:-----------------------|:-------------|:-------------------------------------------------| -| Version | B_INT | 1 ← Version 1 (legacy)
N ← Version N | -| Height | B_INT | Height of the block,
0 means genesis block. | -| Timestamp | B_INT | Micro-seconds after EPOCH | -| Proposer | B_ADDRESS(N) | Proposer of the block | -| PrevID | B_BYTES(N) | 32 bytes hash value | -| VotesHash | B_BYTES(N) | 32 bytes hash value | -| NextValidatorsHash | B_BYTES(N) | 32 bytes hash value | -| PatchTransactionsHash | B_BYTES(N) | 32 bytes hash value | -| NormalTransactionsHash | B_BYTES(N) | 32 bytes hash value | -| LogsBloom | B_BYTES | N(1~256) bytes bloom log value | -| Result | B_BYTES(N) | Encoded bytes of the [Result](#result) | - - -### Result - -> B_LIST of followings - -| Field | Type | Description | -|:------------------|:-----------|:------------------------------------------------------------| -| StateHash | B_BYTES(N) | Hash of world state (account information) | -| PatchReceiptHash | B_BYTES(N) | Root hash of [Merkle List](#merkle-list) of patch receipts | -| NormalReceiptHash | B_BYTES(N) | Root hash of [Merkle List](#merkle-list) of normal receipts | - - -### Validators - -> B_LIST of Validators - -| Field | Type | Description | -|:----------|:--------|:--------------------------------------------------------| -| Validator | B_BYTES | 21 bytes → same as Address
Other bytes → public key | - - -### Votes - -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:------------------------|:---------------------------------------------------------------------------| -| Round | B_INT | Round for votes.
If consensus doesn’t use round, it should be 0(zero). | -| BlockPartSetID | [PartSetID](#partsetid) | PartSetID of the proposed block | -| Items | B_LIST | List of [VoteItem](#voteitem) | - - -#### VoteItem - -> B_LIST of followings - -| Field | Type | Description | -|:----------|:--------|:--------------------------------------------------------------------| -| Timestamp | B_INT | Voted time in micro-seconds | -| Signature | B_BYTES | RSV format signature for [VoteMessage](#votemessage) by a validator | - -Public key of the validator can be recovered with `Signature` and -SHA3Sum256([VoteMessage](#votemessage)). - - -#### VoteMessage -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:------------------------|:----------------------------------------| -| Height | B_INT | [BlockHeader](#blockheader).Height | -| Round | B_INT | [Votes](#votes).Round | -| Type | B_INT | 0 ← PreVote
1 ← PreCommit | -| BlockID | B_BYTES(N) | SHA3Sum256([BlockHeader](#blockheader)) | -| BlockPartSetID | [PartSetID](#partsetid) | [Votes](#votes).BlockPartSetID. | -| Timestamp | B_INT | [VoteItem](#voteitem).Timestamp | - -`Type` field should be `1` for votes of a block. - - -#### PartSetID - -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:-----------|:---------------------------------------------------------------------------| -| Count | B_INT | Number of block parts | -| Hash | B_BYTES(N) | Hash of block parts | - - -### Receipt - -> B_LIST of followings - -| Field | Type | Description | -|:-------------------|:-----------------------------------|:-----------------------------------------------------------------------------------------------| -| Status | B_INT | Result status
0 ← SUCCESS
N ← FAILURE ( N is failure code ) | -| To | B_ADDRESS | The target address of the transaction | -| CumulativeStepUsed | B_BIGINT | Cumulative step used | -| StepUsed | B_BIGINT | Step used | -| StepPrice | B_BIGINT | Step price in LOOP | -| LogsBloom | B_BIGINT | 2048 bits without padding zeros
So, if there is no bit, then it would be a byte with zero. | -| EventLogs | B_LIST(N) of [EventLog](#eventlog) | A list of event logs (empty if there is EventLogHash) | -| SCOREAddress | B_ADDRESS(N) | The address of deployed smart contract | -| EventLogHash | B_BYTES(O) | (from Revision7) Root hash of [Merkle List](#merkle-list) of eventLogs | - - -#### EventLog - -> B_LIST of followings - -| Field | Type | Description | -|:--------|:---------------------|:-------------------------------| -| Addr | B_ADDRESS | SCORE producing this event log | -| Indexed | B_LIST of B_BYTES(N) | Indexed data. | -| Data | B_LIST of B_BYTES(N) | Remaining data. | - - -### Merkle Patricia Trie - -It's similar to [Merkle Patricia Trie](https://github.com/ethereum/wiki/wiki/Patricia-Tree) -except that it uses SHA3-256 instead of KECCAK-256. - - -#### Merkle List - -Root hash of the list is SHA3Sum256([MPT Node](#mpt-node)) of the root. -The key for the list is B_INT encoded index of the item. - - -#### Merkle Proof - -It's list of MPT Nodes from the root to the leaf containing the value. - - -#### MPT Node - -MPT Node is one of followings. -* MPT Leaf -* MPT Extension -* MPT Branch - - -#### MPT Branch - -> RLP List of followings - -| Field | Type | Description | -|:-----------|:----------------------|:-----------------------| -| Link(1~16) | [MPT Link](#mpt-link) | Link to the Nth child. | -| Value | RLP Bytes | Stored data | - - -#### MPT Leaf - -> RLP List of followings - -| Field | Type | Description | -|:-------|:----------|:---------------------------| -| Header | RLP Bytes | [Header](#mpt-node-header) | -| Value | RLP Bytes | Stored data | - - -#### MPT Extension - -> RLP List of followings - -| Field | Type | Description | -|:-------|:----------------------|:---------------------------| -| Header | RLP Bytes | [Header](#mpt-node-header) | -| Link | [MPT Link](#mpt-link) | Link to the child. | - - -#### MPT Link - -> RLP Bytes or MPT Node - -If encoded MPT Node is shorter than 32 bytes, then it's embedded in the link. -Otherwise, it would be RLP Bytes of SHA3Sum256([MPT Node](#mpt-node)) - - -#### MPT Node Header - -The key for the tree can be spliced into 4 bits nibbles. - -| Case | Prefix | Path | -|-----------------------------|--------|---------| -| Leaf with odd nibbles | 0x3 | Nibbles | -| Leaf with even nibbles | 0x20 | Nibbles | -| Extension with odd nibbles | 0x1 | Nibbles | -| Extension with even nibbles | 0x00 | Nibbles | - -> Examples - -| Case | Prefix | Path | Bytes | -|-----------------|--------|-------------|----------------| -| Leaf [A] | 0x3 | [0xA] | [ 0x3A ] | -| Extension [AB] | 0x00 | [0xAB] | [ 0x00, 0xAB ] | -| Extension [ABC] | 0x1 | [0xA, 0xBC] | [ 0x1A, 0xBC ] | - - diff --git a/doc/iconee.md b/doc/iconee.md deleted file mode 100644 index dc176e7..0000000 --- a/doc/iconee.md +++ /dev/null @@ -1,354 +0,0 @@ -# ICONEE (ICON Enterprise Edition) - -## Introduction - -***TODO*** - -## BMV Trust - -| Name | Type | Description | -|:------------|:----------------|:------------| -| NextHeight | Integer | | -| MerkleRoots | List of Bytes | | -| Validators | List of Address | | - - -## BMV Prove - -| Name | Type | Description | -|:--------------------|:--------------|:-------------------------------------------------------------------------------------------------------------------------------------------------| -| BlockHeader | Bytes | fips-sha3-256(BlockHeader) → *BlockID*
BlockHeader.Result.ReceiptRootHash → *ReceiptRootHash*
BlockHeader.Height → *BlockHeight*
| -| Votes | Bytes | [Prove with Votes](#prove-with-votes) | -| NextVaidators | Bytes | Validators = decode(NextValidators).ToAddress() | -| *BlockHeight* | Integer | Check BlockHeight == LastHeight | -| *BlockID* | Bytes | [Prove with MTA](#prove-with-mta) | -| BlockProof | List of Bytes | [Prove with MTA](#prove-with-mta) | -| ReceiptProofs | List of Bytes | [Prove with MPT](#prove-with-mpt) | -| *ReceiptRootHash* | Bytes | [Prove with MPT](#prove-with-mpt) | - -### Prove with Votes -```` -for VoteItem in Votes.Items { - VoteMessage = encode({ - Height: BlockHeader.Height - Round: Votes.Round - Type: 1 - BlockPartSetID: Votes.BlockPartSetID - BlockID: BlockID - Timestamp: VoteItem.Timestamp - }) - PublicKey = DeducePublicKey( - VoteItem.Signature, - fips-sha3-256(VoteMessage)) - ) - Check ToAddress(PublicKey) in Validators -} -```` - -### Prove with MTA -```` -MTA.Prove( - roots=MerkleRoots, - witness=BlockProof -) -```` - -### Prove with MPT -```` -for ReceiptProof in ReceiptProofs { - MPT.Prove( - key=encode(ReceiptProof.Index), - root=ReceiptRootHash - proofs=ReceiptProof.Proofs - ) → Receipt - - for EventProof in ReceiptProof.EventProofs { - MPT.Prove( - key=encode(EventProof.Index), - root=Receipt.EventLogHash - proofs=EventProof.Proofs - ) → EventLog - } -} -```` - -## Binary format - -ICONEE uses MsgPack and RLP with Null(RLPn) for binary encoding and decoding. - -* [MsgPack](https://msgpack.org) -* RLPn is [RLP](https://github.com/ethereum/wiki/wiki/RLP) with Null ( `[ 0xF8 0x00]` ) - -| Type | Msgpack | RLPn | Description | -|:----------|:--------|:---------|:----------------------------------------------------------------------------------------------------------------------------------| -| B_LIST | List | List | List of items | -| B_BYTES | Bytes | Bytes | Raw bytes | -| B_BIGINT | Bytes | Bytes | N bytes of integer representation.
ex)
0x00 → [ 0x00 ]
0x80 → [ 0x00 0x80 ]
-0x01 → [ 0xff ]
-0x80 → [ 0x80 ] | -| B_INT | Integer | B_BIGINT | 64bits signed integer | -| B_ADDRESS | Bytes | Bytes | 1 byte
- 0x00 ← EOA
- 0x01 ← SCORE
20 bytes : Identifier | -| B_NULL | Null | Null | B_BYTES(N), B_ADDRESS(N) or B_LIST(N) can be Null | - -Suffixed `(N)` means a nullable value. - -## RelayMessage - -> B_LIST of followings - -| Field | Type | Description | -|:--------------|:-----------|:---------------------------------------------------------------------------------------------------------------------------------------| -| BlockUpdates | B_LIST(N) | List of encoded bytes of the [BlockUpdate](#blockupdate). If there is no updates, it would be empty, then BlockProof must not be Null. | -| BlockProof | B_BYTES(N) | Encoded bytes of the [BlockProof](#blockproof). If it’s not Null, then BlockUpdates must be empty. | -| ReceiptProofs | B_LIST(N) | List of encoded bytes of the [ReceiptProof](#receiptproof). | - - -### BlockUpdate - -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:----------|:--------------------------------------------------------------------------| -| Header | B_BYTES | Encoded bytes of the [BlockHeader](#blockheader) | -| Votes | B_BYTES | Encoded bytes of the [Votes](#votes) | -| NextValidators | B_BYTES(N) | Encoded bytes of the [Validators](#validators). Null if it’s not changed. | - - -### BlockProof - -> B_LIST of followings - -| Field | Type | Description | -|:-------------|:--------|:-------------------------------------------------| -| Header | B_BYTES | Encoded bytes of the [BlockHeader](#blockheader) | -| BlockWitness | - | [BlockWitness](#blockwitness) | - - -### BlockWitness - -> B_LIST of followings - -| Field | Type | Description | -|:--------|:--------|:-------------------------------------------------------------------------------------------------| -| Height | B_BYTES | Encoded bytes of the [BlockHeader](#blockheader) | -| Witness | B_LIST | List of bytes. Only hashes of witness.Directions can be recovered by height of the block header. | - - -### ReceiptProof - -> B_LIST of followings - -| Field | Type | Description | -|:------------|:-------|:----------------------------------------------------------------------------------------------------------------------------| -| Index | B_INT | Index to the Receipt. | -| Proofs | B_LIST | List of [Merkle Proof](#merkle-proof) of receipt. [MPT Node](#mpt-node) including encoded bytes of the [Receipt](#receipt). | -| EventProofs | B_LIST | List of [EventProof](#eventproof). | - - -### EventProof - -> B_LIST of followings - -| Field | Type | Description | -|:-------|:-------|:----------------------------------------------------------------------------------------------------------------------------| -| Index | B_INT | Index to the EventLog. | -| Proofs | B_LIST | List of [Merkle Proof](#merkle-proof) of event. [MPT Node](#mpt-node) including encoded bytes of the [EventLog](#eventlog). | - - -### Block Header - -> B_LIST of followings - -| Field | Type | Description | -|:-----------------------|:-------------|:-------------------------------------------------| -| Version | B_INT | 1 ← Version 1 (legacy)
N ← Version N | -| Height | B_INT | Height of the block,
0 means genesis block. | -| Timestamp | B_INT | Micro-seconds after EPOCH | -| Proposer | B_ADDRESS(N) | Proposer of the block | -| PrevID | B_BYTES(N) | 32 bytes hash value | -| VotesHash | B_BYTES(N) | 32 bytes hash value | -| NextValidatorsHash | B_BYTES(N) | 32 bytes hash value | -| PatchTransactionsHash | B_BYTES(N) | 32 bytes hash value | -| NormalTransactionsHash | B_BYTES(N) | 32 bytes hash value | -| LogsBloom | B_BYTES | N(1~256) bytes bloom log value | -| Result | B_BYTES(N) | Encoded bytes of the [Result](#result) | - - -### Result - -> B_LIST of followings - -| Field | Type | Description | -|:------------------|:-----------|:------------------------------------------------------------| -| StateHash | B_BYTES(N) | Hash of world state (account information) | -| PatchReceiptHash | B_BYTES(N) | Root hash of [Merkle List](#merkle-list) of patch receipts | -| NormalReceiptHash | B_BYTES(N) | Root hash of [Merkle List](#merkle-list) of normal receipts | - - -### Validators - -> B_LIST of Validators - -| Field | Type | Description | -|:----------|:--------|:--------------------------------------------------------| -| Validator | B_BYTES | 21 bytes → same as Address
Other bytes → public key | - - -### Votes - -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:------------------------|:---------------------------------------------------------------------------| -| Round | B_INT | Round for votes.
If consensus doesn’t use round, it should be 0(zero). | -| BlockPartSetID | [PartSetID](#partsetid) | PartSetID of the proposed block | -| Items | B_LIST | List of [VoteItem](#voteitem) | - - -#### VoteItem - -> B_LIST of followings - -| Field | Type | Description | -|:----------|:--------|:--------------------------------------------------------------------| -| Timestamp | B_INT | Voted time in micro-seconds | -| Signature | B_BYTES | RSV format signature for [VoteMessage](#votemessage) by a validator | - -Public key of the validator can be recovered with `Signature` and -SHA3Sum256([VoteMessage](#votemessage)). - - -#### VoteMessage -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:------------------------|:----------------------------------------| -| Height | B_INT | [BlockHeader](#blockheader).Height | -| Round | B_INT | [Votes](#votes).Round | -| Type | B_INT | 0 ← PreVote
1 ← PreCommit | -| BlockID | B_BYTES(N) | SHA3Sum256([BlockHeader](#blockheader)) | -| BlockPartSetID | [PartSetID](#partsetid) | [Votes](#votes).BlockPartSetID. | -| Timestamp | B_INT | [VoteItem](#voteitem).Timestamp | - -`Type` field should be `1` for votes of a block. - - -#### PartSetID - -> B_LIST of followings - -| Field | Type | Description | -|:---------------|:-----------|:---------------------------------------------------------------------------| -| Count | B_INT | Number of block parts | -| Hash | B_BYTES(N) | Hash of block parts | - - -### Receipt - -> B_LIST of followings - -| Field | Type | Description | -|:-------------------|:-----------------------------------|:-----------------------------------------------------------------------------------------------| -| Status | B_INT | Result status
0 ← SUCCESS
N ← FAILURE ( N is failure code ) | -| To | B_ADDRESS | The target address of the transaction | -| CumulativeStepUsed | B_BIGINT | Cumulative step used | -| StepUsed | B_BIGINT | Step used | -| StepPrice | B_BIGINT | Step price in LOOP | -| LogsBloom | B_BIGINT | 2048 bits without padding zeros
So, if there is no bit, then it would be a byte with zero. | -| EventLogs | B_LIST(N) of [EventLog](#eventlog) | A list of event logs (empty if there is EventLogHash) | -| SCOREAddress | B_ADDRESS(N) | The address of deployed smart contract | -| EventLogHash | B_BYTES(O) | (from Revision7) Root hash of [Merkle List](#merkle-list) of eventLogs | - - -#### EventLog - -> B_LIST of followings - -| Field | Type | Description | -|:--------|:---------------------|:-------------------------------| -| Addr | B_ADDRESS | SCORE producing this event log | -| Indexed | B_LIST of B_BYTES(N) | Indexed data. | -| Data | B_LIST of B_BYTES(N) | Remaining data. | - - -### Merkle Patricia Trie - -It's similar to [Merkle Patricia Trie](https://github.com/ethereum/wiki/wiki/Patricia-Tree) -except that it uses SHA3-256 instead of KECCAK-256. - - -#### Merkle List - -Root hash of the list is SHA3Sum256([MPT Node](#mpt-node)) of the root. -The key for the list is B_INT encoded index of the item. - - -#### Merkle Proof - -It's list of MPT Nodes from the root to the leaf containing the value. - - -#### MPT Node - -MPT Node is one of followings. -* MPT Leaf -* MPT Extension -* MPT Branch - - -#### MPT Branch - -> RLP List of followings - -| Field | Type | Description | -|:-----------|:----------------------|:-----------------------| -| Link(1~16) | [MPT Link](#mpt-link) | Link to the Nth child. | -| Value | RLP Bytes | Stored data | - - -#### MPT Leaf - -> RLP List of followings - -| Field | Type | Description | -|:-------|:----------|:---------------------------| -| Header | RLP Bytes | [Header](#mpt-node-header) | -| Value | RLP Bytes | Stored data | - - -#### MPT Extension - -> RLP List of followings - -| Field | Type | Description | -|:-------|:----------------------|:---------------------------| -| Header | RLP Bytes | [Header](#mpt-node-header) | -| Link | [MPT Link](#mpt-link) | Link to the child. | - - -#### MPT Link - -> RLP Bytes or MPT Node - -If encoded MPT Node is shorter than 32 bytes, then it's embedded in the link. -Otherwise, it would be RLP Bytes of SHA3Sum256([MPT Node](#mpt-node)) - - -#### MPT Node Header - -The key for the tree can be spliced into 4 bits nibbles. - -| Case | Prefix | Path | -|-----------------------------|--------|---------| -| Leaf with odd nibbles | 0x3 | Nibbles | -| Leaf with even nibbles | 0x20 | Nibbles | -| Extension with odd nibbles | 0x1 | Nibbles | -| Extension with even nibbles | 0x00 | Nibbles | - -> Examples - -| Case | Prefix | Path | Bytes | -|-----------------|--------|-------------|----------------| -| Leaf [A] | 0x3 | [0xA] | [ 0x3A ] | -| Extension [AB] | 0x00 | [0xAB] | [ 0x00, 0xAB ] | -| Extension [ABC] | 0x1 | [0xA, 0xBC] | [ 0x1A, 0xBC ] | - - diff --git a/doc/iip-draft_btp.md b/doc/iip-draft_btp.md deleted file mode 100644 index 833d1ab..0000000 --- a/doc/iip-draft_btp.md +++ /dev/null @@ -1,715 +0,0 @@ ---- -iip: -title: ICON BTP Standard -author: MoonKyu Song (@mksong-icon) -discussions-to: MoonKyu Song (@mksong-icon) -status: Draft -type: Standard Track -category: IRC -created: 2020-03-04 ---- - -## Simple Summary - -Standard interfaces for contracts used in Blockchain Transmission Protocol(BTP) - -## Abstract - -Blockchain Transmission Protocol is used to deliver messages between blockchains. -A Relay delivers BTP messages between blockchains and smart contracts will verify and decode the delivered messages according to the services. -Complex and heavy functions of smart contracts can be shared if they are implemented according to standardized interfaces. Smart contracts are also more extensible staying compliant to the standards. - - -## Motivation - -BTP Messages from multiple services are delivered to multiple blockchains. -BTP smart contracts to support multiple services and blockchains. -BTP Message Center(BMC) is the center of smart contracts. - -For each blockchain, BTP Message Verifier(BMV) verifies the relay message and decodes it into standardized messages (BTP Messages). - -For each service, BTP Message Handler(BSH) handles received messages of the service and sends messages through the BTP Message Center(BMC). - - -## Specification - -### Terminology - -* [Network Address](#network-address) - - A string to identify blockchain network - -* [BTP Address](#btp-address) - - A string of URL for locating an account of the blockchain network - -* [Relay Message](#relay-message) - - A message that a relay sends to the blockchain. - -* [BTP Message](#btp-message) - - Standardized messages delivered between different blockchains - -* [BTP Message Center(BMC)](#btp-message-center) - - BMC accepts messages from a relay (Relay Messages). - A Relay Message contains standardized messages(BTP Messages) and proof of existence for these messages. - Corresponding BMV will verify and decode the Relay Message, then the BMC will process the BTP Messages. - - If the destination of the message isn't current BMC, then it's sent to the next BMC to reach its destination. - If current BMC is the destination, then it's dispatched to the corresponding BSH. - If the message cannot be processed, then it sends an error back to the source. - - -* [BTP Message Verifier(BMV)](#btp-message-verifier) - - BMV verifies a Relay Message and decodes it into BTP Messages. - - -* [BTP Service Handler(BSH)](#btp-service-handler) - - BSH handles BTP Messages of the service. It also sends messages according to different service scenarios. - -### Network Address - -A string to identify blockchain network - -``` -. -``` - -**Network System**: -Short name of the blockchain network system. - -| Name | Description | -|:-------|:---------------------| -| icon | Loopchain for ICON | -| iconee | Loopchain Enterprise | - -**NID**: -ID of the network in the blockchain network system. - -> Example - -| Network Address | Description | -|:----------------|:---------------------------------------------| -| `0x1.icon` | ICON Network with nid="0x1" <- ICON Main-Net | -| `0x1.iconee` | Loopchain Enterprise network with nid="0x1" | - -### BTP Address - -A string of URL for locating an account of the blockchain network - -> Example -``` -btp:/// -``` -**Account Identifier**: -Identifier of the account including smart contract. -It should be composed of URL safe characters except "."(dot). - -> Example -``` -btp://0x1.icon/hxc0007b426f8880f9afbab72fd8c7817f0d3fd5c0 -btp://0x1.iconee/cx429731644462ebcfd22185df38727273f16f9b87 -``` - -It could be expanded to other resources. - -### BTP Message - -A message delivered across blockchains. - -| Name | Type | Description | -|:-----|:--------|:-----------------------------------------------------| -| src | String | BTP Address of source BMC | -| dst | String | BTP Address of destination BMC | -| svc | String | name of the service | -| sn | Integer | serial number of the message | -| msg | Bytes | serialized bytes of Service Message or Error Message | - -if **sn** is negative, **msg** should be Error Message. -It would be serialized in [RLP serialization](#rlp-serialization). - - -### Error Message - -A message for delivering error information. - -| Name | Type | Description | -|:-----|:--------|:--------------| -| code | Integer | error code | -| msg | String | error message | - -It would be serialized in [RLP serialization](#rlp-serialization). - - -### RLP serialization - -For encoding [BTP Message](#btp-message) and [Error Message](#error-message), it uses Recursive Length Prefix (RLP). -RLP supports bytes and list naturally. -Here are some descriptions about other types. - -#### String - -It uses UTF-8 encoded bytes of the string. -There is no termination bytes. - -#### Integer - -It uses the shortest form of two's complemented bytes representations. -If it's negative, the highest bit of the first byte should be 1. - -> Example - -| Value | Encoded bytes | -|:------|:--------------| -| 0 | 0x00 | -| -1 | 0xff | -| -128 | 0x80 | - -### Relay Message - -It's used to deliver BTP Messages along with other required contents. Normally, it contains the following. - -* BTP Messages along with their proof of existence -* Trust information updates along with their proof of consensus - -The relay gathers the information through APIs of a source blockchain system and its internal database. The actual content of the message is decided according to the blockchain system and BMV implementation. - - -### BTP Message Center - -#### Introduction - -BTP Message Center is a smart contract that builds BTP Message and sends it to a relay and handles Relay Message from the other relay. It stores the following information. - -* Routing information - * Reachable networks and corresponding BMCs - * Next BMCs for reachable networks - * Directly connected networks - * Current network address -* Smart contracts - * BMV address for the directly connected network - * BSH address for the service - -#### Setup - -1. Registers [BSH](#btp-service-handler)s for the services. - (BSH should be deployed before the registration) -2. Registers [BMV](#btp-message-verifier)s for the directly connected blockchains. - (BMV should be deployed before the registration) -3. Adds links, BMCs of directly connected blockchains -4. Adds routes to other BMCs of in-directly connected blockchains - -#### Send a message - -BSH sends a message through [BMC.sendMessage](#sendmessage). It accepts only requests from the registered BTP Service Handler(BSH). If the service name of those requests is not in the service names of the BSH, then it will be rejected. - -Then it builds a BTP Message from the request. -1. Decides destination BMC from the given Network Address -2. Fills in other information from given parameters. -3. Serializes them for sending. - -Then it tries to send the BTP Message. -1. Decide next BMC from the destination referring routing information. -2. Get sequence number corresponding to the next. -3. Emit the event, [Message](#message) including the information. - -The event will be monitored by the Relay, it will build Relay Message -for next BMC. - -#### Receive a message - -It receives the Relay Message, then it tries to decode it with registered -BMV. It may contain multiple BTP Messages. -It dispatches received BTP Messages one-by-one in sequence. - -If it is the destination, then it tries to find the BSH for the -service, and then calls [BSH.handleBTPMessage](#handlebtpmessage). -It calls [BSH.handleBTPError](#handlebtperror) if it's an error. - -If it's not the destination, then it sends the message to -the next BMC reaching the destination. - -If it fails, then it replies an error. -BTP Message with error reply is composed of the following, -* sn : negated serial number of the message. -* dst : BTP Address of the source. -* src : BTP Address of the BMC. -* msg : Error Message including error code and message. - -#### Interface - -##### Writable methods - -###### handleRelayMessage -```python -@external -def handleRelayMessage(self, _prev: str, _msg: str): -``` -* Params - - _prev: String ( BTP Address of the previous BMC ) - - _msg: String ( base64 encoded string of serialized bytes of Relay Message ) -* Description: - - It verifies and decodes the Relay Message with BMV and dispatches BTP - Messages to registered BSHs. - - It's allowed to be called by the BMC. - -###### sendMessage -```python -@external -def sendMessage(self, _to: str, _svc: str, _sn: int, _msg: bytes): -``` -* Params - - _to: String ( Network Address of destination network ) - - _svc: String ( name of the service ) - - _sn: Integer ( serial number of the message, must be positive ) - - _msg: Bytes ( serialized bytes of Service Message ) -* Description: - - Sends the message to a specific network. - - Only allowed to be called by registered BSHs. - -###### addService -```python -@external -def addService(self, _svc: str, _addr: Address): -``` -* Params - - _svc: String (the name of the service) - - _addr: Address (the address of the smart contract handling the service) -* Description: - - Registers the smart contract for the service. - - Called by the operator to manage the BTP network. - -###### removeService -```python -@external -def removeService(self, _svc: str): -``` -* Params - - _svc: String (the name of the service) -* Description: - - De-registers the smart contract for the service. - - Called by the operator to manage the BTP network. - -###### addVerifier -```python -@external -def addVerifier(self, _net: str, _addr: Address): -``` -* Params - - _net: String (Network Address of the blockchain ) - - _addr: Address (the address of BMV) -* Description - - Registers BMV for the network. - - Called by the operator to manage the BTP network. - -###### removeVerifier -```python -@external -def removeVerifier(self, _net: str): -``` -* Params - - _net: String (Network Address of the blockchain ) -* Description - - De-registers BMV for the network. - - May fail if it's referred by the link. - - Called by the operator to manage the BTP network. - -###### addLink -```python -@external -def addLink(self, _link: str): -``` -* Params - - _link: String (BTP Address of connected BMC) -* Description - - If it generates the event related to the link, the relay shall - handle the event to deliver BTP Message to the BMC. - - If the link is already registered, or its network is already - registered then it fails. - - If there is no verifier related with the network of the link, - then it fails. - - Initializes status information for the link. - - Called by the operator to manage the BTP network. - -###### removeLink -```python -@external -def removeLink(self, _link: str): -``` -* Params - - link: String (BTP Address of connected BMC) -* Description - - Removes the link and status information. - - Called by the operator to manage the BTP network. - -###### addRoute -```python -@external -def addRoute(self, _dst: str, _link: str): -``` -* Params - - _dst: String ( BTP Address of the destination BMC ) - - _link: String ( BTP Address of the next BMC for the destination ) -* Description: - - Add route to the BMC. - - May fail if there more than one BMC for the network. - - Called by the operator to manage the BTP network. - -###### removeRoute -```python -@external -def removeRoute(self, _dst: str): -``` -* Params - - dst: String ( BTP Address of the destination BMC ) -* Description: - - Remove route to the BMC. - - Called by the operator to manage the BTP network. - -##### Read-only methods - -###### getServices -```python -@external(readonly=True) -def getServices(self) -> dict: -``` -* Description - - Get registered services. -* Returns - - A dictionary with the name of the service as key and address of the BSH - related to the service as value. - ```json - { - "token": "cx72eaed466599ca5ea377637c6fa2c5c0978537da" - } - ``` - -###### getVerifiers -```python -@external(readonly=True) -def getVerifiers(self) -> dict: -``` -* Description - - Get registered verifiers. -* Returns - - A dictionary with the Network Address as a key and smart contract - address of the BMV as a value. - ```json - { - "0x1.iconee": "cx72eaed466599ca5ea377637c6fa2c5c0978537da" - } - ``` - -###### getLinks -```python -@external(readonly=True) -def getLinks(self) -> list: -``` -* Description - - Get registered links. -* Returns - - A list of links ( BTP Addresses of the BMCs ) - ```json - [ "btp://0x1.iconee/cx9f8a75111fd611710702e76440ba9adaffef8656" ] - ``` - -###### getRoutes -```python -@external(readonly=True) -def getRoutes(self) -> dict: -``` -* Description: - - Get routing information. -* Return - - A dictionary with the BTP Address of the destination BMC as key and - the BTP Address of the next as value. - ```json - { - "btp://0x2.iconee/cx1d6e4decae8160386f4ecbfc7e97a1bc5f74d35b": "btp://0x1.iconee/cx9f8a75111fd611710702e76440ba9adaffef8656" - } - ``` - -###### getStatus -```python -@external(readonly=True) -def getStatus(self, _link: str) -> dict: -``` -* Params - - _link: String ( BTP Address of the connected BMC ) -* Description: - - Get status of BMC. - - Used by the relay to resolve next BTP Message to send. - - If target is not registered, it will fail. -* Return - - The object contains followings fields. - - | Field | Type | Description | - |:---------|:--------|:-------------------------------------------------| - | tx_seq | Integer | next sequence number of the next sending message | - | rx_seq | Integer | next sequence number of the message to receive | - | verifier | Object | status information of the BMV | - - -##### Events - -###### Message -```python -@eventlog(indexed=1) -def Message(self, _next: str, _seq: int, _msg: bytes): -``` -* Indexed: 1 -* Params - - _next: String ( BTP Address of the BMC to handle the message ) - - _seq: Integer ( sequence number of the message from current BMC to the next ) - - _msg: Bytes ( serialized bytes of BTP Message ) -* Description - - Sends the message to the next BMC. - - The relay monitors this event. - -### BTP Message Verifier - -#### Introduction - -BTP Message Verifier verifies and decodes Relay Messages to -[BTP Message](#btp-message)s. -A Relay Message is composed of both BTP Messages and with proof of -existence for these BTP Messages. - -For easy verification, it may update trust information for the -followed events. Most of the implementations may track the hashes of block -headers. - -If the blockchain system provides proof of absence of the -BTP Messages, then it's enough for the verifier to sustain the last state only. -It updates the hash only if it sees proof of absence of further -BTP Messages in the block. - -Most blockchain systems don't provide proof of absence for their data, therefore, it is mandatory to -provide methods to verify historical hashes. - -Merkle Accumulator can be used for verifying old hashes. -BMV sustains roots of Merkle Tree Accumulator, and relay -will sustain all elements of Merkle Tree Accumulator. The relay -may make the proof of any one of old hashes. -So, even if byzantine relay updated the trust information with the -proof of new block, normal relay can send BTP Messages in -the past block with the proof. - -#### Interface - -##### Writable methods - -###### BMV.handleRelayMessage -```python -@external -def handleRelayMessage(self, _bmc: str, _prev: str, _seq: int, _msg: bytes) -> list: -``` -* Description - - Decodes Relay Messages and process BTP Messages - - If there is an error, then it sends a BTP Message containing the - Error Message - - BTP Messages with old sequence numbers are ignored. A BTP Message contains future sequence number will fail. -* Params - - _bmc: String ( BTP Address of the BMC handling the message ) - - _prev: String ( BTP Address of the previous BMC ) - - _seq: Integer ( next sequence number to get a message ) - - _msg: Bytes ( serialized bytes of Relay Message ) -* Returns - - List of serialized bytes of a [BTP Message](#btp-message) - -### BTP Service Handler - -#### Introduction - -BSH can send messages through BTP Message Center(BMC) from any user -request, the request can also come from other smart contracts. -BSHs are also responsible for handling message from other BSHs. - -BSH can communicate with other BSHs with the same service name. -If there is already a service using the same name, then it should choose -a different name for the service when registering a new service. -If the intention is to become a part of the service, then it should -use same name. BSH follows the protocol of the service. - -Before a BSH is registered to the BMC, it's unable to send messages, and unable to handle messages from others. -To become a BSH, following criteria must be met, - -1. Implements the interface -2. Registered to the BMC through [BMC.addService](#addservice) - -After registration, it can send messages through -[BMC.sendMessage](#sendmessage). -If there is an error while delivering message, BSH will -return error information though [handleBTPError](#handlebtperror). -If messages are successfully delivered, BMC will call -[handleBTPMessage](#handlebtpmessage) of the target BSH. -While processing the message, it can reply though -[BMC.sendMessage](#sendmessage). - -#### Security - -BSH should not handle messages or errors from other contract -except BMC. -BMC also accepts only the service messages from registered BSH. -BSH can have other APIs, but APIs related with BMC are -only called by BMC. - -#### Interface - -##### Writable methods - -###### handleBTPMessage -```python -@external -def handleBTPMessage(self, _from: str, _svc: str, _sn: int, _msg: bytes): -``` -* Description - - Handles BTP Messages from other blockchains. - - Accepts messages only from BMC. - - If it fails, then BMC will generate a BTP Message that includes - error information, then delivered to the source. -* Params - - _from: String ( Network Address of source network ) - - _svc: String ( name of the service ) - - _sn: Integer ( serial number of the message ) - - _msg: Bytes ( serialized bytes of ServiceMessage ) - -###### handleBTPError -```python -@external -def handleBTPError(self, _src: str, _svc: str, _sn: int, _code: int, _msg: str): -``` -* Description - - Handle the error on delivering the message. - - Accept the error only from the BMC. -* Params - - _src: String ( BTP Address of BMC that generated the error ) - - _svc: String ( name of the service ) - - _sn: Integer ( serial number of the original message ) - - _code: Integer ( code of the error ) - - _msg: String ( message of the error ) - - -### Message delivery flow - -![Components](./img/btp_components.svg) - -1. BSH sends a Service Message through BMC. - - * BSH calls [BMC.sendMessage](#sendmessage) with followings. - - | Name | Type | Description | - |:--------|:--------|:----------------------------------------------| - | _to | String | Network Address of the destination blockchain | - | _svc | String | Name of the service. | - | _sn | Integer | Serial number of the message. | - | _msg | Bytes | Service message to be delivered. | - - * BMC lookup the destination BMC belonging to *_to*. - If there is no known BMC to the network, then it will fail. - - * BMC builds a BTP Message. - - | Name | Type | Description | - |:-----|:--------|:----------------------------------------------| - | src | String | BTP Address of current BMC | - | dst | String | BTP Address of destination BMC in the network | - | svc | String | Given service name | - | sn | Integer | Given serial number | - | msg | Bytes | Given service message | - - * BMC decide the next BMC according to the destination. - If there is no route to the destination BMC. - - * BMC generates an event with BTP Message. - - | Name | Type | Description | - |:------|:--------|:-------------------------------------------| - | _next | String | BTP Address of the next BMC | - | _seq | Integer | Sequence number of the msg to the next BMC | - | _msg | Bytes | Serialized BTP Message | - -2. The BTP Message Relay(BMR) detects events. - * Relay detects [BMC.Message](#message) through various ways. - * Relay can confirm that it occurs and it's finalized. - -3. BMR gathers proofs - * Relay gathers proofs of the event(POE)s - - Proof for the new block - - Proof for the event in the block - * Relay builds Relay Message including the following, - - Proof of new events - - New events including the BTP Message. - * Relay calls [BMC.handleRelayMessage](#handlerelaymessage) - with built Relay Message. - - | Name | Type | Description | - |:------|:-------|:------------------------------------------------| - | _prev | String | BTP Address of the previous BMC | - | _msg | Bytes | serialized Relay Message including BTP Messages | - -4. BMC handles Relay Message - - * It finds BMV for the network address of the previous BMC. - * It gets the sequence number of the next message from the source network. - * BMC calls [BMV.handleRelayMessage](#bmvhandlerelaymessage) - to decode Relay Message and gets a list of BTP Messages. - - | Name | Type | Description | - |:------|:--------|:----------------------------------------------------------| - | _bmc | String | BTP Address of the current BMC | - | _prev | String | BTP Address of given previous BMC | - | _seq | Integer | Next sequence number of the BTP Message from previous BMC | - | _msg | Bytes | The Relay Message | - -5. BMV decodes Relay Message - - * Verifies and decodes Relay Messages, then returns a list of - BTP Messages. - * If verification of the message is unsuccessful, it fails. - * The events from the previous BMC to the current BMC will be processed. - * The events should have proper sequence number, otherwise it fails. - -6. BSH handles Service Messages - - * BMC dispatches BTP Messages. - * If the destination BMC isn't current one, then it locates - the next BMC and generates the event. - * If the destination BMC is the current one, then it locates BSH - for the service of the BTP Message. - * Calls [BSH.handleBTPMessage](#handlebtpmessage) if - the message has a positive value as *_sn*. - - | Name | Type | Description | - |:------|:--------|:--------------------------------------| - | _from | String | Network Address of the source network | - | _svc | String | Given service name | - | _sn | Integer | Given serial number | - | _msg | Bytes | Given service message | - - * Otherwise, it calls [BSH.handleBTPError](#handlebtperror). - - | Name | Type | Description | - |:------|:--------|:-----------------------------------------------| - | _src | String | BTP Address of the BMC that generated the error| - | _svc | String | Given service name | - | _sn | Integer | Given serial number | - | _code | Integer | Given error code | - | _msg | String | Given error message | - - -## Rationale - - - -## Implementation - - -## Copyright -Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). \ No newline at end of file diff --git a/doc/img/btp_components.svg b/doc/img/btp_components.svg deleted file mode 100644 index c18b014..0000000 --- a/doc/img/btp_components.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/doc/relay_cli.md b/doc/relay_cli.md new file mode 100644 index 0000000..739fdbf --- /dev/null +++ b/doc/relay_cli.md @@ -0,0 +1,182 @@ +# Relay + +## Description + +Command Line Interface of Relay for Blockchain Transmission Protocol + +## Usage + +` relay [flags] ` + +### Options + +| Name,shorthand | Environment Variable | Required | Default | Description | +|-------------------------|-----------------------------|----------|---------|-------------------------------------------------------------| +| --base_dir | RELAY_BASE_DIR | false | | Base directory for data | +| --src_config | RELAY_SOURCE_CONFIG | false | | Source network configuration | +| --dst_config | RELAY_DESTINATION_CONFIG | false | | Destination network configuration | +| --direction | RELAY_DIRECTION | false | | Relay network direction (both,front,reverse) | +| --config, -c | RELAY_CONFIG | false | | Parsing configuration file | +| --console_level | RELAY_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | +| --log_forwarder.address | RELAY_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | +| --log_forwarder.level | RELAY_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | +| --log_forwarder.name | RELAY_LOG_FORWARDER_NAME | false | | LogForwarder name | +| --log_forwarder.options | RELAY_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | +| --log_forwarder.vendor | RELAY_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | +| --log_level | RELAY_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | +| --log_writer.compress | RELAY_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | +| --log_writer.filename | RELAY_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | +| --log_writer.localtime | RELAY_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | +| --log_writer.maxage | RELAY_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | +| --log_writer.maxbackups | RELAY_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | +| --log_writer.maxsize | RELAY_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | + +### Child commands + +| Command | Description | +|---------------------------------|---------------------| +| [relay save](#RELAY-save) | Save configuration | +| [relay start](#RELAY-start) | Start server | +| [relay version](#RELAY-version) | Print relay version | + +## Relay save + +### Description + +Save configuration + +### Usage + +` relay save [file] [flags] ` + +### Inherited Options + +| Name,shorthand | Environment Variable | Required | Default | Description | +|-------------------------|-----------------------------|----------|---------|-------------------------------------------------------------| +| --base_dir | RELAY_BASE_DIR | false | | Base directory for data | +| --src_config | RELAY_SOURCE_CONFIG | false | | Source network configuration | +| --dst_config | RELAY_DESTINATION_CONFIG | false | | Destination network configuration | +| --direction | RELAY_DIRECTION | false | | Relay network direction (both,front,reverse) | +| --config, -c | RELAY_CONFIG | false | | Parsing configuration file | +| --console_level | RELAY_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | +| --log_forwarder.address | RELAY_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | +| --log_forwarder.level | RELAY_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | +| --log_forwarder.name | RELAY_LOG_FORWARDER_NAME | false | | LogForwarder name | +| --log_forwarder.options | RELAY_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | +| --log_forwarder.vendor | RELAY_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | +| --log_level | RELAY_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | +| --log_writer.compress | RELAY_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | +| --log_writer.filename | RELAY_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | +| --log_writer.localtime | RELAY_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | +| --log_writer.maxage | RELAY_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | +| --log_writer.maxbackups | RELAY_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | +| --log_writer.maxsize | RELAY_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | + +### Parent command + +| Command | Description | +|-----------------|---------------| +| [relay](#RELAY) | BTP Relay CLI | + +### Related commands + +| Command | Description | +|---------------------------------|---------------------| +| [relay save](#relay-save) | Save configuration | +| [relay start](#relay-start) | Start server | +| [relay version](#relay-version) | Print relay version | + +## Relay start + +### Description + +Start server + +### Usage + +` RELAY start [flags] ` + +### Inherited Options + +| Name,shorthand | Environment Variable | Required | Default | Description | +|-------------------------|-----------------------------|----------|---------|-------------------------------------------------------------| +| --base_dir | RELAY_BASE_DIR | false | | Base directory for data | +| --src_config | RELAY_SOURCE_CONFIG | false | | Source network configuration | +| --dst_config | RELAY_DESTINATION_CONFIG | false | | Destination network configuration | +| --direction | RELAY_DIRECTION | false | | Relay network direction (both,front,reverse) | +| --config, -c | RELAY_CONFIG | false | | Parsing configuration file | +| --console_level | RELAY_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | +| --log_forwarder.address | RELAY_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | +| --log_forwarder.level | RELAY_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | +| --log_forwarder.name | RELAY_LOG_FORWARDER_NAME | false | | LogForwarder name | +| --log_forwarder.options | RELAY_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | +| --log_forwarder.vendor | RELAY_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | +| --log_level | RELAY_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | +| --log_writer.compress | RELAY_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | +| --log_writer.filename | RELAY_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | +| --log_writer.localtime | RELAY_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | +| --log_writer.maxage | RELAY_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | +| --log_writer.maxbackups | RELAY_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | +| --log_writer.maxsize | RELAY_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | + +### Parent command + +| Command | Description | +|-----------------|---------------| +| [relay](#RELAY) | BTP Relay CLI | + +### Related commands + +| Command | Description | +|---------------------------------|---------------------| +| [relay save](#relay-save) | Save configuration | +| [relay start](#relay-start) | Start server | +| [relay version](#relay-version) | Print relay version | + +## Relay version + +### Description + +Print relay version + +### Usage + +` relay version ` + +### Inherited Options + +| Name,shorthand | Environment Variable | Required | Default | Description | +|-------------------------|-----------------------------|----------|---------|-------------------------------------------------------------| +| --base_dir | RELAY_BASE_DIR | false | | Base directory for data | +| --src_config | RELAY_SOURCE_CONFIG | false | | Source network configuration | +| --dst_config | RELAY_DESTINATION_CONFIG | false | | Destination network configuration | +| --direction | RELAY_DIRECTION | false | | Relay network direction (both,front,reverse) | +| --config, -c | RELAY_CONFIG | false | | Parsing configuration file | +| --console_level | RELAY_CONSOLE_LEVEL | false | trace | Console log level (trace,debug,info,warn,error,fatal,panic) | +| --log_forwarder.address | RELAY_LOG_FORWARDER_ADDRESS | false | | LogForwarder address | +| --log_forwarder.level | RELAY_LOG_FORWARDER_LEVEL | false | info | LogForwarder level | +| --log_forwarder.name | RELAY_LOG_FORWARDER_NAME | false | | LogForwarder name | +| --log_forwarder.options | RELAY_LOG_FORWARDER_OPTIONS | false | [] | LogForwarder options, comma-separated 'key=value' | +| --log_forwarder.vendor | RELAY_LOG_FORWARDER_VENDOR | false | | LogForwarder vendor (fluentd,logstash) | +| --log_level | RELAY_LOG_LEVEL | false | debug | Global log level (trace,debug,info,warn,error,fatal,panic) | +| --log_writer.compress | RELAY_LOG_WRITER_COMPRESS | false | false | Use gzip on rotated log file | +| --log_writer.filename | RELAY_LOG_WRITER_FILENAME | false | | Log file name (rotated files resides in same directory) | +| --log_writer.localtime | RELAY_LOG_WRITER_LOCALTIME | false | false | Use localtime on rotated log file instead of UTC | +| --log_writer.maxage | RELAY_LOG_WRITER_MAXAGE | false | 0 | Maximum age of log file in day | +| --log_writer.maxbackups | RELAY_LOG_WRITER_MAXBACKUPS | false | 0 | Maximum number of backups | +| --log_writer.maxsize | RELAY_LOG_WRITER_MAXSIZE | false | 100 | Maximum log file size in MiB | + +### Parent command + +| Command | Description | +|-----------------|---------------| +| [relay](#RELAY) | BTP Relay CLI | + +### Related commands + +| Command | Description | +|---------------------------------|---------------------| +| [relay save](#RELAY-save) | Save configuration | +| [relay start](#RELAY-start) | Start server | +| [relay version](#RELAY-version) | Print RELAY version | + diff --git a/doc/tutorial.md b/doc/tutorial.md deleted file mode 100644 index 4a0e6b9..0000000 --- a/doc/tutorial.md +++ /dev/null @@ -1,741 +0,0 @@ -# Tutorial - -## Introduction -This document describes how to setup a BTP network and interchain token transfer scenario. - -## Preparation - -### Requirements -* [Docker](https://docs.docker.com) -* goloop v0.9.6 or later - -### blockchain -1. Start the server -```console -$ export CONFIG_DIR=/path/to/config -$ docker run -d --name goloop -p 9080:9080 \ - -e GOLOOP_LOGFILE=/goloop/data/log/goloop.log \ - -v ${CONFIG_DIR}:/goloop/config \ - iconloop/goloop-icon -``` -for follows, execute under `docker exec -ti --workdir /goloop/config goloop sh`. - -install jq -```console -# apk add jq -``` - -2. Create genesis - -```console -# goloop gn gen --out src.genesis.json $GOLOOP_KEY_STORE -# goloop gn gen --out dst.genesis.json $GOLOOP_KEY_STORE -``` - -modify genesis for javaee -```console -# echo $(cat src.genesis.json | jq -r '.*{"chain":{"fee":{"stepLimit":{"invoke":"0x10000000","query":"0x1000000"}}}}') > src.genesis.json -# echo $(cat dst.genesis.json | jq -r '.*{"chain":{"fee":{"stepLimit":{"invoke":"0x10000000","query":"0x1000000"}}}}') > dst.genesis.json -``` - -3. Join the chain - -```console -# goloop chain join --genesis_template src.genesis.json --channel src -# goloop chain join --genesis_template dst.genesis.json --channel dst -``` - -4. Start the chain - -```console -# goloop chain start src -# goloop chain start dst -``` - -5. Configure for debugging - -set log level to `trace` in `${CONFIG_DIR}/server.json` -``` -{ - ...skip... - "log_level": "trace", - "console_level": "trace" -} -``` -> restart goloop container to apply changes - -set debug config to get smart-contract log with `goloop debug trace txhash` -```console -# goloop system config rpcIncludeDebug true -``` - -> log file located in `/goloop/data/log` - -## Deploy Smart Contracts -### Package -zip each BTP-Smart-Contracts from project source, and copy files to `/path/to/config` which is mounted with `/goloop/config` of goloop container - -package for javascore/bmc -```console -$ make dist-java -$ mkdir -p ${CONFIG_DIR}/javascore -$ cp build/contracts/javascore/*.jar ${CONFIG_DIR}/javascore/ -``` - -### Environment for JSON-RPC -To use `goloop` as json-rpc client, execute shell via `docker exec -ti --workdir /goloop/config goloop sh` on goloop container. -For parse json-rpc response, install jq via `apk add jq` to goloop container. -Prepare 'rpc.sh' file as below, and apply by `source rpc.sh`. -Set keystore for json-rpc by `rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET` -```shell -rpchelp() { - echo "rpcch CHANNEL" - echo "rpcks KEYSTORE_PATH" -} - -rpcch() { - if [ ! "$1" == "" ]; then - export GOLOOP_RPC_CHANNEL=$1 - URI_PREFIX=http://$(goloop system info -f '{{.Setting.RPCAddr}}')/api - export GOLOOP_RPC_URI=$URI_PREFIX/v3/$GOLOOP_RPC_CHANNEL - export GOLOOP_RPC_NID=$(goloop chain inspect $GOLOOP_RPC_CHANNEL --format {{.NID}}) - export GOLOOP_DEBUG_URI=$URI_PREFIX/v3d/$GOLOOP_RPC_CHANNEL - export GOLOOP_RPC_STEP_LIMIT=${GOLOOP_RPC_STEP_LIMIT:-0x10000000} - fi - echo $GOLOOP_RPC_CHANNEL -} - -rpcks() { - if [ ! "$1" == "" ]; then - export GOLOOP_RPC_KEY_STORE=$1 - if [ ! "$2" == "" ]; then - if [ -f "$2" ]; then - export GOLOOP_RPC_KEY_SECRET=$2 - else - export GOLOOP_RPC_KEY_PASSWORD=$2 - fi - fi - fi - echo $GOLOOP_RPC_KEY_STORE -} - -export GOLOOP_CHAINSCORE=cx0000000000000000000000000000000000000000 -``` - -### BMC -Deploy BMC contract to 'src' chain -```console -# rpcch src -# echo "$GOLOOP_RPC_NID.icon" > net.btp.$(rpcch) -# goloop rpc sendtx deploy javascore/bmc.jar --content_type application/java \ - --param _net=$(cat net.btp.$(rpcch)) | jq -r . > tx.bmc.$(rpcch) -``` - -Extract BMC contract address from deploy result -```console -# goloop rpc txresult $(cat tx.bmc.$(rpcch)) | jq -r .scoreAddress > bmc.$(rpcch) -``` - -Create BTP-Address -```console -# echo "btp://$(cat net.btp.$(rpcch))/$(cat bmc.$(rpcch))" > btp.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst'. -```console -# rpcch dst -# echo "$GOLOOP_RPC_NID.icon" > net.btp.$(rpcch) -# goloop rpc sendtx deploy javascore/bmc.jar --content_type application/java \ - --param _net=$(cat net.btp.$(rpcch)) | jq -r . > tx.bmc.$(rpcch) -# sleep 2 -# goloop rpc txresult $(cat tx.bmc.$(rpcch)) | jq -r .scoreAddress > bmc.$(rpcch) -# echo "btp://$(cat net.btp.$(rpcch))/$(cat bmc.$(rpcch))" > btp.$(rpcch) -``` - -### BMV -To create parameters for deploy BMV contract -```console -# rpcch dst -# goloop rpc call --to $GOLOOP_CHAINSCORE --method getValidators| jq -r 'map(.)|join(",")' > validators.$(rpcch) -# echo "0x$(printf %x $(goloop chain inspect $(rpcch) --format {{.Height}}))" > offset.$(rpcch) -``` - -Deploy BMV contract to 'src' chain -```console -# rpcch src -# goloop rpc sendtx deploy javascore/bmv-icon.jar --content_type application/java \ - --param _bmc=$(cat bmc.$(rpcch)) \ - --param _net=$(cat net.btp.dst) \ - --param _validators=$(cat validators.dst) \ - --param _offset=$(cat offset.dst) \ - | jq -r . > tx.bmv.$(rpcch) -``` - -Extract BMV contract address from deploy result -```console -# goloop rpc txresult $(cat tx.bmv.$(rpcch)) | jq -r .scoreAddress > bmv.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst' and 'dst' to 'src'. -```console -# rpcch src -# goloop rpc call --to $GOLOOP_CHAINSCORE --method getValidators| jq -r 'map(.)|join(",")' > validators.$(rpcch) -# echo "0x$(printf %x $(goloop chain inspect $(rpcch) --format {{.Height}}))" > offset.$(rpcch) -# rpcch dst -# goloop rpc sendtx deploy javascore/bmv-icon.jar --content_type application/java \ - --param _bmc=$(cat bmc.$(rpcch)) \ - --param _net=$(cat net.btp.src) \ - --param _validators=$(cat validators.src) \ - --param _offset=$(cat offset.src) \ - | jq -r . > tx.bmv.$(rpcch) -sleep 2 -# goloop rpc txresult $(cat tx.bmv.$(rpcch)) | jq -r .scoreAddress > bmv.$(rpcch) -``` - -### Token-BSH -Deploy Token-BSH contract to 'src' chain -```console -# rpcch src -# goloop rpc sendtx deploy javascore/bsh.jar --content_type application/java \ - --param _bmc=$(cat bmc.$(rpcch)) | jq -r . > tx.token.$(rpcch) -``` - -Extract Token-BSH contract address from deploy result -```console -# goloop rpc txresult $(cat tx.token.$(rpcch)) | jq -r .scoreAddress > token.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst'. -```console -# rpcch dst -# goloop rpc sendtx deploy javascore/bsh.jar --content_type application/java \ - --param _bmc=$(cat bmc.$(rpcch)) | jq -r . > tx.token.$(rpcch) -# goloop rpc txresult $(cat tx.token.$(rpcch)) | jq -r .scoreAddress > token.$(rpcch) -``` - -### IRC-2.0 Token -Deploy IRC-2.0 Token contract to 'src' chain -```console -# rpcch src -# goloop rpc sendtx deploy javascore/irc2.jar --content_type application/java \ - --param _name=IRC2Token \ - --param _symbol=I2T \ - --param _initialSupply=1000 \ - --param _decimals=18 \ - | jq -r . > tx.irc2.$(rpcch) -``` - -Extract IRC-2.0 Token contract address from deploy result -```console -# goloop rpc txresult $(cat tx.irc2.$(rpcch)) | jq -r .scoreAddress > irc2.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst' and add `_owner` parameter. because IRC-2.0 Token contract of 'dst' chain is proxy. -```console -# rpcch dst -# goloop rpc sendtx deploy javascore/irc2.jar --content_type application/java \ - --param _name=IRC2Token \ - --param _symbol=I2T \ - --param _initialSupply=0x3E8 \ - --param _decimals=0x12 \ - | jq -r . > tx.irc2.$(rpcch) -# goloop rpc txresult $(cat tx.irc2.$(rpcch)) | jq -r .scoreAddress > irc2.$(rpcch) -``` - -### Fee aggregator -Deploy Fee aggregator -```console -# rpcch src -# goloop rpc sendtx deploy javascore/fee-aggregation.jar --content_type application/java \ - --param _cps_address=$(cat keystore.json | jq -r .address) \ - --param _band_protocol_address=$(cat keystore.json | jq -r .address) \ - | jq -r . > tx.feeaggr.$(rpcch) -``` - -Extract Fee aggregator contract address from deploy result -```console -# goloop rpc txresult $(cat tx.feeaggr.$(rpcch)) | jq -r .scoreAddress > feeaggr.$(rpcch) -``` - - -## Configuration - -### Register BMV -Register verifier of 'dst' chain to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addVerifier \ - --param _net=$(cat net.btp.dst) \ - --param _addr=$(cat bmv.$(rpcch)) \ - | jq -r . > tx.verifier.$(rpcch) -``` - -Register verifier of 'src' chain to 'dst' chain -```console -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addVerifier \ - --param _net=$(cat net.btp.src) \ - --param _addr=$(cat bmv.$(rpcch)) \ - | jq -r . > tx.verifier.$(rpcch) -``` - -### Register Link -Register BTP-Address of 'dst' chain to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addLink \ - --param _link=$(cat btp.dst) \ - | jq -r . > tx.link.$(rpcch) -``` - -Register BTP-Address of 'src' chain to 'dst' chain -```console -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addLink \ - --param _link=$(cat btp.src) \ - | jq -r . > tx.link.$(rpcch) -``` - -> To retrieve list of registered links, use `getLinks` method of BMC. -> ```console -> # goloop rpc call --to $(cat bmc.$(rpcch)) --method getLinks -> ``` - -### Configure Link -To use multiple-BMR for relay, should set properties of link via `BMC.setLinkRotateTerm` - -Set properties of 'dst' link to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method setLinkRotateTerm \ - --param _link=$(cat btp.dst) \ - --param _block_interval=0x3e8 \ - --param _max_agg=0x10 \ - | jq -r . > tx.setlink.$(rpcch) -``` - -Set properties of 'src' link to 'dst' chain -```console -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method setLinkRotateTerm \ - --param _link=$(cat btp.src) \ - --param _block_interval=0x3e8 \ - --param _max_agg=0x10 \ - | jq -r . > tx.setlink.$(rpcch) -``` - -> To retrieve properties of link, use `getStatus(_link)` method of BMC. -> -> ```console -> # rpcch src -> # goloop rpc call --to $(cat bmc.src) --method getStatus --param _link=$(cat btp.dst) -> -> # rpcch dst -> # goloop rpc call --to $(cat bmc.dst) --method getStatus --param _link=$(cat btp.src) -> ``` - -### Register Token-BSH -Register Token service to BMC -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addService \ - --param _svc=TokenBSH \ - --param _addr=$(cat token.$(rpcch)) | jq -r . > tx.service.token.$(rpcch) - -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addService \ - --param _svc=TokenBSH \ - --param _addr=$(cat token.$(rpcch)) | jq -r . > tx.service.token.$(rpcch) -``` - -### Register IRC2Token -Register IRC 2.0 Token contract to Token-BSH -```console -# rpcch src -# goloop rpc sendtx call --to $(cat token.$(rpcch)) \ - --method register \ - --param name=IRC2Token \ - --param symbol=I2T \ - --param feeNumerator=0x64 \ - --param decimals=0x12 \ - --param address=$(cat irc2.$(rpcch)) - -# rpcch dst -# goloop rpc sendtx call --to $(cat token.$(rpcch)) \ - --method register \ - --param name=IRC2Token \ - --param symbol=I2T \ - --param feeNumerator=0x64 \ - --param decimals=0x12 \ - --param address=$(cat irc2.$(rpcch)) -``` - -> To retrieve list of registered token, use `tokenNames` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.$(rpcch)) --method tokenNames -> ``` - -### Register BMC-Owner and BMR -Create key store for BMC-Owner, BMR of both chain -```console -# echo -n $(date|md5sum|head -c16) > src.secret -# goloop ks gen -o src.ks.json -p $(cat src.secret) -# echo -n $(date|md5sum|head -c16) > dst.secret -# goloop ks gen -o dst.ks.json -p $(cat dst.secret) -``` - -Register BMC-Owner to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addOwner \ - --param _addr=$(jq -r .address $(rpcch).ks.json) -``` - -BMC-Owner register BMR to 'src' chain (Address of BMR could be any keystore) -```console -# rpcks src.ks.json src.secret -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addRelay \ - --param _link=$(cat btp.dst) \ - --param _addr=$(jq -r .address dst.ks.json) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst' -```console -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addOwner \ - --param _addr=$(jq -r .address $(rpcch).ks.json) -# rpcks dst.ks.json dst.secret -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addRelay \ - --param _link=$(cat btp.src) \ - --param _addr=$(jq -r .address src.ks.json) -``` - -> To retrieve list of registered BMC-Owners, use `getOwners` method of BMC. -> ```console -> # goloop rpc call --to $(cat bmc.$(rpcch)) --method getOwners -> ``` - -> To retrieve list of registered relay of link, use `getRelays(_link)` method of BMC. -> -> ```console -> # rpcch src -> # goloop rpc call --to $(cat bmc.src) --method getRelays --param _link=$(cat btp.dst) -> -> # rpcch dst -> # goloop rpc call --to $(cat bmc.dst) --method getRelays --param _link=$(cat btp.src) -> ``` - -### Register fee aggregator -Register Fee aggreator to BMC -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method setFeeAggregator \ - --param _addr=$(cat feeaggr.$(rpcch)) \ - | jq -r . > tx.setFeeAggr.$(rpcch) -``` - -> Get registered contract address of Fee aggregator -> ```console -> # goloop rpc call --to $(cat bmc.$(rpcch)) \ -> --method getFeeAggregator -> ``` - -### Register relayer candidate : only for testing of ICON main network environment -Create key store for relayer -```console -# echo -n $(date|md5sum|head -c16) > relayer.secret -# goloop ks gen -o relayer.ks.json -p $(cat relayer.secret) -``` - -To register relayer candidate, bonding is required. -The account of 'god' transfer some icx to account of relayer candidate. -Assume 'src' chain as ICON -```console -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# rpcch src -# goloop rpc sendtx transfer --to $(jq -r .address relayer.ks.json) --value 0x10 -``` - -Register to 'src' chain -```console -# rpcch src -# rpcks relayer.ks.json relayer.secret -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method registerRelayer \ - --param _desc="first candidate for relayer" \ - --value 0x10 -``` - -> To retrieve list of registered relayers, use `getRelayers` method of BMC. -> -> ```console -> # goloop rpc call --to $(cat bmc.src) --method getRelayers -> ``` - -## Shortcut deploy and configuration -To make it easier to deploy and configuration -```console -$ cp scprits/provision.sh config/provision.sh -``` - -in goloop docker -```console -# source provision.sh -# deploy_all -deploy all -... -# register_all -register all -... -``` - -> Now you can check deploy result in `src_result.json` and `dst_result.json` - - -## Start relay - -Prepare 'btpsimple' docker image via `make btpsimple-image` - -Start relay 'src' chain to 'dst' chain -```console -$ docker run -d --name btpsimple_src --link goloop \ - -v ${CONFIG_DIR}:/btpsimple/config \ - -e BTPSIMPLE_CONFIG=/btpsimple/config/src.config.json \ - -e BTPSIMPLE_SRC_ADDRESS=$(cat ${CONFIG_DIR}/btp.src) \ - -e BTPSIMPLE_SRC_ENDPOINT=http://goloop:9080/api/v3/src \ - -e BTPSIMPLE_DST_ADDRESS=$(cat ${CONFIG_DIR}/btp.dst) \ - -e BTPSIMPLE_DST_ENDPOINT=http://goloop:9080/api/v3/dst \ - -e BTPSIMPLE_OFFSET=$(cat ${CONFIG_DIR}/offset.src) \ - -e BTPSIMPLE_KEY_STORE=/btpsimple/config/src.ks.json \ - -e BTPSIMPLE_KEY_SECRET=/btpsimple/config/src.secret \ - btpsimple -``` - -For relay of 'dst' chain, same flows with replace 'src' to 'dst' and 'dst' to 'src'. -```console -$ docker run -d --name btpsimple_dst --link goloop \ - -v ${CONFIG_DIR}:/btpsimple/config \ - -e BTPSIMPLE_CONFIG=/btpsimple/config/dst.config.json \ - -e BTPSIMPLE_SRC_ADDRESS=$(cat ${CONFIG_DIR}/btp.dst) \ - -e BTPSIMPLE_SRC_ENDPOINT=http://goloop:9080/api/v3/dst \ - -e BTPSIMPLE_DST_ADDRESS=$(cat ${CONFIG_DIR}/btp.src) \ - -e BTPSIMPLE_DST_ENDPOINT=http://goloop:9080/api/v3/src \ - -e BTPSIMPLE_OFFSET=$(cat ${CONFIG_DIR}/offset.dst) \ - -e BTPSIMPLE_KEY_STORE=/btpsimple/config/dst.ks.json \ - -e BTPSIMPLE_KEY_SECRET=/btpsimple/config/dst.secret \ - btpsimple -``` - -> To retrieve status of relay, use `getStatus(_link)` method of BMC. -> ```console -> # rpcch src -> # goloop rpc call --to $(cat bmc.src) --method getStatus --param _link=$(cat btp.dst) -> -> # rpcch dst -> # goloop rpc call --to $(cat bmc.dst) --method getStatus --param _link=$(cat btp.src) -> ``` - -## Interchain Token Transfer -> To use `goloop` as json-rpc client, execute shell via `docker exec -ti --workdir /goloop/config goloop sh` on goloop container. - -Create key store for Alice and Bob -```console -# echo -n $(date|md5sum|head -c16) > alice.secret -# goloop ks gen -o alice.ks.json -p $(cat alice.secret) -# echo -n $(date|md5sum|head -c16) > bob.secret -# goloop ks gen -o bob.ks.json -p $(cat bob.secret) -``` - -Mint token to Alice -```console -# rpcch src -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# goloop rpc sendtx call --to $(cat irc2.src) \ - --method transfer \ - --param _to=$(jq -r .address alice.ks.json) \ - --param _value=1000 -``` - -> To retrieve balance of Alice, use `balanceOf(_owner)` method of IRC-2.0 Token contract. -> -> ```console -> # goloop rpc call --to $(cat irc2.src) --method balanceOf --param _owner=$(jq -r .address alice.ks.json) -> ``` - -Mint token to Token-BSH of dst -```console -# rpcch dst -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# goloop rpc sendtx call --to $(cat irc2.dst) \ - --method transfer \ - --param _to=$(cat token.dst) \ - --param _value=1000 -``` - -> To retrieve balance of dst Token-BSH, use `balanceOf(_owner)` method of IRC-2.0 Token contract. -> ```console -> # goloop rpc call --to $(cat irc2.dst) --method balanceOf --param _owner=$(cat token.dst) -> ``` - -Alice transfer token to Token-BSH -```console -# rpcch src -# rpcks alice.ks.json alice.secret -# goloop rpc sendtx call --to $(cat irc2.src) \ - --method transfer \ - --param _to=$(cat token.src) \ - --param _value=100 -``` - -> To retrieve balance of Alice which is able to interchain-transfer, use `balanceOf(_owner)` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.src) --method getBalance \ -> --param user=$(jq -r .address alice.ks.json) \ -> --param tokenName=IRC2Token -> ``` - -Alice transfer token to Bob via Token-BSH -```console -# rpcch src -# rpcks alice.ks.json alice.secret -# goloop rpc sendtx call --to $(cat token.src) \ - --method transfer \ - --param tokenName=IRC2Token \ - --param to=btp://$(cat net.btp.dst)/$(jq -r .address bob.ks.json) \ - --param value=10 -``` - -> To retrieve balance of Alice, use `balanceOf(_owner)` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.src) --method getBalance \ -> --param user=$(jq -r .address alice.ks.json) \ -> --param tokenName=IRC2Token -> ``` -> -> To retrieve transferred balance of Token-BSH which is, use `balanceOf(_owner)` method of IRC-2.0 token contract. -> -> ```console -> # rpcch dst -> # goloop rpc call --to $(cat irc2.dst) --method balanceOf --param _owner=$(cat token.dst) -> ``` -> -> alice usable balance is 0x3de, dst Token-BSH balance is 0x3de - -Balance of Bob from Token-BSH - -> To retrieve balance of Bob which is, use `balanceOf(_owner)` method of IRC-2.0 Token contract. -> -> ```console -> # goloop rpc call --to $(cat irc2.dst) --method balanceOf --param _owner=$(jq -r .address bob.ks.json) -> "0xa" -> ``` - -## Docker-compose - -Tutorial with [Docker-compose](https://docs.docker.com/compose/) -Using javascore/bmc instead of pyscore/bmc - -### Preparation -Prepare 'btpsimple' docker image via `make btpsimple-image` and Copy files from project source to `/path/to/tutorial` -```console -$ make btpsimple-image -$ mkdir -p /path/to/tutorial -$ cp docker-compose/* /path/to/tutorial/ -``` - -### Run chain and relay -`docker-compose up` will build `tutorial_goloop` docker image that provisioned of belows - -* scripts files in `/goloop/bin` -* source chain and destination chain (channel name : `src`, `dst`) -* transaction related files in `/goloop/config` - - Transaction hash : `tx..` - - SCORE Address : `.` - - BTP Address : `btp.`, `net.btp.` - -And It creates containers for `tutorial_goloop`, `tutorial_btpsimple_src`, `tutorial_btpsimple_dst` services - -### Prepare wallet - -> To use `goloop` as json-rpc client, execute shell via `docker-compose exec tutorial_goloop sh` - -Create key store for Alice and Bob -```console -# source /goloop/bin/keystore.sh -# ensure_key_store alice.ks.json alice.secret -# ensure_key_store bob.ks.json bob.secret -``` - -### Approve NativeCoin-BSH -> apply `source /goloop/bin/nativecoin.sh` for transfer and retrieve balance - -Alice for source chain -```console -# rpcks alice.ks.json alice.secret -# irc31_approve src -``` - -Bob for destination chain -```console -# rpcks bob.ks.json bob.secret -# irc31_approve dst -``` - -### Transfer native-coin -Mint native-coin of source chain to Alice -```console -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# rpcch src -# goloop rpc sendtx transfer --to $(rpceoa alice.ks.json) --value 0x64 -``` - -> To retrieve balance of Alice, use `goloop rpc balance $(rpceoa alice.ks.json)` - -Alice transfer native-coin of source chain to Bob of destination chain via NativeCoin-BSH -```console -# rpcks alice.ks.json alice.secret -# nc_transfer src dst bob.ks.json src 0x64 -``` - -> To retrieve locked-balance of Alice, `nc_balance src src alice.ks.json` -> To retrieve transferred balance of Bob, use `irc31_balance dst src bob.ks.json` - -### Transfer native-coin represented as IRC31-Token -Bob transfer irc31-token of destination chain to Alice of source chain via NativeCoin-BSH -```console -# rpcks bob.ks.json bob.secret -# nc_transfer dst src alice.ks.json src 0x10 -``` - -> To retrieve locked-balance of Bob, -> ```console -> # nc_balance dst src bob.ks.json -> ``` -> -> To retrieve transferred balance of Alice, use -> ```console -> # rpcch src -> # goloop rpc balance $(rpceoa alice.ks.json) -> ``` -> -> To retrieve remained balance of Bob, use -> ```console -> # irc31_balance dst src bob.ks.json -> ``` diff --git a/doc/tutorial_pyscore.md b/doc/tutorial_pyscore.md deleted file mode 100644 index 6aa44f6..0000000 --- a/doc/tutorial_pyscore.md +++ /dev/null @@ -1,677 +0,0 @@ -# Tutorial - -## Introduction -This document describes how to setup a BTP network and interchain token transfer scenario. - -## Preparation - -### Requirements -* [Docker](https://docs.docker.com) -* goloop v0.9.6 or later - -### blockchain -1. Start the server -```console -$ export CONFIG_DIR=/path/to/config -$ docker run -d --name goloop -p 9080:9080 \ - -e GOLOOP_LOGFILE=/goloop/data/log/goloop.log \ - -v ${CONFIG_DIR}:/goloop/config \ - iconloop/goloop-icon -``` -for follows, execute under `docker exec -ti --workdir /goloop/config goloop sh`. - -install jq -```console -# apk add jq -``` - -2. Create genesis - -```console -# goloop gn gen --out src.genesis.json $GOLOOP_KEY_STORE -# goloop gn gen --out dst.genesis.json $GOLOOP_KEY_STORE -``` - -modify genesis for javaee -```console -# echo $(cat src.genesis.json | jq -r '.*{"chain":{"fee":{"stepLimit":{"invoke":"0x10000000","query":"0x1000000"}}}}') > src.genesis.json -# echo $(cat dst.genesis.json | jq -r '.*{"chain":{"fee":{"stepLimit":{"invoke":"0x10000000","query":"0x1000000"}}}}') > dst.genesis.json -``` - -3. Join the chain - -```console -# goloop chain join --genesis_template src.genesis.json --channel src -# goloop chain join --genesis_template dst.genesis.json --channel dst -``` - -4. Start the chain - -```console -# goloop chain start src -# goloop chain start dst -``` - -5. Configure for debugging - -set log level to `trace` in `${CONFIG_DIR}/server.json` -``` -{ - ...skip... - "log_level": "trace", - "console_level": "trace" -} -``` -> restart goloop container to apply changes - -set debug config to get smart-contract log with `goloop debug trace txhash` -```console -# goloop system config rpcIncludeDebug true -``` - -> log file located in `/goloop/data/log` - -## Deploy Smart Contracts -### Package -zip each BTP-Smart-Contracts from project source, and copy files to `/path/to/config` which is mounted with `/goloop/config` of goloop container - -```console -$ make dist-py -$ mkdir -p ${CONFIG_DIR}/pyscore -$ cp build/contracts/pyscore/*.zip ${CONFIG_DIR}/pyscore/ -``` - -package for javascore/bmc -```console -$ make dist-java -$ mkdir -p ${CONFIG_DIR}/javascore -$ cp build/contracts/javascore/*.jar ${CONFIG_DIR}/javascore/ -``` - -### Environment for JSON-RPC -To use `goloop` as json-rpc client, execute shell via `docker exec -ti --workdir /goloop/config goloop sh` on goloop container. -For parse json-rpc response, install jq via `apk add jq` to goloop container. -Prepare 'rpc.sh' file as below, and apply by `source rpc.sh`. -Set keystore for json-rpc by `rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET` -```shell -rpchelp() { - echo "rpcch CHANNEL" - echo "rpcks KEYSTORE_PATH" -} - -rpcch() { - if [ ! "$1" == "" ]; then - export GOLOOP_RPC_CHANNEL=$1 - URI_PREFIX=http://$(goloop system info -f '{{.Setting.RPCAddr}}')/api - export GOLOOP_RPC_URI=$URI_PREFIX/v3/$GOLOOP_RPC_CHANNEL - export GOLOOP_RPC_NID=$(goloop chain inspect $GOLOOP_RPC_CHANNEL --format {{.NID}}) - export GOLOOP_DEBUG_URI=$URI_PREFIX/v3d/$GOLOOP_RPC_CHANNEL - export GOLOOP_RPC_STEP_LIMIT=${GOLOOP_RPC_STEP_LIMIT:-0x10000000} - fi - echo $GOLOOP_RPC_CHANNEL -} - -rpcks() { - if [ ! "$1" == "" ]; then - export GOLOOP_RPC_KEY_STORE=$1 - if [ ! "$2" == "" ]; then - if [ -f "$2" ]; then - export GOLOOP_RPC_KEY_SECRET=$2 - else - export GOLOOP_RPC_KEY_PASSWORD=$2 - fi - fi - fi - echo $GOLOOP_RPC_KEY_STORE -} - -export GOLOOP_CHAINSCORE=cx0000000000000000000000000000000000000000 -``` - -### BMC -Deploy BMC contract to 'src' chain -```console -# rpcch src -# echo "$GOLOOP_RPC_NID.icon" > net.btp.$(rpcch) -# goloop rpc sendtx deploy javascore/bmc.jar --content_type application/java \ - --param _net=$(cat net.btp.$(rpcch)) | jq -r . > tx.bmc.$(rpcch) -``` - -Extract BMC contract address from deploy result -```console -# goloop rpc txresult $(cat tx.bmc.$(rpcch)) | jq -r .scoreAddress > bmc.$(rpcch) -``` - -Create BTP-Address -```console -# echo "btp://$(cat net.btp.$(rpcch))/$(cat bmc.$(rpcch))" > btp.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst'. -```console -# rpcch dst -# echo "$GOLOOP_RPC_NID.icon" > net.btp.$(rpcch) -# goloop rpc sendtx deploy javascore/bmc.jar --content_type application/java \ - --param _net=$(cat net.btp.$(rpcch)) | jq -r . > tx.bmc.$(rpcch) -# sleep 2 -# goloop rpc txresult $(cat tx.bmc.$(rpcch)) | jq -r .scoreAddress > bmc.$(rpcch) -# echo "btp://$(cat net.btp.$(rpcch))/$(cat bmc.$(rpcch))" > btp.$(rpcch) -``` - -### BMV -To create parameters for deploy BMV contract -```console -# rpcch dst -# goloop rpc call --to $GOLOOP_CHAINSCORE --method getValidators| jq -r 'map(.)|join(",")' > validators.$(rpcch) -# echo "0x$(printf %x $(goloop chain inspect $(rpcch) --format {{.Height}}))" > offset.$(rpcch) -``` - -Deploy BMV contract to 'src' chain -```console -# rpcch src -# goloop rpc sendtx deploy javascore/bmv-icon.jar --content_type application/java \ - --param _bmc=$(cat bmc.$(rpcch)) \ - --param _net=$(cat net.btp.dst) \ - --param _validators=$(cat validators.dst) \ - --param _offset=$(cat offset.dst) \ - | jq -r . > tx.bmv.$(rpcch) -``` - -Extract BMV contract address from deploy result -```console -# goloop rpc txresult $(cat tx.bmv.$(rpcch)) | jq -r .scoreAddress > bmv.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst' and 'dst' to 'src'. -```console -# rpcch src -# goloop rpc call --to $GOLOOP_CHAINSCORE --method getValidators| jq -r 'map(.)|join(",")' > validators.$(rpcch) -# echo "0x$(printf %x $(goloop chain inspect $(rpcch) --format {{.Height}}))" > offset.$(rpcch) -# rpcch dst -# goloop rpc sendtx deploy javascore/bmv-icon.jar --content_type application/java \ - --param _bmc=$(cat bmc.$(rpcch)) \ - --param _net=$(cat net.btp.src) \ - --param _validators=$(cat validators.src) \ - --param _offset=$(cat offset.src) \ - | jq -r . > tx.bmv.$(rpcch) -sleep 2 -# goloop rpc txresult $(cat tx.bmv.$(rpcch)) | jq -r .scoreAddress > bmv.$(rpcch) -``` - -### Token-BSH -Deploy Token-BSH contract to 'src' chain -```console -# rpcch src -# goloop rpc sendtx deploy pyscore/token.zip \ - --param _bmc=$(cat bmc.$(rpcch)) | jq -r . > tx.token.$(rpcch) -``` - -Extract Token-BSH contract address from deploy result -```console -# goloop rpc txresult $(cat tx.token.$(rpcch)) | jq -r .scoreAddress > token.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst'. -```console -# rpcch dst -# goloop rpc sendtx deploy pyscore/token.zip \ - --param _bmc=$(cat bmc.$(rpcch)) | jq -r . > tx.token.$(rpcch) -# goloop rpc txresult $(cat tx.token.$(rpcch)) | jq -r .scoreAddress > token.$(rpcch) -``` - -### IRC-2.0 Token -Deploy IRC-2.0 Token contract to 'src' chain -```console -# rpcch src -# goloop rpc sendtx deploy pyscore/irc2.zip \ - --param _name=IRC2Token \ - --param _symbol=I2T \ - --param _initialSupply=1000 \ - --param _decimals=18 \ - | jq -r . > tx.irc2.$(rpcch) -``` - -Extract IRC-2.0 Token contract address from deploy result -```console -# goloop rpc txresult $(cat tx.irc2.$(rpcch)) | jq -r .scoreAddress > irc2.$(rpcch) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst' and add `_owner` parameter. because IRC-2.0 Token contract of 'dst' chain is proxy. -```console -# rpcch dst -# goloop rpc sendtx deploy pyscore/irc2.zip \ - --param _name=IRC2Token \ - --param _symbol=I2T \ - --param _initialSupply=0x3E8 \ - --param _decimals=0x12 \ - --param _owner=$(cat token.$(rpcch)) \ - | jq -r . > tx.irc2.$(rpcch) -# goloop rpc txresult $(cat tx.irc2.$(rpcch)) | jq -r .scoreAddress > irc2.$(rpcch) -``` - -## Configuration - -### Register BMV -Register verifier of 'dst' chain to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addVerifier \ - --param _net=$(cat net.btp.dst) \ - --param _addr=$(cat bmv.$(rpcch)) \ - | jq -r . > tx.verifier.$(rpcch) -``` - -Register verifier of 'src' chain to 'dst' chain -```console -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addVerifier \ - --param _net=$(cat net.btp.src) \ - --param _addr=$(cat bmv.$(rpcch)) \ - | jq -r . > tx.verifier.$(rpcch) -``` - -### Register Link -Register BTP-Address of 'dst' chain to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addLink \ - --param _link=$(cat btp.dst) \ - | jq -r . > tx.link.$(rpcch) -``` - -Register BTP-Address of 'src' chain to 'dst' chain -```console -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addLink \ - --param _link=$(cat btp.src) \ - | jq -r . > tx.link.$(rpcch) -``` - -> To retrieve list of registered links, use `getLinks` method of BMC. -> ```console -> # goloop rpc call --to $(cat bmc.$(rpcch)) --method getLinks -> ``` - -### Configure Link -To use multiple-BMR for relay, should set properties of link via `BMC.setLinkRotateTerm` - -Set properties of 'dst' link to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method setLinkRotateTerm \ - --param _link=$(cat btp.dst) \ - --param _block_interval=0x3e8 \ - --param _max_agg=0x10 \ - | jq -r . > tx.setlink.$(rpcch) -``` - -Set properties of 'src' link to 'dst' chain -```console -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method setLinkRotateTerm \ - --param _link=$(cat btp.src) \ - --param _block_interval=0x3e8 \ - --param _max_agg=0x10 \ - | jq -r . > tx.setlink.$(rpcch) -``` - -> To retrieve properties of link, use `getStatus(_link)` method of BMC. -> -> ```console -> # rpcch src -> # goloop rpc call --to $(cat bmc.src) --method getStatus --param _link=$(cat btp.dst) -> -> # rpcch dst -> # goloop rpc call --to $(cat bmc.dst) --method getStatus --param _link=$(cat btp.src) -> ``` - -### Register Token-BSH -Register Token service to BMC -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addService \ - --param _svc=token \ - --param _addr=$(cat token.$(rpcch)) | jq -r . > tx.service.token.$(rpcch) - -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addService \ - --param _svc=token \ - --param _addr=$(cat token.$(rpcch)) | jq -r . > tx.service.token.$(rpcch) -``` - -### Register IRC2Token -Register IRC 2.0 Token contract to Token-BSH -```console -# rpcch src -# goloop rpc sendtx call --to $(cat token.$(rpcch)) \ - --method register \ - --param _name=IRC2Token \ - --param _addr=$(cat irc2.$(rpcch)) - -# rpcch dst -# goloop rpc sendtx call --to $(cat token.$(rpcch)) \ - --method register \ - --param _name=IRC2Token \ - --param _addr=$(cat irc2.$(rpcch)) -``` - -> To retrieve list of registered token, use `tokenNames` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.$(rpcch)) --method tokenNames -> ``` - -### Register BMC-Owner and BMR -Create key store for BMC-Owner, BMR of both chain -```console -# echo -n $(date|md5sum|head -c16) > src.secret -# goloop ks gen -o src.ks.json -p $(cat src.secret) -# echo -n $(date|md5sum|head -c16) > dst.secret -# goloop ks gen -o dst.ks.json -p $(cat dst.secret) -``` - -Register BMC-Owner to 'src' chain -```console -# rpcch src -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addOwner \ - --param _addr=$(jq -r .address $(rpcch).ks.json) -``` - -BMC-Owner register BMR to 'src' chain (Address of BMR could be any keystore) -```console -# rpcks src.ks.json src.secret -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addRelay \ - --param _link=$(cat btp.dst) \ - --param _addr=$(jq -r .address dst.ks.json) -``` - -For 'dst' chain, same flows with replace 'src' to 'dst' -```console -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# rpcch dst -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addOwner \ - --param _addr=$(jq -r .address $(rpcch).ks.json) -# rpcks dst.ks.json dst.secret -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method addRelay \ - --param _link=$(cat btp.src) \ - --param _addr=$(jq -r .address src.ks.json) -``` - -> To retrieve list of registered BMC-Owners, use `getOwners` method of BMC. -> ```console -> # goloop rpc call --to $(cat bmc.$(rpcch)) --method getOwners -> ``` - -> To retrieve list of registered relay of link, use `getRelays(_link)` method of BMC. -> -> ```console -> # rpcch src -> # goloop rpc call --to $(cat bmc.src) --method getRelays --param _link=$(cat btp.dst) -> -> # rpcch dst -> # goloop rpc call --to $(cat bmc.dst) --method getRelays --param _link=$(cat btp.src) -> ``` - -### Register relayer candidate : only for testing of ICON main network environment -Create key store for relayer -```console -# echo -n $(date|md5sum|head -c16) > relayer.secret -# goloop ks gen -o relayer.ks.json -p $(cat relayer.secret) -``` - -To register relayer candidate, bonding is required. -The account of 'god' transfer some icx to account of relayer candidate. -Assume 'src' chain as ICON -```console -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# rpcch src -# goloop rpc sendtx transfer --to $(jq -r .address relayer.ks.json) --value 0x10 -``` - -Register to 'src' chain -```console -# rpcch src -# rpcks relayer.ks.json relayer.secret -# goloop rpc sendtx call --to $(cat bmc.$(rpcch)) \ - --method registerRelayer \ - --param _desc="first candidate for relayer" \ - --value 0x10 -``` - -> To retrieve list of registered relayers, use `getRelayers` method of BMC. -> -> ```console -> # goloop rpc call --to $(cat bmc.src) --method getRelayers -> ``` - -## Start relay - -Prepare 'btpsimple' docker image via `make btpsimple-image` - -Start relay 'src' chain to 'dst' chain -```console -$ docker run -d --name btpsimple_src --link goloop \ - -v ${CONFIG_DIR}:/btpsimple/config \ - -e BTPSIMPLE_CONFIG=/btpsimple/config/src.config.json \ - -e BTPSIMPLE_SRC_ADDRESS=$(cat ${CONFIG_DIR}/btp.src) \ - -e BTPSIMPLE_SRC_ENDPOINT=http://goloop:9080/api/v3/src \ - -e BTPSIMPLE_DST_ADDRESS=$(cat ${CONFIG_DIR}/btp.dst) \ - -e BTPSIMPLE_DST_ENDPOINT=http://goloop:9080/api/v3/dst \ - -e BTPSIMPLE_OFFSET=$(cat ${CONFIG_DIR}/offset.src) \ - -e BTPSIMPLE_KEY_STORE=/btpsimple/config/src.ks.json \ - -e BTPSIMPLE_KEY_SECRET=/btpsimple/config/src.secret \ - btpsimple -``` - -For relay of 'dst' chain, same flows with replace 'src' to 'dst' and 'dst' to 'src'. -```console -$ docker run -d --name btpsimple_dst --link goloop \ - -v ${CONFIG_DIR}:/btpsimple/config \ - -e BTPSIMPLE_CONFIG=/btpsimple/config/dst.config.json \ - -e BTPSIMPLE_SRC_ADDRESS=$(cat ${CONFIG_DIR}/btp.dst) \ - -e BTPSIMPLE_SRC_ENDPOINT=http://goloop:9080/api/v3/dst \ - -e BTPSIMPLE_DST_ADDRESS=$(cat ${CONFIG_DIR}/btp.src) \ - -e BTPSIMPLE_DST_ENDPOINT=http://goloop:9080/api/v3/src \ - -e BTPSIMPLE_OFFSET=$(cat ${CONFIG_DIR}/offset.dst) \ - -e BTPSIMPLE_KEY_STORE=/btpsimple/config/dst.ks.json \ - -e BTPSIMPLE_KEY_SECRET=/btpsimple/config/dst.secret \ - btpsimple -``` - -> To retrieve status of relay, use `getStatus(_link)` method of BMC. -> ```console -> # rpcch src -> # goloop rpc call --to $(cat bmc.src) --method getStatus --param _link=$(cat btp.dst) -> -> # rpcch dst -> # goloop rpc call --to $(cat bmc.dst) --method getStatus --param _link=$(cat btp.src) -> ``` - -## Interchain Token Transfer -> To use `goloop` as json-rpc client, execute shell via `docker exec -ti --workdir /goloop/config goloop sh` on goloop container. - -Create key store for Alice and Bob -```console -# echo -n $(date|md5sum|head -c16) > alice.secret -# goloop ks gen -o alice.ks.json -p $(cat alice.secret) -# echo -n $(date|md5sum|head -c16) > bob.secret -# goloop ks gen -o bob.ks.json -p $(cat bob.secret) -``` - -Mint token to Alice -```console -# rpcch src -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# goloop rpc sendtx call --to $(cat irc2.src) \ - --method transfer \ - --param _to=$(jq -r .address alice.ks.json) \ - --param _value=10 -``` - -> To retrieve balance of Alice, use `balanceOf(_owner)` method of IRC-2.0 Token contract. -> -> ```console -> # goloop rpc call --to $(cat irc2.src) --method balanceOf --param _owner=$(jq -r .address alice.ks.json) -> ``` - -Alice transfer token to Token-BSH -```console -# rpcch src -# rpcks alice.ks.json alice.secret -# goloop rpc sendtx call --to $(cat irc2.src) \ - --method transfer \ - --param _to=$(cat token.src) \ - --param _value=10 -``` - -> To retrieve balance of Alice which is able to interchain-transfer, use `balanceOf(_owner)` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.src) --method balanceOf --param _owner=$(jq -r .address alice.ks.json) -> ``` - -Alice transfer token to Bob via Token-BSH -```console -# rpcch src -# rpcks alice.ks.json alice.secret -# goloop rpc sendtx call --to $(cat token.src) \ - --method transfer \ - --param _tokenName=IRC2Token \ - --param _to=btp://$(cat net.btp.dst)/$(jq -r .address bob.ks.json) \ - --param _value=5 -``` - -> To retrieve locked-balance of Alice, use `balanceOf(_owner)` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.src) --method balanceOf --param _owner=$(jq -r .address alice.ks.json) -> ``` -> -> To retrieve transferred balance of Bob which is, use `balanceOf(_owner)` method of Token-BSH. -> -> ```console -> # goloop rpc call --to $(cat token.dst) --method balanceOf --param _owner=$(jq -r .address bob.ks.json) -> ``` -> -> alice usable balance is 5, bob usable balance is 5 - -Bob withdraw usable token from Token-BSH -```console -# rpcch dst -# rpcks bob.ks.json bob.secret -# goloop rpc sendtx call --to $(cat token.dst) \ - --method reclaim \ - --param _tokenName=IRC2Token \ - --param _value=5 -``` - -> To retrieve balance of Bob which is, use `balanceOf(_owner)` method of IRC-2.0 Token contract. -> -> ```console -> # goloop rpc call --to $(cat irc2.dst) --method balanceOf --param _owner=$(jq -r .address bob.ks.json) -> ``` - -## Docker-compose - -Tutorial with [Docker-compose](https://docs.docker.com/compose/) -Using javascore/bmc instead of pyscore/bmc - -### Preparation -Prepare 'btpsimple' docker image via `make btpsimple-image` and Copy files from project source to `/path/to/tutorial` -```console -$ make btpsimple-image -$ mkdir -p /path/to/tutorial -$ cp docker-compose/* /path/to/tutorial/ -``` - -### Run chain and relay -`docker-compose up` will build `tutorial_goloop` docker image that provisioned of belows - -* scripts files in `/goloop/bin` -* source chain and destination chain (channel name : `src`, `dst`) -* transaction related files in `/goloop/config` - - Transaction hash : `tx..` - - SCORE Address : `.` - - BTP Address : `btp.`, `net.btp.` - -And It creates containers for `tutorial_goloop`, `tutorial_btpsimple_src`, `tutorial_btpsimple_dst` services - -### Prepare wallet - -> To use `goloop` as json-rpc client, execute shell via `docker-compose exec tutorial_goloop sh` - -Create key store for Alice and Bob -```console -# source /goloop/bin/keystore.sh -# ensure_key_store alice.ks.json alice.secret -# ensure_key_store bob.ks.json bob.secret -``` - -### Approve NativeCoin-BSH -> apply `source /goloop/bin/nativecoin.sh` for transfer and retrieve balance - -Alice for source chain -```console -# rpcks alice.ks.json alice.secret -# irc31_approve src -``` - -Bob for destination chain -```console -# rpcks bob.ks.json bob.secret -# irc31_approve dst -``` - -### Transfer native-coin -Mint native-coin of source chain to Alice -```console -# rpcks $GOLOOP_KEY_STORE $GOLOOP_KEY_SECRET -# rpcch src -# goloop rpc sendtx transfer --to $(rpceoa alice.ks.json) --value 0x64 -``` - -> To retrieve balance of Alice, use `goloop rpc balance $(rpceoa alice.ks.json)` - -Alice transfer native-coin of source chain to Bob of destination chain via NativeCoin-BSH -```console -# rpcks alice.ks.json alice.secret -# nc_transfer src dst bob.ks.json src 0x64 -``` - -> To retrieve locked-balance of Alice, `nc_balance src src alice.ks.json` -> To retrieve transferred balance of Bob, use `irc31_balance dst src bob.ks.json` - -### Transfer native-coin represented as IRC31-Token -Bob transfer irc31-token of destination chain to Alice of source chain via NativeCoin-BSH -```console -# rpcks bob.ks.json bob.secret -# nc_transfer dst src alice.ks.json src 0x10 -``` - -> To retrieve locked-balance of Bob, -> ```console -> # nc_balance dst src bob.ks.json -> ``` -> -> To retrieve transferred balance of Alice, use -> ```console -> # rpcch src -> # goloop rpc balance $(rpceoa alice.ks.json) -> ``` -> -> To retrieve remained balance of Bob, use -> ```console -> # irc31_balance dst src bob.ks.json -> ``` diff --git a/docker-compose/relay/config/icon_to_hardhat_config.json b/docker-compose/relay/config/icon_to_hardhat_config.json new file mode 100644 index 0000000..15dc6e8 --- /dev/null +++ b/docker-compose/relay/config/icon_to_hardhat_config.json @@ -0,0 +1,36 @@ +{ + "relay_config": { + "direction": "both", + "base_dir": ".", + "log_level": "debug", + "console_level": "trace", + "log_forwarder": { + "vendor": "", + "address": "", + "level": "info", + "name": "" + }, + "log_writer": { + "filename": "relay.log", + "maxsize": 100, + "maxage": 0, + "maxbackups": 0, + "localtime": false, + "compress": false + } + }, + "chains_config": { + "src": { + "address": "btp://0x3.icon/cx24a7d0637203f2d8737c1d1cd02ef6599ae0c7ee", + "endpoint": "http://icon-node:9080/api/v3/icon_dex", + "key_store": "/keystore/icon/keystore.json", + "key_password": "gochain" + }, + "dst": { + "address": "btp://0x539.hardhat/0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9", + "endpoint": "http://docker-ganache-1:8545", + "key_store": "/keystore/hardhat/keystore.json", + "key_password": "hardhat" + } + } +} diff --git a/docker-compose/relay/config/icon_to_icon_config.json b/docker-compose/relay/config/icon_to_icon_config.json new file mode 100644 index 0000000..b639c20 --- /dev/null +++ b/docker-compose/relay/config/icon_to_icon_config.json @@ -0,0 +1,38 @@ +{ + "relay_config": { + "direction": "both", + "base_dir": ".", + "log_level": "debug", + "console_level": "trace", + "log_forwarder": { + "vendor": "", + "address": "", + "level": "info", + "name": "" + }, + "log_writer": { + "filename": "relay.log", + "maxsize": 100, + "maxage": 0, + "maxbackups": 0, + "localtime": false, + "compress": false + } + }, + "chains_config": { + "src": { + "address": "btp://0x3.icon/cx24a7d0637203f2d8737c1d1cd02ef6599ae0c7ee", + "endpoint": "http://icon-node:9080/api/v3/icon_dex", + "key_store": "/keystore/icon/keystore.json", + "key_password": "gochain", + "type": "icon-btpblock" + }, + "dst": { + "address": "btp://0x101.icon/cxc530e07588f159fc235e0c17c9954c5e03b5f521", + "endpoint": "http://icon-node:9180/api/v3/icon_dex", + "key_store": "/keystore/icon1/keystore.json", + "key_password": "gochain", + "type": "icon-btpblock" + } + } +} diff --git a/docker-compose/relay/config/relay_config.json b/docker-compose/relay/config/relay_config.json deleted file mode 100644 index 0099280..0000000 --- a/docker-compose/relay/config/relay_config.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "base_dir": ".", - "direction": "both", - "maxSizeTx": false, - "offset": 0, - "src": { - "address": "btp://0x3.icon/cx24a7d0637203f2d8737c1d1cd02ef6599ae0c7ee", - "endpoint": "http://icon-node:9080/api/v3/icon_dex", - "key_store": "/keystore/icon/keystore.json", - "key_password": "gochain" - }, - "dst": { - "address": "btp://0x539.hardhat/0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9", - "endpoint": "http://docker-ganache-1:8545", - "key_store": "/keystore/hardhat/keystore.json", - "key_password": "hardhat" - }, - "log_level": "trace", - "console_level": "trace", - "log_forwarder": { - "vendor": "", - "address": "", - "level": "trace", - "name": "" - }, - "log_writer": { - "filename": "./log", - "maxsize": 100, - "maxage": 0, - "maxbackups": 0, - "localtime": false, - "compress": false - } -} \ No newline at end of file diff --git a/docker-compose/relay/docker-compose.yml b/docker-compose/relay/docker-compose.yml index e4d453f..258d19c 100644 --- a/docker-compose/relay/docker-compose.yml +++ b/docker-compose/relay/docker-compose.yml @@ -14,5 +14,5 @@ services: source: ./keystore target: /keystore environment: - - RELAY_CONFIG=/etc/config/relay_config.json + - RELAY_CONFIG=/etc/config/icon_to_hardhat_config.json restart: always diff --git a/docker-compose/relay/keystore/icon1/keysecret b/docker-compose/relay/keystore/icon1/keysecret new file mode 100644 index 0000000..2fc16e8 --- /dev/null +++ b/docker-compose/relay/keystore/icon1/keysecret @@ -0,0 +1 @@ +gochain \ No newline at end of file diff --git a/docker-compose/relay/keystore/icon1/keystore.json b/docker-compose/relay/keystore/icon1/keystore.json new file mode 100644 index 0000000..978fea4 --- /dev/null +++ b/docker-compose/relay/keystore/icon1/keystore.json @@ -0,0 +1,22 @@ +{ + "address": "hxb6b5791be0b5ef67063b3c10b840fb81514db2fd", + "id": "87323a66-289a-4ce2-88e4-00278deb5b84", + "version": 3, + "coinType": "icx", + "crypto": { + "cipher": "aes-128-ctr", + "cipherparams": { + "iv": "069e46aaefae8f1c1f840d6b09144999" + }, + "ciphertext": "f35ff7cf4f5759cb0878088d0887574a896f7f0fc2a73898d88be1fe52977dbd", + "kdf": "scrypt", + "kdfparams": { + "dklen": 32, + "n": 65536, + "r": 8, + "p": 1, + "salt": "0fc9c3b24cdb8175" + }, + "mac": "1ef4ff51fdee8d4de9cf59e160da049eb0099eb691510994f5eca492f56c817a" + } +} \ No newline at end of file