@chorus-one/polygon 1.0.0

package/dist/mjs/types.d.ts

@@ -0,0 +1,40 @@
+import type { Hex, TransactionReceipt } from 'viem';
+import type { PolygonNetworks } from './constants';
+export interface PolygonNetworkConfig {
+    /** Network to use: 'mainnet' (Ethereum L1) or 'testnet' (Sepolia L1) */
+    network: PolygonNetworks;
+    /** Optional RPC endpoint URL override. If not provided, uses viem's default for the network. */
+    rpcUrl?: string;
+}
+export interface Transaction {
+    /** The recipient (contract) address in hexadecimal format */
+    to: Hex;
+    /** The data to be included in the transaction in hexadecimal format (includes referrer tracking suffix) */
+    data: Hex;
+    /** The amount of ETH (in wei) to be sent with the transaction */
+    value?: bigint;
+}
+export interface PolygonTxStatus {
+    /** Status of the transaction */
+    status: 'success' | 'failure' | 'unknown';
+    /** Transaction receipt (null if unknown) */
+    receipt: TransactionReceipt | null;
+}
+export interface StakeInfo {
+    /** Total staked amount formatted in POL */
+    balance: string;
+    /** Total shares held by the delegator */
+    shares: bigint;
+    /** Current exchange rate between shares and POL (with high precision) */
+    exchangeRate: bigint;
+}
+export interface UnbondInfo {
+    /** Amount pending unbonding in POL */
+    amount: string;
+    /** Whether the unbond can be withdrawn now */
+    isWithdrawable: boolean;
+    /** Shares amount pending unbonding */
+    shares: bigint;
+    /** Epoch number when the unbond becomes claimable */
+    withdrawEpoch: bigint;
+}

package/dist/mjs/types.js

@@ -0,0 +1 @@
+export {};

package/hardhat.config.ts

