Contract Interfaces

4.2 Contract Interfaces

This section summarizes the externally accessible interface of each core contract.

It does not describe internal logic. It lists callable and readable functions relevant to participants and auditors.

Refer to verified ABI on explorer for full definitions.

---

I. RecyclingEngine

Primary execution contract.

---

Write Functions

recycle(address token) payable

Consumes accounting units and mints weight.

Requirements:

• Asset enabled in Registry

• Sufficient units available

• Non-zero msg.value

Effects:

• Routes native through Router

• Increases accNativePerWeight

• Updates weightOf

• Emits Recycled(...)

---

claim()

Transfers claimable native value to caller.

Effects:

• Calculates pending

• Updates rewardDebt

• Transfers native

• Emits Claimed(user, amountWei)

---

Read Functions

weightOf(address user) → uint256

Returns accounting weight.

---

totalWeight() → uint256

Returns total system weight.

---

claimable(address user) → uint256

Returns current claimable native.

---

accNativePerWeight() → uint256

Returns cumulative per-weight distribution metric.

---

router() → address

Returns Router contract address.

---

owner() → address

Returns current owner.

---

Events

• Recycled(address user, address token, uint256 nativeIn, uint256 weightMinted)

• Claimed(address user, uint256 amountWei)

• ParamsSet(...)

• OwnershipTransferred(...)

---

II. SponsorshipLedger

Manages accounting units.

---

Write Functions

sponsor(address beneficiary, address token, uint256 tokenAmountUnits)

Transfers ERC-20 tokens to BlackHole and credits units.

Requirements:

• Token enabled

• Not self-sponsoring

• Cap not exceeded

Emits:

Sponsored(provider, beneficiary, token, units)

---

consume(address beneficiary, address token, uint256 units)

Restricted to RecyclingEngine.

Reduces unit balance.

---

Read Functions

recyclableBalance(address beneficiary, address token) → uint256

Returns available units.

---

blackHole() → address

Returns burn destination.

---

engine() → address

Returns authorized RecyclingEngine.

---

owner() → address

Returns contract owner.

---

Events

• Sponsored(...)

• Consumed(...)

• OwnershipTransferred(...)

---

III. RecycleAssetRegistry

Controls asset eligibility and parameters.

---

Write Functions (Owner-Controlled)

setAsset(address token, bool enabled, uint256 unitsPer1e18Native, uint256 capUnits)

Configures token eligibility and unit ratio.

Emits:

AssetSet(...)

---

Read Functions

isEnabled(address token) → bool

Returns asset status.

---

unitsPer1e18Native(address token) → uint256

Returns unit conversion ratio.

---

capUnits(address token) → uint256

Returns optional cap.

---

owner() → address

Returns owner.

---

IV. Router

Splits native rails.

---

Read Functions

recycleRailPPM()

opsRailPPM()

providerRailPPM()

Return rail split proportions.

---

recipientOps()

recipientProvider()

Return recipient addresses.

---

Write Functions (Owner-Controlled)

setRails(...)

Adjusts rail percentages.

---

V. Fund (Ethereum)

Treasury contract.

---

Read Functions

shareBalances(address user) → uint256

Returns governance weight.

---

totalShares() → uint256

Returns total share supply.

---

owner() → address

Returns owner (should be Timelock if governed).

---

Write Functions (Governed via Timelock)

Distribution or treasury functions

Exact callable functions depend on deployment.

---

VI. Weighted Governor

---

Write Functions

propose(...)

castVote(...)

queue(...)

execute(...)

---

Read Functions

state(proposalId)

votingPeriod()

quorum()

proposalThreshold()

---

VII. Timelock

---

Read Functions

getMinDelay()

isOperationReady()

isOperationDone()

---

Write Functions

execute(...)

Restricted to queued proposals.

---

VIII. Interface Boundaries

Execution Layer does not expose:

• Arbitrary mint • Arbitrary withdraw • Arbitrary redistribution

Treasury Layer does not expose:

• Ledger modification • Weight override • Burn reversal

Interface surface is minimal and bounded.