Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: migrate falcon pr #15

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/products/falcon/01-introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Introduction

As the blockchain industry continues to evolve, the importance of interoperability and connectivity between different blockchain networks has become increasingly clear. While Cosmos is the prominent player in this space, it's important to recognize the value that other chains can bring to the table.

The Falcon program is designed to enable secure and efficient cross-chain communication between different blockchain networks. It achieves this by requesting data from BandChain, and then sending the data along with the proof to the other chain.

By using Falcon, any smart contract developers can easily integrate data from BandChain into their applications and services, enabling a more seamless and interconnected blockchain ecosystem. This can unlock new use cases and applications, and provide users with access to a wider range of data from BandChain.

### Workflow

The Falcon program consists of three key components, trigger, band, and relayer that work together to enable secure cross-chain communication. The first component is the Trigger, which can be set to initiate the 'band' requester at specified intervals or under specified conditions. The Band Requester component queries data from BandChain and its proof. Finally, The Relayer component then securely relays the data to other chains, such as EVM chains. Together, these components provide a comprehensive and secure solution for cross-chain communication and data exchange.

![Falcon_Infographic_Chapter1](https://user-images.githubusercontent.com/54426055/234471438-47b3de9f-4660-4c34-80ae-2d075c92d547.png)

At a high level, the workflow will be as follows. Firstly, when reached the specified condition such as time interval, Trigger will trigger Falcon to request data from BandChain. Then, BandChain will run the Oracle script specified in the request which will get data from the Data sources and return data result along with its proof to Falcon.

After Falcon recieved the result and proof, it will send the data and proof to all other chains' contract that are specified in the Falcon program.

At this point, the smart contract in other chains can verify the proof using the bridge contract provided in that chain. If the proof is correct, the smart contract can trust and use the data.

### Bridge contract

Conceptually, you can think of the Bridge contract as a generic logic that helps verify the availability of any data stored on the BandChain. In order to verify the data's availability, the Bridge contract contains a set of validators of the BandChain, which is used for signature verification when any external actors relay a BandChain's block. After the block relaying is successful (accumulated power of more than 2/3), the rest is the verification of the actual data (leaf) against the root hash. Finally, the result/leaf is extracted and returned to the caller if the data is successfully verified.

#### State

```
// The encoded chain's ID of Band.
// This value is only set at the deployment time
bytes public encodedChainID;



//============================== Set by the owner ==============================

struct ValidatorWithPower {
address addr;
uint256 power;
}

// Mapping from an address to its voting power.
EnumerableMap.AddressToUintMap private validatorPowers;

// The total voting power of active validators currently on duty.
uint256 public totalValidatorPower;

//============================== Set by the owner ==============================




//============================== Public ==============================

struct BlockDetail {
bytes32 oracleState;
uint64 timeSecond;
uint32 timeNanoSecondFraction; // between 0 to 10^9
}

// Mapping from block height to the struct that contains block time and hash of "oracle" iAVL Merkle tree.
mapping(uint256 => BlockDetail) public blockDetails;

//============================== Public ==============================
```

#### Functions

The key function of the Bridge contract is `relayAndVerify`.

The `relayAndVerify` function is a public function for anyone who wants to relay request data from the BandChain into the Bridge contract. As a result, the relayed and verified data can be used safely by those who wish to consume data from Band oracle.
22 changes: 22 additions & 0 deletions docs/products/falcon/02-getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Getting started

This guide serves as a quick reference on how to run Falcon.

### Step 1: Prepare an oracle script and data sources

There are two main components on the BandChain in the requesting process:

- [Oracle script](/develop/custom-scripts/oracle-script/introduction)
- [Data source](/develop/custom-scripts/data-source/introduction)

For requesting data from BandChain, you have to deploy both of them in the BandChain first so that your Falcon program can specify the `oracle_script_id` when sending the request.

### Step 2: Prepare Consumer contract

For Falcon to relay data to your contract, it need to implement functions `verifyProofAndHandleResponse(bytes calldata data)` for Falcon to call to relay the data

For example of Consumer contract please refer to the [BandBridgeConsumer](https://github.com/bandprotocol/BandBridgeConsumer)

### Step 3: Initialize and start Falcon

You can install falcon and start using it with this [documentation](https://github.com/bandprotocol/falcon/blob/main/docs/getting_started.md)
25 changes: 25 additions & 0 deletions docs/products/falcon/03-supported-blockchains.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Supported BlockChains

`Bridge` contracts have reviewed and audited by [PeckShield](https://peckshield.com/)

[Audit report](https://github.com/bandprotocol/vrf-and-bridge-contracts/blob/master/audit/PeckShield-Audit-Report-Band-VRF-Bridge-v1.0.pdf)

Our deployed `Bridge` contracts on each chain are shown in the table below.

#### Testnet

| Chain \ Contract | Bridge |
| ---------------------------------------------------- | ------------------------------------------ |
| [Goerli](https://goerli.etherscan.io) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Cronos](https://testnet.cronoscan.com) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [OKC](https://www.oklink.com/en/okc-test) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Oasis](https://testnet.explorer.emerald.oasis.dev) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [BSC](https://testnet.bscscan.com) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [OP Goerli](https://goerli-optimism.etherscan.io) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Polygon](https://mumbai.polygonscan.com) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Avalanche](https://testnet.snowtrace.io) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Shibuya](https://blockscout.com/shibuya) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Klaytn](https://baobab.scope.klaytn.com/) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Godwoken](https://gw-explorer.nervosdao.community/) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
| [Meter](https://scan-warringstakes.meter.io/) | 0xb865B52A5DC922C6cb7926B234725F37716Ed97d |
| [TCGverse](http://20.78.2.231:4000) | 0xFCb11e9560F9a646C0A917De27C9600cDf210A19 |
3 changes: 3 additions & 0 deletions docs/products/falcon/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"label": "Falcon"
}
2 changes: 1 addition & 1 deletion src/components/pages/HelpAndSupportSection/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ const items: CardItem[] = [
title: 'Found an Issue?',
Svg: require('@site/static/img/github.svg').default,
description: <>Help us improve this page by suggesting edits on GitHub.</>,
to: 'https://github.com/bandprotocol/bandchain-docs/edit/master/docs/README.md', // TODO: change to this repo
to: 'https://github.com/bandprotocol/bandchain-docs/issues/new',
target: '_blank',
},
]
Expand Down