Add details on how to use slippage on Polygon docs

Author: Pessina

book/build-your-staking-dapp/polygon/methods.md

@@ -50,8 +50,11 @@ To build a staking transaction, you will need to specify:
 - **delegatorAddress**: The delegator's Ethereum address
 - **validatorShareAddress**: The validator's ValidatorShare contract address
 - **amount**: The amount to stake in POL
-- **slippageBps**: (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint automatically.
-- **minSharesToMint**: (Optional) Minimum validator shares to receive for slippage protection. Use this OR slippageBps, not both.
+- **slippageBps**: Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint automatically. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+- **minSharesToMint**: Minimum validator shares to receive for slippage protection. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default).
+
+> **Why is slippage required?** Polygon uses a share-based delegation model where the exchange rate between POL and validator shares fluctuates. The slippage parameter protects against unfavorable rate changes between transaction submission and execution. This is a requirement of the ValidatorShare contract itself.
+
 - **referrer**: (Optional) Custom referrer string for tracking. Defaults to `'sdk-chorusone-staking'`.
 
 ### Example
@@ -99,8 +102,11 @@ To build an unstaking transaction, you need to specify:
 - **delegatorAddress**: The address of the delegator
 - **validatorShareAddress**: The validator's ValidatorShare contract address
 - **amount**: The amount of POL to unstake
-- **slippageBps**: (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn automatically.
-- **maximumSharesToBurn**: (Optional) Maximum validator shares willing to burn for slippage protection. Use this OR slippageBps, not both.
+- **slippageBps**: Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn automatically. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+- **maximumSharesToBurn**: Maximum validator shares willing to burn for slippage protection. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default).
+
+> **Why is slippage required?** Polygon uses a share-based delegation model where the exchange rate between POL and validator shares fluctuates. The slippage parameter protects against unfavorable rate changes between transaction submission and execution. This is a requirement of the ValidatorShare contract itself.
+
 - **referrer**: (Optional) Custom referrer string for tracking. Defaults to `'sdk-chorusone-staking'`.
 
 ### Example

book/docs/classes/polygon_src.PolygonStaker.md

@@ -124,6 +124,9 @@ Builds a staking (delegation) transaction
 Delegates POL tokens to a validator via their ValidatorShare contract.
 Requires prior token approval to the StakeManager contract.
 
+**Slippage requirement:** Exactly one of `slippageBps` or `minSharesToMint` must be provided.
+There is no default value. Providing neither or both will throw an error.
+
 ### Parameters
 
 | Name | Type | Description |
@@ -132,8 +135,8 @@ Requires prior token approval to the StakeManager contract.
 | `params.delegatorAddress` | \`0x$\{string}\` | The delegator's Ethereum address |
 | `params.validatorShareAddress` | \`0x$\{string}\` | The validator's ValidatorShare contract address |
 | `params.amount` | `string` | The amount to stake in POL |
-| `params.slippageBps?` | `number` | (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate minSharesToMint. |
-| `params.minSharesToMint?` | `bigint` | (Optional) Minimum validator shares to receive. Use this OR slippageBps, not both. |
+| `params.slippageBps?` | `number` | 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). |
+| `params.minSharesToMint?` | `bigint` | Minimum validator shares to receive. Exactly one of `slippageBps` or `minSharesToMint` must be provided (not both, no default). |
 | `params.referrer?` | `string` | (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'. |
 
 ### Returns
@@ -153,6 +156,9 @@ Builds an unstaking transaction
 Creates an unbond request to unstake POL tokens from a validator.
 After the unbonding period (~80 checkpoints, approximately 3-4 days), call buildWithdrawTx() to claim funds.
 
+**Slippage requirement:** Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided.
+There is no default value. Providing neither or both will throw an error.
+
 ### Parameters
 
 | Name | Type | Description |
@@ -161,8 +167,8 @@ After the unbonding period (~80 checkpoints, approximately 3-4 days), call build
 | `params.delegatorAddress` | \`0x$\{string}\` | The delegator's address |
 | `params.validatorShareAddress` | \`0x$\{string}\` | The validator's ValidatorShare contract address |
 | `params.amount` | `string` | The amount to unstake in POL (will be converted to wei internally) |
-| `params.slippageBps?` | `number` | (Optional) Slippage tolerance in basis points (e.g., 50 = 0.5%). Used to calculate maximumSharesToBurn. |
-| `params.maximumSharesToBurn?` | `bigint` | (Optional) Maximum validator shares willing to burn. Use this OR slippageBps, not both. |
+| `params.slippageBps?` | `number` | 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). |
+| `params.maximumSharesToBurn?` | `bigint` | Maximum validator shares willing to burn. Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided (not both, no default). |
 | `params.referrer?` | `string` | (Optional) Custom referrer string for tracking. If not provided, uses 'sdk-chorusone-staking'. |
 
 ### Returns

package-lock.json

@@ -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({
@@ -215,7 +219,7 @@ console.log(status) // 'success', 'failure', or 'unknown'
 - **Ethereum L1 Based**: Polygon PoS staking operates via ValidatorShare contracts deployed on Ethereum mainnet (or Sepolia for testnet)
 - **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
 

packages/polygon/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-one/polygon",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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",

packages/polygon/package.json

@@ -140,12 +140,15 @@ export class PolygonStaker {
    * Delegates POL tokens to a validator via their ValidatorShare contract.
    * Requires prior token approval to the StakeManager contract.
    *
+   * **Slippage requirement:** Exactly one of `slippageBps` or `minSharesToMint` must be provided.
+   * There is no default value. Providing neither or both will throw an error.
+   *
    * @param params - Parameters for building the transaction
    * @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
@@ -214,12 +217,15 @@ export class PolygonStaker {
    * Creates an unbond request to unstake POL tokens from a validator.
    * After the unbonding period (~80 checkpoints, approximately 3-4 days), call buildWithdrawTx() to claim funds.
    *
+   * **Slippage requirement:** Exactly one of `slippageBps` or `maximumSharesToBurn` must be provided.
+   * There is no default value. Providing neither or both will throw an error.
+   *
    * @param params - Parameters for building the transaction
    * @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