Ethereum: Delegation Tracking Section (#6)

* Ethereum: Delegation Tracking Section

* Update delegation-tracking.md Minor tweaks and review

* Update delegation-tracking.md Updated and elaborated on "Benefits" section

* Ethereum: Remove empty hint

---------

Co-authored-by: Nathan Hallen <[email protected]>

book/README.md

@@ -240,7 +240,9 @@ const validatorAddress = CHORUS_ONE_ETHEREUM_VALIDATORS.ethereum.mevMaxVault
 const { tx } = await staker.buildStakeTx({
   delegatorAddress,
   validatorAddress,
-  amount: '1' // 1 ETH
+  amount: '1', // 1 ETH
+  // Optional - Unique Ethereum address for tracking
+  referrer: '0xReferrerAddressHere'
 })
 
 // Signing the transaction with Fireblocks
@@ -576,11 +578,6 @@ console.log(status) // 'success'
 
 import { SubstrateStaker, RewardDestination, CHORUS_ONE_SUBSTRATE_VALIDATORS } from '@chorus-one/substrate'
 
-import { FireblocksSigner } from '@chorus-one/signer-fireblocks'
-
-const signer = new FireblocksSigner({...})
-await signer.init()
-
 const staker = new SubstrateStaker({
   rpcUrl: 'wss://rpc.polkadot.io',
   denomMultiplier: 1000000000000,
@@ -609,6 +606,11 @@ const { tx: nominateTx } = await staker.buildNominateTx({
 // Signing the transactions with Fireblocks
 // ----------------------------------------
 
+import { FireblocksSigner } from '@chorus-one/signer-fireblocks'
+
+const signer = new FireblocksSigner({...})
+await signer.init()
+
 const { signedTx: signedStakeTx } = await staker.sign({
   signerAddress: delegatorAddress,
   tx: stakeTx

book/SUMMARY.md

@@ -13,6 +13,7 @@
 - [Ethereum](build-your-staking-dapp/ethereum/README.md)
   - [Overview](build-your-staking-dapp/ethereum/overview.md)
   - [Methods](build-your-staking-dapp/ethereum/methods.md)
+  - [Delegation Tracking](build-your-staking-dapp/ethereum/delegation-tracking.md)
 - [NEAR](build-your-staking-dapp/near/README.md)
   - [Overview](build-your-staking-dapp/near/overview.md)
   - [Methods](build-your-staking-dapp/near/methods.md)

book/build-your-staking-dapp/ethereum/delegation-tracking.md

@@ -0,0 +1,74 @@
+# Delegation Tracking
+
+## Introduction
+
+Delegation tracking enables businesses to precisely attribute staking activities to specific campaigns, partners, or sources.
+
+Understanding the origin and impact of your staking transactions is important for maximizing marketing efforts and partnership strategies. With these insights into the performance of your marketing campaigns and partner engagements you can ensure that your resources are directed towards the most effective initiatives and generate accurate revenue reports.
+
+## How It Works
+
+This section will show you how to implement delegation tracking using the Chorus One SDK.
+
+The `referrer` field in the SDK allows you to associate transactions with a specific Ethereum address, representing the source of the delegation or minting, such as a marketing campaign or integration partner. 
+
+Including this field as a parameter in both the `buildStakeTx` and `buildMintTx` methods provides detailed insights and accurate attribution of delegations and minting transactions tailored to your specific needs.
+
+{% hint style="info" %}
+
+To ensure precise tracking and management of transaction origins, it is important to use unique addresseses for different customers or campaigns. 
+
+It is advisable to generate a unique Ethereum address for each referrer or use your own Ethereum address to track transactions.
+
+{% endhint %}
+
+### Example Usage
+
+Here's an example of how to use the `referrer` field when building a staking transaction:
+
+```javascript
+const { tx } = await staker.buildStakeTx({
+  delegatorAddress: '0x70aEe8a9099ebADB186C2D530F72CF5dC7FE6B30',
+  validatorAddress: '0xe6d8d8ac54461b1c5ed15740eee322043f696c08',
+  amount: '1', // 1 ETH
+  referrer: '0xReferrerAddressHere' // Unique Ethereum address for tracking
+})
+```
+
+And here is an example of how to use the `referrer` field when building a minting transaction:
+
+```javascript
+const { tx } = await staker.buildMintTx({
+  delegatorAddress: '0x70aEe8a9099ebADB186C2D530F72CF5dC7FE6B30',
+  validatorAddress: '0xe6d8d8ac54461b1c5ed15740eee322043f696c08',
+  amount: '1', // 1 osETH
+  referrer: '0xReferrerAddressHere' // Unique Ethereum address for tracking
+})
+```
+
+## Benefits for Your Business
+
+Leveraging delegation tracking via the Chorus One SDK ensures that your business remains at the forefront of industry developments and provides important benefits and insights for delegation activity such as: 
+
+**Accurate Reporting:**
+- Delegation tracking ensures accurate revenue tracking to the right partners or campaigns and provides clear revenue reports for different referral sources.
+- It allows evaluation of partner performance by tracking staking transaction volume, value, and measuring campaign success by analyzing which referrers generate the most delegations.
+- Delegation tracking also ensures that all activities are documented and accountable, facilitating smoother audits, compliance, and financial reporting.
+- Detailed delegation reports can be shared with clients as needed, providing them with insights into their holdings and fostering transparency.
+
+**Strategic Planning:** 
+- Delegation tracking provides clear and detailed insights into delegation activities, enabling businesses to maintain transparency and build trust with stakeholders.
+- Tracking customer behavior and preferences to improve engagement strategies and implement retention strategies for high-value customers based on delegation data.
+- Access to real-time delegation data allows your business to make informed decisions, optimize strategies, and respond promptly to market changes.
+- Historical delegation data can be analyzed to forecast trends and improve business strategy and long-term planning.
+
+**Performance Monitoring:**
+- By tracking delegations, businesses can identify high-performing assets and allocate resources more effectively to maximize returns.
+- Continuous tracking of delegations helps in monitoring the performance of delegated assets, ensuring you can identify and address underperforming areas swiftly.
+- Automated tracking reduces the need for manual monitoring, saving time and reducing errors.
+
+## Conclusion
+
+Using delegation tracking in the Chorus One SDK optimizes strategies and partnerships for your business by providing accurate attribution and insights into customer staking activity while also enabling precise revenue tracking. 
+
+This allows your business to stay competitive and allocate resources effectively as well as maintain accurate financial records and reporting. 

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

@@ -12,13 +12,20 @@ The `buildStakeTx` method helps you create a transaction for staking tokens with
 
 To build a staking transaction, you need to specify the amount to stake, the delegator's address (your wallet), and the validator's address where you want to stake your tokens. Optionally, you can also specify a referrer address for tracking purposes.
 
+{% hint style="info" %}
+
+For more information on tracking and attributing staking transactions to specific sources, such as marketing campaigns or integration partners, refer to the [Delegation Tracking](./delegation-tracking.md) section.
+
+{% endhint %}
+
 ### Example
 
 ```javascript
 const { tx } = await staker.buildStakeTx({
   delegatorAddress: '0x70aEe8a9099ebADB186C2D530F72CF5dC7FE6B30',
   validatorAddress: '0xe6d8d8ac54461b1c5ed15740eee322043f696c08',
-  amount: '1' // 1 ETH
+  amount: '1', // 1 ETH
+  referrer: '0xReferrerAddressHere' // Unique Ethereum address for tracking
 })
 ```
 
@@ -100,13 +107,20 @@ The `buildMintTx` method helps you create a transaction for minting shares (osET
 
 To build a minting transaction, you need to specify the amount of osETH to mint, the delegator's address, and the validator's address where you want to mint your shares. Optionally, you can also specify a referrer address for tracking purposes.
 
+{% hint style="info" %}
+
+For more information on tracking and attributing minting transactions to specific sources, such as marketing campaigns or integration partners, refer to the [Delegation Tracking](./delegation-tracking.md) section.
+
+{% endhint %}
+
 ### Example
 
 ```javascript
 const { tx } = await staker.buildMintTx({
   delegatorAddress: '0x70aEe8a9099ebADB186C2D530F72CF5dC7FE6B30',
   validatorAddress: '0xe6d8d8ac54461b1c5ed15740eee322043f696c08',
-  amount: '1' // 1 osETH
+  amount: '1', // 1 osETH
+  referrer: '0xReferrerAddressHere' // Unique Ethereum address for tracking
 })
 ```
 

book/build-your-staking-dapp/ethereum/overview.md

@@ -121,6 +121,14 @@ const { tx } = await staker.buildStakeTx({
 })
 ```
 
+{% hint style="info" %}
+
+**Delegation Tracking**
+
+For more information on tracking and attributing staking transactions to specific sources, such as marketing campaigns or integration partners, refer to the [Delegation Tracking](./delegation-tracking.md) section.
+
+{% endhint %}
+
 ### Ensuring Correct Amount Format for Staking
 
 The `amount` parameter must be a string representing the amount of ETH to deposit. For example, `'1'` represents 1 ETH.

book/ethereum-tutorial/3-staking.md

@@ -45,10 +45,6 @@ export const FormComponent = ({ onSubmit }) => {
 
 This form component uses the `useAccount` and `useBalance` hooks from `wagmi` to manage user account details and balance information. The `onSubmit` prop is a function that handles the actual staking process, which you can define in your application logic.
 
-{% hint style="info" %}
-
-{% endhint %}
-
 This simple yet effective form provides the basic functionality to integrate staking into your Ethereum-based application.
 
 ![Stake form](../assets/tutorial/stake.png)
@@ -96,6 +92,15 @@ const stake = async ({
   await walletClient.sendTransaction(request)
 }
 ```
+{% hint style="info" %}
+
+**Delegation Tracking**
+
+If you would like to learn how to track and attribute staking transactions to
+specific sources, such as marketing campaigns or integration partners, refer to the [Delegation Tracking](../build-your-staking-dapp/ethereum/delegation-tracking.md) section.
+
+{% endhint %}
+
 
 The `Transaction` object returned by `buildStakeTransaction` includes the following parameters:
 

packages/ethereum/src/staker.ts

@@ -77,9 +77,8 @@ export class EthereumStaker {
    * @param params.delegatorAddress - The delegator (wallet) address to stake from
    * @param params.validatorAddress - The validator (vault) address to stake with
    * @param params.amount - The amount to stake, specified in `ETH`. E.g. "1" - 1 ETH
-   * @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.referrer - (Optional) A unique Ethereum address representing the source of the delegation, such as a
+   * marketing campaign or integration partner. This allows precise tracking and management of transaction origins.
    *
    * @returns Returns a promise that resolves to an Ethereum staking transaction.
    */
@@ -168,9 +167,8 @@ export class EthereumStaker {
    * @param params.delegatorAddress - The delegator (wallet) address
    * @param params.validatorAddress - The validator (vault) address to mint shares for
    * @param params.amount - The amount to mint, specified in `osETH`. E.g. "1" - 1 osETH
-   * @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.referrer - (Optional) A unique Ethereum address representing the source of the delegation, such as a
+   * marketing campaign or integration partner. This allows precise tracking and management of transaction origins.
    *
    * @returns Returns a promise that resolves to an Ethereum mint transaction.
    */