Add referrer field for TON staking tx

Author: welldan97

book/build-your-staking-dapp/ton/ton-pool/methods.md

@@ -18,7 +18,7 @@ Staking tokens supports the network's operations and earns rewards for the deleg
 
 ### How to Use
 
-To build a staking transaction, you need to provide the validator address pair, the staking amount (in TON), and optionally, a Unix timestamp indicating when the transaction expires.
+To build a staking transaction, you need to provide the validator address pair, and the staking amount (in TON). Optionally, you can also specify a referrer address for tracking purposes, and a Unix timestamp indicating when the transaction expires.
 
 ### Example
 
@@ -29,7 +29,8 @@ const { tx } = await staker.buildStakeTx({
     'kQCltujow9Sq3ZVPPU6CYGfqwDxYwjlmFGZ1Wt0bAYebio4o'
   ],
   amount: '2', // 2 TON
-  validUntil: Math.floor(Date.now() / 1000) + 3600 // Optional, expires in 1 hour
+  validUntil: Math.floor(Date.now() / 1000) + 3600, // Optional, expires in 1 hour
+  referrer: 'Telegram' // Optional, unique referrer string for tracking
 })
 ```
 

book/docs/classes/ton_src.TonPoolStaker.md

@@ -178,6 +178,7 @@ to stake to automatically.
 | `params` | `Object` | Parameters for building the transaction |
 | `params.validatorAddressPair` | [`string`, `string`] | The validator address pair to stake to |
 | `params.amount` | `string` | The amount to stake, specified in `TON` |
+| `params.referrer?` | `string` | (Optional) The address of the referrer. This is used to track the origin of transactions, providing insights into which sources or campaigns are driving activity. This can be useful for analytics and optimizing user acquisition strategies |
 | `params.validUntil?` | `number` | (Optional) The Unix timestamp when the transaction expires |
 
 ### Returns

packages/ton/src/TonPoolStaker.ts

@@ -10,16 +10,20 @@ export class TonPoolStaker extends TonBaseStaker {
    * @param params - Parameters for building the transaction
    * @param params.validatorAddressPair - The validator address pair to stake to
    * @param params.amount - The amount to stake, specified in `TON`
+   * @param params.referrer - (Optional) The address of the referrer. This is used to track the origin of transactions,
+   * providing insights into which sources or campaigns are driving activity. This can be useful for analytics and
+   * optimizing user acquisition strategies
    * @param params.validUntil - (Optional) The Unix timestamp when the transaction expires
    *
    * @returns Returns a promise that resolves to a TON nominator pool staking transaction.
    */
   async buildStakeTx (params: {
     validatorAddressPair: [string, string]
     amount: string
+    referrer?: string
     validUntil?: number
   }): Promise<{ tx: UnsignedTx }> {
-    const { validatorAddressPair, amount, validUntil } = params
+    const { validatorAddressPair, amount, validUntil, referrer } = params
     const validatorAddress = await this.getPoolAddressForStake({ validatorAddressPair })
 
     // ensure the address is for the right network
@@ -35,11 +39,16 @@ export class TonPoolStaker extends TonBaseStaker {
     }
 
     // https://github.com/tonwhales/ton-nominators/blob/0553e1b6ddfc5c0b60505957505ce58d01bec3e7/compiled/nominators.fc#L18
-    const payload = beginCell()
+    let basePayload = beginCell()
       .storeUint(2077040623, 32) // stake_deposit method const
       .storeUint(getRandomQueryId(), 64) // Query ID
       .storeCoins(getDefaultGas()) // Gas
-      .endCell()
+
+    if (referrer) {
+      basePayload = basePayload.storeStringTail(referrer)
+    }
+
+    const payload = basePayload.endCell()
 
     const tx = {
       validUntil: defaultValidUntil(validUntil),