> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powfi.alephium.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 推荐质押与渠道分润

> 用 stakeAlphWithReferral 把质押归属到你的渠道地址，以及渠道分润的计算和支付方式。

export const VersionBanner = ({network = 'mainnet', products = [], lang = 'en'}) => {
  const SDK_VERSION = '1.0.2';
  const ADDRESSES = {
    mainnet: {
      cpmm: {
        Router: 'ze15rnAwTyVCPnDhN7J8An3SvNeWBsZHAVMeBx1ehXeP',
        TokenPairFactory: '24CXRLvj1QiDH6riwr1EPERG7BcduHKZtktygbq97MfYb'
      },
      clmm: {
        PoolFactory: '24gqd4DMQXVzjm5QDAGxUtYupx3WM2PSu3vZUseuBCV9h',
        PositionManager: 'vFyKSqnJHS9MicrojBcLgztyRFqhS4hB349Ci3LJCELw'
      },
      staking: {
        XAlphToken: '225WevmFp5ZgzPsyVJTvyp2v2uyKrvp329HfrVmzffnWj',
        RewardFeeCollector: '22CE7vG6u64zjjsLZLxeJqQuPDydjPvbP9iG1d861j2G7'
      }
    },
    testnet: {
      cpmm: {
        Router: 'xaueT8kPMvpnaFJEfHv6CJLgqsSPpoNmHjF1QgTxoF9R',
        TokenPairFactory: '29hdd9b9Gp7oXuamwHKfUqBaRXP487HoeTcutS3RhZJEj'
      },
      clmm: {
        PoolFactory: 'z2QFT7qBQrfm8UwAYG3VHWoHs7B56ZDFNdSCcDu5j53m',
        PositionManager: '21p6egW8d6FEyVVuH17WqvHCARsCsD61GcBmeCr75XdGT'
      },
      staking: {
        XAlphToken: '23psDicimC5VdpM56wrgqgCzQzcyXWGCkQGSYWbtZAPRq',
        RewardFeeCollector: '29qQ1LPJ5uqawRviXLVDMeo19JUygRrNNTQy5RUBh817D'
      }
    }
  };
  const EXPLORERS = {
    mainnet: 'https://explorer.alephium.org/addresses/',
    testnet: 'https://testnet.alephium.org/addresses/'
  };
  const LABELS = {
    en: {
      sdk: 'SDK',
      network: 'Network',
      contracts: 'Contracts',
      all: 'All addresses',
      allNetworks: 'mainnet · testnet · devnet',
      devnet: 'Local deployment (addresses vary per devnet)'
    },
    zh: {
      sdk: 'SDK 版本',
      network: '网络',
      contracts: '合约',
      all: '全部地址',
      allNetworks: 'mainnet · testnet · devnet',
      devnet: '本地部署（每个 devnet 的地址不同）'
    },
    fr: {
      sdk: 'SDK',
      network: 'Réseau',
      contracts: 'Contrats',
      all: 'Toutes les adresses',
      allNetworks: 'mainnet · testnet · devnet',
      devnet: 'Déploiement local (adresses propres à chaque devnet)'
    }
  };
  const t = LABELS[lang] ?? LABELS.en;
  const contractsPage = lang === 'en' ? '/reference/contracts' : `/${lang}/reference/contracts`;
  const short = a => `${a.slice(0, 6)}…${a.slice(-4)}`;
  const entries = [];
  const addrs = ADDRESSES[network];
  if (addrs) {
    for (const p of products) {
      for (const [name, address] of Object.entries(addrs[p] ?? ({}))) entries.push({
        name,
        address
      });
    }
  }
  let contractsCell;
  if (network === 'devnet' && products.length > 0) {
    contractsCell = <span>{t.devnet}</span>;
  } else if (entries.length > 0) {
    contractsCell = entries.map(({name, address}, i) => <span key={name}>
        {i > 0 && <span className="mx-1 opacity-50">·</span>}
        {name}{' '}
        <a href={EXPLORERS[network] + address} target="_blank" rel="noreferrer" title={address}>
          <code>{short(address)}</code>
        </a>
      </span>);
  }
  const row = (label, value) => <div className="flex flex-wrap gap-x-2">
      <span className="font-semibold min-w-[5.5rem]">{label}</span>
      <span className="flex-1 min-w-0 break-words">{value}</span>
    </div>;
  return <div className="not-prose mb-6 rounded-xl border border-zinc-950/10 dark:border-white/10 bg-zinc-50 dark:bg-white/5 px-4 py-3 text-sm leading-6 text-zinc-700 dark:text-zinc-300">
      {row(t.sdk, <code>@alephium/powfi-sdk@{SDK_VERSION}</code>)}
      {row(t.network, network === 'all' ? t.allNetworks : network)}
      {contractsCell && row(t.contracts, <span>
            {contractsCell}
            <span className="mx-1 opacity-50">·</span>
            <a href={contractsPage}>{t.all} →</a>
          </span>)}
    </div>;
};

<VersionBanner network="mainnet" products={['staking']} lang="zh" />

渠道商可以为 Powfi 带来质押用户，并从这些用户获得的收益中分成。归属关系通过质押时的 `referral` 参数记录在链上；分润在链下计算，由 Powfi 团队支付。

