API Reference

This section details the public API of the core CommissionRoad contracts.

---

CommissionRoad

The main entry point for the protocol.

Public Variables

Variable	Type	Description
ETH_ADDRESS	address	Sentinel address used to represent native ETH (0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE).
mintFee	uint256	The fee (in wei) required to mint a new CommissionRoad NFT.
commissionRoadNFT	CommissionRoadERC721	Reference to the ERC721 contract that manages CommissionRoad NFTs.
commissionVault	ICommissionVault	Reference to the vault contract that stores and manages commission funds.
isCallTargetAllowlisted	mapping(uint256 => mapping(address => bool))	Per-NFT mapping of call targets that are allowed when the allowlist is enabled.
isAllowlistEnabled	mapping(uint256 => bool)	Per-NFT flag indicating whether the allowlist is active.

---

Events

Event	Parameters	Description
CommissionCall	uint256 indexed nftId, address indexed user, address commissionToken, uint256 commission	Emitted when a commission call is made.
AllowlistUpdated	uint256 indexed nftId, address indexed target, bool allowed	Emitted when a allowlist entry is added or removed.
AllowlistEnabledUpdated	uint256 indexed nftId, bool enabled	Emitted when the allowlist is enabled or disabled.

---

Errors

Error	Parameters	Description
CommissionCallFailed	uint256 index, uint256 msgValue	Thrown when a call in the batch fails.
InvalidNftId	—	Thrown when a referenced NFT ID does not exist.
IncorrectMintFeeAmount	—	Thrown when the mint fee sent does not match mintFee.
CallTargetNotAllowlisted	uint256 nftId, address target	Thrown when a call target is not allowlisted and the allowlist is enabled.
NotNftOwner	uint256 nftId	Thrown when the caller is not the owner of the specified NFT.

---

mint / mintTo

Mints a new CommissionRoad NFT ID. The caller must pay the mintFee (in ETH).

// Mint to msg.sender
function mint() external payable returns (uint256 nftId);

// Mint to a specific address
function mintTo(address to) external payable returns (uint256 nftId);

// Mint to msg.sender with metadata
function mint(CommissionRoadERC721.Metadata memory metadata) external payable returns (uint256 nftId);

// Mint to a specific address with metadata
function mintTo(address to, CommissionRoadERC721.Metadata memory metadata) external payable returns (uint256 nftId);

Parameters

Parameter	Type	Description
to	address	The address that will receive ownership of the minted NFT. If omitted (using mint()), defaults to msg.sender.
metadata	Metadata	Optional on-chain metadata to associate with the NFT. See Metadata Struct for details.

Returns

Type	Description
uint256	The newly minted NFT ID.

Emitted Events

• Standard ERC721 Transfer event (from CommissionRoadERC721)

---

commissionCall

Executes a batch of calls to target contracts and collects a commission.

struct BatchCallData {
    address target;
    bytes callData;
    uint256 value;
}

function commissionCall(
    BatchCallData[] calldata batchCallData,
    uint256 nftId,
    address commissionToken,
    uint256 commission
) external payable;

Parameters

Parameter	Type	Description
batchCallData	BatchCallData[]	Array of calls to execute sequentially. See BatchCallData Struct below.
nftId	uint256	The ID of the CommissionRoad NFT that will receive the commission. Must be a valid, minted NFT ID.
commissionToken	address	The address of the token to take the commission in. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH.
commission	uint256	The total commission amount to collect. The protocol fee is automatically deducted, with the remainder going to the NFT owner.

BatchCallData Struct

Member	Type	Description
target	address	The contract address to call. Cannot be the CommissionRoad.commissionCall method itself (reentrancy protected).
callData	bytes	The encoded function call data (use abi.encodeWithSelector or similar).
value	uint256	The ETH value (in wei) to send with this specific call.

Reentrancy Protection

You cannot call back into CommissionRoad from a target contract during a commissionCall.

msg.value Requirements

When sending ETH, any excess ETH is refunded to msg.sender. Ensure your value calculation is precise to avoid reverts, or send slightly more to rely on the refund.

Suggested Reading

• Standard Calls

Emitted Events

