@chorus-one/polygon 1.0.1 → 1.0.4

package/README.md

@@ -99,7 +99,9 @@ const { txHash } = await staker.broadcast({ signedTx })
 
 ### Stake (Delegate) to Validator
 
-Delegate POL tokens to a validator via their ValidatorShare contract:
+Delegate POL tokens to a validator via their ValidatorShare contract.
+
+You must provide exactly one of `slippageBps` or `minSharesToMint` (not both). There is no default — omitting both will throw an error.
 
 ```javascript
 const { tx } = await staker.buildStakeTx({
@@ -121,7 +123,9 @@ const { txHash } = await staker.broadcast({ signedTx })
 
 ### Unstake (Unbond) from Validator
 
-Create an unbond request to unstake POL tokens. After the unbonding period (~80 epochs, approximately 3-4 days), call withdraw to claim funds:
+Create an unbond request to unstake POL tokens. After the unbonding period (~80 epochs, approximately 3-4 days), call withdraw to claim funds.
+
+You must provide exactly one of `slippageBps` or `maximumSharesToBurn` (not both). There is no default — omitting both will throw an error.
 
 ```javascript
 const { tx } = await staker.buildUnstakeTx({
@@ -212,10 +216,10 @@ console.log(status) // 'success', 'failure', or 'unknown'
 
 ## Key Features
 
-- **Ethereum L1 Based**: Polygon PoS staking operates via ValidatorShare contracts deployed on Ethereum mainnet (or Sepolia for testnet)
+- **Ethereum L1 Based**: Polygon PoS staking operates via ValidatorShare contracts deployed on Ethereum mainnet (or Sepolia for testnet). Every transaction includes a `chainId` field so you know exactly which chain to broadcast on (`1` for mainnet, `11155111` for Sepolia).
 - **POL Token Staking**: Stake the native POL token (formerly MATIC) to validators
 - **Human-Readable Amounts**: Pass token amounts as strings (e.g., '1.5'), conversion to wei is handled automatically
-- **Slippage Protection**: Stake and unstake operations support `slippageBps` (basis points) for automatic slippage calculation, or manual `minSharesToMint`/`maximumSharesToBurn` parameters
+- **Slippage Protection**: Stake and unstake operations require either `slippageBps` (basis points) for automatic slippage calculation, or manual `minSharesToMint`/`maximumSharesToBurn` parameters. Exactly one must be provided — there is no default.
 - **Query Methods**: Read stake balances, rewards, allowances, unbond status (with POL amount and withdrawability), and epoch information
 - **Rewards Management**: Claim rewards to wallet or compound them back into your delegation
 
@@ -227,6 +231,19 @@ console.log(status) // 'success', 'failure', or 'unknown'
 - **Referrer Tracking**: Transaction builders that support referrer tracking (stake, unstake, claim rewards, compound) append a tracking marker to the transaction calldata. By default, `sdk-chorusone-staking` is used as the referrer. You can provide a custom referrer via the `referrer` parameter.
 - **Exchange Rate**: The exchange rate between shares and POL may fluctuate. Use `slippageBps` for automatic slippage protection, or specify `minSharesToMint`/`maximumSharesToBurn` directly. Foundation validators (ID < 8) use different precision than others.
 - **Validator Share Contracts**: Each validator has their own ValidatorShare contract address. You must specify the correct contract address for the validator you want to delegate to.
+- **Testnet Validators**: Testnet validators on Sepolia may be locked or inactive. To list all active ValidatorShare addresses, use [Foundry's](https://book.getfoundry.sh/) `cast`:
+
+  ```bash
+  export ETH_RPC_URL="https://ethereum-sepolia-rpc.publicnode.com"
+  SM="0x4AE8f648B1Ec892B6cc68C89cc088583964d08bE"
+  count=$(cast call $SM "NFTCounter()(uint256)")
+  for id in $(seq 1 $((count - 1))); do
+    raw=$(cast call $SM "validators(uint256)(uint256,uint256,uint256,uint256,uint256,address,address,uint8,uint256,uint256,uint256,uint256,uint256)" $id 2>/dev/null)
+    contract=$(echo "$raw" | sed -n 7p)
+    st=$(echo "$raw" | sed -n 8p)
+    [ "$st" = "1" ] && echo $contract
+  done
+  ```
 
 ## License
 

package/dist/cjs/constants.d.ts

@@ -184,4 +184,59 @@ export declare const STAKE_MANAGER_ABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "validators";
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reward";
+        readonly type: "uint256";
+    }, {
+        readonly name: "activationEpoch";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deactivationEpoch";
+        readonly type: "uint256";
+    }, {
+        readonly name: "jailTime";
+        readonly type: "uint256";
+    }, {
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "contractAddress";
+        readonly type: "address";
+    }, {
+        readonly name: "status";
+        readonly type: "uint256";
+    }, {
+        readonly name: "commissionRate";
+        readonly type: "uint256";
+    }, {
+        readonly name: "lastCommissionUpdate";
+        readonly type: "uint256";
+    }, {
+        readonly name: "delegatorsReward";
+        readonly type: "uint256";
+    }, {
+        readonly name: "delegatedAmount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "initialRewardPerStake";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
 }];
+export declare const VALIDATOR_STATUS: {
+    readonly 0: "Inactive";
+    readonly 1: "Active";
+    readonly 2: "Locked";
+    readonly 3: "Unstaked";
+};

package/dist/cjs/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STAKE_MANAGER_ABI = exports.EXCHANGE_RATE_HIGH_PRECISION = exports.EXCHANGE_RATE_PRECISION = exports.VALIDATOR_SHARE_ABI = exports.CHORUS_ONE_POLYGON_VALIDATORS = exports.NETWORK_CONTRACTS = void 0;
+exports.VALIDATOR_STATUS = exports.STAKE_MANAGER_ABI = exports.EXCHANGE_RATE_HIGH_PRECISION = exports.EXCHANGE_RATE_PRECISION = exports.VALIDATOR_SHARE_ABI = exports.CHORUS_ONE_POLYGON_VALIDATORS = exports.NETWORK_CONTRACTS = void 0;
 /** Contract addresses per network (mainnet = Ethereum L1, testnet = Sepolia L1) */
 // Reference: https://docs.polygon.technology/pos/reference/rpc-endpoints/
 exports.NETWORK_CONTRACTS = {
@@ -15,10 +15,12 @@ exports.NETWORK_CONTRACTS = {
 };
 /** Chorus One Polygon ValidatorShare contract addresses */
 // Reference mainnet: https://staking.polygon.technology/validators/106
-// Reference testnet (Random Validator): https://staking.polygon.technology/validators/31
+// Reference testnet: https://staking.polygon.technology/validators/31
+// Note: Testnet validators may be locked. To list active validators, query the StakeManager
+// contract on Sepolia: https://sepolia.etherscan.io/address/0x4AE8f648B1Ec892B6cc68C89cc088583964d08bE
 exports.CHORUS_ONE_POLYGON_VALIDATORS = {
     mainnet: '0xD9E6987D77bf2c6d0647b8181fd68A259f838C36',
-    testnet: '0x91344055cb0511b3aa36c561d741ee356b95f1c9'
+    testnet: '0xe50f5ad9b885675fd11d8204eb01c83a8a32a91d'
 };
 // Reference: https://github.com/0xPolygon/pos-contracts/blob/main/contracts/staking/validatorShare/ValidatorShare.sol
 exports.VALIDATOR_SHARE_ABI = [
@@ -137,5 +139,32 @@ exports.STAKE_MANAGER_ABI = [
         inputs: [],
         outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
         stateMutability: 'view'
+    },
+    {
+        type: 'function',
+        name: 'validators',
+        inputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+        outputs: [
+            { name: 'amount', type: 'uint256' },
+            { name: 'reward', type: 'uint256' },
+            { name: 'activationEpoch', type: 'uint256' },
+            { name: 'deactivationEpoch', type: 'uint256' },
+            { name: 'jailTime', type: 'uint256' },
+            { name: 'signer', type: 'address' },
+            { name: 'contractAddress', type: 'address' },
+            { name: 'status', type: 'uint256' },
+            { name: 'commissionRate', type: 'uint256' },
+            { name: 'lastCommissionUpdate', type: 'uint256' },
+            { name: 'delegatorsReward', type: 'uint256' },
+            { name: 'delegatedAmount', type: 'uint256' },
+            { name: 'initialRewardPerStake', type: 'uint256' }
+        ],
+        stateMutability: 'view'
     }
 ];
+exports.VALIDATOR_STATUS = {
+    0: 'Inactive',
+    1: 'Active',
+    2: 'Locked',
+    3: 'Unstaked'
+};

package/dist/cjs/staker.d.ts

@@ -54,8 +54,8 @@ export declare class PolygonStaker {
      * @param params.delegatorAddress - The delegator's Ethereum address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to stake in POL
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
-     * @param params.minSharesToMint - (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+     * @param params.minSharesToMint - Minimum validator shares to receive. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon staking transaction
@@ -80,8 +80,8 @@ export declare class PolygonStaker {
      * @param params.delegatorAddress - The delegator's address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to unstake in POL (will be converted to wei internally)
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
-     * @param params.maximumSharesToBurn - (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+     * @param params.maximumSharesToBurn - Maximum validator shares willing to burn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon unstaking transaction
@@ -331,5 +331,6 @@ export declare class PolygonStaker {
     getTxStatus(params: {
         txHash: Hex;
     }): Promise<PolygonTxStatus>;
+    private assertValidatorActive;
     private parseAmount;
 }

package/dist/cjs/staker.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PolygonStaker = void 0;
 const viem_1 = require("viem");
 const chains_1 = require("viem/chains");
-const secp256k1_js_1 = require("@noble/curves/secp256k1.js");
+const secp256k1_1 = require("@noble/curves/secp256k1");
 const referrer_1 = require("./referrer");
 const constants_1 = require("./constants");
 /**
@@ -46,7 +46,8 @@ class PolygonStaker {
      * @returns Returns an array containing the derived address.
      */
     static getAddressDerivationFn = () => async (publicKey) => {
-        const pkUncompressed = secp256k1_js_1.secp256k1.Point.fromBytes(publicKey).toBytes(false);
+        const point = secp256k1_1.secp256k1.Point.fromHex(publicKey);
+        const pkUncompressed = point.toBytes(false);
         const hash = (0, viem_1.keccak256)(pkUncompressed.subarray(1));
         const ethAddress = hash.slice(-40);
         return [ethAddress];
@@ -94,7 +95,8 @@ class PolygonStaker {
             tx: {
                 to: this.contracts.stakingTokenAddress,
                 data,
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -108,8 +110,8 @@ class PolygonStaker {
      * @param params.delegatorAddress - The delegator's Ethereum address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to stake in POL
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
-     * @param params.minSharesToMint - (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+     * @param params.minSharesToMint - Minimum validator shares to receive. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon staking transaction
@@ -127,7 +129,10 @@ class PolygonStaker {
             throw new Error('Cannot specify both slippageBps and minSharesToMint. Use one or the other.');
         }
         const amountWei = this.parseAmount(amount);
-        const allowance = await this.getAllowance(delegatorAddress);
+        const [allowance] = await Promise.all([
+            this.getAllowance(delegatorAddress),
+            this.assertValidatorActive(validatorShareAddress)
+        ]);
         if ((0, viem_1.parseEther)(allowance) < amountWei) {
             throw new Error(`Insufficient POL allowance. Current: ${allowance}, Required: ${amount}. Call buildApproveTx() first.`);
         }
@@ -151,7 +156,8 @@ class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: (0, referrer_1.appendReferrerTracking)(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -165,8 +171,8 @@ class PolygonStaker {
      * @param params.delegatorAddress - The delegator's address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to unstake in POL (will be converted to wei internally)
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
-     * @param params.maximumSharesToBurn - (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+     * @param params.maximumSharesToBurn - Maximum validator shares willing to burn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon unstaking transaction
@@ -205,7 +211,8 @@ class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: (0, referrer_1.appendReferrerTracking)(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -252,7 +259,8 @@ class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data,
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -288,7 +296,8 @@ class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: (0, referrer_1.appendReferrerTracking)(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -312,7 +321,10 @@ class PolygonStaker {
         if (!(0, viem_1.isAddress)(validatorShareAddress)) {
             throw new Error(`Invalid validator share address: ${validatorShareAddress}`);
         }
-        const rewards = await this.getLiquidRewards({ delegatorAddress, validatorShareAddress });
+        const [rewards] = await Promise.all([
+            this.getLiquidRewards({ delegatorAddress, validatorShareAddress }),
+            this.assertValidatorActive(validatorShareAddress)
+        ]);
         if ((0, viem_1.parseEther)(rewards) === 0n) {
             throw new Error('No rewards available to compound');
         }
@@ -324,7 +336,8 @@ class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: (0, referrer_1.appendReferrerTracking)(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -692,6 +705,26 @@ class PolygonStaker {
             };
         }
     }
+    async assertValidatorActive(validatorShareAddress) {
+        const validatorId = await this.publicClient.readContract({
+            address: validatorShareAddress,
+            abi: constants_1.VALIDATOR_SHARE_ABI,
+            functionName: 'validatorId'
+        });
+        const validator = await this.publicClient.readContract({
+            address: this.contracts.stakeManagerAddress,
+            abi: constants_1.STAKE_MANAGER_ABI,
+            functionName: 'validators',
+            args: [validatorId]
+        });
+        const status = Number(validator[7]);
+        if (status !== 1) {
+            const statusName = constants_1.VALIDATOR_STATUS[status] ?? 'Unknown';
+            throw new Error(`Validator is not active (status: ${statusName}). ` +
+                'The validator may be locked, inactive, or unstaked. ' +
+                'See the @chorus-one/polygon README for how to list active validators on testnet.');
+        }
+    }
     parseAmount(amount) {
         if (typeof amount === 'bigint') {
             throw new Error('Amount must be a string, denominated in POL. e.g. "1.5" - 1.5 POL. You can use `formatEther` to convert a `bigint` to a string');

package/dist/cjs/types.d.ts

@@ -13,6 +13,14 @@ export interface Transaction {
     data: Hex;
     /** The amount of ETH (in wei) to be sent with the transaction */
     value?: bigint;
+    /**
+     * The chain ID where the transaction must be broadcast.
+     *
+     * Polygon staking contracts live on Ethereum L1, not on the Polygon chain itself:
+     * - mainnet: `1` (Ethereum Mainnet)
+     * - testnet: `11155111` (Sepolia)
+     */
+    chainId: number;
 }
 export interface PolygonTxStatus {
     /** Status of the transaction */

package/dist/mjs/constants.d.ts

@@ -184,4 +184,59 @@ export declare const STAKE_MANAGER_ABI: readonly [{
         readonly internalType: "uint256";
     }];
     readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "validators";
+    readonly inputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+        readonly internalType: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reward";
+        readonly type: "uint256";
+    }, {
+        readonly name: "activationEpoch";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deactivationEpoch";
+        readonly type: "uint256";
+    }, {
+        readonly name: "jailTime";
+        readonly type: "uint256";
+    }, {
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "contractAddress";
+        readonly type: "address";
+    }, {
+        readonly name: "status";
+        readonly type: "uint256";
+    }, {
+        readonly name: "commissionRate";
+        readonly type: "uint256";
+    }, {
+        readonly name: "lastCommissionUpdate";
+        readonly type: "uint256";
+    }, {
+        readonly name: "delegatorsReward";
+        readonly type: "uint256";
+    }, {
+        readonly name: "delegatedAmount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "initialRewardPerStake";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
 }];
+export declare const VALIDATOR_STATUS: {
+    readonly 0: "Inactive";
+    readonly 1: "Active";
+    readonly 2: "Locked";
+    readonly 3: "Unstaked";
+};

package/dist/mjs/constants.js

@@ -12,10 +12,12 @@ export const NETWORK_CONTRACTS = {
 };
 /** Chorus One Polygon ValidatorShare contract addresses */
 // Reference mainnet: https://staking.polygon.technology/validators/106
-// Reference testnet (Random Validator): https://staking.polygon.technology/validators/31
+// Reference testnet: https://staking.polygon.technology/validators/31
+// Note: Testnet validators may be locked. To list active validators, query the StakeManager
+// contract on Sepolia: https://sepolia.etherscan.io/address/0x4AE8f648B1Ec892B6cc68C89cc088583964d08bE
 export const CHORUS_ONE_POLYGON_VALIDATORS = {
     mainnet: '0xD9E6987D77bf2c6d0647b8181fd68A259f838C36',
-    testnet: '0x91344055cb0511b3aa36c561d741ee356b95f1c9'
+    testnet: '0xe50f5ad9b885675fd11d8204eb01c83a8a32a91d'
 };
 // Reference: https://github.com/0xPolygon/pos-contracts/blob/main/contracts/staking/validatorShare/ValidatorShare.sol
 export const VALIDATOR_SHARE_ABI = [
@@ -134,5 +136,32 @@ export const STAKE_MANAGER_ABI = [
         inputs: [],
         outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
         stateMutability: 'view'
+    },
+    {
+        type: 'function',
+        name: 'validators',
+        inputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+        outputs: [
+            { name: 'amount', type: 'uint256' },
+            { name: 'reward', type: 'uint256' },
+            { name: 'activationEpoch', type: 'uint256' },
+            { name: 'deactivationEpoch', type: 'uint256' },
+            { name: 'jailTime', type: 'uint256' },
+            { name: 'signer', type: 'address' },
+            { name: 'contractAddress', type: 'address' },
+            { name: 'status', type: 'uint256' },
+            { name: 'commissionRate', type: 'uint256' },
+            { name: 'lastCommissionUpdate', type: 'uint256' },
+            { name: 'delegatorsReward', type: 'uint256' },
+            { name: 'delegatedAmount', type: 'uint256' },
+            { name: 'initialRewardPerStake', type: 'uint256' }
+        ],
+        stateMutability: 'view'
     }
 ];
+export const VALIDATOR_STATUS = {
+    0: 'Inactive',
+    1: 'Active',
+    2: 'Locked',
+    3: 'Unstaked'
+};

package/dist/mjs/staker.d.ts

@@ -54,8 +54,8 @@ export declare class PolygonStaker {
      * @param params.delegatorAddress - The delegator's Ethereum address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to stake in POL
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
-     * @param params.minSharesToMint - (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+     * @param params.minSharesToMint - Minimum validator shares to receive. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon staking transaction
@@ -80,8 +80,8 @@ export declare class PolygonStaker {
      * @param params.delegatorAddress - The delegator's address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to unstake in POL (will be converted to wei internally)
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
-     * @param params.maximumSharesToBurn - (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+     * @param params.maximumSharesToBurn - Maximum validator shares willing to burn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon unstaking transaction
@@ -331,5 +331,6 @@ export declare class PolygonStaker {
     getTxStatus(params: {
         txHash: Hex;
     }): Promise<PolygonTxStatus>;
+    private assertValidatorActive;
     private parseAmount;
 }

package/dist/mjs/staker.js

@@ -1,8 +1,8 @@
 import { createPublicClient, http, encodeFunctionData, parseEther, formatEther, isAddress, keccak256, serializeTransaction, createWalletClient, maxUint256, erc20Abi } from 'viem';
 import { mainnet, sepolia } from 'viem/chains';
-import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { secp256k1 } from '@noble/curves/secp256k1';
 import { appendReferrerTracking } from './referrer';
-import { VALIDATOR_SHARE_ABI, STAKE_MANAGER_ABI, NETWORK_CONTRACTS, EXCHANGE_RATE_PRECISION, EXCHANGE_RATE_HIGH_PRECISION } from './constants';
+import { VALIDATOR_SHARE_ABI, STAKE_MANAGER_ABI, NETWORK_CONTRACTS, EXCHANGE_RATE_PRECISION, EXCHANGE_RATE_HIGH_PRECISION, VALIDATOR_STATUS } from './constants';
 /**
  * PolygonStaker - TypeScript SDK for Polygon PoS staking operations
  *
@@ -43,7 +43,8 @@ export class PolygonStaker {
      * @returns Returns an array containing the derived address.
      */
     static getAddressDerivationFn = () => async (publicKey) => {
-        const pkUncompressed = secp256k1.Point.fromBytes(publicKey).toBytes(false);
+        const point = secp256k1.Point.fromHex(publicKey);
+        const pkUncompressed = point.toBytes(false);
         const hash = keccak256(pkUncompressed.subarray(1));
         const ethAddress = hash.slice(-40);
         return [ethAddress];
@@ -91,7 +92,8 @@ export class PolygonStaker {
             tx: {
                 to: this.contracts.stakingTokenAddress,
                 data,
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -105,8 +107,8 @@ export class PolygonStaker {
      * @param params.delegatorAddress - The delegator's Ethereum address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to stake in POL
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
-     * @param params.minSharesToMint - (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+     * @param params.minSharesToMint - Minimum validator shares to receive. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon staking transaction
@@ -124,7 +126,10 @@ export class PolygonStaker {
             throw new Error('Cannot specify both slippageBps and minSharesToMint. Use one or the other.');
         }
         const amountWei = this.parseAmount(amount);
-        const allowance = await this.getAllowance(delegatorAddress);
+        const [allowance] = await Promise.all([
+            this.getAllowance(delegatorAddress),
+            this.assertValidatorActive(validatorShareAddress)
+        ]);
         if (parseEther(allowance) < amountWei) {
             throw new Error(`Insufficient POL allowance. Current: ${allowance}, Required: ${amount}. Call buildApproveTx() first.`);
         }
@@ -148,7 +153,8 @@ export class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: appendReferrerTracking(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -162,8 +168,8 @@ export class PolygonStaker {
      * @param params.delegatorAddress - The delegator's address
      * @param params.validatorShareAddress - The validator's ValidatorShare contract address
      * @param params.amount - The amount to unstake in POL (will be converted to wei internally)
-     * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
-     * @param params.maximumSharesToBurn - (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
+     * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+     * @param params.maximumSharesToBurn - Maximum validator shares willing to burn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
      * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
      *
      * @returns Returns a promise that resolves to a Polygon unstaking transaction
@@ -202,7 +208,8 @@ export class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: appendReferrerTracking(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -249,7 +256,8 @@ export class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data,
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -285,7 +293,8 @@ export class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: appendReferrerTracking(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -309,7 +318,10 @@ export class PolygonStaker {
         if (!isAddress(validatorShareAddress)) {
             throw new Error(`Invalid validator share address: ${validatorShareAddress}`);
         }
-        const rewards = await this.getLiquidRewards({ delegatorAddress, validatorShareAddress });
+        const [rewards] = await Promise.all([
+            this.getLiquidRewards({ delegatorAddress, validatorShareAddress }),
+            this.assertValidatorActive(validatorShareAddress)
+        ]);
         if (parseEther(rewards) === 0n) {
             throw new Error('No rewards available to compound');
         }
@@ -321,7 +333,8 @@ export class PolygonStaker {
             tx: {
                 to: validatorShareAddress,
                 data: appendReferrerTracking(calldata, referrer),
-                value: 0n
+                value: 0n,
+                chainId: this.chain.id
             }
         };
     }
@@ -689,6 +702,26 @@ export class PolygonStaker {
             };
         }
     }
+    async assertValidatorActive(validatorShareAddress) {
+        const validatorId = await this.publicClient.readContract({
+            address: validatorShareAddress,
+            abi: VALIDATOR_SHARE_ABI,
+            functionName: 'validatorId'
+        });
+        const validator = await this.publicClient.readContract({
+            address: this.contracts.stakeManagerAddress,
+            abi: STAKE_MANAGER_ABI,
+            functionName: 'validators',
+            args: [validatorId]
+        });
+        const status = Number(validator[7]);
+        if (status !== 1) {
+            const statusName = VALIDATOR_STATUS[status] ?? 'Unknown';
+            throw new Error(`Validator is not active (status: ${statusName}). ` +
+                'The validator may be locked, inactive, or unstaked. ' +
+                'See the @chorus-one/polygon README for how to list active validators on testnet.');
+        }
+    }
     parseAmount(amount) {
         if (typeof amount === 'bigint') {
             throw new Error('Amount must be a string, denominated in POL. e.g. "1.5" - 1.5 POL. You can use `formatEther` to convert a `bigint` to a string');

package/dist/mjs/types.d.ts

@@ -13,6 +13,14 @@ export interface Transaction {
     data: Hex;
     /** The amount of ETH (in wei) to be sent with the transaction */
     value?: bigint;
+    /**
+     * The chain ID where the transaction must be broadcast.
+     *
+     * Polygon staking contracts live on Ethereum L1, not on the Polygon chain itself:
+     * - mainnet: `1` (Ethereum Mainnet)
+     * - testnet: `11155111` (Sepolia)
+     */
+    chainId: number;
 }
 export interface PolygonTxStatus {
     /** Status of the transaction */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-one/polygon",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "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",
@@ -38,7 +38,7 @@
   "type": "module",
   "dependencies": {
     "@chorus-one/signer": "^1.0.0",
-    "@noble/curves": "^2.0.1",
+    "@noble/curves": "^1.9.2",
     "viem": "^2.28.0"
   },
   "devDependencies": {

package/src/constants.ts

@@ -22,10 +22,12 @@ export const NETWORK_CONTRACTS: Record<PolygonNetworks, NetworkContracts> = {
 
 /** Chorus One Polygon ValidatorShare contract addresses */
 // Reference mainnet: https://staking.polygon.technology/validators/106
-// Reference testnet (Random Validator): https://staking.polygon.technology/validators/31
+// Reference testnet: https://staking.polygon.technology/validators/31
+// Note: Testnet validators may be locked. To list active validators, query the StakeManager
+// contract on Sepolia: https://sepolia.etherscan.io/address/0x4AE8f648B1Ec892B6cc68C89cc088583964d08bE
 export const CHORUS_ONE_POLYGON_VALIDATORS = {
   mainnet: '0xD9E6987D77bf2c6d0647b8181fd68A259f838C36' as Address,
-  testnet: '0x91344055cb0511b3aa36c561d741ee356b95f1c9' as Address
+  testnet: '0xe50f5ad9b885675fd11d8204eb01c83a8a32a91d' as Address
 } as const
 
 // Reference: https://github.com/0xPolygon/pos-contracts/blob/main/contracts/staking/validatorShare/ValidatorShare.sol
@@ -147,5 +149,33 @@ export const STAKE_MANAGER_ABI = [
     inputs: [],
     outputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
     stateMutability: 'view'
+  },
+  {
+    type: 'function',
+    name: 'validators',
+    inputs: [{ name: '', type: 'uint256', internalType: 'uint256' }],
+    outputs: [
+      { name: 'amount', type: 'uint256' },
+      { name: 'reward', type: 'uint256' },
+      { name: 'activationEpoch', type: 'uint256' },
+      { name: 'deactivationEpoch', type: 'uint256' },
+      { name: 'jailTime', type: 'uint256' },
+      { name: 'signer', type: 'address' },
+      { name: 'contractAddress', type: 'address' },
+      { name: 'status', type: 'uint256' },
+      { name: 'commissionRate', type: 'uint256' },
+      { name: 'lastCommissionUpdate', type: 'uint256' },
+      { name: 'delegatorsReward', type: 'uint256' },
+      { name: 'delegatedAmount', type: 'uint256' },
+      { name: 'initialRewardPerStake', type: 'uint256' }
+    ],
+    stateMutability: 'view'
   }
 ] as const
+
+export const VALIDATOR_STATUS = {
+  0: 'Inactive',
+  1: 'Active',
+  2: 'Locked',
+  3: 'Unstaked'
+} as const

package/src/staker.ts

@@ -16,7 +16,7 @@ import {
   type Chain
 } from 'viem'
 import { mainnet, sepolia } from 'viem/chains'
-import { secp256k1 } from '@noble/curves/secp256k1.js'
+import { secp256k1 } from '@noble/curves/secp256k1'
 import type { Signer } from '@chorus-one/signer'
 import type { Transaction, PolygonNetworkConfig, PolygonTxStatus, StakeInfo, UnbondInfo } from './types'
 import { appendReferrerTracking } from './referrer'
@@ -26,6 +26,7 @@ import {
   NETWORK_CONTRACTS,
   EXCHANGE_RATE_PRECISION,
   EXCHANGE_RATE_HIGH_PRECISION,
+  VALIDATOR_STATUS,
   type PolygonNetworks,
   type NetworkContracts
 } from './constants'
@@ -75,7 +76,8 @@ export class PolygonStaker {
   static getAddressDerivationFn =
     () =>
     async (publicKey: Uint8Array): Promise<Array<string>> => {
-      const pkUncompressed = secp256k1.Point.fromBytes(publicKey).toBytes(false)
+      const point = secp256k1.Point.fromHex(publicKey)
+      const pkUncompressed = point.toBytes(false)
       const hash = keccak256(pkUncompressed.subarray(1))
       const ethAddress = hash.slice(-40)
       return [ethAddress]
@@ -129,7 +131,8 @@ export class PolygonStaker {
       tx: {
         to: this.contracts.stakingTokenAddress,
         data,
-        value: 0n
+        value: 0n,
+        chainId: this.chain.id
       }
     }
   }
@@ -144,8 +147,8 @@ export class PolygonStaker {
    * @param params.delegatorAddress - The delegator's Ethereum address
    * @param params.validatorShareAddress - The validator's ValidatorShare contract address
    * @param params.amount - The amount to stake in POL
-   * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint.
-   * @param params.minSharesToMint - (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both.
+   * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+   * @param params.minSharesToMint - Minimum validator shares to receive. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
    * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
    *
    * @returns Returns a promise that resolves to a Polygon staking transaction
@@ -173,7 +176,10 @@ export class PolygonStaker {
 
     const amountWei = this.parseAmount(amount)
 
-    const allowance = await this.getAllowance(delegatorAddress)
+    const [allowance] = await Promise.all([
+      this.getAllowance(delegatorAddress),
+      this.assertValidatorActive(validatorShareAddress)
+    ])
     if (parseEther(allowance) < amountWei) {
       throw new Error(
         `Insufficient POL allowance. Current: ${allowance}, Required: ${amount}. Call buildApproveTx() first.`
@@ -203,7 +209,8 @@ export class PolygonStaker {
       tx: {
         to: validatorShareAddress,
         data: appendReferrerTracking(calldata, referrer),
-        value: 0n
+        value: 0n,
+        chainId: this.chain.id
       }
     }
   }
@@ -218,8 +225,8 @@ export class PolygonStaker {
    * @param params.delegatorAddress - The delegator's address
    * @param params.validatorShareAddress - The validator's ValidatorShare contract address
    * @param params.amount - The amount to unstake in POL (will be converted to wei internally)
-   * @param params.slippageBps - (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn.
-   * @param params.maximumSharesToBurn - (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both.
+   * @param params.slippageBps - Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+   * @param params.maximumSharesToBurn - Maximum validator shares willing to burn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
    * @param params.referrer - (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'.
    *
    * @returns Returns a promise that resolves to a Polygon unstaking transaction
@@ -272,7 +279,8 @@ export class PolygonStaker {
       tx: {
         to: validatorShareAddress,
         data: appendReferrerTracking(calldata, referrer),
-        value: 0n
+        value: 0n,
+        chainId: this.chain.id
       }
     }
   }
@@ -330,7 +338,8 @@ export class PolygonStaker {
       tx: {
         to: validatorShareAddress,
         data,
-        value: 0n
+        value: 0n,
+        chainId: this.chain.id
       }
     }
   }
@@ -375,7 +384,8 @@ export class PolygonStaker {
       tx: {
         to: validatorShareAddress,
         data: appendReferrerTracking(calldata, referrer),
-        value: 0n
+        value: 0n,
+        chainId: this.chain.id
       }
     }
   }
@@ -406,7 +416,10 @@ export class PolygonStaker {
       throw new Error(`Invalid validator share address: ${validatorShareAddress}`)
     }
 
-    const rewards = await this.getLiquidRewards({ delegatorAddress, validatorShareAddress })
+    const [rewards] = await Promise.all([
+      this.getLiquidRewards({ delegatorAddress, validatorShareAddress }),
+      this.assertValidatorActive(validatorShareAddress)
+    ])
     if (parseEther(rewards) === 0n) {
       throw new Error('No rewards available to compound')
     }
@@ -420,7 +433,8 @@ export class PolygonStaker {
       tx: {
         to: validatorShareAddress,
         data: appendReferrerTracking(calldata, referrer),
-        value: 0n
+        value: 0n,
+        chainId: this.chain.id
       }
     }
   }
@@ -854,6 +868,31 @@ export class PolygonStaker {
     }
   }
 
+  private async assertValidatorActive (validatorShareAddress: Address): Promise<void> {
+    const validatorId = await this.publicClient.readContract({
+      address: validatorShareAddress,
+      abi: VALIDATOR_SHARE_ABI,
+      functionName: 'validatorId'
+    })
+
+    const validator = await this.publicClient.readContract({
+      address: this.contracts.stakeManagerAddress,
+      abi: STAKE_MANAGER_ABI,
+      functionName: 'validators',
+      args: [validatorId]
+    })
+
+    const status = Number(validator[7])
+    if (status !== 1) {
+      const statusName = VALIDATOR_STATUS[status as keyof typeof VALIDATOR_STATUS] ?? 'Unknown'
+      throw new Error(
+        `Validator is not active (status: ${statusName}). ` +
+          'The validator may be locked, inactive, or unstaked. ' +
+          'See the @chorus-one/polygon README for how to list active validators on testnet.'
+      )
+    }
+  }
+
   private parseAmount (amount: string): bigint {
     if (typeof amount === 'bigint') {
       throw new Error(

package/src/types.ts

@@ -15,6 +15,14 @@ export interface Transaction {
   data: Hex
   /** The amount of ETH (in wei) to be sent with the transaction */
   value?: bigint
+  /**
+   * The chain ID where the transaction must be broadcast.
+   *
+   * Polygon staking contracts live on Ethereum L1, not on the Polygon chain itself:
+   * - mainnet: `1` (Ethereum Mainnet)
+   * - testnet: `11155111` (Sepolia)
+   */
+  chainId: number
 }
 
 export interface PolygonTxStatus {

package/test/fixtures/expected-data.ts

@@ -12,6 +12,7 @@ export const EXPECTED_APPROVE_TX = {
     to: stakingTokenAddress as Address,
     // approve(address spender, uint256 amount) with spender = stakeManagerAddress (0x5e3e...), amount = 100e18
     data: '0x095ea7b30000000000000000000000005e3ef299fddf15eaa0432e6e66473ace8c13d9080000000000000000000000000000000000000000000000056bc75e2d63100000' as Hex,
-    value: 0n
+    value: 0n,
+    chainId: 1
   }
 }

package/test/integration/staker.spec.ts

@@ -93,6 +93,34 @@ describe('PolygonStaker', () => {
       const precision = await staker.getExchangeRatePrecision(validatorShareAddress)
       assert.equal(precision, EXCHANGE_RATE_HIGH_PRECISION)
     })
+
+    it('rejects staking to an unstaked validator', async () => {
+      const unstakedValidator = '0xd245710936382e5ED099d4F8D9AAE64e67e30EF3' as Address
+      await expect(
+        staker.buildStakeTx({
+          delegatorAddress: WHALE_DELEGATOR,
+          validatorShareAddress: unstakedValidator,
+          amount: '100',
+          minSharesToMint: 0n
+        })
+      ).to.be.rejectedWith('Validator is not active (status: Unstaked)')
+    })
+
+    it('allows staking to an active validator', async () => {
+      // Should not throw — the default validatorShareAddress is active
+      const allowance = await staker.getAllowance(WHALE_DELEGATOR)
+      // Will fail on allowance, not on validator status
+      if (parseEther(allowance) === 0n) {
+        await expect(
+          staker.buildStakeTx({
+            delegatorAddress: WHALE_DELEGATOR,
+            validatorShareAddress,
+            amount: '100',
+            minSharesToMint: 0n
+          })
+        ).to.be.rejectedWith('Insufficient POL allowance')
+      }
+    })
   })
 
   describe('staking lifecycle', () => {

package/test/lib/networks.json

@@ -2,7 +2,7 @@
   "networks": {
     "ethereum": {
       "name": "ethereum",
-      "url": "https://ethereum-rpc.publicnode.com"
+      "url": "https://eth.drpc.org"
     }
   },
   "accounts": [

package/test/staker.spec.ts

@@ -27,6 +27,7 @@ describe('PolygonStaker', () => {
       assert.equal(tx.to, EXPECTED_APPROVE_TX.expected.to)
       assert.equal(tx.data, EXPECTED_APPROVE_TX.expected.data)
       assert.equal(tx.value, EXPECTED_APPROVE_TX.expected.value)
+      assert.equal(tx.chainId, EXPECTED_APPROVE_TX.expected.chainId)
     })
 
     it('should generate correct unsigned approve tx for max (unlimited) amount', async () => {
@@ -50,6 +51,22 @@ describe('PolygonStaker', () => {
     })
   })
 
+  describe('chainId', () => {
+    it('should return mainnet chainId (1) for mainnet network', async () => {
+      const { tx } = await staker.buildApproveTx({ amount: '100' })
+      assert.equal(tx.chainId, 1)
+    })
+
+    it('should return sepolia chainId (11155111) for testnet network', async () => {
+      const testnetStaker = new PolygonStaker({
+        network: 'testnet',
+        rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com'
+      })
+      const { tx } = await testnetStaker.buildApproveTx({ amount: '100' })
+      assert.equal(tx.chainId, 11155111)
+    })
+  })
+
   describe('address validation', () => {
     it('should reject invalid delegator address in buildStakeTx', async () => {
       await expect(