Architecture

Folks Finance employs a hub-and-spoke architecture to efficiently manage cross-chain interactions. This model ensures liquidity, security, and ease of use across multiple blockchains.

Hub and Spoke Structure

1. Hub Chain:

   • The hub chain stores the entire state of the protocol. The unified state storage ensures consistency and avoids issues related to asynchronicity and race conditions between chains.

   • All protocol logic and state updates are handled by the hub chain, making it the axis of coordination for all transactions.

2. Spoke Chains:

   • Spoke chains act as entry points for users interacting with Folks Finance. They connect outlying blockchains to the central hub chain.

   • Unlike the hub chain, spoke chains do not store any state related to lending functionality. They only maintain state related to communication with the hub chain, thereby simplifying the overall architecture and reducing the risk of inconsistencies.

Benefits of Hub and Spoke Model

• Capital Efficiency: All liquidity is available irrespective of which chain the user is on, maximizing capital efficiency.

• User Convenience: Users can interact with the protocol from their favorite wallet and familiar chains, lowering the barriers to entry.

• Cross-Chain Collateralization: Users can use funds deposited on one chain as collateral to borrow on another, enhancing the flexibility and usability of the protocol.

---

Cross-chain Messaging

Cross-chain messaging is a critical component of Folks Finance, enabling secure and efficient communication between the hub and spoke chains. This ensures that transactions are consistent and reliable across different blockchain networks.

Key Communication Protocols

1. Wormhole:

   • Wormhole provides a cross-chain messaging protocol that allows secure and efficient communication between the hub and spoke chains.

   • It uses an automatic relayer to send and receive messages, ensuring the integrity and reliability of the data being transferred.

2. Chainlink CCIP (Cross-Chain Interoperability Protocol):

   • Chainlink CCIP facilitates cross-chain communication by providing a secure method to send and receive messages between chains.

   • It leverages Chainlink’s decentralized oracle network to ensure the security and accuracy of cross-chain messages.

3. Circle CCTP (Cross-Chain Transfer Protocol):

   • Circle CCTP enables cross-chain native USDC transfers, providing a secure and efficient way to transfer USDC between different blockchains.

Cross-Chain Messaging Architecture

• Generic Messaging Protocol (GMP):

  • The hub chain and spoke chains communicate using GMPs such as Wormhole, Chainlink CCIP, and Circle CCTP.

  • GMPs are responsible for relaying messages between the hub and spoke chains, ensuring that all transactions are accurately recorded and executed.

• BridgeRouter:

  • The BridgeRouter abstracts the differences between available GMPs, routing messages to the appropriate protocol based on user specifications and system requirements.

  • It also handles message storage for failed transactions, allowing for retries or reversals as necessary.

Message Lifecycle

1. Sending a Message:

   • When a user initiates a transaction on a spoke chain, the message is sent to the hub chain using the specified GMP.

   • The message parameters include details such as the adapter ID, destination chain ID, payload, and finality level.

2. Receiving a Message:

   • The hub chain receives the message, verifies its integrity, and processes it accordingly.

   • Upon processing, the hub chain may send a return message to the spoke chain to confirm the transaction's completion.

3. Finality and Security:

   • Finality is crucial for ensuring that transactions cannot be reversed or altered once confirmed. Folks Finance waits for finality on the spoke chain before relaying messages to the hub chain for critical operations like deposits and repayments.

   • For operations that do not involve value transfer, finality is not required, allowing for immediate message relaying to enhance user experience.

Cross-Chain Messaging Components

1. BridgeMessenger:

   • An abstract contract that enables inheritors to send and receive messages without needing to know the internal details of the GMPs.

2. BridgeRouter:

   • The BridgeRouter abstracts the differences between available GMPs, routing messages to the appropriate protocol based on user specifications and system requirements.

   • Responsibilities include:

     • Routing a requested message to the specified GMP.

     • Forwarding a received message to the desired smart contract.

     • Storing failed messages to be retried or reversed.

3. Adapters:

   • Each GMP has its own adapter that implements the necessary interfaces for communication.

   • Example: The WormholeAdapter and CCIPAdapter convert messages to a common format for processing by the BridgeRouter.

Error Handling and Recovery

1. Error Recording:

   • If a message fails to be processed, the BridgeRouter records the error and stores the message for future action.

2. Retry and Reverse Functions:

   • Users have the option to retry failed messages or reverse the operation to return any locked funds back to their original state.

Detailed Message Lifecycle Example

1. Initiating a Transaction:

   • A user submits an "Invite Address" transaction to the spoke chain, specifying the use of CCIP for cross-chain communication.

   • The spoke chain calls BridgeRouter with the necessary parameters.

2. Forwarding the Message:

   • The BridgeRouter verifies the sender and forwards the message to the appropriate adapter (e.g., CCIPAdapter).

   • The adapter processes the message and sends it to the corresponding adapter on the hub chain.

3. Receiving the Message:

   • The hub chain adapter receives the message, verifies its integrity, and processes it.

   • The BridgeRouter stores the message details for retry or reversal if necessary.