# Smart Contracts

Numex uses two smart contracts on Base to handle coin ownership and marketplace settlement.

## Contract Architecture

```mermaid
classDiagram
  class NumexRegistryV3 {
    +MINTER_ROLE
    +OPERATOR_ROLE
    +computeIntegrityProof(fingerprint, salt)
    +tokenIdForProof(proof)
    +mintVaultAsset(to, proof, tokenUri)
    +updateCustodyStatus(tokenId, status)
    +operatorForceTransfer(from, to, tokenId)
    +operatorBurn(tokenId)
    +setCuratorResidualBps(bps)
    +originalCuratorOf(tokenId)
    +royaltyInfo(tokenId, salePrice)
    +setForceTransferEnabled(enabled)
  }

  class NumexMarketplaceSettlement {
    +DISTRIBUTOR_ROLE
    +OPERATOR_ROLE
    +settle(tokenId, seller, buyer, priceUsdc, curator, residualBps, platformBps, saleRef)
    +claim()
    +pendingResiduals(curator)
    +setPlatformAddress(addr)
    +setRegistry(addr)
  }

  NumexMarketplaceSettlement --> NumexRegistryV3 : transfers tokens
```

## NumexRegistryV3

ERC-721 token registry for vaulted physical coins on Base.

* **Freely transferable** — holders can send coins to any address
* **Integrity proofs** — each coin has a unique on-chain fingerprint that prevents duplicate minting
* **Custody lifecycle** — tracks each coin through Vaulted, Redemption Pending, Redeemed, and Burned states
* **Curator provenance** — records the original submitter of each coin for residual payments
* **EIP-2981 royalties** — signals curator residual percentage to compatible marketplaces
* **Operator controls** — force-transfer (admin-flagged only) and burn (for physical redemption)
* **Pausable** — admin can pause all transfers in an emergency

## NumexMarketplaceSettlement

Atomic on-chain settlement for marketplace trades, paid in USDC.

* **Settle** — transfers the coin from seller to buyer and splits USDC in one transaction:
  * Seller receives the sale price minus fees
  * Curator (original submitter) accrues a residual percentage
  * Platform receives a fee percentage
* **Curator claim** — curators withdraw their accumulated residuals at any time
* **Idempotent** — each trade has a unique reference; the same trade cannot settle twice
* **Role-gated** — only authorized distributors can call settle; unauthorized calls revert
* **Pausable** — admin can pause settlement and claims in an emergency

## Deployed Contracts

### Base Mainnet

| Contract                   | Address                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| NumexRegistryV3            | [`0xb2110D936573ADE7122333b316863Ca4e5780f64`](https://basescan.org/address/0xb2110D936573ADE7122333b316863Ca4e5780f64) |
| NumexMarketplaceSettlement | [`0x8266a80633a4B7f02B19d438cAE37D1E4075216A`](https://basescan.org/address/0x8266a80633a4B7f02B19d438cAE37D1E4075216A) |

### Base Sepolia (Testnet)

| Contract                   | Address                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| NumexRegistryV3            | [`0x1bFF7e20d4248C7A6dA8d02A5aeF5b45DdBBA5CD`](https://sepolia.basescan.org/address/0x1bFF7e20d4248C7A6dA8d02A5aeF5b45DdBBA5CD) |
| NumexMarketplaceSettlement | [`0xb2110D936573ADE7122333b316863Ca4e5780f64`](https://sepolia.basescan.org/address/0xb2110D936573ADE7122333b316863Ca4e5780f64) |


---

# Agent Instructions: 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:

```
GET https://numex-greenfield.gitbook.io/numex-docs/technology/smart-contracts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.