github.com/klaytn/klaytn@v1.12.1/node/sc/doc.go (about)

     1  // Copyright 2019 The klaytn Authors
     2  // This file is part of the klaytn library.
     3  //
     4  // The klaytn library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The klaytn library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the klaytn library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  /*
    18  Package sc implements an auxiliary blockchain called Service Chain.
    19  
    20  Service Chains in Klaytn are auxiliary blockchains independent from the Klaytn main chain.
    21  They mostly act like normal Klaytn blockchains but has additional features to connect them to another Klaytn network.
    22  They can be used as separate public/private blockchains or child chains of a Klaytn chain (or another Service Chain).
    23  The followings describe main features of Service chain.
    24    - Anchoring block data of Service Chain
    25    - Value Transfer (KLAY, KCT)
    26    - Various bridge contract configurations
    27    - Support high availability
    28  
    29  
    30  Service Chain provides the inter-connectivity to another Klaytn chain through two bridges, MainBridge and SubBridge.
    31  Each bridge has a bridge contract on different blockchain networks and pairs up with another bridge to interact with.
    32  They are directly connected on the network layer and communicate with each other through p2p messages enabling inter-chain operations.
    33  
    34  MainBridge is configured on the node of a parent chain and SubBridge is configured on the node of a child chain.
    35  Both of a Klaytn chain and a Service Chain can be a parent chain, but only a Service Chain can be a child chain.
    36  The block data of a child chain can be anchored to the bridge contract of MainBridge with the chain data anchoring transaction.
    37  
    38  Unlike the block data anchoring, user data transfer is bi-directional.
    39  For example, users can transfer KLAY of Klaytn main chain to an address of a Service Chain or vice versa.
    40  This kind of inter-chain operation requires read/write ability on both chains but does not use MainBridge functions in the process.
    41  Instead of the MainBridge, the SubBridge in the child chain directly calls read/write operations to the parent chain node through RPC (In the basic configuration, the parent chain node is the same with the MainBridge enabled node).
    42  Of course, the accounts of both chains should be registered on the SubBridge to generate transactions.
    43  Following is the process of the KLAY transfer from Klaytn main chain to a Service Chain.
    44  1. A user executes the inter-chain operation by sending a transaction with KLAY to the bridge contract of Klaytn main chain.
    45  2. The bridge contract keeps KLAY on its account and creates an event for the inter-chain request.
    46  3. The SubBridge subscribes the event log on the main chain node through RPC.
    47  4. The SubBridge generates a transaction on the child chain node to the bridge contract of the SubBridge.
    48  5. Finally, The bridge contract mints (or uses its KLAY) and sends KLAY to the target address.
    49  
    50  
    51  Source Files
    52  
    53  Functions and variables related to Service Chain are defined in the files listed below.
    54    - api_bridge.go : provides APIs for MainBridge or SubBridge.
    55    - bridge_accounts.go : generates inter-chain transactions between a parent chain and a child chain.
    56    - bridge_addr_journal.go : provides a journal mechanism for bridge addresses to provide the persistence service.
    57    - bridge_manager.go : handles the bridge information and manages the bridge operations.
    58    - bridgepeer.go : implements data structures of p2p peers used for Service Chain bridges.
    59    - config.go : provides configurations of Service Chain nodes.
    60    - gen_config.go : provides marshalling and unmarshalling functions of the Service Chain configuration.
    61    - local_backend.go : provides read/write operations for the child chain block data.
    62    - main_bridge_handler.go : implements a p2p message handler of MainBridge.
    63    - main_event_handler.go : implements a event handler of MainBridge.
    64    - mainbridge.go : implements MainBridge of the parent chain node.
    65    - metrics.go : contains metrics used for sc package.
    66    - protocol.go : defines protocols of Service Chain.
    67    - remote_backend.go : provides read/write RPC calls for the parent chain block data.
    68    - sub_bridge_handler.go : implements a p2p message handler of SubBridge.
    69    - sub_event_handler.go : implements a event handler of SubBridge.
    70    - subbridge.go : implements SubBridge of the child chain node.
    71    - vt_recovery.go : provides recovery from the service failure for inter-chain value transfer.
    72  */
    73  package sc