SDK Reference
JavaScript and TypeScript SDK
Pre-launch
Section
SDK Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete reference for the SwssChain JavaScript and TypeScript SDK including client setup, transaction submission, Deed settlement, and event subscriptions.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

JavaScript and TypeScript SDK

The @swsschain/sdk package provides a full-featured JavaScript and TypeScript interface to the SwssChain network. It is built on top of viem v2 and exports all standard EVM utilities alongside SwssChain-specific extensions for Deed settlement and Finality Certificate retrieval.

Installation

npm install @swsschain/sdk
# or
yarn add @swsschain/sdk
# or
pnpm add @swsschain/sdk

Minimum Node.js version: 18.0.0. The package ships both CommonJS and ESM builds. TypeScript types are bundled: no separate @types package is required.

Peer Dependencies

The SDK does not bundle viem or ethers: they are peer dependencies. Install the version your project already uses:

npm install viem@^2.0.0
# or, if you prefer ethers
npm install ethers@^6.0.0

Client Initialisation

import { SwssChain, networks, type SwssChainConfig } from '@swsschain/sdk';

const config: SwssChainConfig = {
  network: networks.mainnet,       // or networks.testnet
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  // Optional: override the default RPC URL
  rpcUrl: process.env.SWSSCHAIN_RPC_URL,
  // Optional: WebSocket URL for subscriptions
  wsUrl: process.env.SWSSCHAIN_WS_URL,
};

const client = new SwssChain(config);

Reading Chain State

// Current block number
const block = await client.getBlockNumber();

// Block details
const blockData = await client.getBlock(block);
console.log(blockData.hash, blockData.timestamp, blockData.transactions.length);

// Account balance
const balance = await client.getBalance('0xRecipientAddress');
console.log(client.formatSWSSCoin(balance)); // human-readable SWSS

// Transaction by hash
const tx = await client.getTransaction('0xTxHash');

// Transaction receipt
const receipt = await client.getTransactionReceipt('0xTxHash');
console.log(receipt.status); // 'success' | 'reverted'

Sending Transactions

// Simple SWSS Coin transfer
const txHash = await client.sendTransaction({
  to: '0xRecipientAddress',
  value: client.parseSWSSCoin('1.5'),  // 1.5 SWSS in wei
});

// Wait for confirmation (finality on SwssChain: ~2 seconds)
const receipt = await client.waitForTransaction(txHash, {
  confirmations: 2,
  timeout: 30_000,  // 30 seconds
});

console.log('Confirmed in block:', receipt.blockNumber);

Contract Interaction

import { SwssChain, networks } from '@swsschain/sdk';

const ABI = [
  {
    name: 'transfer',
    type: 'function',
    inputs: [
      { name: 'to', type: 'address' },
      { name: 'amount', type: 'uint256' }
    ],
    outputs: [{ name: '', type: 'bool' }]
  },
  {
    name: 'balanceOf',
    type: 'function',
    stateMutability: 'view',
    inputs: [{ name: 'account', type: 'address' }],
    outputs: [{ name: '', type: 'uint256' }]
  }
] as const;

const client = new SwssChain({ network: networks.mainnet });
const contract = client.getContract({
  address: '0xContractAddress',
  abi: ABI,
});

// Read (no gas)
const balance = await contract.read.balanceOf(['0xHolderAddress']);

// Write (requires funded account and private key)
const hash = await contract.write.transfer([
  '0xRecipientAddress',
  BigInt('1000000000000000000')  // 1 token with 18 decimals
]);

Deed Settlement

import { SwssChain, networks, DeedType } from '@swsschain/sdk';

const client = new SwssChain({
  network: networks.mainnet,
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

// Submit a Home Deed settlement
const settlement = await client.deed.submit({
  type: DeedType.HOME_DEED,
  propertyId: 'PROP-2025-00142',
  parcelRef: 'SG-00142-A',
  settlementValue: client.parseSWSSCoin('250000'),
  fromAddress: '0xSellerAddress',
  toAddress: '0xBuyerAddress',
  metadata: {
    jurisdiction: 'SG',
    registrationRef: 'REF-2025-00142',
  },
});

console.log('Settlement ID:', settlement.id);
console.log('Transaction hash:', settlement.txHash);

// Retrieve Finality Certificate once confirmed
const certificate = await client.deed.getFinalityCertificate(settlement.id);
console.log('Certificate hash:', certificate.certificateHash);
console.log('Validator signatures:', certificate.signatures.length);

Event Subscriptions

WebSocket subscriptions require the wsUrl configuration option.

const client = new SwssChain({
  network: networks.mainnet,
  wsUrl: process.env.SWSSCHAIN_WS_URL,
});

// Subscribe to new blocks
const unsubscribeBlocks = await client.subscribeToBlocks((block) => {
  console.log('New block:', block.number, block.hash);
});

// Subscribe to transactions for a specific address
const unsubscribeAddress = await client.subscribeToAddress(
  '0xWatchedAddress',
  (event) => {
    console.log('Incoming tx:', event.txHash, 'value:', event.value);
  }
);

// Subscribe to Deed settlement events
const unsubscribeDeeds = await client.deed.subscribeToSettlements(
  DeedType.HOME_DEED,
  (settlement) => {
    console.log('Settlement confirmed:', settlement.id);
  }
);

// Clean up
unsubscribeBlocks();
unsubscribeAddress();
unsubscribeDeeds();

Wagmi Integration

For React applications using wagmi v2, use the SwssChain chain definition:

import { createConfig, http } from 'wagmi';
import { swssChainMainnet, swssChainTestnet } from '@swsschain/sdk/wagmi';

const config = createConfig({
  chains: [swssChainMainnet, swssChainTestnet],
  transports: {
    [swssChainMainnet.id]: http(process.env.SWSSCHAIN_RPC_URL),
    [swssChainTestnet.id]: http(process.env.SWSSCHAIN_TESTNET_RPC_URL),
  },
});

Error Handling

import { SwssChainError, RpcError, DeedError } from '@swsschain/sdk';

try {
  const hash = await client.sendTransaction({ to: '0x...', value: 1n });
} catch (err) {
  if (err instanceof DeedError) {
    console.error('Deed settlement failed:', err.code, err.message);
  } else if (err instanceof RpcError) {
    console.error('RPC error:', err.code, err.message);
  } else if (err instanceof SwssChainError) {
    console.error('SDK error:', err.message);
  } else {
    throw err;  // Re-throw unexpected errors
  }
}

TypeScript Types

The SDK exports all types used internally. Import them as needed:

import type {
  SwssChainConfig,
  Block,
  Transaction,
  TransactionReceipt,
  DeedSubmission,
  DeedSettlement,
  FinalityCertificate,
  DeedType,
  Network,
  SwssAddress,
  SWSSCoinValue,
} from '@swsschain/sdk';