light

README

Light node contract on Conflux Network

This package aims to deploy light node contract on any other blockchain to verify transaction or receipt from Conflux network.

Contracts

Please refer to the repository for more details.

Relay Blocks

Off-chain service is required to relay blocks to light node contract for MPT root verification. Basically, there are two kinds of blocks to relay:

1. PoS blocks: indicates the last finalized PoW block.
2. PoW blocks: any PoW block could be optional relayed on chain for proof verification. In this way, less block headers in receipt proof is required to be verified on chain and reduce gas cost.

Note, any one could relay the blocks, since all blocks are cryptographically verified.

There is an available component EvmRelayer to relay PoS blocks on eSpace:

relayer := light.NewEvmRelayer(coreClient, relayerClient, config)
go relayer.Relay()

If necessary, EvmRelayer could be used to relay partial PoW blocks as well:

relayer.RelayPoWBlocks(headers)

Verify Receipt with Proof

Given a transaction hash, there is available API to generate receipt proof for eSpace.

generator := light.NewProofGenerator(coreClient, evmClient, lightNodeContract)
proof, err := generator.CreateReceiptProofEvm(txHash)
// Handle error
abiEncodedProof := proof.ABIEncode()

If there're too many PoW blocks in proof, e.g. 30, client could relay partial PoW blocks on chain at first, so as to avoid OutOfGas issue.

proof, err := generator.CreateReceiptProofEvm(txHash)
// Handle error
maxBlocks := 30
for len(proof.Headers) > maxBlocks {
    index := len(proof.Headers) - maxBlocks - 1
    if err = relayer.RelayPoWBlocks(proof.Headers[index:]); err != nil {
        // Handle error
    }
    proof.Headers = proof.Headers[:index+1]
}
abiEncodedProof := proof.ABIEncode()

With ABI encoded receipt proof, user could verify against light node contract and get RLP encoded event logs.

function verifyProofData(bytes memory receiptProof) external view returns (bool success, string memory message, bytes memory rlpLogs);

Documentation

Index

• Variables
• func CreateReceiptProofEvm(coreClient *sdk.Client, evmClient *web3go.Client, txHash common.Hash, ...) (*contract.TypesReceiptProof, error)
• func CreateReceiptsMPT(epochReceipts [][]types.TransactionReceipt) ([]*mpt.Node, *mpt.Node)
• func CreateTransactionsMPT(txs []types.WrapTransaction) *mpt.Node
• type EvmRelayConfig
• type EvmRelayer
  • func NewEvmRelayer(coreClient *sdk.Client, relayerClient *web3go.Client, config EvmRelayConfig) *EvmRelayer
  • func (r *EvmRelayer) Relay()
  • func (r *EvmRelayer) RelayPoWBlocks(headers [][]byte) error
• type ProofGenerator
  • func NewProofGenerator(coreClient *sdk.Client, relayerClient *web3go.Client, ...) *ProofGenerator
  • func (g *ProofGenerator) CreateReceiptProofEvm(evmClient *web3go.Client, txHash common.Hash) (*contract.TypesReceiptProof, error)

Variables

var ErrTransactionExecutionFailed = errors.New("transaction execution failed")

var RelayInterval = 3 * time.Second

Functions

func CreateReceiptProofEvm

func CreateReceiptProofEvm(coreClient *sdk.Client, evmClient *web3go.Client, txHash common.Hash, epochNumber uint64, pivot uint64) (*contract.TypesReceiptProof, error)

func CreateReceiptsMPT

func CreateReceiptsMPT(epochReceipts [][]types.TransactionReceipt) ([]*mpt.Node, *mpt.Node)

func CreateTransactionsMPT

func CreateTransactionsMPT(txs []types.WrapTransaction) *mpt.Node

Types

type EvmRelayConfig

type EvmRelayConfig struct {
	LightNode  common.Address // light node contract
	LedgerInfo common.Address // ledger info contract
	Verifier   common.Address // MPT verification contract
	Admin      common.Address // management admin address or relayer

	EpochFrom uint64 // epoch for initialization
	GcLimits  int64  // maximum number of blocks to remove at a time

	GasLimit uint64 // Fixed gas limit to send transaction if specified
}

type EvmRelayer

type EvmRelayer struct {
	EvmRelayConfig
	// contains filtered or unexported fields
}

func NewEvmRelayer

func NewEvmRelayer(coreClient *sdk.Client, relayerClient *web3go.Client, config EvmRelayConfig) *EvmRelayer

func (*EvmRelayer) Relay

func (r *EvmRelayer) Relay()

func (*EvmRelayer) RelayPoWBlocks

func (r *EvmRelayer) RelayPoWBlocks(headers [][]byte) error

type ProofGenerator

type ProofGenerator struct {
	// contains filtered or unexported fields
}

func NewProofGenerator

func NewProofGenerator(coreClient *sdk.Client, relayerClient *web3go.Client, lightNodeContract common.Address) *ProofGenerator

func (*ProofGenerator) CreateReceiptProofEvm

func (g *ProofGenerator) CreateReceiptProofEvm(evmClient *web3go.Client, txHash common.Hash) (*contract.TypesReceiptProof, error)

CreateReceiptProofEvm returns the receipt proof for specified `txHash` on eSpace.

If receipt not found, it will return nil and requires client to retry later.

If transaction execution failed, it will return `ErrTransactionExecutionFailed`.