An easy-to-use SDK for building frontend interfaces that interact with a community server and any related smart contracts that we use. This SDK is frontend framework agnostic and includes types, API calls, and state management.
# Introduction
Welcome to the official SDK for our platform.
We hope you find this SDK useful, and we're excited to see what you build with it!
# Installation
To install the SDK, run the following command in your terminal:
```
Deno add jsr:@citizenwallet/sdk
```
# Installation (npm)
To install the SDK, run the following command in your terminal:
```
npm install --save @citizenwallet/sdk
```
# Getting Started
## Understanding CommunityConfig
The `CommunityConfig` class is the foundation of the SDK. Almost all SDK functions require a `CommunityConfig` instance as their first parameter. This config object contains all the information about a community, including blockchain networks, contract addresses, tokens, and more.
## Loading Configuration
### Step 1: Fetch the Configuration JSON
Community configurations are typically hosted as JSON files. You can fetch them from a URL:
```typescript
import { CommunityConfig, type Config } from "@citizenwallet/sdk";
async function loadConfig(configUrl: string): Promise {
const response = await fetch(configUrl);
const configData: Config = await response.json();
return new CommunityConfig(configData);
}
// Example: Load config from a community's domain
const config = await loadConfig("https://example.com/config/community.json");
```
### Step 2: Use CommunityConfig in SDK Functions
Once you have a `CommunityConfig` instance, you can use it with any SDK function:
```typescript
import {
CommunityConfig,
getAccountAddress,
getAccountBalance,
BundlerService,
LogsService
} from "@citizenwallet/sdk";
// Initialize config
const config = await loadConfig("https://example.com/config/community.json");
// Use config in SDK functions
const accountAddress = await getAccountAddress(config, userAddress);
const balance = await getAccountBalance(config, accountAddress);
// Create service instances
const bundler = new BundlerService(config);
const logsService = new LogsService(config);
```
## Configuration Structure
The configuration JSON follows a specific structure. Here's a minimal example:
```json
{
"community": {
"name": "Community Name",
"alias": "community-alias",
"primary_token": {
"address": "0x...",
"chain_id": 42220
},
"primary_account_factory": {
"address": "0x...",
"chain_id": 42220
}
},
"tokens": {
"42220:0x...": {
"standard": "erc20",
"name": "Token Name",
"symbol": "TKN",
"decimals": 18,
"address": "0x...",
"chain_id": 42220
}
},
"chains": {
"42220": {
"id": 42220,
"node": {
"url": "https://...",
"ws_url": "wss://..."
}
}
},
"accounts": {
"42220:0x...": {
"chain_id": 42220,
"entrypoint_address": "0x...",
"paymaster_address": "0x...",
"account_factory_address": "0x...",
"paymaster_type": "cw"
}
},
"scan": {
"url": "https://explorer.example.com",
"name": "Explorer Name"
},
"ipfs": {
"url": "https://ipfs.example.com"
},
"config_location": "https://example.com/config/community.json",
"version": 4
}
```
See the `community.json` file in this repository for a complete example.
## Quick Example
Here's a complete example showing how to use the SDK:
```typescript
import {
CommunityConfig,
getAccountAddress,
getAccountBalance,
BundlerService
} from "@citizenwallet/sdk";
import { Wallet } from "ethers";
// Load configuration
async function main() {
const response = await fetch("https://example.com/config/community.json");
const configData = await response.json();
const config = new CommunityConfig(configData);
// Get smart account address for a user
const userAddress = "0x1234...";
const accountAddress = await getAccountAddress(config, userAddress);
// Check account balance
const balance = await getAccountBalance(config, accountAddress);
// Send tokens using bundler
const signer = new Wallet(privateKey);
const bundler = new BundlerService(config);
const txHash = await bundler.sendERC20Token(
signer,
config.primaryToken.address,
accountAddress,
recipientAddress,
amount,
"Transfer description"
);
console.log("Transaction hash:", txHash);
}
```
**Important**: Always instantiate `CommunityConfig` before using any SDK functions. The config is required for all operations.
# API Reference
## Configuration
### Types and Interfaces
- `Config` - Main configuration interface
- `ConfigCommunity` - Community configuration
- `ConfigToken` - Token configuration
- `ConfigAccount` - Account configuration
- `ConfigChain` - Chain configuration
- `ConfigIPFS` - IPFS configuration
- `ConfigPlugin` - Plugin configuration
### CommunityConfig Class
The main configuration class that provides helper methods for accessing community settings.
```typescript
import { CommunityConfig } from "@citizenwallet/sdk";
const config = new CommunityConfig(configData);
// Access primary token
const token = config.primaryToken;
// Access primary network
const network = config.primaryNetwork;
// Access RPC URL
const rpcUrl = config.primaryRPCUrl;
// Access account configuration
const accountConfig = config.primaryAccountConfig;
// Access session configuration
const sessionConfig = config.primarySessionConfig;
// Access card configuration
const cardConfig = config.primaryCardConfig;
// Get token by project name
const projectToken = config.getProjectToken("project-name");
```
## Constants
### Networks
Predefined network configurations for supported blockchains:
```typescript
import { NETWORKS } from "@citizenwallet/sdk";
// Available networks: 100 (Gnosis), 137 (Polygon), 8453 (Base), 42220 (CELO), 42161 (Arbitrum)
const gnosisNetwork = NETWORKS["100"];
```
## Profiles
Profile management functions for community members.
### `formatProfileImageLinks(ipfsUrl: string, profile: Profile): Profile`
Formats profile image URLs to use the provided IPFS domain.
### `formatUsernameToBytes32(username: string): string`
Converts a username to bytes32 format for smart contract interaction.
### `getProfileFromId(ipfsDomain: string, config: CommunityConfig, id: string): Promise`
Retrieves a profile by its token ID.
### `getProfileFromAddress(ipfsDomain: string, config: CommunityConfig, address: string): Promise`
Retrieves a profile by wallet address.
### `getProfileFromUsername(ipfsDomain: string, config: CommunityConfig, username: string): Promise`
Retrieves a profile by username.
### `hasProfileAdminRole(config: CommunityConfig, address: string): Promise`
Checks if an address has profile admin role.
### `checkUsernameAvailability(config: CommunityConfig, username: string): Promise`
Checks if a username is available for registration.
## Logs
Transaction log management and querying.
### `LogsService` Class
Service for querying transaction logs with pagination and filtering.
```typescript
import { LogsService } from "@citizenwallet/sdk";
const logsService = new LogsService(config);
// Get a specific log
const log = await logsService.getLog(tokenAddress, hash);
// Get logs with pagination and filtering
const logs = await logsService.getLogs(tokenAddress, topic, {
limit: 10,
offset: 0,
maxDate: "2024-01-01T00:00:00Z",
data: { key: "value" },
});
// Get all logs
const allLogs = await logsService.getAllLogs(tokenAddress, topic);
// Get new logs since a date
const newLogs = await logsService.getNewLogs(tokenAddress, topic, {
fromDate: "2024-01-01T00:00:00Z",
});
```
### Event Signatures
- `TRANSFER_EVENT_SIGNATURE` - ERC20 transfer event signature
## Bundler
Smart account transaction bundling and execution.
### `BundlerService` Class
Service for creating and submitting user operations to the bundler.
```typescript
import { BundlerService } from "@citizenwallet/sdk";
const bundler = new BundlerService(config);
// Send ERC20 tokens
const txHash = await bundler.sendERC20Token(
signer,
tokenAddress,
fromAddress,
toAddress,
amount,
description
);
// Mint ERC20 tokens
const txHash = await bundler.mintERC20Token(
signer,
tokenAddress,
fromAddress,
toAddress,
amount,
description
);
// Burn ERC20 tokens
const txHash = await bundler.burnFromERC20Token(
signer,
tokenAddress,
senderAddress,
fromAddress,
amount,
description
);
// Set profile
const txHash = await bundler.setProfile(
signer,
signerAccountAddress,
profileAccountAddress,
username,
ipfsHash
);
// Burn profile
const txHash = await bundler.burnProfile(
signer,
signerAccountAddress,
profileAccountAddress
);
// Grant role
const txHash = await bundler.grantRole(
signer,
tokenAddress,
senderAddress,
role,
accountAddress
);
// Revoke role
const txHash = await bundler.revokeRole(
signer,
tokenAddress,
senderAddress,
role,
accountAddress
);
// Execute custom call
const txHash = await bundler.call(
signer,
contractAddress,
senderAddress,
calldata,
value,
userOpData,
extraData
);
```
## IPFS
IPFS integration utilities.
### `downloadJsonFromIpfs(ipfsDomain: string, uri: string): Promise`
Downloads and parses JSON data from IPFS.
## Vouchers
Voucher creation and parsing for token distribution.
### `createVoucher(config: CommunityConfig, voucherName: string, voucherCreator: string, voucherSigner: BaseWallet): Promise<{voucherLink: string, voucherAccountAddress: string}>`
Creates a voucher for token distribution.
### `parseVoucher(data: string): {voucher: Voucher, signer: BaseWallet}`
Parses a voucher from a URL or data string.
## Deep Links
QR code parsing and deep link generation.
### `generateLegacyReceiveLink(baseUrl: string, config: CommunityConfig, account: string, amount?: string, description?: string): string`
Generates a legacy receive link for token transfers.
### `parseQRFormat(raw: string): QRFormat`
Determines the format of a QR code or URI.
### `parseQRCode(raw: string): ParseQRData`
Parses QR code data into structured format.
### `parseMessageFromReceiveLink(raw: string): string | null`
Extracts message from a receive link.
## Accounts
Account management and verification functions.
### `getENSAddress(mainnetRpcUrl: string, domain: string): Promise`
Resolves ENS domain to address.
### `getAccountAddress(config: CommunityConfig, address: string, salt?: bigint): Promise`
Gets the smart account address for a given owner and salt.
### `getAccountBalance(config: CommunityConfig, address: string): Promise`
Gets the token balance for an account.
### `verifyAccountOwnership(config: CommunityConfig, accountAddress: string, message: string, signature: string): Promise`
Verifies account ownership through signature validation.
### `isSafeOwner(config: CommunityConfig, accountAddress: string, ownerAddress: string): Promise`
Checks if an address is an owner of a Safe account.
## Receive
Receive link generation.
### `generateReceiveLink(baseUrl: string, config: CommunityConfig, account: string, amount?: string, description?: string): string`
Generates a receive link for token transfers.
## Transactions
Transaction utilities.
### `waitForTxSuccess(config: CommunityConfig, txHash: string, timeout?: number): Promise`
Waits for a transaction to be confirmed and checks its success status.
## Cards
Card management functions.
### `getCardAddress(config: CommunityConfig, hashedSerial: string, instanceId?: string): Promise`
Gets the card address for a given serial number and instance.
### `instanceOwner(config: CommunityConfig, instanceId?: string): Promise`
Gets the owner of a card instance.
## Calldata
Smart contract call data generation.
### `tokenTransferCallData(to: string, value: bigint): Uint8Array`
Generates calldata for ERC20 token transfers.
### `tokenMintCallData(to: string, value: bigint): Uint8Array`
Generates calldata for ERC20 token minting.
### `createInstanceCallData(config: CommunityConfig, contracts: string[], instanceId?: string): Uint8Array`
Generates calldata for creating card instances.
### `updateInstanceContractsCallData(config: CommunityConfig, contracts: string[], instanceId?: string): Uint8Array`
Generates calldata for updating instance contracts.
### `updateWhitelistCallData(config: CommunityConfig, addresses: string[], instanceId?: string): Uint8Array`
Generates calldata for updating whitelist.
### `callOnCardCallData(config: CommunityConfig, hashedSerial: string, to: string, value: bigint, data: Uint8Array, instanceId?: string): Uint8Array`
Generates calldata for executing calls on cards.
### `addOwnerCallData(config: CommunityConfig, hashedSerial: string, newOwner: string, instanceId?: string): Uint8Array`
Generates calldata for adding card owners.
### `generateCalldataLink(baseUrl: string, config: CommunityConfig, address: string, value: bigint, calldata: string): string`
Generates a deep link with calldata for execution.
### Event Topics
- `tokenTransferEventTopic` - ERC20 transfer event topic
- `tokenTransferSingleEventTopic` - ERC1155 transfer single event topic
- `roleGrantedEventTopic` - Role granted event topic
- `roleRevokedEventTopic` - Role revoked event topic
## Utils
### Crypto
Cryptographic utilities and role management.
### `isFunctionInABI(func: string, abi: any[]): boolean`
Checks if a function exists in an ABI.
### `hasRole(tokenAddress: string, role: string, account: string, provider: JsonRpcProvider): Promise`
Checks if an account has a specific role.
### Role Constants
- `MINTER_ROLE` - ERC20 minter role hash
- `PROFILE_ADMIN_ROLE` - Profile admin role hash
### Gzip
Compression utilities for voucher and deep link data.
- `compress(data: string): string` - Compresses data using gzip
- `decompress(data: string): string` - Decompresses gzipped data
## Alias
Domain parsing utilities.
### `parseAliasFromDomain(domain: string, basePath: string): string`
Extracts community alias from a domain.
## Connect
Authentication and connection utilities.
### `generateConnectionMessage(accountAddress: string, expiryTimeStamp: string, redirectUrl?: string): string`
Generates a connection message for signature authentication.
### `generateConnectedHeaders(signer: Signer, accountAddress: string, expiryTimeStamp: string, redirectUrl?: string): Promise
