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.7"
soroban-sdk = "23.0.2"

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_chain_data,
    decode_abi_chain_data
};

let encoded = encode_abi_chain_data(&env, &recipient, amount, &text);
let (recipient, amount, text) = decode_abi_chain_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.