> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endaoment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

<img className="block dark:hidden" src="https://mintcdn.com/endaoment/5kHaU3HcCEoL5hsX/images/brand-assets/api-readme-cover.png?fit=max&auto=format&n=5kHaU3HcCEoL5hsX&q=85&s=a871281cb1c39e4518c2eaa514ba00de" width="1635" height="508" data-path="images/brand-assets/api-readme-cover.png" />

<img className="hidden dark:block" src="https://mintcdn.com/endaoment/5kHaU3HcCEoL5hsX/images/brand-assets/api-readme-cover--dark.png?fit=max&auto=format&n=5kHaU3HcCEoL5hsX&q=85&s=cc9af459aa15ee63cda4e8d1f5acb5f0" width="1635" height="508" data-path="images/brand-assets/api-readme-cover--dark.png" />

# Endaoment Smart Contracts

Endaoment's smart contracts enable permissionless, onchain charitable giving through a sophisticated system of Entities and supporting infrastructure. This documentation helps developers integrate directly with Endaoment's contract system.

<Note>
  These contracts are audited, open-source, and deployed across multiple EVM-compatible chains. For API-based integration (recommended for most applications), see our [API Documentation](/developers/getting-started/api-documentation).
</Note>

## When to Use Contracts vs API

**Use Direct Contract Integration for:**

* Fully decentralized applications
* Custom donation flows
* DeFi protocol integrations
* High-volume operations

**Use API for:**

* User authentication and KYC
* Receipt generation
* Email notifications
* Simple integrations

See [API Documentation](/developers/getting-started/api-documentation) for API-based integration.

## Entity Quick Start

New to Endaoment entities? Follow this path:

1. **[Query Entity State](/developers/contracts/entity-state)** - Learn to read entity balances and manager info
2. **[Make a Donation](/developers/contracts/donations)** - Send USDC or other tokens to an entity
3. **[Monitor Activity](/developers/contracts/entity-events)** - Track donations and grants in real-time
4. **[Apply Best Practices](/developers/contracts/entity-best-practices)** - Build robust integrations

<Note>
  **90% of integrations** involve these entity operations: querying state and accepting donations. Start with these guides before exploring entity deployment.
</Note>

## Contract Architecture

### Core Contracts

Endaoment's ecosystem consists of several key contract types:

#### Registry

The central hub of the Endaoment system. The Registry:

* Controls permissions and roles across all contracts
* Tracks approved Entities
* Manages fee structures for donations, transfers, and payouts
* Stores the treasury address for protocol fees

**Key Functions**: Permission management, entity validation, fee configuration