• CommissionCall

---

commissionPlan

Executes a Weiroll script (commands and state) and collects a commission. Used for dependent transaction flows.

function commissionPlan(
    bytes32[] calldata commands,
    bytes[] calldata state,
    uint256 nftId,
    address commissionToken,
    uint256 commission
) external payable;

Parameters

Parameter	Type	Description
commands	bytes32[]	Array of Weiroll command bytes. Each command encodes a function call with flags specifying how inputs/outputs should be handled. See Weiroll documentation for encoding details.
state	bytes[]	Array of state slots used by the Weiroll VM. These slots store intermediate values that can be passed between commands, enabling dependent transaction flows.
nftId	uint256	The ID of the CommissionRoad NFT that will receive the commission. Must be a valid, minted NFT ID.
commissionToken	address	The address of the token to take the commission in. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH.
commission	uint256	The total commission amount to collect. The protocol fee is automatically deducted, with the remainder going to the NFT owner.

Reentrancy Protection

You cannot call back into CommissionRoad.commissionPlan from a target contract during a commissionPlan.

Suggested Reading

• Weiroll Integration

Emitted Events

• CommissionCall

---

setAllowlist

Adds or removes an address from the allowlist for a given NFT. The allowlist must also be enabled for it to take effect.

function setAllowlist(
    uint256 nftId,
    address target,
    bool allowed
) external;

Parameters

Parameter	Type	Description
nftId	uint256	The NFT ID to configure. Caller must be the owner.
target	address	The contract address to add or remove.
allowed	bool	true to allowlist the target, false to remove it.

Emitted Events

• AllowlistUpdated

Suggested Reading

• Allowlist

---

setAllowlistEnabled

Enables or disables the allowlist for a given NFT. When enabled, only allowlisted targets can be called via commissionCall and commissionPlan.

function setAllowlistEnabled(
    uint256 nftId,
    bool enabled
) external;

Parameters

Parameter	Type	Description
nftId	uint256	The NFT ID to configure. Caller must be the owner.
enabled	bool	true to enable the allowlist, false to disable it.

Emitted Events

• AllowlistEnabledUpdated

Suggested Reading

• Allowlist

---

CommissionVault

Handles storing and claiming commissions.

Public Variables

Variable	Type	Description
ETH_ADDRESS	address	Sentinel address used to represent native ETH (0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE).
protocolFeePercent	uint256	The percentage (in 18-decimal fixed point) of each commission that goes to the protocol.
pendingCommissions	mapping(uint256 => mapping(address => uint256))	Nested mapping of NFT ID → token address → pending commission amount available to claim.
commissionRoadNFT	CommissionRoadERC721	Reference to the ERC721 contract used for ownership verification.

---

Events

Event	Parameters	Description
CommissionClaimed	uint256 indexed nftId, address indexed owner, address[] tokens, uint256[] amounts	Emitted when commissions are claimed.
ProtocolFeeCollected	address token, uint256 amount	Emitted when a protocol fee is deducted from a deposit.

---

claim / claimTo

Claims collected commissions for a specific NFT ID. Only the owner of the NFT can call this.

struct ClaimData {
    address token;
    uint256 amount;
}

// Claim to msg.sender
function claim(
    uint256 nftId,
    ClaimData[] calldata claimData
) external;

// Claim to a specific address
function claimTo(
    uint256 nftId,
    ClaimData[] calldata claimData,
    address destination
) public;

Parameters

Parameter	Type	Description
nftId	uint256	The NFT ID to claim commissions for. Caller must be the owner of this NFT.
claimData	ClaimData[]	Array of claim data specifying tokens and amounts to claim. See ClaimData Struct below.
destination	address	(claimTo only) The address to send the claimed funds to. Allows claiming to a different wallet than the NFT owner.

ClaimData Struct

Member	Type	Description
token	address	The token address to claim. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH.
amount	uint256	The amount of commissions to claim for this token. If the amount exceeds the available balance, only the available amount is claimed.

Emitted Events

• CommissionClaimed

---

depositCommission

Deposits a commission into the vault. Normally called internally by CommissionRoad, but can be called directly by any contract or user.

