Bolarity Connect SDK

This documentation provides an overview of the purpose of the Bolarity SDK, details the project’s directory structure, and explains the core modules. It is intended for developers who need to under

Project Purpose

The SDK is designed to simplify and standardize the process of constructing on-chain transactions for cross-chain actions. The primary goals are as follows:

• Abstract Complexity: Hide the intricacies of multiple blockchain interactions by providing a unified interface for generating ready-to-sign transaction data.

• Flexible Transfer Strategies: Support various transfer methods such as Local Transfer (within the same chain), Remote Control Transfer (direct cross-chain message calls), Bridge Transfer (using bridge contracts), and a composite strategy called RemoteBridgeTransfer (a combination of remote control and bridging to cover shortfalls).

• Modular & Extendable: Offer a modular design that allows for the addition of new chains, strategies, or blockchain-specific behaviors without affecting the overall API.

---

Project Structure

The project is organized to ensure a clear separation of concerns, maintainability, and ease of expansion. The top-level structure is as follows:

Bolarity-Connect-sdk/
├── src/
│   ├── types/
│   │   └── index.ts          # Global type definitions and interfaces (e.g., transfer requests, transaction formats, strategy enums)
│   ├── utils/
│   │   ├── evm.ts            # Utility functions specific to EVM chains (e.g., address validation, transaction signing, encoding)
│   │   └── svm.ts            # Utility functions for SVM or non-EVM chains (e.g., constructing transactions, data formatting)
│   ├── core/
│   │   ├── transfer/
│   │   │   ├── LocalTransfer.ts           # Implements local (same-chain) transfer strategy
│   │   │   ├── RemoteControlTransfer.ts   # Implements remote control transfer strategy
│   │   │   ├── BridgeTransfer.ts          # Implements bridge transfer strategy using bridge contracts
│   │   │   └── RemoteBridgeTransfer.ts    # Implements the composite RemoteBridgeTransfer strategy 
│   │   ├── transfer.ts       # Aggregates and dispatches the transfer strategies via a unified interface
│   │   ├── bridge.ts         # Contains the logic for interacting with cross-chain bridge contracts (asset locking/unlocking)
│   │   └── approve.ts        # Contains logic for pre-transfer approval checks and constructing approve transactions
│   └── index.ts              # SDK entry point: integrates core modules and exposes the public API
├── tests/                    # Automated tests (unit and integration)
├── examples/                 # Example scripts and usage scenarios demonstrating the SDK
├── package.json              # Project metadata, dependencies, and build scripts
├── tsconfig.json             # TypeScript configuration file
└── README.md                 # Project overview and documentation

---

Module Explanations

1. Types (src/types/index.ts)

• Purpose: Define all shared interfaces, data types, and enumerations used throughout the SDK.

• Key Components:

  • CrossChainTransferRequest: Defines the structure of a request (source chain ID, destination chain ID, amount, token type, target address, etc.).

  • PreparedTransaction: Represents the structure of a generated transaction that is ready for signing.

  • Strategy Enumerations: Enums for transfer strategies like LocalTransfer, RemoteControlTransfer, BridgeTransfer, and RemoteBridgeTransfer.

2. Utilities (src/utils/)

• evm.ts: Provides functions specific to EVM-compatible chains, such as:

  • Address validation

  • Transaction data encoding

  • Signing utilities and formatting routines

• svm.ts: Tailored for SVM or other non-EVM chains, offering:

  • Transaction construction methods

  • Data serialization and format conversion

3. Core Modules (src/core/)

a. Transfer Strategies (src/core/transfer/)

This folder contains strategy modules for generating transfer transactions. Each file implements a distinct strategy:

• LocalTransfer.ts: Generates transaction data for transfers occurring on the same blockchain.

• RemoteControlTransfer.ts: Handles the logic for cross-chain operations where a direct remote message or command is sufficient.

• BridgeTransfer.ts: Encapsulates the logic needed to interact with bridge contracts, including asset locking and unlocking processes.

• RemoteBridgeTransfer.ts: A composite strategy that combines aspects of remote control and bridge transfers. It is used in scenarios where a simple remote control transfer does not fully satisfy balance requirements on the destination chain.

  • Implementation Note: This module dynamically calculates the required split between remote control and bridging operations, ensuring that the overall transfer is completed despite resource limitations on any single chain.

b. Transfer Aggregator (src/core/transfer.ts)

• Purpose: Serves as the dispatch layer for transfer strategies.

• Functionality: Examines the input request, chooses the appropriate strategy (or combination thereof), and calls the corresponding module’s function to build the transaction data.

• Design Consideration: Utilizes the Strategy Pattern to allow seamless integration and exchange of different transfer modules based on runtime conditions.

c. Bridge Module (src/core/bridge.ts)

• Purpose: Manages interactions with cross-chain bridge contracts.

• Key Functions:

  • Initiating asset locking and unlocking operations.

  • Interfacing with external bridge services.

  • Handling cross-chain communication protocols associated with bridging.

d. Approve Module (src/core/approve.ts)

• Purpose: Performs pre-transfer validations to check if an "approve" action is required and generates the necessary transaction data for such approval.

• Details: Ensures that tokens or assets meet necessary conditions on the destination chain before the primary transfer occurs, potentially preventing transaction failures.

4. SDK Entry Point (src/index.ts)

• Purpose: Integrates all core components and exposes the unified public API.

• Usage: Applications import the entry point and invoke functions such as createCrossChainTransferMessage() to initiate the process of generating the transfer transactions.