Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API Reference

Public exports from @coti-io/coti-wallet-plugin.

Providers

WagmiRainbowKitProvider

Sets up wagmi v2, RainbowKit, and multi-wallet connectors (MetaMask EIP-6963, Rabby, OneKey, Zerion).

<WagmiRainbowKitProvider walletConnectProjectId="your-project-id">
  {children}
</WagmiRainbowKitProvider>

Also exports getWagmiConfig(), wagmiConfig, and WagmiConfigOptions.

PrivacyBridgeProvider

Core provider for wallet, network, tokens, unlock, swap, and PoD state. Nests PrivateUnlockProvider internally.

<PrivacyBridgeProvider privateUnlock={{ theme, warning }}>
  {children}
</PrivacyBridgeProvider>

Props:

Prop
Type
Description

children

React.ReactNode

App content

privateUnlock

PrivateUnlockProviderOptions

Unlock modal theme, warning text, callbacks

PrivateUnlockProvider

Mounted internally by PrivacyBridgeProvider. Exposed for advanced use cases only.

Hooks — unlock

usePrivateUnlock()

High-level unlock controller. Preferred API for app UI.

Property / method
Type
Description

isUnlocked

boolean

Private balances are visible (requires successful balance refresh, not only an AES key)

isUnlocking

boolean

Unlock/onboarding in progress

unlock()

() => Promise<void>

Start unlock flow; succeeds only after private balances refresh

lock()

() => void

Hide private balances

toggleLock()

() => void

Toggle lock state

requireUnlock(action)

(action?) => Promise<boolean>

Ensure unlock, then run action

reset()

() => void

Reset unlock UI state

usePrivacyBridgeUnlock()

Low-level unlock and private crypto operations. Use inside or after requireUnlock.

Property / method
Type
Description

isPrivateUnlocked

boolean

Private balances visible

sessionAesKey

string | null

Session-bound AES key (avoid direct use)

aesKeyChainId

number | undefined

COTI chain for AES state

hasSnap

boolean

Snap detected

sendPrivateToken

(params) => Promise<{ txHash }>

Send a private token transfer

encryptPrivateValue

(params) => Promise<{ ciphertext }>

Encrypt amount to ctUint256 JSON

decryptPrivateValue

(params) => Promise<{ amount }>

Decrypt ctUint256 JSON to amount

lockPrivateBalances

() => void

Hide balances, clear session key

refreshPrivateBalances

(options?) => Promise<boolean>

Low-level balance refresh (do not use for unlock UI)

sendPrivateToken params:

encryptPrivateValue / decryptPrivateValue params:

Hooks — bounded context slices

Prefer these over the legacy flat usePrivacyBridgeContext() for new code.

usePrivacyBridgeWallet()

Property / method
Type
Description

isConnected

boolean

Wallet connected

walletAddress

string

Connected address

handleConnect

() => Promise<void>

Open connect flow

handleDisconnect

() => Promise<void>

Disconnect wallet

metamaskDetected

boolean

MetaMask provider detected

usePrivacyBridgeNetwork()

Property / method
Type
Description

chainId

string | null

Current chain ID

switchNetwork

(chainId) => Promise<boolean>

Switch wallet network

networkName

string

Human-readable network name

isUnsupportedNetwork

boolean

Chain not supported

enforceNetwork

() => Promise<void>

Prompt network switch

usePrivacyBridgeTokens()

Property
Type
Description

publicTokens

Token[]

Public token balances

privateTokens

Token[]

Private token balances (after unlock)

usePrivacyBridgeSwap()

Property / method
Type
Description

amount

string

Bridge amount input

direction

'to-private' | 'to-public'

Bridge direction

selectedTokenIndex

number

Selected token index

handleSwap

(amount?, direction?, tokenIndex?, onProgress?) => Promise<void>

Execute bridge

isBridgingLoading

boolean

Bridge in progress

isApprovalNeeded

boolean

ERC20 approval required

handleApprove

() => Promise<void>

Approve ERC20 spend

estimatedGasFee

string | null

Estimated gas fee display

portalFeeCoti

string | null

COTI bridge portal fee

portalFee

string | null

PoD portal fee (ETH/AVAX)

isPodChain

boolean

Connected chain uses PoD portal

usePrivacyBridgePod()

Property / method
Type
Description

podRequests

PodPortalRequest[]

Tracked PoD portal requests

refreshPodRequest

(request) => Promise<void>

Refresh request status

usePrivacyBridgeModals()

Property
Type
Description

showInstallModal

boolean

Snap install modal visible

showMultipleWalletsModal

boolean

Multiple wallets conflict modal

usePrivacyBridgeContext() (legacy)

Flat union of all slices. Existing consumers may continue using this; new code should prefer bounded hooks.

Hooks — utilities

Hook
Description

useWalletType()

Detect wallet type (MetaMask, Rabby, etc.)

usePrivateTokenBalance()

Fetch and decrypt a single private token balance

useBalanceUpdater()

Balance refresh utility

useNetworkEnforcer()

Network enforcement helper

useMetamask()

MetaMask provider helper

useConnectModal()

Re-exported from RainbowKit

Components

OnboardModal

Onboarding UI component. Do not render directly for unlock — PrivateUnlockProvider mounts it.