<Warning>
  \*\*使用 referral 地址之前，请先联系 Powfi 团队。\*\*合约接受任意地址作为 `referral`，但只有与团队签订协议的渠道商才能获得分润。协议会确定你的渠道地址、分润比例、结算周期和支付方式。用团队不知道的地址标记的质押，可能无法获得分润。
</Warning>

## 流程

<Steps>
  <Step title="向团队登记你的渠道地址">
    约定你要使用的渠道地址、分润比例（y%）和结算周期。
  </Step>

  <Step title="用你的地址作为 referral 发起质押">
    你的前端或集成调用 `stakeAlphWithReferral`，传入你的渠道地址。每次质押都使用同一个地址。
  </Step>

  <Step title="质押用户获得收益">
    随着协议收益的分配，xALPH 的兑换率会上涨。你的质押用户和其他 xALPH 持有者一样获得这部分收益。
  </Step>

  <Step title="结算和支付">
    每个周期，团队计算归属到你的 xALPH 所产生的收益，并以 ALPH 向你支付其中的 y%。
  </Step>
</Steps>

## 带 referral 质押

```ts theme={null}
import { Powfi } from '@alephium/powfi-sdk'
import { ONE_ALPH } from '@alephium/web3'

const powfi = Powfi.load({ networkId: 'mainnet', signer }) // the staker's wallet
const PARTNER_ADDRESS = '<your registered partner address>'

const result = await powfi.staking.stakeAlphWithReferral(100n * ONE_ALPH, PARTNER_ADDRESS)
console.log(result.txId)
```

质押用户不会因为 referral 多付任何费用。这笔交易与 `stakeAlph` 相同（附加 `amount + MINIMAL_CONTRACT_DEPOSIT` 的 ALPH），用户收到的 xALPH 数量也一样。

<Note>
  Powfi 官方前端目前不支持传入 referral 参数。要把质押归属到你的地址，需要自建质押页面或集成，在其中调用 `stakeAlphWithReferral`。
</Note>

### 合约如何处理 `referral`

* **不校验，链上无需注册。**`XAlphToken.stake(amount, referral)` 接受任意地址，只把它记录在 `Staked` 事件里。
* \*\*referral 地址不接收任何代币。\*\*由于没有向它转账，referral 不会出现在浏览器的交易页面中，只能在事件里看到。
* **质押必须由钱包发起。**`stake` 要求调用者是资产（钱包）地址，所以合约不能代替用户质押。
* 事件为 `Staked(to, referral, alphAmount, xAlphAmount)`：质押者、referral、存入的 ALPH、铸造的 xALPH。

## 验证归属

任何人都可以从节点读取交易事件，查看某笔质押归属到哪个 referral：

```ts theme={null}
const xAlphAddress = powfi.staking.getConfig().xAlphTokenAddress
const { events } = await powfi.nodeProvider.events.getEventsTxIdTxid(txId)

// Staked is the first event declared by XAlphToken (eventIndex 0)
const staked = events.find((e) => e.contractAddress === xAlphAddress && e.eventIndex === 0)
const [to, referral, alphAmount, xAlphAmount] = staked!.fields.map((f) => f.value)
```

无分组地址在事件中可能带有 `:<group>` 后缀，它和不带后缀的是同一个地址。

## 分润如何计算

每个结算周期：

1. **归属的 xALPH**：把所有 `referral` 为你地址的 `Staked` 事件中的 `xAlphAmount` 相加。
2. **兑换率涨幅**：`yieldRateDelta = 本期末兑换率 − 上期末兑换率`，其中 `兑换率 = totalDepositedAlph / totalXAlphSupply`（见[质押](/zh/modules/staking)）。
3. **总收益**：`归属的 xALPH × yieldRateDelta`，单位为 ALPH。
4. **你的分润**：`总收益 × y%`。

影响结果的因素：

* \*\*只统计质押时铸造的 xALPH。\*\*之后的 xALPH 转账和解除质押不会被追踪。
* \*\*质押本身不改变兑换率。\*\*新的质押按当前兑换率铸造 xALPH。只有存入奖励时兑换率才会上涨。
* \*\*收益取决于协议收入。\*\*兑换率在 `RewardFeeCollector.distributeRewards()` 执行时上涨。它分配 `totalDepositedAlph × rewardRate × 经过时间 / 1 年`（年化率），上限是费用收集器从交易手续费中获得的 ALPH。先扣除国库份额和销毁份额，剩下的部分用于提高 xALPH 兑换率。如果交易量很少，可分的收益也很少。

## 支付

分润是链下计算出的应付金额，不是质押时自动触发的链上转账。团队按照协议，从国库以 ALPH 支付。由于所有输入（`Staked` 事件和 xALPH 兑换率）都在链上公开，你可以独立复算自己的分润。可以向团队索取列出你各期结算的验证页面。

## 推荐分润与集成方手续费的区别

这是两套独立的机制：

| | 推荐分润（本页） | [集成方手续费](/zh/guides/integrator-fees) |
| - | - | - |
| 适用于 | 质押（`stakeAlphWithReferral`） | 兑换（`cpmm.swap`、`clmm.swap`） |
| 谁付钱 | Powfi，从协议收益中支付 | 用户，在兑换之外额外支付 |
| 计算方式 | 链下，按结算周期 | 链上，金额由集成方设定 |
| 到账 | 由团队按协议支付 | 在同一笔交易中立即到账 |
| 是否需要与团队签协议 | 需要 | 不需要 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.