**Contract Addresses**: See [Deployed Contracts](#deployed-contracts) below

#### Entity (Org & Fund)

Entities represent organizations and funds in the Endaoment system:

* **Org**: Represents a 501(c)(3) nonprofit organization
* **Fund**: Represents a Donor-Advised Fund (DAF) or Community Fund

Entities can:

* Receive donations in ETH or ERC-20s
* Query balances and state information

**Key Functions**:

* `donate(uint256 _amount)` - Direct USDC donation
* `reconcileBalance()` - Process USDC sent directly to entity
* `entityType()` - Query entity type (0 = Org, 1 = Fund)
* `swapAndDonate(...)` - Swap and donate any ERC20 or ETH to USDC
* Public state: `balance`, `manager`, `baseToken`, `registry`

#### OrgFundFactory

Deploys new Org and Fund entities using minimal proxy pattern for gas efficiency:

* Creates deterministic addresses across chains
* Supports atomic deploy-and-donate operations

**Key Functions**: `deployOrg()`, `deployFund()`, `deployOrgAndDonate()`, `deployFundAndDonate()`, `computeOrgAddress()`, `computeFundAddress()`

## Entity Operations

Most integrators work primarily with entities (Orgs and Funds). Start here:

<CardGroup cols={2}>
  <Card title="Entity Deployment" href="/developers/contracts/entity-deployment" icon="rocket">
    Deploy new Org or Fund contracts onchain
  </Card>

  <Card title="Donations" href="/developers/contracts/donations" icon="hand-holding-heart">
    Accept USDC donations and batch operations
  </Card>

  <Card title="Entity State & Querying" href="/developers/contracts/entity-state" icon="chart-simple">
    Read balances and entity metadata
  </Card>

  <Card title="Entity Events & Monitoring" href="/developers/contracts/entity-events" icon="bell">
    Track donations and grants in real-time
  </Card>

  <Card title="Best Practices" href="/developers/contracts/entity-best-practices" icon="star">
    Recommended patterns and security considerations
  </Card>
</CardGroup>

## Common Integration Patterns

### Pattern 1: Simple USDC Donation

```typescript theme={null}
import { ethers } from 'ethers';

const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

// Approve and donate 100 USDC
const usdc = new ethers.Contract(USDC_ADDRESS, USDC_ABI, signer);
const org = new ethers.Contract(ORG_ADDRESS, ENTITY_ABI, signer);

await usdc.approve(ORG_ADDRESS, ethers.utils.parseUnits('100', 6));
await org.donate(ethers.utils.parseUnits('100', 6));
```

### Pattern 2: Deploy and Donate

```typescript theme={null}
// Deploy new Org and donate in one transaction
const factory = new ethers.Contract(FACTORY_ADDRESS, FACTORY_ABI, signer);
const orgId = ethers.utils.formatBytes32String('12-3456789');

await factory.deployOrgAndDonate(orgId, ethers.utils.parseUnits('1000', 6));
// Returns Org address via EntityDeployed event
```

## Deployed Contracts

### Ethereum Mainnet

| Contract          | Address                                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Registry          | [`0x94106ca9c7e567109a1d39413052887d1f412183`](https://etherscan.io/address/0x94106ca9c7e567109a1d39413052887d1f412183) |
| OrgFundFactory    | [`0x10fd9348136dcea154f752fe0b6db45fc298a589`](https://etherscan.io/address/0x10fd9348136dcea154f752fe0b6db45fc298a589) |
| Base Token (USDC) | [`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`](https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) |

### Base Mainnet

| Contract          | Address                                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Registry          | [`0x237b53bcfbd3a114b549dfec96a9856808f45c94`](https://basescan.org/address/0x237b53bcfbd3a114b549dfec96a9856808f45c94) |
| OrgFundFactory    | [`0x10fd9348136dcea154f752fe0b6db45fc298a589`](https://basescan.org/address/0x10fd9348136dcea154f752fe0b6db45fc298a589) |
| Base Token (USDC) | [`0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`](https://basescan.org/address/0x833589fcd6edb6e08f4c7c32d4f71b54bda02913) |

### OP Mainnet

| Contract          | Address                                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Registry          | [`0x5d216bb28852f98ceaa29180670397ab01774ea6`](https://optimistic.etherscan.io/address/0x5d216bb28852f98ceaa29180670397ab01774ea6) |
| OrgFundFactory    | [`0x10fd9348136dcea154f752fe0b6db45fc298a589`](https://optimistic.etherscan.io/address/0x10fd9348136dcea154f752fe0b6db45fc298a589) |
| Base Token (USDC) | [`0x0b2c639c533813f4aa9d7837caf62653d097ff85`](https://optimistic.etherscan.io/address/0x0b2c639c533813f4aa9d7837caf62653d097ff85) |

## Key Concepts

**Base Token**: All entities use USDC.

**Managers**: Fund-specific address with permissions to manage the fund (admin-only operations).

### Minimal Proxy Pattern

Entities use [EIP-1167](https://eips.ethereum.org/EIPS/eip-1167) minimal proxies for:

* Low-cost deployment
* Deterministic cross-chain addresses
* Consistent implementation

## Contract ABIs

Available in [contracts repository](https://github.com/endaoment/endaoment-contracts-v2): Entity, Registry, OrgFundFactory

## Security Considerations

### Audits

Contracts audited by [Least Authority](https://leastauthority.com/static/publications/LeastAuthority%5FEndaoment%5FV2%5FSmart%5FContracts%5FFinal%5FAudit%5FReport.pdf).

### Permissions

* **Donations**: Anyone can donate to any entity
* **Querying**: Anyone can read entity state and balances

### Before Transacting

1. Approve tokens: `token.approve(entity, amount)`
2. Verify entity: `registry.isActiveEntity(address)`

## Developer Resources

<CardGroup cols={2}>
  <Card title="Contract Source Code" href="https://github.com/endaoment/endaoment-contracts-v2" icon="github">
    View the full Solidity source code
  </Card>

  <Card title="Technical Documentation" href="https://github.com/endaoment/endaoment-contracts-v2-docs" icon="book">
    Detailed contract documentation
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Discord Community" href="https://discord.gg/endaoment" icon="discord">
    Join our developer community
  </Card>

  <Card title="Contact Engineering" href="mailto:engineering@endaoment.org" icon="envelope">
    Reach out to our team
  </Card>
</CardGroup>

## Next Steps

Start with [Entity Deployment](/developers/contracts/entity-deployment), then explore [Donations](/developers/contracts/donations).