Referral staking & partner commission

Partners can bring stakers to Powfi and earn a share of the yield those stakers receive. Attribution happens on-chain through the referral argument of a stake. The commission is calculated off-chain and paid by the Powfi team.

Contact the Powfi team before you use a referral address. The contract accepts any address as referral, but commission is only paid to partners who have an agreement with the team. The agreement sets your partner address, commission rate, settlement period, and payment method. Stakes tagged with an address the team doesn’t know about may not be eligible for commission.

How it works

Agree on the partner address you will use, your commission rate (y%), and the settlement schedule.

Stake with your address as referral

Your frontend or integration calls stakeAlphWithReferral with your partner address. Use the same address for every stake.

Yield accrues to your stakers

The xALPH exchange rate rises as protocol rewards are distributed. Your stakers earn that yield like any other xALPH holder.

Settlement and payment

Each period, the team computes the yield earned by the xALPH attributed to you and pays you y% of it in ALPH.

Stake with a referral

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)

The staker pays nothing extra for the referral. The transaction is the same as stakeAlph (it attaches amount + MINIMAL_CONTRACT_DEPOSIT ALPH), and the staker receives the same amount of xALPH.

The official Powfi frontend does not currently accept a referral parameter. To attribute stakes to your address, build your own staking page or integration that calls stakeAlphWithReferral.

What the contract does with `referral`

No validation, no registration on-chain. XAlphToken.stake(amount, referral) accepts any address and only records it in the Staked event.
The referral receives no tokens. Because nothing is transferred to it, the referral does not appear in the explorer’s transaction view. It is only visible in the event.
The stake must come from a wallet. stake requires the caller to be an asset (wallet) address, so contracts cannot stake on a user’s behalf.
The event is Staked(to, referral, alphAmount, xAlphAmount): staker, referral, ALPH deposited, xALPH minted.

Verify attribution

Anyone can check which referral a stake was attributed to by reading the transaction’s events from a node:

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)

Groupless addresses may appear with a :<group> suffix in the event. That is the same address.

How commission is calculated

For each settlement period:

Attributed xALPH: sum the xAlphAmount of every Staked event whose referral is your address.
Rate increase: yieldRateDelta = rate(end of period) − rate(end of previous period), where rate = totalDepositedAlph / totalXAlphSupply (see Staking).
Gross yield: attributed xALPH × yieldRateDelta, in ALPH.
Your commission: gross yield × y%.

Things that affect the numbers:

Only the xALPH minted at stake time counts. Later xALPH transfers and unstakes are not tracked.
Staking does not move the rate. New stakes mint xALPH at the current rate. The rate only rises when rewards are deposited.
Rewards depend on protocol revenue. The rate rises when RewardFeeCollector.distributeRewards() runs. It distributes totalDepositedAlph × rewardRate × elapsed time / 1 year (an annual rate), capped by the ALPH the collector holds from trading fees. The treasury share and the burn share are taken out first, and the rest raises the xALPH rate. If there is little trading volume, there is little yield to share.

Payment

Commission is an off-chain amount owed to you, not an on-chain transfer triggered by the stake. The team pays it in ALPH from the treasury according to your agreement. Because every input (the Staked events and the xALPH rate) is public on-chain, you can recompute your commission independently. Ask the team for the verification page that lists your settlements.

Referral commission vs integrator fees

These are two separate mechanisms:

	Referral commission (this page)	Integrator fees
Applies to	Staking (`stakeAlphWithReferral`)	Swaps (`cpmm.swap`, `clmm.swap`)
Who pays	Powfi, from protocol yield	The user, on top of the swap
Calculated	Off-chain, per settlement period	On-chain, amount set by the integrator
Paid	By the team, according to the agreement	Immediately, in the same transaction
Needs team agreement	Yes	No

SDK & API

Core concepts

Modules

Utilities

Guides

Reference

Referral staking & partner commission

How it works

Stake with a referral

What the contract does with `referral`

Verify attribution

How commission is calculated

Payment

Referral commission vs integrator fees

​How it works

​Stake with a referral

​What the contract does with referral

​Verify attribution

​How commission is calculated

​Payment

​Referral commission vs integrator fees

How it works

Stake with a referral

What the contract does with `referral`

Verify attribution

How commission is calculated

Payment

Referral commission vs integrator fees