Non-Snap flows show a Save Locally switch for optional encrypted backup; Snap onboarding hides it and still shows the persist progress step. Exports onboardModalDefaultStyles and ONBOARD_MODAL_STYLE_KEYS for theming. See Onboard Modal Theming and AES Key Onboarding.

NetworkGuard

Blocks children when the wallet is on an unsupported network.

Configuration

Export
Description

configureCotiPlugin(config)

Set plugin configuration at startup

getPluginConfig()

Read current configuration

getSnapRequestParams(snapId?, snapVersion?)

Params for wallet_requestSnaps

isSnapInstallEnabled()

Whether Snap install is allowed

See Configuration for all CotiPluginConfig options.

Chain registry

Export
Description

CHAIN_CONFIGS

All supported chain configurations

getChainConfig(chainId)

Lookup chain config

getTokensForChain(chainId)

Token list for a chain

getUnlockStrategyForChain(chainId)

Chain-config metadata (snap or manual-aes-key); not the runtime unlock order — see AES Key Onboarding

cotiMainnet, cotiTestnet, sepolia

viem chain definitions

COTI_MAINNET_CHAIN_ID, COTI_TESTNET_CHAIN_ID, SEPOLIA_CHAIN_ID

Chain ID constants

Contracts and tokens

Export
Description

CONTRACT_ADDRESSES

Contract addresses per chain

SUPPORTED_TOKENS

Supported token configurations

getPublicTokensForChain(chainId)

Public tokens for a chain

getPrivateTokensForChain(chainId)

Private tokens for a chain

TOKEN_ABI, BRIDGE_ABI, ERC20_ABI

Contract ABIs

LIMITS

Bridge amount limits

PoD Privacy Portal

Export
Description

PRIVACY_PORTAL_ABI

User deposit / withdraw surface

POD_PTOKEN_ABI

PoD private token (pToken) surface

POD_PORTAL_ADMIN_ABI

Per-portal admin/operator surface (fees, limits, pause, deposit enable, rescue)

POD_PORTAL_FACTORY_ABI

Factory admin/operator roles (isAdmin / isOperator, grantRole / revokeRole)

fetchPodBridgeData(chainId)

Backoffice row data: fees, collateral balance, pause/deposit flags, min/max deposit and withdraw limits

simulatePodPortalFee(...)

Fee simulation helper for portal admin UIs

fetchPodBridgeData maps uncapped max limits (uint128.max sentinels) to "0" (no-cap convention). Collateral balance read failures fail the row instead of returning a false zero balance. Factory and portal addresses live on each PoD chain config (PrivacyPortalFactory, PrivacyPortal*).

Error handling

CotiPluginError

Type guards

Error codes

Wallet / provider

Code
Description

METAMASK_NOT_INSTALLED

MetaMask or EIP-1193 provider not installed

NO_PROVIDER

No EIP-1193 provider on window.ethereum

USER_REJECTED

User rejected wallet request (EIP-1193 code 4001)

Snap

Code
Description

SNAP_CONNECT_FAILED

Snap not installed or connection failed

SNAP_DIALOG_REJECTED

User dismissed Snap dialog

SNAP_REQUIRED

Snap required but unavailable for wallet type

SNAP_KEY_CHECK_FAILED

Snap key existence check failed

AES key / onboarding

Code
Description

AES_KEY_MISMATCH

AES key does not match on-chain account

AES_KEY_MISSING

AES key missing or not provided

ACCOUNT_NOT_ONBOARDED

Account never onboarded to COTI

ONBOARDING_INCOMPLETE

Onboarding did not complete

Network

Code
Description

UNSUPPORTED_NETWORK

Connected to unsupported chain

WALLETCONNECT_PROJECT_ID_MISSING

WalletConnect project ID not configured

Bridge / transaction

Code
Description

INSUFFICIENT_BALANCE

Insufficient token balance

INSUFFICIENT_ALLOWANCE

ERC20 allowance too low

CONTRACT_NOT_FOUND

Contract address not found for chain

TRANSACTION_REVERTED

On-chain transaction reverted

ORACLE_TIMESTAMP_MISMATCH

Stale oracle price data

Other

Code
Description

API_ERROR

External API returned non-success status

VALIDATION_ERROR

Input validation failed

Logging

Export
Description

logger

Plugin logger instance

setDebugLogging(enabled)

Toggle debug logging

Logging is silent by default. Enable via configureCotiPlugin({ debug: true }). Secrets are never logged.

Utilities

Export
Description

formatTokenBalanceDisplay

Format token balance for display

truncateDecimalValue

Truncate decimal values

formatBalanceWithNotation

Compact balance display with K/M notation for large values

addThousandsSeparators

Insert thousands separators into a decimal string

expandExponentialNumber

Expand JS scientific notation (e.g. 1e-18) to a plain decimal string

formatPlainDecimal

String/number → plain decimal (never scientific notation)

formatAmountLimitDisplay

Human label for portal/bridge min/max limits (N/A, dust → —, uncapped max → 0)

isDustAmount / DUST_AMOUNT_THRESHOLD

Detect near-zero on-chain dust floors for UI

getEthereumProvider()

Resolve EIP-1193 provider

muteChainUpdates() / unmuteChainUpdates()

Suppress UI during cross-chain onboarding

isMultipleWalletsError(error)

Detect multiple-wallet conflict

Related docs

PreviousConfigurationNextAES Key Onboarding

Last updated

Was this helpful?