function depositCommission(
    uint256 nftId,
    address token,
    uint256 amount
) external payable;

Parameters

Parameter	Type	Description
nftId	uint256	The NFT ID to deposit commissions for. The owner of this NFT will be able to claim these funds.
token	address	The address of the token being deposited. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for ETH.
amount	uint256	The amount of tokens to deposit. For ETH, must equal msg.value.

NOTE

A protocol fee (based on protocolFeePercent) is automatically deducted from the deposit.

Emitted Events

• ProtocolFeeCollected (if protocol fee is deducted)

---

CommissionRoadERC721

The NFT contract representing CommissionRoad IDs.

Public Variables

Variable	Type	Description
PROTOCOL_NFT_ID	uint256	Constant value 0. The NFT ID that represents protocol ownership. The owner of this NFT is the protocol admin.
nextAvailableNftId	uint256	The next NFT ID that will be minted. Also represents the total number of NFTs minted.
tokenURIContract	TokenURI	Reference to the contract that generates token URI metadata.
authorized	mapping(address => bool)	Mapping of addresses authorized to mint NFTs (e.g., the CommissionRoad contract).

---

transferFrom

Transfers ownership of an NFT from one address to another.

function transferFrom(
    address from,
    address to,
    uint256 id
) public;

Parameters

Parameter	Type	Description
from	address	The current owner of the NFT. Must match the actual owner or the caller must be approved.
to	address	The address to transfer ownership to. Cannot be the zero address.
id	uint256	The NFT ID to transfer. Must be a valid, minted NFT.

safeTransferFrom Not Supported

This contract explicitly reverts on safeTransferFrom to prevent reentrancy and complex callback exploits. Use transferFrom instead.

---

tokenURI

Returns the metadata URI for a given token ID. The URI is a Base64 encoded JSON string.

function tokenURI(uint256 nftId) public view returns (string memory);

Parameters

Parameter	Type	Description
nftId	uint256	The ID of the NFT to get the token URI for. Must be a valid, minted NFT.

Returns

Type	Description
string	A Base64-encoded data URI containing JSON metadata.

Example JSON Output

{
  "name": "CommissionRoadId 0",
  "description": "CommissionRoad is a NFT-based monetization protocol. This NFT holds the rights to claim commissions. Note: Commissions are automatically claimed on NFT transfer",
  "image_data": "data:image/svg+xml;base64,...",
  "attributes": [
    {
      "trait_type": "CommissionRoad Id",
      "value": "0"
    },
    {
      "trait_type": "Owner",
      "value": "0x..."
    }
  ]
}

---

setMetadata

Updates the metadata for an NFT. Only the owner can call this.

function setMetadata(uint256 nftId, Metadata memory metadata) public;

Parameters

Parameter	Type	Description
nftId	uint256	The ID of the NFT to update metadata for. Caller must be the owner.
metadata	Metadata	The new metadata struct to set. See Metadata Struct below.

Metadata Struct

Member	Type	Description
name	string	A custom display name for the NFT (e.g., "My Brand ID").
description	string	A description of the NFT or its purpose.
imageUrl	string	URL to a custom image for the NFT.
ens	string	Associated ENS name (e.g., "myname.eth").
website	string	Website URL associated with this NFT.
socials	Socials	Social media links. See Socials Struct below.

Socials Struct

Member	Type	Description
telegram	string	Telegram username or link.
discord	string	Discord username or invite link.
instagram	string	Instagram handle or profile URL.
snapchat	string	Snapchat username.
tiktok	string	TikTok username or profile URL.
x	string	X (Twitter) handle or profile URL.
email	string	Contact email address.
github	string	GitHub username or profile URL.
youtube	string	YouTube channel URL.
linkedin	string	LinkedIn profile URL.
reddit	string	Reddit username or profile URL.

---

getMetadata

Returns the full on-chain metadata for a given NFT ID.

function getMetadata(uint256 nftId) public view returns (Metadata memory);

Parameters

Parameter	Type	Description
nftId	uint256	The ID of the NFT to retrieve metadata for.

Returns

Type	Description
Metadata	The complete metadata struct for the NFT. See Metadata Struct for member details.