Stellar Common

Common interfaces, types, and utilities for Stellar contracts in the VIA cross-chain messaging system.

Overview

The vialabs-stellar-common crate provides shared interfaces, types, error definitions, encoding utilities, and helper functions used across Stellar contracts in the VIA ecosystem. This crate promotes code reuse, type safety, and consistency across contracts.

Modules

Core Interfaces

message_client_v4 - Interface and base implementation for message client contracts
message_gateway_v4 - Interface for message gateway contracts

Utilities

encoding - Encoding and decoding utilities for cross-chain data (EVM, VIA formats)
utils - Helper functions for address validation and common operations
storage - Storage keys and data structures used across contracts

Error Handling

errors - Standard error types for contract operations

Handler Interfaces

fee - Fee handler contract interface
gas - Gas handler contract interface
pos - Proof of Stake (POS) handler contract interface

Usage

Adding to Your Project

Add the common crate to your contract's Cargo.toml:

[dependencies]
vialabs-stellar-common = "0.1.2"
soroban-sdk = "22.0.8"

Using Interfaces

use vialabs_stellar_common::message_client_v4::{
    MessageClientV4Interface,
    ProcessFromGatewayRequest,
    Base
};
use vialabs_stellar_common::message_gateway_v4::{
    MessageGatewayV4Interface,
    SendRequest,
    ProcessRequest
};

Using Encoding Utilities

use vialabs_stellar_common::encoding::evm::{
    encode_abi_bridge_data,
    decode_abi_bridge_data
};

let encoded = encode_abi_bridge_data(&env, &recipient, amount, &text);
let (recipient, amount, text) = decode_abi_bridge_data(&env, &encoded);

Using Utilities

use vialabs_stellar_common::utils::{is_zero_address, validate_address_bytes};

let is_zero = is_zero_address(&env, address_bytes);
let is_valid = validate_address_bytes(&env, signer, public_key);

Using Error Types

use vialabs_stellar_common::errors::Error;

panic_with_error!(env, Error::MissingMessageGateway);

Message Client V4

The MessageClientV4Interface trait defines the interface for cross-chain message client contracts. The Base implementation provides default functionality that can be used via the #[default_impl] macro from vialabs-stellar-macros.

Required Implementation

Contracts implementing MessageClientV4Interface must implement the message_process method, which handles incoming cross-chain messages.

Default Methods

All other methods have default implementations that can be automatically included using the #[default_impl] macro.

Message Gateway V4

The MessageGatewayV4Interface trait defines the interface for the message gateway contract, which handles routing and processing of cross-chain messages.

Encoding

The encoding module provides utilities for encoding and decoding data in formats compatible with Ethereum (EVM) and other chains.

Storage Keys

The storage module defines common storage keys used across contracts to ensure consistency and avoid conflicts.

Benefits

Code Reuse: Share interfaces and utilities across contracts
Type Safety: Ensure contracts implement the same interface correctly
Consistency: Standardize contract interfaces across the project
Maintainability: Update interfaces and utilities in one place
Interoperability: Use common encoding formats for cross-chain communication

vialabs-stellar-common 0.1.2