Getting Started with SORA Development

Welcome to SORA development! This guide will help you set up your environment, understand the ecosystem, and start building applications on the SORA network.

Choose Your Path

DApp Developer

Build applications that interact with SORA, Polkaswap, or TONSWAP.

Smart Contract Developer

Write WASM contracts for SORA v3 (Iroha).

Integration Developer

Connect existing systems to SORA via APIs and bridges.

Infrastructure

Run nodes, validators, or indexing services.

Prerequisites

Required Knowledge

Topic	Level	Why
JavaScript/TypeScript	Intermediate	Frontend + SDK usage
Blockchain Basics	Beginner	Transaction concepts
React (optional)	Beginner	Frontend development
Rust (optional)	Beginner	Smart contracts (v3)

System Requirements

# Node.js 18+
node --version  # v18.0.0 or higher

# pnpm (recommended) or npm
pnpm --version  # 8.0.0 or higher

# Git
git --version

Quick Start

Option 1: Polkaswap Integration

The fastest way to integrate with SORA:

Install the SDK

pnpm add @sora-substrate/sdk @polkadot/api

Initialize Connection

import { Api } from '@sora-substrate/sdk';

const api = new Api();
await api.connect('wss://mof3.sora.org');

console.log('Connected to SORA mainnet');

Query Data

// Get XOR balance
const balance = await api.query.assets.freeBalance(
  XOR_ASSET_ID,
  accountAddress
);

console.log('XOR Balance:', balance.toString());

Submit Transaction

// Transfer XOR
const tx = api.tx.assets.transfer(
  XOR_ASSET_ID,
  recipientAddress,
  amount
);

await tx.signAndSend(keypair);

Option 2: Web3 Wallet Integration

Connect to user wallets:

import { web3Accounts, web3Enable } from '@polkadot/extension-dapp';

// Request wallet access
const extensions = await web3Enable('My SORA App');

if (extensions.length === 0) {
  throw new Error('No wallet found. Install Fearless or Polkadot.js');
}

// Get accounts
const accounts = await web3Accounts();
console.log('Available accounts:', accounts);

Development Environment

Local Setup

Connect to SORA testnet for development:

const TESTNET_WS = 'wss://ws.stage.sora2.soramitsu.co.jp';

const api = new Api();
await api.connect(TESTNET_WS);

Get test tokens:

Join SORA Discord
Use #faucet channel
Request test XOR

Run a local SORA node:

# Clone repository
git clone https://github.com/sora-xor/sora2-network.git
cd sora2-network

# Build
cargo build --release

# Run development chain
./target/release/sora2-node --dev

Connect to local:

await api.connect('ws://127.0.0.1:9944');

Production endpoints:

// Primary endpoint
const MAINNET_WS = 'wss://mof3.sora.org';

// Backup endpoints
const BACKUP_WS = [
  'wss://ws.mof.sora.org',
  'wss://sora.api.onfinality.io/public-ws',
];

Common Operations

Asset Operations

import { XOR, VAL, PSWAP } from '@sora-substrate/sdk/assets';

// Get asset info
const xorInfo = await api.query.assets.assetInfos(XOR);
console.log('XOR Decimals:', xorInfo.precision.toString());

// Get all balances
const balances = await api.query.assets.freeBalance.multi([
  [XOR, account],
  [VAL, account],
  [PSWAP, account],
]);

// Register new asset (requires permission)
const registerTx = api.tx.assets.register(
  symbol,
  name,
  totalSupply,
  isMintable,
  isIndivisible,
  optionalContent
);

Trading on Polkaswap

// Get quote for swap
const quote = await api.rpc.liquidityProxy.quote(
  dexId,
  inputAssetId,
  outputAssetId,
  amount,
  'WithDesiredInput', // or 'WithDesiredOutput'
  [],  // filter sources
  'Disabled' // filter mode
);

console.log('Expected output:', quote.amount.toString());
console.log('Price impact:', quote.priceImpact.toString());

// Execute swap
const swapTx = api.tx.liquidityProxy.swap(
  dexId,
  inputAssetId,
  outputAssetId,
  swapAmount,
  minAmountOut,
  [],  // sources
  'Disabled'
);

await swapTx.signAndSend(keypair);

Liquidity Operations

// Add liquidity to XYK pool
const addLiquidityTx = api.tx.poolXYK.depositLiquidity(
  dexId,
  assetA,
  assetB,
  amountADesired,
  amountBDesired,
  amountAMin,
  amountBMin
);

// Remove liquidity
const removeLiquidityTx = api.tx.poolXYK.withdrawLiquidity(
  dexId,
  assetA,
  assetB,
  markerAssetId,
  liquidityAmount,
  amountAMin,
  amountBMin
);

Bridge Integration

HASHI (Ethereum)

// Request outgoing transfer to Ethereum
const bridgeTx = api.tx.ethBridge.transferToSidechain(
  assetId,
  ethRecipientAddress,
  amount,
  bridgeNetworkId
);

// Listen for bridge events
api.query.system.events((events) => {
  events.forEach(({ event }) => {
    if (event.section === 'ethBridge') {
      console.log('Bridge event:', event.method, event.data);
    }
  });
});

TONSWAP

// TONSWAP uses its own SDK
import { TonSwapSDK } from '@tonswap/sdk';

const tonswap = new TonSwapSDK();

// Bridge XOR to TON
await tonswap.bridge.toTon({
  asset: 'XOR',
  amount: '100',
  tonRecipient: 'EQ...',
});

Best Practices

Error Handling

try {
  const result = await tx.signAndSend(keypair, ({ status, events }) => {
    if (status.isInBlock) {
      console.log('Transaction in block:', status.asInBlock.toHex());

      // Check for errors in events
      events.forEach(({ event }) => {
        if (api.events.system.ExtrinsicFailed.is(event)) {
          const [error] = event.data;
          if (error.isModule) {
            const decoded = api.registry.findMetaError(error.asModule);
            console.error('Error:', decoded.name, decoded.docs);
          }
        }
      });
    }
  });
} catch (error) {
  console.error('Transaction failed:', error.message);
}

Performance

Practice	Reason
Batch queries	Reduce RPC calls
Cache responses	Avoid redundant requests
Use subscriptions	Real-time updates
Handle reconnects	Network reliability

// Batch multiple queries
const [balance1, balance2, balance3] = await Promise.all([
  api.query.assets.freeBalance(asset1, account),
  api.query.assets.freeBalance(asset2, account),
  api.query.assets.freeBalance(asset3, account),
]);

// Subscribe to changes
const unsub = await api.query.assets.freeBalance(
  XOR,
  account,
  (balance) => {
    console.log('Balance updated:', balance.toString());
  }
);

// Cleanup
unsub();

Security

✅ Use wallet extensions for signing
✅ Validate all user inputs
✅ Handle transaction errors gracefully
✅ Test on testnet first
❌ Don’t hardcode private keys
❌ Don’t trust client-side data

Resources

SDKs and Libraries

Library	Purpose	Install
@sora-substrate/sdk	Core SORA SDK	`pnpm add @sora-substrate/sdk`
@polkadot/api	Substrate base	`pnpm add @polkadot/api`
@polkadot/extension-dapp	Wallet integration	`pnpm add @polkadot/extension-dapp`

Documentation

SORA Wiki — Official documentation
Polkaswap Guide — DEX documentation
Substrate Docs — Framework reference

Community

Discord — Developer chat
Telegram — Community discussion
GitHub — Source code

Next Steps

Iroha Overview

Learn about SORA v3 infrastructure

Smart Contracts

Build WASM contracts

Bridges

Cross-chain integration

Polkaswap

DEX integration guide