Axionvera SDK

Axionvera SDK v2 is a clean, strongly typed TypeScript toolkit for building dApps and services on top of Axionvera Soroban smart contracts on the Stellar network. It is a monorepo split into focused, independently installable packages so applications pull in only what they need.

Packages

Package	Description
@axionvera/core	Core client (AxionveraClient), network configuration, wallet connectors (WalletConnector, MockWalletConnector), the VaultContract module, typed errors, and shared types.
@axionvera/react	React bindings: AxionveraProvider, useWallet, and useVault.

Installation

Requires Node.js 18+.

# Core SDK (client, contracts, wallet connectors)
npm install @axionvera/core

# React bindings (peer dependencies: @axionvera/core, react >= 18)
npm install @axionvera/react @axionvera/core

Quick start

1. Create a client

import { AxionveraClient } from '@axionvera/core';

const client = new AxionveraClient({ network: 'testnet' });

const health = await client.getHealth();
const transaction = await client.getTransaction('TX_HASH');

2. Configure a vault contract

Contract calls are routed through a ContractInvoker that you provide — bring your own adapter for live Soroban calls, or use a mock while developing.

import { VaultContract, type ContractInvoker } from '@axionvera/core';

const invoker: ContractInvoker = {
  async invoke(request) {
    /* forward to your Soroban transaction layer */
    return { status: 'success' };
  },
  async read(request) {
    /* forward to your Soroban read layer */
    return {};
  }
};

const vault = new VaultContract({ contractId: 'YOUR_CONTRACT_ID', invoker });

const info = await vault.getInfo();
const balance = await vault.getBalance('G...');
const result = await vault.deposit('G...', 100n);

3. Use a mock wallet

import { MockWalletConnector } from '@axionvera/core';

const wallet = new MockWalletConnector('G...');
const { publicKey, network } = await wallet.connect();

4. Wire the React provider

import { AxionveraProvider, useVault } from '@axionvera/react';
import { MockWalletConnector } from '@axionvera/core';

const wallet = new MockWalletConnector('G...');

function DepositButton() {
  // `invoker` is the same ContractInvoker from step 2
  const { deposit, isSubmitting, error, resetError } = useVault({
    contractId: 'YOUR_CONTRACT_ID',
    invoker,
    walletAddress: 'G...'
  });

  if (error) {
    return <button onClick={resetError}>{error.message}</button>;
  }

  return (
    <button disabled={isSubmitting} onClick={() => deposit(100n)}>
      {isSubmitting ? 'Depositing...' : 'Deposit 100'}
    </button>
  );
}

function App() {
  return (
    <AxionveraProvider wallet={wallet}>
      <DepositButton />
    </AxionveraProvider>
  );
}

Complete, copyable examples for each package live in the package READMEs: @axionvera/core and @axionvera/react.

Foundation layer

v2 intentionally keeps RPC and Soroban invocation adapter-based:

• AxionveraClient talks to RPC through an RpcTransport (default FetchRpcTransport), which you can replace with a custom transport.
• VaultContract delegates every call to a ContractInvoker you provide.
• MockWalletConnector implements the WalletConnector interface for development and tests.

A production Soroban invoker or transaction-building layer is not shipped yet — pass your own transport and invoker, or start with the mocks.

Documentation

• SDK Overview
• Usage Guide
• Configuration

Development

npm ci             # install dependencies
npm run lint       # ESLint
npm run typecheck  # TypeScript type checking
npm run build      # build all packages
npm run test       # typecheck + build + unit tests

Contributing

Please read CONTRIBUTING.md for details on the code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ by the Axionvera Team.