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.
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.
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';