@elacity-js/contracts

Elacity Contracts SDK. Typed smart-contract wrappers + ABIs for interacting with Elacity's on-chain ecosystem (EVM-compatible networks).

This package is runner-agnostic: pair it with a runner adapter (e.g. @elacity-js/contracts-ethers-adapter or @elacity-js/contracts-viem-adapter) that implements IContractRunner.

Core Interfaces

| Interface | Purpose | | --- | --- | | IContractRunner | Read/write contract calls, raw-ify, gas estimation | | IProvider | Fetch on-chain transaction data & receipts | | IContractTransactionResponse | Submitted transaction handle with wait() | | IContractTransactionReceipt | Minimal receipt (status + hash) | | ICommitableContractTransaction | ABI-encoded tx ready to commit or pass to an executor | | ITransactionExecutor<R> | Executes one or more committable txs (standard or bundled) | | IBulkExecutionResponse | Base response shape for executors (transactions?, extensible) | | IAbiEncoder | ABI encoding abstraction |

Adapters implement IContractRunner and IProvider so they can be used both for contract interactions and transaction lookups.

Contract Version Setup

The contracts client supports ecosystem version selection at setup time.

import { setupContracts, setupContractClient, getContractVersion } from '@elacity-js/contracts';

// Default (if setup is never called): 3.0
setupContracts();

// Explicitly set ecosystem/contract version
setupContracts({ version: '3.0' });

// Alias with same behavior
setupContractClient({ version: '2.0' });

console.log(getContractVersion()); // '2.0'

Versioning Rules

• Default SDK contract/ecosystem version is 3.0.
• Only ecosystem contracts are versioned:
  • CentralStorage (CoreStorage kept as compatibility alias)
  • ChannelFactory (ChannelCore kept as compatibility alias)
  • RoyaltyTradeGateway (TradeGateway kept as compatibility alias)
  • AuthorityGateway
  • EventHub (v3 only)
• Standard/common wrappers are always loaded from the v3 ABI set (e.g. ERC20, ERC1155, DigitalAsset, MultiChannel, Operative*).

Ecosystem Address Resolution

• fromChainId(...) helpers resolve fixed addresses through the configured version.
• 2.0 keeps the existing ecosystem addresses.
• 3.0 currently includes Base + Arbitrum Sepolia entries only; Elastos has no 3.0 entry.
• EventHub is available only on 3.0 ecosystem entries.
• If a chain is not configured for the selected version, helpers throw an Unsupported chainId ... for contract version ... error.

ABI Lookup Helpers

Use the ABI registry helpers when you need ABI access outside wrapper constructors.

import { getContractAbi, getContractAbiForVersion } from '@elacity-js/contracts';

// Uses currently configured SDK version (from setupContracts)
const activeAbi = getContractAbi('AuthorityGateway');

// Explicit/deterministic version lookup
const v2Abi = getContractAbiForVersion('TradeGateway', '2.0');
const v3Abi = getContractAbiForVersion('RoyaltyTradeGateway', '3.0');

Design note:

• getContractAbi(contract) intentionally has no version parameter.
• For explicit version resolution, use getContractAbiForVersion(contract, version).

Documentation

• https://docs.ela.city/sdks/contracts/

Contributing

If you want to contribute:

• Add/adjust wrappers in packages/contracts/src/lib/contracts/ (keep them ABI-aligned)
• Mandatory: when changing anything in packages/contracts/**, also update Contracts docs under .github/wiki/documentation/contracts, including impacted SDK pages
• Run nx test contracts, then nx build contracts

Small, ABI-driven changes are preferred over broad refactors.

This library was generated with Nx.

Building

Run nx build contracts to build the library.

Running unit tests

Run nx test contracts to execute the unit tests via Jest.