createUPDClient — read balances, mint/burn UPD, stake sUPD, and query system health.

createUPDClient

import { createUPDClient } from '@permissionless-technologies/upd-sdk'

const client = createUPDClient({
  publicClient,          // viem PublicClient
  walletClient?,         // viem WalletClient (required for write operations)
  chainId: number,       // e.g. 11155111 (Sepolia)
  oracleUrl?: string,    // defaults to 'https://oracle.upd.io'
})

The client auto-loads contract addresses from the built-in deployment config for the given chain. The oracle client is created internally for convenience methods.

Read Methods

`client.getUPDBalance(address)`

const balance: bigint = await client.getUPDBalance('0x...')

`client.getTotalSupply()`

const supply: bigint = await client.getTotalSupply()

`client.getCollateralInfo()`

const info = await client.getCollateralInfo()
// { totalStEthCollateral: bigint, totalUPDSupply: bigint }

`client.getStabilizerPosition(tokenId)`

const position = await client.getStabilizerPosition(1n)
// {
//   tokenId: bigint,
//   positionEscrowAddress: Address,
//   stabilizerEscrowAddress: Address,
//   backedUPDAmount: bigint,
//   stETHBalance: bigint,
//   unallocatedStETH: bigint,
//   minCollateralRatio: bigint,   // basis points (12500 = 125%)
// }

`client.getSUPDInfo()`

const info = await client.getSUPDInfo()
// {
//   shareValue: bigint,        // current value per share (18 decimals)
//   annualYieldBps: bigint,    // APY in basis points (800 = 8%)
//   totalSupply: bigint,       // total sUPD shares
//   totalLiabilityUSD: bigint, // total USD liability
// }

Write Methods

All write methods require a walletClient in the config.

`client.mint(params)`

Deposit ETH to mint UPD. Requires a signed price attestation.

import { createMockAttestation } from '@permissionless-technologies/upd-sdk'

const attestation = createMockAttestation(2000n * 10n ** 18n) // for testing
const txHash = await client.mint({
  to: '0x...',
  ethAmount: parseEther('1'),
  priceAttestation: attestation,
})

`client.burn(params)`

Burn UPD to receive stETH.

const txHash = await client.burn({
  updAmount: parseUnits('1000', 18),
  priceAttestation: attestation,
})

`client.stakeUPD(params)`

Stake UPD to receive sUPD shares.

const txHash = await client.stakeUPD({
  updAmount: parseUnits('1000', 18),
  priceAttestation: attestation,
})

`client.unstakeUPD(params)`

Unstake sUPD shares to receive UPD.

const txHash = await client.unstakeUPD({
  shares: parseUnits('950', 18),
  priceAttestation: attestation,
})

Convenience Methods (Auto-Oracle)

These methods fetch a price attestation from the oracle automatically:

// Mint — no manual attestation needed
await client.mintWithOracle({ to: '0x...', ethAmount: parseEther('1') })

// Burn
await client.burnWithOracle({ updAmount: parseUnits('1000', 18) })

// Stake sUPD
await client.stakeUPDWithOracle({ updAmount: parseUnits('1000', 18) })

// Unstake sUPD
await client.unstakeUPDWithOracle({ shares: parseUnits('950', 18) })

// System health (on-chain collateral + oracle price)
const health = await client.getSystemHealth()
// { systemCollateralRatioBps, isHealthy, collateralValueUsd, totalUPDSupply, bufferUsd }

Pure Math Functions

These functions require no client — pure math for computing quotes locally:

import {
  quoteMintUPD,
  quoteBurnUPD,
  quoteStakeUPD,
  quoteUnstakeUPD,
  collateralizationRatio,
  stabilizerStEthNeeded,
  computeSystemHealth,
} from '@permissionless-technologies/upd-sdk/core'

`quoteMintUPD(ethAmount, ethUsdPrice)`

const updAmount = quoteMintUPD(parseEther('1'), 2000n * 10n ** 18n)
// → 2000e18 (2000 UPD)

`quoteBurnUPD(updAmount, ethUsdPrice)`

const stEthAmount = quoteBurnUPD(parseUnits('2000', 18), 2000n * 10n ** 18n)
// → 1e18 (1 stETH)

`quoteStakeUPD(updAmount, shareValue)`

const shares = quoteStakeUPD(parseUnits('1000', 18), 1050000000000000000n)
// → ~952.38e18 shares (at $1.05/share)

`quoteUnstakeUPD(shares, shareValue)`

const updOwed = quoteUnstakeUPD(parseUnits('952', 18), 1050000000000000000n)
// → ~999.6e18 UPD

`computeSystemHealth(collateral, ethUsdPrice, minRatioBps?)`

const health = computeSystemHealth(
  { totalStEthCollateral: parseEther('125'), totalUPDSupply: parseUnits('200000', 18) },
  2000n * 10n ** 18n,
)
// { systemCollateralRatioBps: 12500n, isHealthy: true, bufferUsd: 50000e18, ... }

Deployment Config

import { getDeployment, registerDeployment } from '@permissionless-technologies/upd-sdk'

// Built-in chains
const sepolia = getDeployment(11155111)
console.log(sepolia.contracts.UPDToken) // '0x...'

// Register custom chain at runtime
registerDeployment(8453, { chainId: 8453, contracts: { ... }, ... })

Client API