@@ -0,0 +1,27 @@
+import { type HardhatUserConfig } from 'hardhat/config'
+import networkConfig from './test/lib/networks.json'
+
+const config: HardhatUserConfig = {
+  solidity: '0.8.20',
+  networks: {
+    hardhat: {
+      type: 'edr-simulated',
+      initialBaseFeePerGas: 0,
+      forking: {
+        url: networkConfig.networks.ethereum.url,
+        enabled: true,
+        blockNumber: 24382010 // Fetched on 2026-02-04
+      },
+      accounts: networkConfig.accounts.map((acc) => ({
+        privateKey: acc.privateKey,
+        balance: acc.balance
+      }))
+    },
+    localhost: {
+      type: 'http',
+      url: 'http://127.0.0.1:8545'
+    }
+  }
+}
+
+export default config

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@chorus-one/polygon",
+  "version": "1.0.0",
+  "description": "All-in-one toolkit for building staking dApps on Polygon network",
+  "scripts": {
+    "build": "rm -fr dist/* && tsc -p tsconfig.mjs.json --outDir dist/mjs && tsc -p tsconfig.cjs.json --outDir dist/cjs && bash ../../scripts/fix-package-json",
+    "test": "mocha 'test/**/*.spec.ts' --ignore 'test/integration/**/*.spec.ts'",
+    "hardhat:start": "hardhat node --network hardhat & echo $! > hardhat.pid;",
+    "hardhat:stop": "kill $(cat hardhat.pid) && rm hardhat.pid",
+    "test:integration": "npm run hardhat:start > hardhat.log & sleep 5; mocha --require tsx --timeout 60000 'test/integration/setup.ts' 'test/integration/**/*.spec.ts'; status=$?; npm run hardhat:stop; exit $status"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/mjs/index.js",
+  "types": "dist/mjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/mjs/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/mjs/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChorusOne/chorus-one-sdk.git",
+    "directory": "packages/polygon"
+  },
+  "homepage": "https://chorus-one.gitbook.io/sdk",
+  "keywords": [
+    "polygon",
+    "staking",
+    "dApps",
+    "blockchain",
+    "chorus-one",
+    "sdk"
+  ],
+  "author": "Chorus One AG",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@chorus-one/signer": "^1.0.0",
+    "@noble/curves": "^2.0.1",
+    "viem": "^2.28.0"
+  },
+  "devDependencies": {
+    "@chorus-one/signer-local": "^1.0.0",
+    "@scure/bip32": "^1.6.2",
+    "bip39": "^3.1.0",
+    "hardhat": "^3.0.3"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,151 @@
+import type { Address } from 'viem'
+
+export type PolygonNetworks = 'mainnet' | 'testnet'
+
+export interface NetworkContracts {
+  stakeManagerAddress: Address
+  stakingTokenAddress: Address
+}
+
+/** Contract addresses per network (mainnet = Ethereum L1, testnet = Sepolia L1) */
+// Reference: https://docs.polygon.technology/pos/reference/rpc-endpoints/
+export const NETWORK_CONTRACTS: Record<PolygonNetworks, NetworkContracts> = {
+  mainnet: {
+    stakeManagerAddress: '0x5e3Ef299fDDf15eAa0432E6e66473ace8c13D908',
+    stakingTokenAddress: '0x455e53CBB86018Ac2B8092FdCd39d8444aFFC3F6'
+  },
+  testnet: {
+    stakeManagerAddress: '0x4AE8f648B1Ec892B6cc68C89cc088583964d08bE',
+    stakingTokenAddress: '0x44499312f493F62f2DFd3C6435Ca3603EbFCeeBa'
+  }
+}
+
+/** Chorus One Polygon ValidatorShare contract addresses */
+// Reference mainnet: https://staking.polygon.technology/validators/106
+// Reference testnet (Random Validator): https://staking.polygon.technology/validators/31
+export const CHORUS_ONE_POLYGON_VALIDATORS = {
+  mainnet: '0xD9E6987D77bf2c6d0647b8181fd68A259f838C36' as Address,
+  testnet: '0x91344055cb0511b3aa36c561d741ee356b95f1c9' as Address
+} as const
+
+// Reference: https://github.com/0xPolygon/pos-contracts/blob/main/contracts/staking/validatorShare/ValidatorShare.sol
+export const VALIDATOR_SHARE_ABI = [
+  {
+    type: 'function',
+    name: 'buyVoucherPOL',
+    inputs: [
+      { name: '_amount', type: 'uint256', internalType: 'uint256' },
+      { name: '_minSharesToMint', type: 'uint256', internalType: 'uint256' }
+    ],
+    outputs: [{ name: 'amountToDeposit', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'nonpayable'
+  },
+  {
+    type: 'function',
+    name: 'sellVoucher_newPOL',
+    inputs: [
+      { name: 'claimAmount', type: 'uint256', internalType: 'uint256' },
+      { name: 'maximumSharesToBurn', type: 'uint256', internalType: 'uint256' }
+    ],
+    outputs: [],
+    stateMutability: 'nonpayable'
+  },
+  {
+    type: 'function',
+    name: 'unstakeClaimTokens_newPOL',
+    inputs: [{ name: 'unbondNonce', type: 'uint256', internalType: 'uint256' }],
+    outputs: [],
+    stateMutability: 'nonpayable'
+  },
+  {
+    type: 'function',
+    name: 'withdrawRewardsPOL',
+    inputs: [],
+    outputs: [],
+    stateMutability: 'nonpayable'
+  },
+  {
+    type: 'function',
+    name: 'restakePOL',
+    inputs: [],
+    outputs: [
+      { name: 'amountRestaked', type: 'uint256', internalType: 'uint256' },
+      { name: 'liquidReward', type: 'uint256', internalType: 'uint256' }
+    ],
+    stateMutability: 'nonpayable'
+  },
+  {
+    type: 'function',
+    name: 'getTotalStake',
+    inputs: [{ name: 'user', type: 'address', internalType: 'address' }],
+    outputs: [
+      { name: '', type: 'uint256', internalType: 'uint256' },
+      { name: '', type: 'uint256', internalType: 'uint256' }
+    ],
+    stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'unbondNonces',
+    inputs: [{ name: '', type: 'address', internalType: 'address' }],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'unbonds_new',
+    inputs: [
+      { name: '', type: 'address', internalType: 'address' },
+      { name: '', type: 'uint256', internalType: 'uint256' }
+    ],
+    outputs: [
+      { name: 'shares', type: 'uint256', internalType: 'uint256' },
+      { name: 'withdrawEpoch', type: 'uint256', internalType: 'uint256' }
+    ],
+    stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'getLiquidRewards',
+    inputs: [{ name: 'user', type: 'address', internalType: 'address' }],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'validatorId',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'withdrawExchangeRate',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'view'
+  }
+] as const
+
+// Exchange rate precision constants from the ValidatorShare contract
+// Reference: https://github.com/0xPolygon/pos-contracts/blob/main/contracts/staking/validatorShare/ValidatorShare.sol
+export const EXCHANGE_RATE_PRECISION = 100n
+export const EXCHANGE_RATE_HIGH_PRECISION = 10n ** 29n
+
+// Reference: https://github.com/0xPolygon/pos-contracts/blob/main/contracts/staking/stakeManager/StakeManager.sol
+export const STAKE_MANAGER_ABI = [
+  {
+    type: 'function',
+    name: 'epoch',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'withdrawalDelay',
+    inputs: [],
+    outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    stateMutability: 'view'
+  }
+] as const

package/src/index.ts

@@ -0,0 +1,14 @@
+export { PolygonStaker } from './staker'
+
+export { PolygonNetworkConfig, Transaction, PolygonTxStatus, StakeInfo, UnbondInfo } from './types'
+
+export {
+  NETWORK_CONTRACTS,
+  CHORUS_ONE_POLYGON_VALIDATORS,
+  VALIDATOR_SHARE_ABI,
+  STAKE_MANAGER_ABI,
+  EXCHANGE_RATE_PRECISION,
+  EXCHANGE_RATE_HIGH_PRECISION
+} from './constants'
+
+export type { PolygonNetworks, NetworkContracts } from './constants'

package/src/referrer.ts

@@ -0,0 +1,15 @@
+import type { Hex } from 'viem'
+import { keccak256, toHex } from 'viem'
+
+const DEFAULT_REFERRER = 'sdk-chorusone-staking'
+const REFERRER_MARKER = 'c1c1'
+
+const encodeReferrer = (referrer: string): Hex => {
+  const hash = keccak256(toHex(referrer))
+  return `0x${REFERRER_MARKER}${hash.slice(2, 8)}`
+}
+
+export const appendReferrerTracking = (data: Hex, referrer?: string): Hex => {
+  const encoded = encodeReferrer(referrer ?? DEFAULT_REFERRER)
+  return `${data}${encoded.slice(2)}` as Hex
+}