> For the complete documentation index, see [llms.txt](https://docs.symm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/account-layer-diamond/affiliate-facet.md).

# Affiliate Facet

The Affiliate Facet manages the lifecycle of affiliates (frontends/brokers) within the Account Layer. It handles registration, admin management, fee distribution configuration, hook contracts, operator permissions, express deposit settings, and delegated calls to Symmio core.

The Account Layer is a separate diamond from the Symmio Core diamond. It provides account management, affiliate infrastructure, and deposit routing on top of the core trading protocol.

***

### Overview

The Affiliate Facet provides:

* **Registration:** Affiliates submit registration requests which are approved by an `APPROVER_ROLE`. Upon approval, an AccountManager contract is deployed and the affiliate is registered on its Symmio cores.
* **Admin Management:** Two-step admin transfer (propose → accept), display name/brand updates, and affiliate pause/unpause.
* **Fee Management:** Two-step fee configuration updates (request → approve). Fees are split between stakeholders and a Symmio protocol share, summing to 100% (1e18 precision). Any stakeholder or `DISTRIBUTOR_ROLE` can trigger fee claims.
* **Hook Management:** Affiliates can set hook contracts per function selector that are called during account lifecycle events (account creation, call execution, deletion).
* **Operator Management:** Affiliates authorize operators to call specific functions via `callAsAffiliate`.
* **Express Deposit Configuration:** Affiliates configure the express deposit rate and virtual provider for split deposits.
* **Delegated Calls:** `callAsAffiliate` allows the affiliate admin or authorized operators to execute whitelisted Symmio core functions on behalf of the affiliate.

***

### Affiliate Registration

#### requestToRegisterAffiliate()

Submits a registration request. The affiliate address is deterministic based on the registrant and name. The affiliate enters `PENDING` state.

```solidity
function requestToRegisterAffiliate(AffiliateRegistration memory reg) external whenNotPaused returns (address affiliateAddress);
```

**Events:** `AffiliateRegistered(address affiliate, string name)`

#### cancelRegistration()

Affiliate admin cancels a pending registration.

```solidity
function cancelRegistration(address affiliate) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `RegistrationCancelled(address affiliate)`

#### rejectRegistration()

Approver rejects a pending registration.

```solidity
function rejectRegistration(address affiliate) external onlyRole(APPROVER_ROLE);
```

**Events:** `RegistrationRejected(address affiliate, address rejector)`

#### approveAffiliate()

Approver approves a pending affiliate. Deploys the AccountManager contract, generates a fee distributor address, registers the affiliate on all configured Symmio cores, and transitions to `ACTIVE` state.

```solidity
function approveAffiliate(address affiliate) external onlyRole(APPROVER_ROLE) whenNotPaused;
```

**Events:** `AffiliateApproved(address affiliate, address feeDistributor)`

***

### Admin Management

#### proposeAdminTransfer()

Proposes transferring the affiliate admin role to a new address (two-step).

```solidity
function proposeAdminTransfer(address affiliate, address newAdmin) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `AdminTransferProposed(address affiliate, address newAdmin)`

#### acceptAdminTransfer()

The proposed new admin accepts the transfer.

```solidity
function acceptAdminTransfer(address affiliate) external whenNotPaused;
```

**Events:** `AdminTransferCompleted(address affiliate, address oldAdmin, address newAdmin)`

#### cancelAdminTransfer()

Cancels a pending admin transfer.

```solidity
function cancelAdminTransfer(address affiliate) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `AdminTransferCancelled(address affiliate)`

#### updateAffiliateDetails()

Updates the display name and brand color.

```solidity
function updateAffiliateDetails(address affiliate, string memory name, string memory brandColor) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `AffiliateUpdated(address affiliate, string name, string brandColor)`

#### pauseAffiliate() / unpauseAffiliate()

Pauses an affiliate (callable by admin or `PAUSER_ROLE`), preventing new account creation. Unpausing requires `UNPAUSER_ROLE`.

```solidity
function pauseAffiliate(address affiliate) external whenNotPaused;
function unpauseAffiliate(address affiliate) external onlyRole(UNPAUSER_ROLE);
```

**Events:** `AffiliatePaused(address affiliate)` / `AffiliateUnpaused(address affiliate)`

***

### Fee Management

Fee shares are configured as stakeholders (each with a receiver address and share) plus a Symmio protocol share. All shares must sum to exactly 1e18 (100%).

#### requestFeeUpdate()

Requests a fee configuration update (two-step). Must be approved by `APPROVER_ROLE`.

```solidity
function requestFeeUpdate(address affiliate, Stakeholder[] memory newStakeholders, uint256 newSymmioShare) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `StakeholdersUpdateRequested(address affiliate)`

#### cancelFeeUpdate()

Cancels a pending fee update.

```solidity
function cancelFeeUpdate(address affiliate) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `FeeUpdateCancelled(address affiliate)`

#### approveFeeUpdate()

Approver applies the pending fee update.

```solidity
function approveFeeUpdate(address affiliate) external onlyRole(APPROVER_ROLE) whenNotPaused;
```

**Events:** `StakeholdersUpdated(address affiliate)`

#### claimAllFees() / claimFees()

Claims accrued fees from a Symmio core and distributes to all stakeholders proportionally. Callable by any stakeholder or `DISTRIBUTOR_ROLE`.

```solidity
function claimAllFees(address affiliate, address symmio) external whenNotPaused nonReentrant;
function claimFees(address affiliate, address symmio, uint256 amount) external whenNotPaused nonReentrant;
```

**Events:** `FeesClaimed(address affiliate, address symmio, uint256 amount)` and `FeesDistributed(address receiver, uint256 amount)` per stakeholder

***

### Hook & Operator Management

#### setHook() / removeHook()

Sets or removes a hook contract for a specific function selector.

```solidity
function setHook(address affiliate, bytes4 selector, address hook) external whenNotPaused onlyAffiliateAdmin(affiliate);
function removeHook(address affiliate, bytes4 selector) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `HookSet(address affiliate, bytes4 selector, address hook)` / `HookRemoved(address affiliate, bytes4 selector)`

#### setOperator()

Grants or revokes operator permission for a function selector.

```solidity
function setOperator(address affiliate, bytes4 selector, address operator, bool status) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `OperatorSet(address affiliate, bytes4 selector, address operator, bool status)`

***

### Express Deposit Configuration

#### setExpressRate()

Sets the fraction of deposits routed to the virtual provider (1e18 precision, e.g., 0.1e18 = 10%).

```solidity
function setExpressRate(address affiliate, uint256 expressRate) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `ExpressRateSet(address affiliate, uint256 expressRate)`

#### setVirtualProvider()

Sets the virtual provider contract for express deposits. Required when `expressRate > 0`.

```solidity
function setVirtualProvider(address affiliate, address virtualProvider) external whenNotPaused onlyAffiliateAdmin(affiliate);
```

**Events:** `VirtualProviderSet(address affiliate, address virtualProvider)`

***

### Delegated Calls

#### callAsAffiliate()

Executes a whitelisted function call on a Symmio core as the affiliate. The caller must be the affiliate admin or an authorized operator for the function selector. The selector must be in `callAllowedSelectors` for the affiliate.

```solidity
function callAsAffiliate(address affiliate, address symmio, bytes calldata callData) external whenNotPaused nonReentrant returns (bytes memory result);
```

**Access:** Affiliate admin or authorized operator. Symmio core must be in the affiliate's registered cores.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/account-layer-diamond/affiliate-facet.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.