diff --git a/README.md b/README.md index c36d8b3..a016960 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,40 @@ +
+ # PlotLink Contracts -On-chain storytelling protocol on Base. Writers create storylines backed by bonding curve tokens — every trade generates creator royalties, directly incentivizing authors to keep writing. +### On-chain storytelling protocol on Base. + +

+ live + Base + Foundry + AGPL-3.0 +

+ +

+ Web App · + AI Writer · + Contracts +

+ +
+ +--- -## How It Works +## Overview + +Writers create storylines backed by bonding curve tokens — every mint generates creator royalties, directly incentivizing authors to keep writing. **StoryFactory** manages storylines and plots: -- `createStoryline()` — deploys a new MCV2 bonding curve token and stores the opening plot -- `chainPlot()` — appends subsequent plots (chapters) to an existing storyline +- `createStoryline()` — deploys a new MCV2 bonding curve token and stores the opening plot on IPFS +- `chainPlot()` — appends subsequent chapters to an existing storyline - `donate()` — direct tips from readers to writers -Each storyline token trades on a Mint Club V2 bonding curve with 1% creator royalties on mint and 1% on burn. +Each storyline token trades on a **Mint Club V2 bonding curve** with 1% creator royalties on mint and 1% on burn (set in the contract as `MINT_ROYALTY = 100` and `BURN_ROYALTY = 100` basis points). + +## Zap: One-Click Minting -**ZapPlotLinkV2** enables one-click purchases with any supported token: +**ZapPlotLinkV2** enables minting story tokens with any supported token in a single transaction: | Input | Route | Uniswap needed? | |-------|-------|-----------------| @@ -20,44 +43,62 @@ Each storyline token trades on a Mint Club V2 bonding curve with 1% creator roya | HUNT | MCV2 bonding curve (HUNT→PLOT, HUNT is PLOT's reserve) → MCV2_Bond | No | | PLOT | Direct MCV2_Bond.mint | No | -## Deployed Contracts (Base Mainnet) +## Deployed Contracts + +### PlotLink (Base Mainnet) | Contract | Address | |----------|---------| -| StoryFactory (v4b, symbol-collision fix) | [`0x9D2AE1E99D0A6300bfcCF41A82260374e38744Cf`](https://basescan.org/address/0x9D2AE1E99D0A6300bfcCF41A82260374e38744Cf) | -| StoryFactory (v1, deprecated) | [`0x337c5b96f03fB335b433291695A4171fd5dED8B0`](https://basescan.org/address/0x337c5b96f03fB335b433291695A4171fd5dED8B0) | +| StoryFactory (v4b) | [`0x9D2AE1E99D0A6300bfcCF41A82260374e38744Cf`](https://basescan.org/address/0x9D2AE1E99D0A6300bfcCF41A82260374e38744Cf) | | ZapPlotLinkV2 | [`0xAe50C9444DA2Ac80B209dC8B416d1B4A7D3939B0`](https://basescan.org/address/0xAe50C9444DA2Ac80B209dC8B416d1B4A7D3939B0) | -## External Dependencies +### External Dependencies (Base Mainnet) | Contract | Address | Role | |----------|---------|------| -| MCV2_Bond | `0xc5a076cad94176c2996B32d8466Be1cE757FAa27` | Bonding curve trading, token creation | -| MCV2_BondPeriphery | `0x492C412369Db76C9cdD9939e6C521579301473a3` | Reverse calculations for mint | -| PLOT | `0x4F567DACBF9D15A6acBe4A47FC2Ade0719Fb63C4` | Protocol token (MCV2, backed by HUNT) | -| HUNT | `0x37f0c2915CeCC7e977183B8543Fc0864d03E064C` | Reserve token for PLOT | -| Uniswap V4 Universal Router | `0x6fF5693b99212Da76ad316178A184AB56D299b43` | Swap execution | -| Uniswap V4 Quoter | `0x0d5e0F971ED27FBfF6c2837bf31316121532048D` | Price estimation | -## Build +| MCV2_Bond | [`0xc5a076cad94176c2996B32d8466Be1cE757FAa27`](https://basescan.org/address/0xc5a076cad94176c2996B32d8466Be1cE757FAa27) | Bonding curve, token creation | +| PLOT | [`0x4F567DACBF9D15A6acBe4A47FC2Ade0719Fb63C4`](https://basescan.org/address/0x4F567DACBF9D15A6acBe4A47FC2Ade0719Fb63C4) | Protocol token (backed by HUNT) | +| HUNT | [`0x37f0c2915CeCC7e977183B8543Fc0864d03E064C`](https://basescan.org/address/0x37f0c2915CeCC7e977183B8543Fc0864d03E064C) | Reserve token for PLOT | +| ERC-8004 Registry | [`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`](https://basescan.org/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432) | AI agent identity | +| Uniswap V4 Universal Router | [`0x6fF5693b99212Da76ad316178A184AB56D299b43`](https://basescan.org/address/0x6fF5693b99212Da76ad316178A184AB56D299b43) | Swap execution | + +## Project Structure -```bash -forge build ``` +src/ +├── StoryFactory.sol Storyline + plot management, royalty config +├── ZapPlotLinkV2.sol Multi-token zap (ETH/USDC/HUNT/PLOT → story token) +└── interfaces/ + ├── IMCV2_Bond.sol Mint Club V2 bonding curve interface + ├── IZapInterfaces.sol Uniswap V4 + MCV2 interfaces for Zap + └── IERC20.sol ERC-20 interface -## Test +script/ +├── DeployBase.s.sol Deploy StoryFactory to Base mainnet +├── DeployZapPlotLinkV2.s.sol Deploy ZapPlotLinkV2 to Base mainnet +├── CreatePlotEthPool.s.sol Create PLOT/ETH Uniswap V4 pool +├── E2ETest.s.sol End-to-end StoryFactory lifecycle test +└── E2EZapTest.s.sol End-to-end Zap trading test +``` + +## Development ```bash -# Unit tests -forge test +forge build # Compile contracts +forge test # Run unit tests +``` -# E2E on Base mainnet (requires DEPLOYER_PRIVATE_KEY in .env) +### E2E Tests (requires Base mainnet RPC + deployer key) + +```bash +# StoryFactory lifecycle forge script script/E2ETest.s.sol --rpc-url https://mainnet.base.org --broadcast -# E2E Zap trades on Base mainnet +# Zap trading forge script script/E2EZapTest.s.sol --rpc-url https://mainnet.base.org --broadcast --slow ``` -## Deploy +### Deploy ```bash # StoryFactory @@ -65,32 +106,15 @@ forge script script/DeployBase.s.sol --rpc-url https://mainnet.base.org --broadc # ZapPlotLinkV2 forge script script/DeployZapPlotLinkV2.s.sol --rpc-url https://mainnet.base.org --broadcast --verify --verifier sourcify - -# Create PLOT/ETH Uniswap V4 pool -forge script script/CreatePlotEthPool.s.sol --rpc-url https://mainnet.base.org --broadcast ``` -## Project Structure - -``` -src/ -├── StoryFactory.sol Storyline + plot management -├── ZapPlotLinkV2.sol Multi-token zap (ETH/USDC/HUNT/PLOT → storyline token) -├── ZapPlotLink.sol V1 zap (deprecated) -└── interfaces/ - ├── IMCV2_Bond.sol Mint Club V2 interface - ├── IZapInterfaces.sol Uniswap V4 + MCV2 interfaces for Zap - └── IERC20.sol ERC-20 interface +## Related Repositories -script/ -├── DeployBase.s.sol Deploy StoryFactory to Base mainnet -├── DeployZapPlotLinkV2.s.sol Deploy ZapPlotLinkV2 to Base mainnet -├── CreatePlotEthPool.s.sol Create PLOT/ETH Uniswap V4 pool -├── E2ETest.s.sol End-to-end StoryFactory lifecycle -├── E2EZapTest.s.sol End-to-end Zap trading tests -└── ... Testnet deploy, gas measurement, curve utilities -``` +| Repo | Description | +|------|-------------| +| [plotlink](https://github.com/realproject7/plotlink) | Web app — frontend, indexer, airdrop | +| [plotlink-ows](https://github.com/realproject7/plotlink-ows) | AI Writer — local CLI for story writing | ## License -MIT +[AGPL-3.0](LICENSE)