[Pre-Mainnet] Contract integration audit checklist

[realproject7]

Context

PlotLink is preparing to deploy on Base mainnet. Before switching from Base Sepolia, we need a thorough review of all contract integration code — ABIs, constants, indexers, trading widgets, SDK, and CLI.

There are no Solidity source files in this repo. The three contracts are already deployed externally:

Contract	Role	Sepolia Address	Mainnet Address
StoryFactory	Storyline creation, plot chaining, donations	0xfa5489b6710Ba2f8406b37fA8f8c3018e51FA229	TBD (0x000...000)
MCV2_Bond (Mint Club V2)	Bonding curve trading, token creation, royalties	0x5dfA75b0185efBaEF286E80B847ce84ff8a62C2d	0xc5a076cad94176c2996B32d8466Be1cE757FAa27
ERC-8004 Registry	AI agent identity NFTs	0x8004A169FB4a3325136EB29fA0ceB6D2e539a432	Same address (?)

The integration layer is spread across:

• Web app ABIs: lib/contracts/abi.ts, lib/contracts/erc8004.ts, lib/price.ts (extended MCV2 ABI)
• SDK ABIs (separate copy): packages/sdk/src/abi.ts
• Constants: lib/contracts/constants.ts (web), packages/sdk/src/constants.ts (SDK)
• Indexer routes: src/app/api/index/{storyline,plot,donation}/route.ts
• Backfill cron: src/app/api/cron/backfill/route.ts
• Frontend write flows: src/hooks/usePublish.ts, src/hooks/useChainPlot.ts
• Trading/Donate widgets: src/components/TradingWidget.tsx, src/components/DonateWidget.tsx
• SDK client: packages/sdk/src/client.ts
• CLI commands: packages/cli/src/commands/{create,chain,claim,status,agent-register}.ts
• IPFS upload: packages/sdk/src/ipfs.ts
• Price/TVL reads: lib/price.ts
• Content hashing: lib/content.ts
• Reconciliation: lib/reconcile.ts
• RPC client: lib/rpc.ts

---

Audit Checklist

Review each item. Post your findings as comments with the checklist item number and PASS/FAIL/CONCERN.

---

A. ABI Consistency and Correctness

• A1. ABI duplication drift risk — ABIs are maintained in TWO separate copies: lib/contracts/abi.ts (web app) and packages/sdk/src/abi.ts (SDK). Additionally, lib/price.ts defines its own extended mcv2BondAbi with extra functions (mint, burn, getReserveForToken, etc.). Verify all three are consistent where they overlap. Flag any divergence.

• A2. getRoyaltyInfo ABI mismatch — The web app (lib/price.ts:62-72) defines getRoyaltyInfo with inputs: [wallet, reserveToken] and outputs: [balance, claimed] (two outputs). The SDK (packages/sdk/src/abi.ts:131-142) defines it with inputs: [token, beneficiary] and outputs: [unclaimed] (one output). These are structurally different. Verify which matches the actual MCV2_Bond contract and fix the wrong one. The SDK client (packages/sdk/src/client.ts:503-510) casts the result as a single bigint — is this correct?

• A3. claimRoyalties ABI mismatch — Web app (lib/price.ts:76-79) has inputs: [{ name: "reserveToken" }]. SDK (packages/sdk/src/abi.ts:143-148) has inputs: [{ name: "token" }]. The parameter name differs — more importantly, the SDK client calls claimRoyalties(tokenAddress) passing the storyline token address, but the web ABI suggests it takes the reserve token. Verify against the actual Mint Club V2 contract which address it expects.

• A4. Event signatures match deployed contract — Verify that all event ABIs (StorylineCreated, PlotChained, Donation, Registered) match the actual deployed contract events exactly (parameter names, types, indexed flags). A mismatch would cause event decoding to silently fail.

• A5. Function signatures match deployed contract — Verify createStoryline, chainPlot, donate, priceForNextMint, tokenBond, register, setAgentWallet, mint, burn, getReserveForToken, getRefundForTokens all match the deployed contracts.

---

B. Hardcoded Values and Magic Numbers

• B1. IPFS gateway URL duplicated — "https://ipfs.filebase.io/ipfs/" is hardcoded in 3 files: src/app/api/index/storyline/route.ts:15, src/app/api/index/plot/route.ts:14, src/app/api/cron/backfill/route.ts:13. Should be a shared constant or env var.

• B2. IPFS timeout duplicated — IPFS_TIMEOUT_MS = 10_000 is independently defined in 3 files (same files as B1). Should be shared.

• B3. Gas limits hardcoded in multiple places — gas: BigInt(500_000) in useChainPlot.ts:37, gas: BigInt(2_000_000) in TradingWidget.tsx:111-112,146-147, gas: BigInt(150_000) in DonateWidget.tsx:87. Are these appropriate for mainnet? Gas costs differ between testnet and mainnet. Consider whether these need tuning or should be configurable.

• B4. Slippage tolerance hardcoded — SLIPPAGE_BPS = 300 (3%) in TradingWidget.tsx:14. Should this be user-configurable or at least a shared constant? 3% may be too tight for low-liquidity early tokens or too loose for established ones.

• B5. Block time assumption — BLOCKS_PER_24H = BigInt(43200) in lib/price.ts:168 assumes exactly 2-second block times on Base. Base block times can vary. If used for price change calculations, slight inaccuracy is acceptable — but document the assumption.

• B6. Backfill scan range — SCAN_BLOCKS = BigInt(200) in backfill cron. At 2s/block this covers ~6.6 minutes per 5-minute cron run. Verify this keeps up with block production and doesn't fall behind.

• B7. DEPLOYMENT_BLOCK is testnet-specific — packages/sdk/src/constants.ts:23: DEPLOYMENT_BLOCK = BigInt(20_000_000) is a Base Sepolia block number. This is used as fromBlock for event log queries. On mainnet, this would need to be the actual deployment block. Currently the SDK has no mainnet deployment block.

• B8. Indexer sleep — await new Promise((r) => setTimeout(r, 5000)) in usePublish.ts:115 and DonateWidget.tsx:95. A fixed 5-second delay before calling the indexer. Is this sufficient on mainnet? Too long? Should it be adaptive or use polling instead?

• B9. EIP-712 signature deadline — packages/sdk/src/client.ts:445: deadline is Date.now()/1000 + 3600 (1 hour). Is this appropriate? Too short for slow signers, too long for security?

• B10. Token decimals hardcoded to 18 — parseUnits(amount, 18) and formatUnits(*, 18) used throughout TradingWidget.tsx, DonateWidget.tsx, lib/price.ts. This assumes both the reserve token and storyline tokens are 18 decimals. If the mainnet reserve token ($PLOT) has different decimals, everything breaks. getTokenTVL() in lib/price.ts:245-249 correctly reads decimals on-chain — but the trading/donate widgets don't.

• B11. Filebase endpoint hardcoded — packages/sdk/src/ipfs.ts:21: endpoint: "https://s3.filebase.com" and region: "us-east-1". These are fine if Filebase is the permanent IPFS provider, but should be noted.

• B12. Retry constants scattered — maxRetries = 3 in IPFS upload, maxAttempts = 5 in receipt retry, attempt * 2000 backoff in receipt retry, Math.pow(2, attempt-1) * 1000 in IPFS retry. Different retry strategies in different places.

---

C. Mainnet Readiness and Zero Addresses

• C1. StoryFactory mainnet address is 0x000...000 — lib/contracts/constants.ts:31: mainnet fallback is the zero address. This MUST be updated before mainnet deployment. The backfill cron correctly skips when the address is zero (line 64), but the trading widgets and indexers would call the zero address.

• C2. PLOT_TOKEN mainnet address is 0x000...000 — lib/contracts/constants.ts:41: mainnet $PLOT token is zero address. Every trade and donation on mainnet would try to transfer from/approve the zero address.

• C3. ZAP_PLOTLINK permanently zero — lib/contracts/constants.ts:34: always 0x000...000. If this contract isn't part of the initial mainnet launch, remove references. If it is planned, flag it.

• C4. ERC-8004 Registry address is chain-agnostic — lib/contracts/constants.ts:78 and packages/sdk/src/constants.ts:42: same address 0x8004A1...9A432 for both testnet and mainnet. Verify this is a cross-chain deployment at the same address, or if the mainnet address is different.

• C5. SDK defaults are testnet-only — packages/sdk/src/constants.ts only has Sepolia addresses as defaults. SDK users targeting mainnet must override every address via PlotLinkConfig. Is this documented?

• C6. Chain ID env var default — lib/contracts/constants.ts:14 and lib/rpc.ts:4 both default to 84532 (Sepolia). On mainnet deploy, NEXT_PUBLIC_CHAIN_ID=8453 must be set. Verify there's no path where the default leaks through.

---

D. Security and Access Control

• D1. Indexer routes have no authentication — POST /api/index/storyline, /api/index/plot, /api/index/donation are open to anyone. An attacker could submit arbitrary txHash values. The routes do verify on-chain receipt + content hash, so they can't inject fake data — but they can trigger RPC calls, IPFS fetches, and DB writes. Consider rate limiting or requiring an API key.

• D2. Backfill cron auth is optional — src/app/api/cron/backfill/route.ts:24: if (!secret) return true — when CRON_SECRET is not set, anyone can trigger the backfill. Fine for dev, dangerous for production.

• D3. IPFS content used directly — Indexers fetch arbitrary CIDs from IPFS and store content in Supabase. If the IPFS content is very large (the gateway fetch has a 10s timeout but no size limit), it could cause memory issues or DB bloat. Consider adding a content size limit.

• D4. Content hash verification is sound — Verify that hashContent() (keccak256(toHex(content))) matches the Solidity-side hash computation exactly. The comment says it matches keccak256(abi.encodePacked(content)) — confirm this is true for UTF-8 strings. This is the primary integrity check.

• D5. No double-index protection beyond upsert — Indexer idempotency relies on onConflict: "tx_hash,log_index". Verify this unique constraint exists in the Supabase schema for all three tables (storylines, plots, donations).

• D6. Reconciliation race condition — reconcileStorylinePlotCount() reads plot count then updates storyline. If two plots for the same storyline are indexed concurrently, the count could be stale. The function uses COUNT(*) which should be consistent, but verify there's no TOCTOU issue with Supabase.

---

E. Logic and Correctness

• E1. SDK getRoyaltyInfo may return wrong data — packages/sdk/src/client.ts:503-510 calls getRoyaltyInfo(tokenAddress, beneficiary) but the SDK ABI (packages/sdk/src/abi.ts:134-140) takes (token, beneficiary). The web ABI (lib/price.ts:62-72) takes (wallet, reserveToken). If the actual contract signature is getRoyaltyInfo(address wallet, address reserveToken), then the SDK is passing arguments in the wrong order.

• E2. SDK claimRoyalties argument — packages/sdk/src/client.ts:521-533 calls claimRoyalties(tokenAddress) where tokenAddress is the storyline token. But the web ABI names the parameter reserveToken. If the contract expects the reserve token address (not the storyline token), claims will fail or claim the wrong royalties.

• E3. Backfill skips plot title — processPlotChained() in backfill/route.ts:261 destructures title from args but doesn't include it in the PlotInsert row. The direct indexer index/plot/route.ts:118 does include title: title || "". Inconsistency — backfilled plots will have no title.

• E4. BigInt to Number precision — Multiple places convert bigint to Number(): Number(storylineId), Number(plotIndex), Number(toBlock) for Supabase rows and backfill cursor. JavaScript Number is safe up to 2^53 - 1. Storyline IDs and plot indices should be fine, but block numbers on mature chains could eventually overflow (though Base is far from this).

• E5. approve() exact amount vs max — Trading and donate widgets approve the exact amount needed per transaction. This is safer but means every trade requires a separate approval tx (2 wallet popups). On mainnet with real gas costs, this UX friction is significant. Consider MAX_UINT256 approval or Permit2 integration (Permit2 address is already in constants).

• E6. Backfill silently skips failed IPFS content — In backfill/route.ts:265-266, if IPFS content can't be fetched or hash doesn't match, the plot is silently skipped with no retry mechanism. These plots will never be backfilled unless the cron is replayed from an earlier cursor.

• E7. Backfill advances cursor even on partial failure — backfill/route.ts:165: cursor advances to toBlock even if some events within the range failed to process. Those failed events are permanently skipped. Consider only advancing to the last successfully processed block.

• E8. Genesis plot count race — index/storyline/route.ts:139: storyline is created with plot_count: 1 (counting genesis). But if the genesis plot insert (step 9) fails while the storyline insert (step 8) succeeds, plot_count would be 1 but no genesis plot exists in the plots table. The reconciler would later correct it to 0. Minor data inconsistency window.

---

F. Over-Engineering and Duplication

• F1. lib/viem.ts is a useless re-export — lib/viem.ts contains only export { publicClient } from "./rpc" with a backward compat comment. The backfill route imports from lib/viem, everything else from lib/rpc. Pick one and delete the other.

• F2. ABI definitions in three places — As noted in A1, ABIs exist in lib/contracts/abi.ts, packages/sdk/src/abi.ts, and lib/price.ts. The web app ones could import from the SDK package instead of maintaining a separate copy. Evaluate if the SDK ABI can be the single source of truth.

• F3. Duplicate error helper — The error() helper function is independently defined in all three indexer routes with identical code. Should be a shared utility.

• F4. Duplicate IPFS_GATEWAY + IPFS_TIMEOUT_MS — Same as B1/B2. Three identical definitions across indexer routes and backfill.

• F5. Inconsistent publicClient import paths — Backfill imports publicClient from lib/viem, indexer routes import from lib/rpc. Same object, different paths. Confusing.

• F6. Content hashing duplicated — lib/content.ts defines hashContent(). packages/sdk/src/client.ts:598-599 defines its own identical hashContent(). If the hashing algorithm ever changes, both must be updated.

• F7. Unused constants — ZAP_PLOTLINK, UNISWAP_V4_ROUTER, UNISWAP_V4_QUOTER, PERMIT2 are defined in lib/contracts/constants.ts but never imported or used anywhere. They're reserved for future features. If not launching with mainnet, remove to reduce confusion.

---

G. Mainnet Deployment Switchover

• G1. Create a mainnet deployment checklist covering at minimum: (1) Deploy StoryFactory on Base mainnet, (2) Deploy or verify $PLOT reserve token, (3) Update STORY_FACTORY mainnet address in constants, (4) Update PLOT_TOKEN mainnet address, (5) Set NEXT_PUBLIC_CHAIN_ID=8453 in production env, (6) Set NEXT_PUBLIC_CONTRACT_ADDRESS in production env, (7) Update DEPLOYMENT_BLOCK for mainnet in SDK, (8) Set CRON_SECRET in production, (9) Verify ERC8004_REGISTRY address on mainnet, (10) Initialize backfill_cursor table with mainnet deployment block.

• G2. No mainnet integration test path — There's no way to test against mainnet contracts without real funds. Consider a staging environment pointing to mainnet RPCs with a separate Supabase instance.

• G3. Reserve token label accuracy — RESERVE_LABEL switches between "WETH" and "$PLOT" based on IS_TESTNET. Verify $PLOT is the correct mainnet reserve token symbol and it displays correctly everywhere.

---

How to Review

1. Read each checklist item and the referenced file(s)
2. For ABI items (A1-A5), compare against the actual deployed contract on BaseScan
3. Post findings as a comment with format: **A1: PASS/FAIL/CONCERN** — explanation
4. Flag any additional issues you discover

Acceptance Criteria

• All checklist items reviewed and commented on by T2a and T2b
• All FAIL items have follow-up tickets created
• All CONCERN items are triaged (accept risk or create ticket)
• Mainnet deployment blockers clearly identified

[realproject7]

T2-2 Review Report

Reviewed against the repo code, live Base/Base Sepolia reads/simulations, and the upstream Mint Club V2 source for MCV2_Bond/MCV2_Royalty (Steemhunt/mint.club-v2-contract).

A. ABI Consistency and Correctness

• A1: FAIL — There is real drift already, not just theoretical drift. lib/contracts/abi.ts and packages/sdk/src/abi.ts match for StoryFactory and the shared MCV2 views, but lib/price.ts and the SDK disagree on royalties, and the SDK copy is the wrong one.
• A2: FAIL — Upstream MCV2_Royalty.getRoyaltyInfo is getRoyaltyInfo(address wallet, address reserveToken) returns (uint256 balance, uint256 claimed). The web ABI in lib/price.ts matches that. The SDK ABI in packages/sdk/src/abi.ts is wrong on both inputs and outputs, and packages/sdk/src/client.ts incorrectly treats the result as a single bigint.
• A3: FAIL — Upstream MCV2_Royalty.claimRoyalties is claimRoyalties(address reserveToken). The web ABI is correct. The SDK/CLI currently pass the storyline token address, not the reserve token address, so claims will fail or target the wrong asset.
• A4: CONCERN — PlotChained was validated against live Base Sepolia logs and decodes correctly with the current ABI. StorylineCreated / Donation / Registered were not fully verifiable from explorer-accessible verified sources in this pass, so I would not mark exact indexed flags/names as fully proven yet.
• A5: CONCERN — createStoryline and chainPlot do hit the deployed StoryFactory with the current signatures (simulation reverted with contract-specific reasons like Invalid CID / Not writer, which is strong evidence the selectors/arg layout are correct). Mint Club functions (priceForNextMint, tokenBond, mint, burn, getReserveForToken, getRefundForTokens) line up with upstream source. register / setAgentWallet on the ERC-8004 registry were not fully verified against deployed source in this pass.

B. Hardcoded Values and Magic Numbers

• B1: CONCERN — IPFS_GATEWAY is duplicated in the storyline indexer, plot indexer, and backfill route.
• B2: CONCERN — IPFS_TIMEOUT_MS = 10_000 is duplicated in the same three files.
• B3: CONCERN — Hardcoded gas limits are brittle for mainnet. They may work, but they are not derived from simulation/estimation and will need retuning if contract behavior or calldata size changes.
• B4: CONCERN — SLIPPAGE_BPS = 300 is hardcoded in TradingWidget. This should at least be a shared constant, and probably user-adjustable.
• B5: PASS — BLOCKS_PER_24H = 43200 is an approximation, but it is clearly documented and acceptable for a coarse 24h price-change indicator.
• B6: PASS — SCAN_BLOCKS = 200 should keep up with a 5-minute cron on Base under normal conditions because it scans slightly more than the ~150 blocks expected in 5 minutes. The margin is not huge, but it is positive.
• B7: FAIL — packages/sdk/src/constants.ts hardcodes a Sepolia deployment block only. getStoryline() / getPlots() on mainnet will either miss data or scan the wrong range unless callers override behavior externally.
• B8: CONCERN — Fixed 5-second sleeps before indexing are brittle. Mainnet propagation variance can be lower or higher; polling for receipt/log availability would be safer.
• B9: CONCERN — The 1-hour EIP-712 deadline is reasonable, but it is still a magic constant with no configurability or explicit security/UX rationale.
• B10: CONCERN — Trading/donate flows hardcode 18 decimals for parsing and display. If the mainnet reserve token is not 18 decimals, approvals, displayed balances, and entered amounts become wrong.
• B11: PASS — Hardcoding Filebase’s S3 endpoint/region is acceptable if Filebase is the intended permanent provider.
• B12: CONCERN — Retry policies are scattered and inconsistent across IPFS upload, receipt fetch, and indexing waits.

C. Mainnet Readiness and Zero Addresses

• C1: FAIL — STORY_FACTORY mainnet fallback is still the zero address in lib/contracts/constants.ts.
• C2: FAIL — PLOT_TOKEN mainnet fallback is still the zero address in lib/contracts/constants.ts.
• C3: CONCERN — ZAP_PLOTLINK is permanently zero and unused. Either remove it from launch-scope constants or ship the actual address.
• C4: CONCERN — The ERC-8004 registry is assumed to be the same address on both networks, but that is not verified here. A live agentIdByWallet read against 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 on Base mainnet reverted with the current ABI, so this address/ABI pairing needs explicit confirmation before launch.
• C5: CONCERN — SDK defaults are Sepolia-only. Mainnet users must override addresses in PlotLinkConfig, and that is easy to miss.
• C6: CONCERN — Both lib/contracts/constants.ts and lib/rpc.ts default to Sepolia if NEXT_PUBLIC_CHAIN_ID is missing. Production deployment must guarantee 8453 is set everywhere.

D. Security and Access Control

• D1: CONCERN — The indexer routes are unauthenticated. Content integrity is protected by receipt decoding + hash checks, but the routes are still open to RPC/IPFS/DB abuse.
• D2: FAIL — Backfill auth is optional in production because verifyCron() returns true when CRON_SECRET is unset.
• D3: CONCERN — IPFS fetches have a timeout, but no response size cap. A very large payload can still create memory/DB pressure.
• D4: PASS — hashContent(content) = keccak256(toHex(content)) matches Solidity hashing of the UTF-8 bytes (keccak256(bytes(content)) / keccak256(abi.encodePacked(content))). The hashing algorithm itself is sound.
• D5: PASS — The unique constraints backing onConflict: "tx_hash,log_index" do exist in supabase/migrations/00001_schema.sql for storylines, plots, and donations.
• D6: CONCERN — reconcileStorylinePlotCount() is idempotent, but concurrent plot indexing can still briefly write a stale count because it does a read-then-update outside a transaction.

E. Logic and Correctness

• E1: FAIL — packages/sdk/src/client.ts:getRoyaltyInfo() is wrong because the SDK ABI is wrong. It currently passes (tokenAddress, beneficiary) where the contract expects (wallet, reserveToken).
• E2: FAIL — packages/sdk/src/client.ts:claimRoyalties() and the CLI claim command pass the storyline token address, but the contract expects the reserve token address.
• E3: FAIL — processPlotChained() in the backfill route drops title entirely, while the direct plot indexer stores it. Backfilled rows will not match directly indexed rows.
• E4: PASS — The current bigint -> Number conversions are not an immediate correctness bug for storyline IDs / plot indices / current Base block heights, though this is worth watching long-term.
• E5: CONCERN — Exact-value approvals are safer, but the UX cost on mainnet is real because every trade/donation may require a separate approval transaction.
• E6: FAIL — The backfill silently skips plots when IPFS fetch/hash validation fails. There is no retry queue, so those rows are effectively lost unless the cursor is replayed manually.
• E7: FAIL — The backfill advances the cursor to toBlock even when some events in that range failed. That permanently skips failed events.
• E8: CONCERN — index/storyline can temporarily store plot_count = 1 before the genesis plot row exists. This should self-heal later, but it is still an inconsistency window.

F. Over-Engineering and Duplication

• F1: CONCERN — lib/viem.ts is only a re-export and currently just adds import-path confusion.
• F2: FAIL — ABI definitions in three places are already causing runtime drift. This is no longer a style issue; it is a correctness issue.
• F3: CONCERN — The error() helper is copy-pasted across all three indexer routes.
• F4: CONCERN — Same as B1/B2: duplicated IPFS gateway/timeout constants.
• F5: CONCERN — publicClient comes from both lib/viem and lib/rpc depending on file. This is confusing and unnecessary.
• F6: CONCERN — hashContent() is duplicated between lib/content.ts and packages/sdk/src/client.ts. The implementations match today, but this is drift-prone for a critical integrity path.
• F7: CONCERN — ZAP_PLOTLINK, UNISWAP_V4_ROUTER, UNISWAP_V4_QUOTER, and PERMIT2 are currently unused and create launch-scope ambiguity.

G. Mainnet Deployment Switchover

• G1: FAIL — There is no concrete mainnet switchover checklist in-repo yet, and the codebase still contains multiple unresolved placeholders/blockers (STORY_FACTORY, PLOT_TOKEN, SDK deployment block, cron auth, registry verification).
• G2: CONCERN — There is no low-risk mainnet-like integration path. A staging env that points at mainnet RPCs with a separate Supabase project would materially reduce launch risk.
• G3: CONCERN — $PLOT label correctness is not yet verifiable because the mainnet reserve token address is still zero/unset.

Additional findings

• AD1: FAIL (mainnet/blocker) — The Supabase schema is not actually multi-contract safe yet. storylines still has unique (storyline_id) and plots.storyline_id / donations.storyline_id still key only by storyline_id, not (contract_address, storyline_id). If StoryFactory is redeployed on mainnet (or another network) and IDs restart from 1, rows can collide or relate to the wrong contract.
• AD2: FAIL (SDK/blocker) — packages/sdk/src/client.ts:createStoryline() uploads JSON metadata ({ title, genre, content }) to IPFS but hashes only the raw content string before sending openingHash on-chain. The indexer later fetches the CID payload and hashes the fetched body, so SDK-created storylines will fail the content-hash integrity check unless a fallback body is supplied out-of-band.

Mainnet blockers I would fix before launch

• Royalty ABI/call mismatches: A2, A3, E1, E2
• Missing mainnet addresses / deployment block: B7, C1, C2, G1
• Unprotected production backfill: D2
• Backfill data-loss behavior: E6, E7
• Schema not contract-scoped: AD1
• SDK createStoryline payload/hash mismatch: AD2

[realproject7]

Contract Integration Audit — T2-3 Review Report

Issue: #320 — [Pre-Mainnet] Contract integration audit checklist
Reviewer: T2-3
Date: 2026-03-18

---

Executive Summary

Verified against the Mint Club V2 source (MCV2_Royalty.sol):

• Web app (lib/price.ts, ClaimRoyalties.tsx): Correct — getRoyaltyInfo(wallet, reserveToken) and claimRoyalties(reserveToken) match the contract.
• SDK (packages/sdk/src/abi.ts, client.ts): FAIL — ABI and client use wrong signatures; royalty flows will fail.

---

A. ABI Consistency and Correctness

A1: CONCERN — ABI duplication drift risk. Three locations: lib/contracts/abi.ts, packages/sdk/src/abi.ts, lib/price.ts. StoryFactory events/functions are consistent between web and SDK. MCV2 royalty functions diverge (see A2, A3). Recommend single source of truth (e.g. SDK package) with web importing from it.

A2: FAIL — getRoyaltyInfo ABI mismatch. Contract (MCV2_Royalty.sol:169-176): getRoyaltyInfo(address wallet, address reserveToken) returns (uint256, uint256). Web (lib/price.ts:62-72): ✓ correct. SDK (packages/sdk/src/abi.ts:131-142): ✗ wrong — defines (token, beneficiary) and outputs: [unclaimed]. SDK client passes (tokenAddress, beneficiary) — wrong argument order and semantics. Fix: Update SDK ABI to match contract; SDK should call getRoyaltyInfo(beneficiary, reserveToken) where reserveToken is PLOT_TOKEN/WETH.

A3: FAIL — claimRoyalties ABI mismatch. Contract (MCV2_Royalty.sol:129): claimRoyalties(address reserveToken). Web (lib/price.ts:76-79): ✓ correct. SDK (packages/sdk/src/abi.ts:143-148): ✗ wrong — defines inputs: [{ name: "token" }]. SDK client calls claimRoyalties(tokenAddress) (storyline token). Contract expects reserve token (WETH/$PLOT). Fix: Update SDK ABI and client to pass reserve token address. SDK must accept chain/reserve-token context (or read from tokenBond) to resolve reserve token.

A4: PASS — Event signatures (StorylineCreated, PlotChained, Donation, Registered) match between web and SDK. Structure and indexed flags are consistent. No on-chain verification performed; recommend spot-check on BaseScan if available.

A5: PASS — Function signatures for createStoryline, chainPlot, donate, priceForNextMint, tokenBond, register, setAgentWallet, mint, burn, getReserveForToken, getRefundForTokens are consistent with contract usage. Web lib/price.ts mcv2BondAbi correctly includes mint/burn/getReserveForToken/getRefundForTokens.

---

B. Hardcoded Values and Magic Numbers

B1: CONCERN — IPFS gateway "https://ipfs.filebase.io/ipfs/" duplicated in 3 files. Should be a shared constant or env var.

B2: CONCERN — IPFS_TIMEOUT_MS = 10_000 duplicated in same 3 files. Should be shared.

B3: CONCERN — Gas limits: 500_000 (useChainPlot), 2_000_000 (TradingWidget), 150_000 (DonateWidget). Mainnet gas costs differ; consider configurable or documented tuning.

B4: CONCERN — SLIPPAGE_BPS = 300 (3%) hardcoded in TradingWidget. Consider user-configurable or shared constant.

B5: PASS — BLOCKS_PER_24H = 43200 documented as ~24h at 2s/block. Acceptable for price-change display.

B6: PASS — SCAN_BLOCKS = 200 (~6.6 min at 2s/block) vs 5-min cron. Slight overscan; adequate.

B7: FAIL — DEPLOYMENT_BLOCK = 20_000_000 is Sepolia-only. SDK has no mainnet deployment block. Mainnet event queries will fail or scan from genesis. Blocker for mainnet.

B8: CONCERN — Fixed 5s delay before indexer calls. May be insufficient on mainnet; consider polling or adaptive delay.

B9: PASS — EIP-712 deadline 1h is reasonable for setAgentWallet.

B10: CONCERN — Token decimals hardcoded to 18 in TradingWidget, DonateWidget. getTokenTVL correctly reads decimals on-chain. If mainnet $PLOT has different decimals, trading/donate will break.

B11: PASS — Filebase endpoint hardcoded; acceptable if Filebase is permanent provider.

B12: CONCERN — Retry constants scattered (maxRetries=3, maxAttempts=5, different backoff strategies). Consider centralizing.

---

C. Mainnet Readiness and Zero Addresses

C1: FAIL — StoryFactory mainnet address is 0x000...000. Blocker. Backfill skips correctly; trading/indexers would call zero address.

C2: FAIL — PLOT_TOKEN mainnet is 0x000...000. Blocker. Trades and donations would fail.

C3: CONCERN — ZAP_PLOTLINK permanently zero. Remove if not part of launch; otherwise document.

C4: CONCERN — ERC8004 Registry same address for testnet/mainnet. Verify cross-chain deployment or correct mainnet address.

C5: CONCERN — SDK defaults are Sepolia-only. Mainnet users must override all addresses. Document in SDK README.

C6: CONCERN — NEXT_PUBLIC_CHAIN_ID defaults to 84532. Production must set 8453. Verify no path leaks default.

---

D. Security and Access Control

D1: CONCERN — Indexer routes unauthenticated. Receipt + content-hash verification prevents fake data; still allows RPC/IPFS/DB load. Consider rate limiting or API key.

D2: FAIL — Backfill cron: if (!secret) return true — when CRON_SECRET unset, anyone can trigger. Dangerous for production.

D3: CONCERN — IPFS fetch has 10s timeout but no size limit. Large content could cause memory/DB issues.

D4: PASS — hashContent() uses keccak256(toHex(content)). For UTF-8 strings this matches Solidity keccak256(abi.encodePacked(content)). Comment in lib/content.ts is accurate.

D5: PASS — Unique constraints (tx_hash, log_index) exist in schema (storylines, plots, donations).

D6: PASS — Reconciliation uses COUNT(*) and MAX(block_timestamp); idempotent. No obvious TOCTOU with Supabase.

---

E. Logic and Correctness

E1: FAIL — SDK getRoyaltyInfo(tokenAddress, beneficiary) uses wrong ABI and args. Contract expects (wallet, reserveToken). SDK will return wrong data or revert.

E2: FAIL — SDK claimRoyalties(tokenAddress) passes storyline token. Contract expects reserve token. Claims will fail or claim wrong royalties.

E3: FAIL — Backfill processPlotChained (line 261) destructures title but does not include it in PlotInsert. Direct indexer includes title: title || "". Backfilled plots will have no title.

E4: PASS — BigInt→Number for storylineId, plotIndex is safe. Block numbers on Base are far from 2^53.

E5: CONCERN — Exact-amount approvals cause 2 popups per trade. Consider MAX_UINT256 or Permit2 for mainnet UX.

E6: CONCERN — Backfill silently skips failed IPFS content. No retry; plots permanently missing until manual replay.

E7: CONCERN — Backfill advances cursor to toBlock even on partial failure. Failed events skipped permanently. Consider advancing only to last successful block.

E8: CONCERN — Genesis plot insert failure after storyline insert leaves plot_count=1 with no genesis plot. Reconciler corrects later; brief inconsistency window.

---

F. Over-Engineering and Duplication

F1: CONCERN — lib/viem.ts is re-export of lib/rpc. Backfill imports from viem; others from rpc. Consolidate.

F2: CONCERN — ABIs in three places. Evaluate SDK as single source of truth.

F3: CONCERN — error() helper duplicated in all three indexer routes. Extract to shared util.

F4: CONCERN — IPFS_GATEWAY + IPFS_TIMEOUT_MS duplicated (B1/B2).

F5: CONCERN — Inconsistent publicClient import paths (viem vs rpc).

F6: CONCERN — hashContent duplicated in lib/content.ts and packages/sdk/src/client.ts. Single source needed.

F7: CONCERN — ZAP_PLOTLINK, UNISWAP_V4_ROUTER, UNISWAP_V4_QUOTER, PERMIT2 defined but never imported. Remove if not launching with mainnet.

---

G. Mainnet Deployment Switchover

G1: FAIL — No mainnet deployment checklist exists. Create one covering: StoryFactory deploy, $PLOT deploy, address updates, chain ID, CRON_SECRET, DEPLOYMENT_BLOCK, ERC8004 verification, backfill_cursor init.

G2: CONCERN — No mainnet integration test path. Consider staging env.

G3: PASS — RESERVE_LABEL switches WETH/$PLOT by IS_TESTNET. Correct.

---

Summary: Blockers and High Priority

Priority	Item	Action
Blocker	A2, A3, E1, E2	Fix SDK getRoyaltyInfo/claimRoyalties ABI and client — use (beneficiary, reserveToken) and claimRoyalties(reserveToken)
Blocker	C1, C2	Update StoryFactory and PLOT_TOKEN mainnet addresses before launch
Blocker	B7	Add mainnet DEPLOYMENT_BLOCK to SDK
Blocker	D2	Require CRON_SECRET in production; fail closed when unset
High	E3	Add title to backfill processPlotChained
High	G1	Create mainnet deployment checklist

---

Additional Findings

• ClaimRoyalties.tsx correctly uses web mcv2BondAbi with getRoyaltyInfo(beneficiary, PLOT_TOKEN) and claimRoyalties(PLOT_TOKEN). Web royalty flow is correct.
• ERC8004 Registered event: SDK uses owner in event; web erc8004 uses same. Consistent.

[realproject7]

Contract Integration Audit Report — T2-1

Reviewed all files referenced in the checklist against source code and the actual deployed Mint Club V2 contracts (MCV2_Bond.sol, MCV2_Royalty.sol).

---

A. ABI Consistency and Correctness

A1: FAIL — ABI duplication has real divergence. The web app (lib/price.ts) defines getRoyaltyInfo with inputs (wallet, reserveToken) → outputs (balance, claimed) (2 outputs). The SDK (packages/sdk/src/abi.ts) defines it with inputs (token, beneficiary) → output (unclaimed) (1 output). These are structurally incompatible. Additionally, getReserveForToken and getRefundForTokens in the web app ABI each define 1 output, but the actual contract returns 2 values (amount, royalty). The mint and burn functions in the web app ABI have outputs: [] but the actual contract returns uint256. These return value mismatches can cause viem to silently drop data.

A2: FAIL — MAINNET BLOCKER — The actual MCV2_Royalty contract signature is getRoyaltyInfo(address wallet, address reserveToken) → (uint256, uint256). The web app ABI is correct (inputs: wallet, reserveToken; outputs: balance, claimed). The SDK ABI is WRONG — it defines inputs as (token, beneficiary) with only 1 output (unclaimed). The SDK client (client.ts:503-510) calls getRoyaltyInfo(tokenAddress, beneficiary) — this passes the storyline token address as wallet and beneficiary as reserveToken, which is argument order inverted from the actual contract. The cast to single bigint also discards the claimed value. CLI claim.ts depends on this — royalty queries will return garbage data on mainnet.

A3: FAIL — MAINNET BLOCKER — The actual contract signature is claimRoyalties(address reserveToken). The web app ABI correctly names the parameter reserveToken. But the SDK client (client.ts:521) calls claimRoyalties(tokenAddress) where tokenAddress is the storyline token — not the reserve token. This will attempt to claim royalties for the wrong token. The CLI claim.ts command inherits this bug. Must pass the reserve token address (e.g., WETH on testnet, $PLOT on mainnet).

A4: PASS — All event ABIs (StorylineCreated, PlotChained, Donation, Registered) are consistent between web app and SDK. Parameter names, types, and indexed flags match across both copies. Event decoding works correctly in all indexer routes and backfill.

A5: CONCERN — createStoryline, chainPlot, donate signatures look correct and match between copies. priceForNextMint and tokenBond match the deployed contract. However, as noted in A1: getReserveForToken and getRefundForTokens actual returns are (uint256, uint256) (amount + royalty), not single uint256. The web app ABI only declares 1 output for each. viem will return a tuple, but the TradingWidget uses the result as a single bigint for price estimation — it's receiving only the first element of the tuple. The royalty portion is silently dropped. This means buy/sell estimates are slightly off (don't account for the royalty component in the displayed estimate). The slippage tolerance likely absorbs this, but it's technically incorrect. mint and burn return uint256 in the contract but the ABI says outputs: [] — since the return values aren't used, this is functionally harmless but should be corrected.

---

B. Hardcoded Values and Magic Numbers

B1: CONCERN — IPFS_GATEWAY = "https://ipfs.filebase.io/ipfs/" is identically defined in src/app/api/index/storyline/route.ts:15, src/app/api/index/plot/route.ts:14, and src/app/api/cron/backfill/route.ts:12. Should be a shared constant. Not a blocker but increases maintenance risk.

B2: CONCERN — IPFS_TIMEOUT_MS = 10_000 independently defined in same 3 files. Same recommendation as B1 — extract to shared constant.

B3: CONCERN — Gas limits: 500_000 in useChainPlot.ts:37, 2_000_000 in TradingWidget.tsx:111,145, 150_000 in DonateWidget.tsx:87. Base mainnet gas costs are similar to testnet since both are L2, so these values should work. However, the 2_000_000 for mint/burn is generous (likely safe), and 150_000 for donate is tight — monitor in mainnet testing. Consider making these env-configurable for tuning without redeployment.

B4: CONCERN — SLIPPAGE_BPS = 300 (3%) in TradingWidget.tsx:14. For early low-liquidity tokens, 3% may cause reverts. For established tokens, it's loose. Should be user-configurable via a dropdown or at minimum a shared constant. Not a blocker for launch but impacts UX.

B5: PASS — BLOCKS_PER_24H = BigInt(43200) in lib/price.ts:168. Base targets 2-second blocks. Slight variance is acceptable for a 24h price-change indicator — this is a cosmetic metric, not a financial calculation.

B6: PASS — SCAN_BLOCKS = BigInt(200) covers ~400 seconds at 2s/block = ~6.6 minutes. For a 5-minute cron, this slightly over-scans which is correct — ensures no gaps between runs. Verified the math checks out.

B7: FAIL — MAINNET BLOCKER — DEPLOYMENT_BLOCK = BigInt(20_000_000) in packages/sdk/src/constants.ts:23 is a Base Sepolia block number. On mainnet, the SDK's getStoryline() and getPlots() use this as fromBlock. Scanning from block 20M on mainnet would scan billions of empty blocks (Base mainnet is past block 20M already). Must be updated to the actual mainnet deployment block, or the SDK methods will time out or return no results.

B8: CONCERN — Fixed 5-second delay before indexer call in usePublish.ts:115 and DonateWidget.tsx:95. On mainnet, Base RPC propagation may differ. A polling approach (retry indexer call 3 times with 2s intervals) would be more robust than a blind 5s wait. Not a blocker — the backfill cron is the safety net — but affects perceived latency.

B9: PASS — EIP-712 deadline of 1 hour (client.ts:445) is reasonable. Short enough for security (replay window is bounded), long enough for human interaction with hardware wallets.

B10: CONCERN — parseUnits(amount, 18) and formatUnits(*, 18) hardcoded throughout TradingWidget.tsx and DonateWidget.tsx. If $PLOT has different decimals than 18, all trading and donation amounts break. getTokenTVL() in lib/price.ts:245-249 correctly reads decimals on-chain — the widgets should do the same. Verify that $PLOT is 18 decimals before mainnet launch. If it is, document the assumption. If it isn't, this is a blocker.

B11: PASS — Filebase S3 endpoint and region are stable constants for the Filebase service. Fine as hardcoded values in the IPFS upload utility.

B12: CONCERN — Retry strategies vary: IPFS upload uses exponential backoff 2^(attempt-1) * 1000ms with 3 retries. Receipt fetching uses linear backoff attempt * 2000ms with 5 retries. Different strategies for different concerns is defensible, but the inconsistency makes the codebase harder to reason about. Consider a shared retry utility with configurable strategy. Low priority.

---

C. Mainnet Readiness and Zero Addresses

C1: FAIL — MAINNET BLOCKER — STORY_FACTORY mainnet fallback is 0x000...000 in lib/contracts/constants.ts:31. The backfill cron correctly guards against this (line 64), but trading widgets, indexer routes, and the frontend useChainPlot/usePublish hooks would all submit transactions to the zero address. Must be updated before mainnet deployment.

C2: FAIL — MAINNET BLOCKER — PLOT_TOKEN mainnet is 0x000...000 in lib/contracts/constants.ts:41. Every trade approval and donation approval would target the zero address. All trading and donation flows are completely broken on mainnet without this.

C3: CONCERN — ZAP_PLOTLINK is permanently 0x000...000. I verified it's never imported or used anywhere in the codebase. It's dead code. Should be removed to reduce confusion, but not a blocker.

C4: CONCERN — ERC8004_REGISTRY = "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432" is the same address for testnet and mainnet in both lib/contracts/constants.ts:78 and packages/sdk/src/constants.ts:42. If this is a CREATE2-deployed contract at a deterministic address, this is correct. Should be verified by checking the address on Base mainnet before launch. If the contract doesn't exist at this address on mainnet, agent detection silently falls back to "human" (which is safe but incorrect).

C5: CONCERN — SDK defaults (packages/sdk/src/constants.ts) are all Sepolia addresses. The PlotLinkConfig interface allows overriding all addresses, but there's no documentation or example for mainnet configuration. SDK consumers targeting mainnet must know to override storyFactoryAddress, mcv2BondAddress, and chainId. Add a mainnet config example to SDK docs.

C6: CONCERN — Both lib/contracts/constants.ts:14 and lib/rpc.ts:4 default chain ID to 84532 (Sepolia) via process.env.NEXT_PUBLIC_CHAIN_ID || "84532". The env var NEXT_PUBLIC_CHAIN_ID=8453 must be set in production. There's no runtime validation or warning if the default leaks through — the app would silently connect to Sepolia. Consider adding a startup check that warns if running with testnet defaults when NODE_ENV=production.

---

D. Security and Access Control

D1: CONCERN — Indexer routes (POST /api/index/storyline, /api/index/plot, /api/index/donation) are unauthenticated. An attacker can't inject fake data (content hash is verified on-chain), but they can: (a) trigger arbitrary RPC calls and IPFS fetches (DOS vector), (b) cause unnecessary DB writes via upsert. Rate limiting (e.g., via Vercel's built-in rate limiting or a simple IP-based limiter) would mitigate this. Not a launch blocker but should be addressed for production.

D2: FAIL — verifyCron() in backfill/route.ts:24 returns true when CRON_SECRET is unset. In production without CRON_SECRET, anyone can trigger backfill scans, causing uncontrolled RPC usage and DB writes. CRON_SECRET must be set in the production environment. Consider failing closed (return false when secret is unset) instead of open.

D3: CONCERN — IPFS gateway fetches have a 10s timeout but no content size limit. A malicious CID could point to a very large file that fits within 10s but consumes significant memory. However, since the content hash is verified on-chain (the CID must match the hash committed in the transaction), an attacker would need to have deployed the large content on-chain first, making this a theoretical rather than practical concern. Low priority.

D4: PASS — hashContent() uses keccak256(toHex(content)) in both lib/content.ts and packages/sdk/src/client.ts:598-599. toHex() from viem converts UTF-8 strings to hex, which matches Solidity's keccak256(abi.encodePacked(content)) for raw string bytes. The encoding is consistent.

D5: PASS — Idempotency relies on onConflict: "tx_hash,log_index" for all three tables (storylines, plots, donations). This is a sound approach — each event log is uniquely identified by its transaction hash and log index. As long as the unique constraint exists in the Supabase schema (which should be verified in the migration files), this prevents double-indexing.

D6: PASS — reconcileStorylinePlotCount() uses COUNT(*) and MAX(block_timestamp) which are point-in-time consistent reads. Even if two plots are indexed concurrently, the reconciler runs after each plot insert, and the last one to run will have the correct count. The function is idempotent by design — repeated calls converge to the correct state.

---

E. Logic and Correctness

E1: FAIL — MAINNET BLOCKER — As detailed in A2: SDK getRoyaltyInfo(tokenAddress, beneficiary) passes args in the wrong order relative to the actual contract getRoyaltyInfo(wallet, reserveToken). The SDK passes the storyline token where the contract expects a wallet address, and passes the beneficiary where the contract expects the reserve token. Result will be meaningless data (likely zeros). All royalty display in the CLI status and claim commands is affected.

E2: FAIL — MAINNET BLOCKER — As detailed in A3: SDK claimRoyalties(tokenAddress) passes the storyline token, but the contract expects the reserve token address. Claims will fail (no royalties accumulated for a random token address) or claim the wrong asset's royalties. The CLI claim command is broken.

E3: FAIL — Confirmed: processPlotChained() in backfill/route.ts:261 destructures title from args in the type assertion (line 262) but does not include title in the PlotInsert row (lines 270-281). The direct indexer index/plot/route.ts:118 correctly includes title: title || "". Backfilled plots will have null title. This causes data inconsistency between directly-indexed and backfilled plots. Fix: add title: title || "" to the backfill PlotInsert.

E4: PASS — Number() conversions for storylineId, plotIndex, and toBlock are safe. Storyline IDs and plot indices grow slowly (sequential counters). Block numbers on Base are ~40M as of early 2026 — well within Number.MAX_SAFE_INTEGER (2^53 - 1 ≈ 9 quadrillion). No precision risk for the foreseeable future.

E5: CONCERN — Exact-amount approvals mean every trade requires 2 wallet popups (approve + execute). On mainnet with real gas costs (~$0.01 per tx on Base L2), the gas overhead is minimal, but the UX friction is significant. MAX_UINT256 approval is the standard DeFi pattern. Permit2 address is already defined in constants. Recommend switching to MAX_UINT256 approval or Permit2 for mainnet to improve UX. Not a blocker — the current approach is safer but slower.

E6: CONCERN — In backfill/route.ts:265-266, plots with unavailable IPFS content or mismatched hashes are silently skipped. The cursor advances past them (E7). These plots are permanently lost from the database unless the cron is manually rewound. The content is available on-chain (the CID is in the event), so a dedicated recovery job could re-fetch later. But there's no such mechanism currently. Consider logging skipped events to a backfill_failures table for retry.

E7: FAIL — backfill/route.ts:165: cursor advances to toBlock regardless of how many events within the range failed. Combined with E6, this means failed events are permanently skipped. If IPFS is temporarily down during a cron run, all events in that range are lost. Fix: track the last successfully processed block and only advance the cursor to that point. Alternatively, log failures for retry as suggested in E6.

E8: CONCERN — index/storyline/route.ts:139: storyline is created with plot_count: 1, but if the genesis plot insert (step 9, line 174) fails, the storyline exists with plot_count: 1 and no actual plot in the plots table. The reconciler would eventually correct it to 0. The window for this inconsistency is small and self-healing. Low priority.

---

F. Over-Engineering and Duplication

F1: PASS (minor) — lib/viem.ts is a 1-line re-export of publicClient from lib/rpc. The backfill cron imports from lib/viem, everything else from lib/rpc. This is harmless but confusing. Recommend deleting lib/viem.ts and updating the one import in backfill/route.ts:3 to use lib/rpc. Low priority cleanup.

F2: CONCERN — ABIs exist in 3 places: lib/contracts/abi.ts, packages/sdk/src/abi.ts, lib/price.ts. The SDK comment says "Mirrored from lib/contracts/abi.ts" but the two have already diverged (A2, A3). Making the SDK package the single source of truth and having the web app import from @plotlink/sdk would eliminate drift. This is the root cause of the A2/A3 bugs.

F3: CONCERN — Identical error() helper defined independently in all 3 indexer routes. Trivial to extract to a shared utility. Low priority.

F4: CONCERN — Same as B1/B2. IPFS_GATEWAY and IPFS_TIMEOUT_MS duplicated in 3 files.

F5: CONCERN — Same as F1. Backfill imports from lib/viem, indexers from lib/rpc. Same object, confusing paths.

F6: CONCERN — hashContent() is independently defined in lib/content.ts:16-18 and packages/sdk/src/client.ts:598-599. Both use keccak256(toHex(content)) — identical today. If the hashing algorithm changes, both must be updated. The SDK should either import from a shared package or the web app should import from @plotlink/sdk.

F7: CONCERN — ZAP_PLOTLINK, UNISWAP_V4_ROUTER, UNISWAP_V4_QUOTER, PERMIT2 are defined in lib/contracts/constants.ts but never used. Confirmed via grep. Remove to reduce confusion. These can be re-added when the features are implemented.

---

G. Mainnet Deployment Switchover

G1: FAIL — MAINNET BLOCKER — No formal mainnet deployment checklist exists. Based on this audit, the minimum checklist is:

1. Deploy StoryFactory on Base mainnet → update STORY_FACTORY in lib/contracts/constants.ts
2. Deploy or verify $PLOT ERC-20 → update PLOT_TOKEN in lib/contracts/constants.ts
3. Verify $PLOT decimals = 18 (or update all parseUnits/formatUnits calls)
4. Set NEXT_PUBLIC_CHAIN_ID=8453 in production env
5. Set NEXT_PUBLIC_CONTRACT_ADDRESS to the mainnet StoryFactory address
6. Update DEPLOYMENT_BLOCK in packages/sdk/src/constants.ts for mainnet
7. Set CRON_SECRET in production env
8. Verify ERC8004_REGISTRY exists at 0x8004A1...9A432 on Base mainnet
9. Initialize backfill_cursor table with mainnet deployment block
10. Fix SDK getRoyaltyInfo argument order (A2)
11. Fix SDK claimRoyalties parameter — must pass reserve token, not storyline token (A3)
12. Fix backfill missing plot title (E3)
13. Fix backfill cursor advancement on partial failure (E7)
14. Fix web app ABI return types for getReserveForToken, getRefundForTokens, mint, burn (A1/A5)

G2: CONCERN — No mainnet integration test path exists. Recommend a staging environment with mainnet RPC + separate Supabase instance for pre-launch validation. At minimum, a read-only smoke test that verifies contract calls succeed (priceForNextMint, tokenBond) against mainnet addresses.

G3: PASS — RESERVE_LABEL correctly switches between "WETH" (testnet) and "$PLOT" (mainnet) based on IS_TESTNET. Assuming $PLOT is the correct mainnet reserve token symbol, this is correct.

---

Summary of Mainnet Blockers

ID	Issue	Severity
A2	SDK getRoyaltyInfo wrong argument order and return type	BLOCKER
A3	SDK claimRoyalties passes wrong token (storyline vs reserve)	BLOCKER
B7	SDK DEPLOYMENT_BLOCK is testnet-specific	BLOCKER
C1	STORY_FACTORY mainnet address is zero	BLOCKER
C2	PLOT_TOKEN mainnet address is zero	BLOCKER
E1	SDK royalty queries return garbage (consequence of A2)	BLOCKER
E2	SDK royalty claims fail (consequence of A3)	BLOCKER
E7	Backfill cursor advances past failed events	HIGH
G1	No formal deployment checklist	HIGH

Additional Issues Found (not in original checklist)

• A1-extra: Web app getReserveForToken and getRefundForTokens ABIs declare 1 output each, but the actual contract returns 2 values (amount, royalty). The TradingWidget receives the amount correctly (viem returns the first tuple element when ABI declares 1 output) but the royalty component is silently dropped. Price estimates are slightly off.
• A1-extra: Web app mint and burn ABIs have outputs: [] but the actual contract returns uint256. Functionally harmless since return values aren't used, but should be corrected for ABI accuracy.
• F1/F5: lib/viem.ts backward-compat shim should be removed — only one file (backfill/route.ts) uses it.

---

Reviewed by T2-1. Follow-up tickets should be created for all BLOCKER and HIGH items before mainnet deployment.

[project7-interns]

T2b Contract Integration Audit Report

A. ABI Consistency and Correctness

A1: ABI duplication drift risk — FAIL
MCV2_Bond ABIs are fragmented across three locations with no single source of truth. lib/contracts/abi.ts has priceForNextMint and tokenBond only. packages/sdk/src/abi.ts adds getRoyaltyInfo, claimRoyalties. lib/price.ts adds getReserveForToken, getRefundForTokens, mint, burn plus its own divergent getRoyaltyInfo and claimRoyalties. The SDK lacks 4 bonding curve functions (mint, burn, getReserveForToken, getRefundForTokens). StoryFactory and ERC-8004 ABIs are consistent across locations.

A2: getRoyaltyInfo ABI mismatch — FAIL
SDK (packages/sdk/src/abi.ts): inputs (token, beneficiary), outputs (unclaimed) — 1 output.
Web app (lib/price.ts): inputs (wallet, reserveToken), outputs (balance, claimed) — 2 outputs.
Three differences: parameter names reversed, output count differs, output semantics differ. These cannot both be correct. The SDK client casts the result as a single bigint — if the contract returns two values, the SDK silently reads wrong data.

A3: claimRoyalties ABI mismatch — FAIL
SDK: inputs: [{ name: "token" }]. Web app: inputs: [{ name: "reserveToken" }]. While Solidity selectors only depend on types (both address), the naming indicates semantic confusion about which address to pass — storyline token vs reserve token. If the SDK passes the storyline token but the contract expects the reserve token, claims will fail or claim from the wrong pool.

A4: Event signatures match deployed contract — PASS
All events (StorylineCreated, PlotChained, Donation, Registered) are identical across all locations. Indexed flags match. No divergence.

A5: Function signatures match deployed contract — FAIL
createStoryline, chainPlot, donate, priceForNextMint, tokenBond, register, setAgentWallet — all consistent. getRoyaltyInfo and claimRoyalties have incompatible definitions (see A2/A3). getReserveForToken, getRefundForTokens, mint, burn exist only in lib/price.ts — SDK consumers cannot call bonding curve buy/sell operations.

---

B. Hardcoded Values and Magic Numbers

B1: IPFS gateway URL duplicated — FAIL
"https://ipfs.filebase.io/ipfs/" hardcoded identically in index/storyline/route.ts, index/plot/route.ts, and cron/backfill/route.ts. Should be a shared constant.

B2: IPFS timeout duplicated — FAIL
IPFS_TIMEOUT_MS = 10_000 independently defined in the same 3 files. Should be shared.

B3: Gas limits hardcoded — CONCERN
Four distinct gas limits: 500_000 (chainPlot), 2_000_000 (mint/burn), 150_000 (donate). No gas estimation fallback. createStoryline uses wallet estimation while chainPlot uses a hardcoded value — inconsistent approach. Values are reasonable for current contracts but fragile to upgrades.

B4: Slippage tolerance hardcoded — CONCERN
SLIPPAGE_BPS = 300 (3%) in TradingWidget.tsx. Reasonable for bonding curve trades but not user-configurable. Acceptable for MVP.

B5: Block time assumption — CONCERN
BLOCKS_PER_24H = BigInt(43200) assumes exactly 2-second blocks. Base targets 2s but can vary. Acceptable for approximate price change display; should be documented.

B6: Backfill scan range — CONCERN
SCAN_BLOCKS = BigInt(200) covers ~6.7 minutes at 2s/block. Healthy overlap for 5-minute cron. But recovery from outages is slow — a 1-hour outage (1800 blocks) takes 9 cron cycles. Consider making configurable via env var.

B7: DEPLOYMENT_BLOCK is testnet-specific — FAIL
DEPLOYMENT_BLOCK = BigInt(20_000_000) in SDK is a Base Sepolia block number. No per-chain mapping exists. Must be updated for mainnet deployment, and ideally keyed by chainId.

B8: Indexer sleep — CONCERN
setTimeout(r, 5000) in usePublish.ts and DonateWidget.tsx before indexer call. Fixed 5-second delay is a UX penalty and may be insufficient on mainnet. Should use polling with backoff.

B9: EIP-712 signature deadline — PASS
1-hour deadline in setAgentWallet() is standard and appropriate.

B10: Token decimals hardcoded to 18 — CONCERN
parseUnits(amount, 18) and formatUnits(*, 18) used throughout TradingWidget, DonateWidget, and lib/price.ts. Correct for WETH and MCV2 bonding curve tokens, but breaks if mainnet reserve token has different decimals (e.g., USDC = 6). getTokenTVL() correctly reads decimals on-chain — trading widgets should follow the same pattern.

B11: Filebase endpoint hardcoded — PASS
endpoint: "https://s3.filebase.com" is the canonical Filebase endpoint. Single location, bucket is configurable. Fine.

B12: Retry constants scattered — FAIL
Three different retry strategies: IPFS upload (exponential, max 3), receipt retry (linear, max 5), indexer call (no retry at all). No shared utility, no jitter. Should consolidate into a shared retryWithBackoff utility.

---

C. Mainnet Readiness and Zero Addresses

C1: StoryFactory mainnet address is 0x000...000 — FAIL
STORY_FACTORY defaults to zero address on mainnet when NEXT_PUBLIC_CONTRACT_ADDRESS is not set. The backfill cron has a guard that skips on zero address, but frontend write transactions and other code paths would call the zero address. Only partially guarded.

C2: PLOT_TOKEN mainnet address is 0x000...000 — FAIL
PLOT_TOKEN resolves to zero address on mainnet with no env var override mechanism (unlike STORY_FACTORY). Every trade and donation on mainnet would interact with the zero address. Hard blocker — there is no escape hatch.

C3: ZAP_PLOTLINK permanently zero — CONCERN
Hardcoded to zero unconditionally. However, it is exported but never imported anywhere — currently dead code. Low risk today, but will need attention if the zap feature launches.

C4: ERC-8004 Registry address is chain-agnostic — CONCERN
Same address 0x8004...a432 used for both chains without conditional logic. Valid if deployed with CREATE2 to the same address, but this is unverified and undocumented. SDK allows override via config.

C5: SDK defaults are testnet-only — FAIL
STORY_FACTORY_ADDRESS and MCV2_BOND_ADDRESS in SDK are hardcoded to Base Sepolia addresses with no mainnet equivalents. Override mechanism exists via PlotLinkConfig, but no mainnet values are documented. If caller sets chainId: 8453 but forgets to override addresses, SDK silently calls testnet contracts on mainnet chain.

C6: Chain ID env var default — CONCERN
Both lib/contracts/constants.ts and lib/rpc.ts default to 84532 (Sepolia). No startup validation warns when running with wrong chain. Combined with C1+C2, a forgotten env var causes silent testnet operation rather than clear failure.

---

D. Security and Access Control

D1: Indexer routes have no authentication — CONCERN
POST routes are open. On-chain verification (receipt + content hash) prevents fake data injection, but an attacker can trigger RPC calls, IPFS fetches, and DB writes at will. Recommend rate limiting or API key.

D2: Backfill cron auth is optional — FAIL
if (!secret) return true — when CRON_SECRET is unset, anyone can trigger backfill. Should fail closed in production (NODE_ENV === 'production').

D3: IPFS content used directly — CONCERN
No content size limit on fetched IPFS data. AbortSignal.timeout(10_000) is the only guard. lib/content.ts has MAX_CONTENT_LENGTH = 10_000 and validateContentLength(), but none of the indexer routes call it. A large CID could cause OOM before timeout.

D4: Content hash verification is sound — PASS
keccak256(toHex(content)) in both lib/content.ts and SDK matches Solidity keccak256(abi.encodePacked(content)) for UTF-8 strings. Consistent across locations.

D5: No double-index protection beyond upsert — PASS
All indexer routes and backfill use onConflict: "tx_hash,log_index". This composite key is a natural unique identifier for on-chain events. Assumes matching DB constraint exists (should verify in migrations).

D6: Reconciliation race condition — CONCERN
reconcileStorylinePlotCount() uses a read-then-write pattern (COUNT(*) then UPDATE). Classic TOCTOU — concurrent indexing of the same storyline could write stale counts. Self-heals on next reconciliation call. Low risk in practice but architecturally unsound.

---

E. Logic and Correctness

E1: SDK getRoyaltyInfo may return wrong data — FAIL
SDK passes (tokenAddress, beneficiary) but web ABI defines parameters as (wallet, reserveToken) — reversed order. If the contract signature matches the web ABI, the SDK is passing arguments in the wrong order and will return incorrect royalty data.

E2: SDK claimRoyalties argument — FAIL
SDK calls claimRoyalties(tokenAddress) where tokenAddress is the storyline token. Web ABI names the parameter reserveToken. If the contract expects the reserve token address, SDK claims will fail or claim from the wrong pool.

E3: Backfill skips plot title — FAIL
processPlotChained() in backfill does not extract or store title from event args. Direct indexer (index/plot/route.ts) correctly includes title: title || "". Backfilled plots will have null/missing titles — data inconsistency.

E4: BigInt to Number precision — CONCERN
Multiple Number(bigint) conversions for storyline IDs, plot indices, block numbers. All safe for realistic values (well under 2^53). Low severity.

E5: approve() exact amount vs max — CONCERN
Trading and donate widgets use exact-amount approvals, requiring a separate approval tx per trade. Functionally correct but UX friction with real gas costs on mainnet. Consider MAX_UINT256 or Permit2.

E6: Backfill silently skips failed IPFS content — FAIL
When IPFS content is unavailable or hash doesn't match, processPlotChained() silently returns without incrementing the error counter. The cursor advances past these events, permanently skipping them. No retry mechanism exists.

E7: Backfill advances cursor even on partial failure — FAIL
Cursor advances to toBlock regardless of error count. Combined with E6, IPFS downtime during a backfill run permanently loses all plots in that block range. Cursor should only advance to the last successfully processed block.

E8: Genesis plot count race — CONCERN
Storyline inserted with plot_count: 1 before genesis plot. If genesis plot insert fails (IPFS unavailable in backfill), storyline persists with plot_count: 1 but zero actual plot rows. Reconciler only runs for PlotChained events, not StorylineCreated — so this inconsistency persists.

---

F. Over-Engineering and Duplication

F1: lib/viem.ts is a useless re-export — FAIL
Contains only export { publicClient } from "./rpc". Only imported by backfill route. Should migrate to lib/rpc and delete this file.

F2: ABI definitions in three places — FAIL
lib/contracts/abi.ts, packages/sdk/src/abi.ts, and lib/price.ts all define MCV2 ABIs independently. SDK copy is justified for package isolation but has signature mismatches with lib/price.ts (see A2/A3).

F3: Duplicate error helper — FAIL
Identical function error(message, status) defined in all 3 indexer routes. Should be a shared utility.

F4: Duplicate IPFS_GATEWAY + IPFS_TIMEOUT_MS — FAIL
Same as B1/B2. Three identical definitions.

F5: Inconsistent publicClient import paths — FAIL
Backfill imports from lib/viem, indexers from lib/rpc. Same object, different paths.

F6: Content hashing duplicated — FAIL
Identical hashContent() in lib/content.ts and packages/sdk/src/client.ts. If hashing scheme changes, both must update in lockstep.

F7: Unused constants — FAIL
ZAP_PLOTLINK, UNISWAP_V4_ROUTER, UNISWAP_V4_QUOTER, PERMIT2, and RESERVE_LABEL are defined but never imported anywhere in the codebase. Dead code — remove or clearly mark as roadmap placeholders.

---

G. Mainnet Deployment Switchover

G1: Create a mainnet deployment checklist — FAIL
No deployment checklist exists anywhere in the repository. Only a comment in constants.ts saying "Swap to mainnet addresses before production deployment."

G2: No mainnet integration test path — FAIL
No integration tests, no fork-test setup, no test configuration found. There is no way to validate contract interactions against mainnet state before deployment.

G3: Reserve token label accuracy — CONCERN
RESERVE_LABEL = IS_TESTNET ? "WETH" : "$PLOT" is logically correct but is never imported or used anywhere — dead code. The $PLOT mainnet token address is still a zero placeholder.

---

Summary

Section	FAILs	CONCERNs	PASSes
A. ABI Consistency	4	0	1
B. Hardcoded Values	4	6	2
C. Mainnet Readiness	3	3	0
D. Security	1	3	2
E. Logic/Correctness	5	3	0
F. Duplication	7	0	0
G. Deployment	2	1	0
Total	26	16	5

Mainnet Blockers (must fix before deployment)

1. A2/E1 — getRoyaltyInfo ABI mismatch between SDK and web app (wrong argument order + output arity)
2. A3/E2 — claimRoyalties semantic mismatch (storyline token vs reserve token)
3. C1 — StoryFactory mainnet address is zero (partially guarded)
4. C2 — PLOT_TOKEN mainnet address is zero with NO override mechanism
5. C5 — SDK has no mainnet addresses
6. B7 — DEPLOYMENT_BLOCK is testnet-only
7. D2 — Backfill cron silently fails open without CRON_SECRET
8. E6/E7 — Backfill permanently loses data on IPFS failure
9. G1 — No mainnet deployment checklist exists

Recommended Follow-Up Tickets

• Fix getRoyaltyInfo / claimRoyalties ABI to match deployed contract (A2, A3, E1, E2)
• Add mainnet addresses and env var override for PLOT_TOKEN (C1, C2, C5)
• Fix backfill cursor advancement on partial failure (E6, E7)
• Add backfill plot title extraction (E3)
• Extract shared IPFS constants and error helper (B1, B2, F3, F4)
• Consolidate ABI to single source of truth (F2)
• Add content size limit to indexer IPFS fetches (D3)
• Fail closed on missing CRON_SECRET in production (D2)
• Create mainnet deployment checklist (G1)
• Remove unused constants (F7)

[project7-interns]

T2a independent contract integration audit report.

Mainnet blockers from my pass:

• Royalty ABI/use mismatch in the SDK (packages/sdk/src/abi.ts:131-148, packages/sdk/src/client.ts:502-533). I verified with raw eth_call against both deployed MCV2_Bond addresses that getRoyaltyInfo(address,address) returns 64 bytes, i.e. two uint256 values, not one.
• Mainnet critical addresses are still zeroed in the web app (lib/contracts/constants.ts:28-41).
• The configured ERC-8004 registry address is not actually cross-chain: cast code 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 --rpc-url https://sepolia.base.org returned 0x, while Base mainnet has code there.
• Backfill can permanently lose events on partial failures because it skips bad IPFS rows and still advances the cursor (src/app/api/cron/backfill/route.ts:165, :265-266).

A1: FAIL — ABI drift is already real. lib/price.ts:60-79 disagrees with packages/sdk/src/abi.ts:131-148 on the royalty surface, and the MCV2 extension ABI in lib/price.ts is a third source of truth.

A2: FAIL — The SDK royalty ABI is wrong. Live eth_call against Sepolia 0x5dfA75... and mainnet 0xc5a076... returned two 32-byte words for getRoyaltyInfo(address,address), matching the web ABI shape in lib/price.ts:62-72, not the SDK single-uint256 ABI in packages/sdk/src/abi.ts:134-140. packages/sdk/src/client.ts:503-510 therefore truncates/retags the result incorrectly.

A3: FAIL — The SDK treats claimRoyalties() as if it accepts the storyline token address (packages/sdk/src/client.ts:520-527), while the web integration consistently treats it as the reserve token (lib/price.ts:75-78, src/components/ClaimRoyalties.tsx:70-75). This is a semantic mismatch on a value-moving mainnet path.

A4: CONCERN — Web and SDK event ABIs are internally consistent for StorylineCreated, PlotChained, Donation, and Registered (lib/contracts/abi.ts, packages/sdk/src/abi.ts, lib/contracts/erc8004.ts). I could not fully verify StoryFactory/Registry event metadata against explorer-pinned verified ABIs from this repo alone, and StoryFactory mainnet is not deployed yet.

A5: CONCERN — I verified the deployed MCV2_Bond accepts the 4-arg mint(address,uint256,uint256,address) selector used by lib/price.ts/TradingWidget.tsx, and rejects the 3-arg form, so that surface appears aligned. Exact explorer-side verification for StoryFactory and ERC-8004 function metadata is still missing in-tree.

B1: CONCERN — IPFS_GATEWAY is duplicated in src/app/api/index/storyline/route.ts:15, src/app/api/index/plot/route.ts:14, and src/app/api/cron/backfill/route.ts:12.

B2: CONCERN — IPFS_TIMEOUT_MS = 10_000 is duplicated in the same three files.

B3: CONCERN — Gas limits are hardcoded in src/hooks/useChainPlot.ts:31, src/components/TradingWidget.tsx:110-145, and src/components/DonateWidget.tsx:81-86. There is no evidence in-tree that these numbers were profiled for mainnet.

B4: CONCERN — SLIPPAGE_BPS = 300 is hardcoded in src/components/TradingWidget.tsx:14 with no user override.

B5: CONCERN — BLOCKS_PER_24H = 43200 in lib/price.ts:167-181 bakes in a 2s Base cadence. Probably acceptable for UI analytics, but it is an undocumented approximation.

B6: PASS — SCAN_BLOCKS = 200 in src/app/api/cron/backfill/route.ts:19 covers more than five minutes of 2s blocks, so the cron should keep up under normal conditions.

B7: FAIL — The SDK DEPLOYMENT_BLOCK is a Sepolia-only default (packages/sdk/src/constants.ts:18-23) but is still used as the generic fromBlock in packages/sdk/src/client.ts:300 and :337. Mainnet consumers have no safe default.

B8: CONCERN — The fixed 5s delay before indexing in src/hooks/usePublish.ts:115 and src/components/DonateWidget.tsx:95 is brittle. It may be too short under RPC lag and too long when receipts propagate immediately.

B9: CONCERN — The 1h EIP-712 deadline in packages/sdk/src/client.ts:444-468 is reasonable, but it is another unconfigurable magic number on a signing path.

B10: FAIL — The trading and donation UIs hardcode 18 decimals via parseUnits(..., 18) / formatUnits(..., 18) in src/components/TradingWidget.tsx:36-39,223,232 and src/components/DonateWidget.tsx:30-33,149,158,170. lib/price.ts:245-255 already proves reserve decimals can vary and should be read on-chain.

B11: CONCERN — Filebase endpoint/region are hardcoded in packages/sdk/src/ipfs.ts:20-22. Fine if permanent, but it is a deployment assumption.

B12: CONCERN — Retry policy is scattered across packages/sdk/src/ipfs.ts:68-87, lib/rpc.ts:29-36, and other call sites with different backoff schemes.

C1: FAIL — Mainnet STORY_FACTORY still falls back to the zero address in lib/contracts/constants.ts:28-31.

C2: FAIL — Mainnet PLOT_TOKEN still falls back to the zero address in lib/contracts/constants.ts:39-41. Trading and donating would approve/read the zero address.

C3: CONCERN — ZAP_PLOTLINK is permanently zero in lib/contracts/constants.ts:34. If it is not part of launch, it should not be represented as a live contract constant.

C4: FAIL — The ERC-8004 registry is treated as chain-agnostic in lib/contracts/constants.ts:77-78 and packages/sdk/src/constants.ts:40-42, but the configured address has no code on Base Sepolia (cast code ... --rpc-url https://sepolia.base.org => 0x). That means current testnet agent-registry reads/writes cannot actually work against the configured address.

C5: FAIL — SDK defaults are Sepolia-only (packages/sdk/src/constants.ts:32-42). Mainnet users must override every meaningful address plus deployment block, which is not encoded as a safe default.

C6: FAIL — Both lib/contracts/constants.ts:14 and lib/rpc.ts:4 silently default to Sepolia. A missing production env var sends the app to the wrong chain instead of failing closed.

D1: CONCERN — The indexer routes are unauthenticated (src/app/api/index/storyline/route.ts, src/app/api/index/plot/route.ts, src/app/api/index/donation/route.ts). Integrity checks prevent forged content, but the endpoints are still open to RPC/IPFS/DB abuse.

D2: FAIL — Backfill auth is optional by default (src/app/api/cron/backfill/route.ts:22-26). If CRON_SECRET is absent in production, anyone can drive backfill work.

D3: CONCERN — IPFS bodies are read with res.text() and no size guard in the indexers/backfill (src/app/api/index/storyline/route.ts:104-117, src/app/api/index/plot/route.ts:78-89, src/app/api/cron/backfill/route.ts:29-37). Timeout alone does not cap payload size.

D4: PASS — lib/content.ts:16-17 uses keccak256(toHex(content)), which is the UTF-8 byte sequence Solidity hashes for abi.encodePacked(string). This matches the intended integrity check.

D5: PASS — The unique constraints backing onConflict: "tx_hash,log_index" exist in supabase/migrations/00001_schema.sql:24-25, :46, and :64.

D6: CONCERN — lib/reconcile.ts:13-41 is eventually consistent, not atomic. Concurrent plot indexing can transiently write a stale count, though later reconciliation should self-heal.

E1: FAIL — packages/sdk/src/client.ts:502-510 passes (tokenAddress, beneficiary) into getRoyaltyInfo, but the live contract/web ABI shape is (wallet, reserveToken). That means the SDK reads the wrong slot even before the one-vs-two-output issue.

E2: FAIL — packages/sdk/src/client.ts:520-527 calls claimRoyalties(tokenAddress). The rest of the app claims against the reserve token (src/components/ClaimRoyalties.tsx:70-75), so the SDK path is inconsistent and likely wrong.

E3: FAIL — Backfill drops plot titles. processPlotChained() in src/app/api/cron/backfill/route.ts:261-281 never writes title, while the online plot indexer does at src/app/api/index/plot/route.ts:106-118.

E4: CONCERN — The code repeatedly narrows bigint to Number() for IDs and blocks (src/app/api/cron/backfill/route.ts:166,173, indexers, etc.). Safe today, but it is a latent long-horizon precision bug.

E5: CONCERN — Exact-amount approvals in src/components/TradingWidget.tsx:93-100,128-135 and src/components/DonateWidget.tsx:68-75 are safer but expensive on mainnet UX.

E6: FAIL — src/app/api/cron/backfill/route.ts:264-266 silently drops plots whose IPFS fetch/hash validation fails, with no retry queue or cursor rollback.

E7: FAIL — src/app/api/cron/backfill/route.ts:164-167 advances backfill_cursor to toBlock even when some events failed earlier in the loop. That permanently skips those events.

E8: CONCERN — src/app/api/index/storyline/route.ts:136-176 can temporarily leave storylines.plot_count = 1 without a corresponding genesis plot row if step 9 fails after step 8 succeeds.

F1: CONCERN — lib/viem.ts is only a re-export shim, and backfill still imports from it while the rest of the app uses lib/rpc.

F2: CONCERN — ABI definitions are split across lib/contracts/abi.ts, packages/sdk/src/abi.ts, and lib/price.ts; A1 shows this is already creating behavioral divergence.

F3: CONCERN — The same error() helper is duplicated in all three indexer routes.

F4: CONCERN — IPFS_GATEWAY and IPFS_TIMEOUT_MS are duplicated across indexers/backfill as noted in B1/B2.

F5: CONCERN — publicClient import paths are inconsistent (lib/viem in backfill, lib/rpc elsewhere), which makes the integration surface harder to reason about.

F6: CONCERN — hashContent() is duplicated in lib/content.ts and packages/sdk/src/client.ts:598-599.

F7: CONCERN — ZAP_PLOTLINK, UNISWAP_V4_ROUTER, UNISWAP_V4_QUOTER, and PERMIT2 remain defined in lib/contracts/constants.ts:33-71 despite not being part of the current live integration path.

G1: FAIL — I do not see an explicit mainnet switchover checklist in-tree covering contract addresses, envs, deployment block, cron secret, or backfill initialization.

G2: CONCERN — I do not see a documented staging/mainnet-readiness path that exercises live mainnet RPCs with isolated storage.

G3: CONCERN — RESERVE_LABEL in lib/contracts/constants.ts:43-44 assumes the unresolved mainnet reserve asset is $PLOT. Until PLOT_TOKEN is finalized, this is still an unchecked launch assumption.

Net: I count the main launch blockers as A1-A3, B7, B10, C1-C2, C4-C6, D2, E1-E3, E6-E7, and G1.

[realproject7]

Update: Contracts Source Available

Reviewers should also check the actual Solidity source in the contracts repo:

• Repo: realproject7/plotlink-contracts
• Local path: ~/Projects/plotlink-contracts
• Key files:
  • src/StoryFactory.sol — the core contract (createStoryline, chainPlot, donate)
  • src/interfaces/IMCV2_Bond.sol — Mint Club V2 interface with exact function signatures (mint, burn, getReserveForToken, getRefundForTokens, claimRoyalties)

This was not referenced in the original checklist. If you are re-reviewing, verify your ABI findings against these source files in addition to the deployed contracts and upstream Mint Club V2 repo.

[realproject7]

T2-3: ABI Re-verification Against plotlink-contracts Source

Re-checked A1–A5 against the actual Solidity source in realproject7/plotlink-contracts (per pinned comment):

• StoryFactory.sol — src/StoryFactory.sol
• IMCV2_Bond.sol — src/interfaces/IMCV2_Bond.sol

---

A1: CONFIRM FAIL

ABI drift is real. lib/contracts/abi.ts and packages/sdk/src/abi.ts match for StoryFactory. lib/price.ts and SDK disagree on MCV2 royalty functions. PlotLink IMCV2_Bond.sol:52 explicitly defines claimRoyalties(address reserveToken) — web is correct, SDK is wrong.

---

A2: CONFIRM FAIL

getRoyaltyInfo is not in PlotLink IMCV2_Bond.sol (it lives in upstream MCV2_Royalty). Verified against upstream Steemhunt/mint.club-v2-contract: getRoyaltyInfo(address wallet, address reserveToken) returns (uint256, uint256). Web lib/price.ts:62-72 matches. SDK packages/sdk/src/abi.ts:131-142 defines (token, beneficiary) and single output — wrong.

---

A3: CONFIRM FAIL

PlotLink IMCV2_Bond.sol:52:

function claimRoyalties(address reserveToken) external;

Web lib/price.ts:76-79: inputs: [{ name: "reserveToken" }] ✓
SDK packages/sdk/src/abi.ts:143-148: inputs: [{ name: "token" }] ✗

SDK client passes storyline token; contract expects reserve token. Verdict unchanged.

---

A4: CONFIRM PASS

StoryFactory.sol events match web/SDK ABIs exactly:

Event	StoryFactory.sol	Web/SDK ABI
StorylineCreated	(uint256 indexed storylineId, address indexed writer, address tokenAddress, string title, bool hasDeadline, string openingCID, bytes32 openingHash)	✓ Match
PlotChained	(uint256 indexed storylineId, uint256 indexed plotIndex, address indexed writer, string title, string contentCID, bytes32 contentHash)	✓ Match
Donation	(uint256 indexed storylineId, address indexed donor, uint256 amount)	✓ Match

Parameter names, types, and indexed flags are correct.

---

A5: CONFIRM PASS (with minor note)

StoryFactory functions — Match StoryFactory.sol exactly:

• createStoryline(title, openingCID, openingHash, hasDeadline) → storylineId ✓
• chainPlot(storylineId, title, contentCID, contentHash) ✓
• donate(storylineId, amount) ✓

IMCV2_Bond / MCV2 — IMCV2_Bond.sol defines: mint, burn, getReserveForToken, getRefundForTokens, claimRoyalties. All match. getReserveForToken and getRefundForTokens return tuples (reserveAmount, royalty) / (refundAmount, royalty) per interface; web ABI declares only the first output. Viem typically decodes the first element when one output is declared — TradingWidget uses that value. Works in practice; ABI is technically incomplete but not a correctness bug.

---

Net: A1–A3 verdicts unchanged (FAIL). A4–A5 confirmed PASS against PlotLink contract source.

[realproject7]

T2-2 ABI Re-check Update

Re-checked A1-A5 against the actual contracts source called out in the pinned comment:

• /Users/cho/Projects/plotlink-contracts/src/StoryFactory.sol
• /Users/cho/Projects/plotlink-contracts/src/interfaces/IMCV2_Bond.sol

This updates my earlier ABI verdicts as follows.

• A1: FAIL — Confirmed, and broader than my first pass. Source proves there is already real drift across the app/SDK ABI copies:

  • IMCV2_Bond.mint(...) and burn(...) both return uint256, but lib/price.ts models them with no outputs.
  • IMCV2_Bond.getReserveForToken(...) and getRefundForTokens(...) both return two values (amount, royalty), but lib/price.ts models each with only one output.
  • SDK royalty ABI still disagrees with the web ABI as previously noted.

• A2: FAIL — Verdict unchanged. plotlink-contracts does not expose getRoyaltyInfo in IMCV2_Bond.sol, but it does confirm the royalty surface is reserve-token based via claimRoyalties(address reserveToken). There is still no source support for the SDK shape (token, beneficiary) -> uint256. My earlier conclusion stands: the SDK ABI/client is wrong, while the web shape matches the Mint Club royalty source.

• A3: FAIL — Confirmed directly by source. IMCV2_Bond.sol defines claimRoyalties(address reserveToken) external;. The web ABI is aligned. The SDK/CLI path that passes the storyline token address is not.

• A4: CONCERN — StoryFactory.sol confirms the app/web SDK event ABIs for StorylineCreated, PlotChained, and Donation are correct against the current Solidity source. I am keeping the overall checklist item at CONCERN because the pinned source repo does not include the ERC-8004 registry source, so I still cannot verify Registered against the actual PlotLink contracts source.

• A5: FAIL — Updated from CONCERN to FAIL. StoryFactory.createStoryline, chainPlot, and donate match the current source. But IMCV2_Bond.sol proves several exact signature mismatches in the app ABI layer:

  • mint(address,uint256,uint256,address) returns (uint256)
  • burn(address,uint256,uint256,address) returns (uint256)
  • getReserveForToken(address,uint256) returns (uint256 reserveAmount, uint256 royalty)
  • getRefundForTokens(address,uint256) returns (uint256 refundAmount, uint256 royalty)
  • claimRoyalties(address reserveToken)

Additional note from the contracts repo: script/MeasureGas.s.sol and its broadcast/.../run-latest.json artifact are stale relative to src/StoryFactory.sol and still show a 3-arg chainPlot(...) call path. I did not use those artifacts as the source of truth; src/StoryFactory.sol is the authoritative contract source for this re-check.

[realproject7]

T2-1 Re-Review: ABI Findings A1–A5 Verified Against Solidity Source

Re-checked against the actual Solidity source in realproject7/plotlink-contracts:

• src/StoryFactory.sol — events and write functions
• src/interfaces/IMCV2_Bond.sol — Mint Club V2 interface used by StoryFactory

---

A1: FAIL — Confirmed, with additional detail

ABI duplication drift is real and verified against Solidity source.

Comparing IMCV2_Bond.sol against the three ABI locations:

Function	Solidity Source (IMCV2_Bond.sol)	Web ABI (lib/price.ts)	SDK ABI (packages/sdk/src/abi.ts)
getReserveForToken	returns (uint256 reserveAmount, uint256 royalty)	✗ 1 output (reserveAmount) — missing royalty	Not defined
getRefundForTokens	returns (uint256 refundAmount, uint256 royalty)	✗ 1 output (refundAmount) — missing royalty	Not defined
mint	returns (uint256)	✗ outputs: [] — missing return	Not defined
burn	returns (uint256)	✗ outputs: [] — missing return	Not defined
claimRoyalties	(address reserveToken)	✓ (reserveToken)	✗ (token) — wrong name/semantics
getRoyaltyInfo	Inherited from MCV2_Royalty: (address wallet, address reserveToken) → (uint256, uint256)	✓ Correct	✗ (token, beneficiary) → (unclaimed) — wrong
priceForNextMint	(address token) → (uint128)	✓ Correct	✓ Correct
tokenBond	struct mapping	✓ Correct	✓ Correct

Impact of the getReserveForToken/getRefundForTokens single-output ABI: When viem decodes a 2-tuple response against a 1-output ABI, it returns only the first value. So TradingWidget.tsx gets the reserveAmount/refundAmount correctly, but silently drops the royalty value. The buy/sell price estimates shown to users exclude the royalty component. With 5% mint/burn royalty (per StoryFactory.sol:53-54), displayed estimates could be ~5% off from actual cost. The 3% slippage tolerance (SLIPPAGE_BPS = 300) does NOT fully absorb a 5% royalty — users may experience unexpected reverts on buy orders when the actual cost (including royalty) exceeds maxReserveAmount.

Updated severity: This is a functional bug, not just an ABI cleanliness issue. Recommend upgrading to a mainnet concern or blocker.

---

A2: FAIL — Confirmed

Verified via Solidity source chain: StoryFactory.sol calls BOND.updateBondCreator(tokenAddress, msg.sender) (line 128), making the storyline writer the royalty beneficiary. Royalties are claimed via MCV2_Royalty.claimRoyalties(address reserveToken) and queried via MCV2_Royalty.getRoyaltyInfo(address wallet, address reserveToken).

The web app ABI (lib/price.ts:62-72) correctly mirrors this: getRoyaltyInfo(wallet, reserveToken) → (balance, claimed).

The SDK ABI (packages/sdk/src/abi.ts:131-141) is wrong:

• Input names: (token, beneficiary) instead of (wallet, reserveToken) — semantically inverted
• Outputs: single unclaimed instead of (balance, claimed) tuple

The SDK client (client.ts:503) calls getRoyaltyInfo(tokenAddress, beneficiary) — passing the storyline token where the contract expects a wallet address. This returns meaningless data.

Verdict unchanged: FAIL — MAINNET BLOCKER.

---

A3: FAIL — Confirmed

Verified directly from IMCV2_Bond.sol:52:

function claimRoyalties(address reserveToken) external;

The web ABI (lib/price.ts:76-79) correctly uses reserveToken. The SDK ABI (packages/sdk/src/abi.ts:143-148) uses token — and the SDK client (client.ts:521) passes tokenAddress (the storyline ERC-20 token), not the reserve token (WETH/$PLOT). Claims will target the wrong asset.

Additionally, from StoryFactory.sol:119, the reserve token is always PLOT_TOKEN (immutable, set at construction). The SDK claimRoyalties method needs to resolve the actual reserve token — either by:

1. Reading tokenBond(tokenAddress) to get reserveToken from index [4], then calling claimRoyalties(reserveToken), or
2. Accepting the reserve token as a parameter

Verdict unchanged: FAIL — MAINNET BLOCKER.

---

A4: PASS — Confirmed against Solidity source

All three events verified line-by-line against StoryFactory.sol:

Event	Solidity (StoryFactory.sol)	Web ABI (lib/contracts/abi.ts)	SDK ABI (packages/sdk/src/abi.ts)
StorylineCreated	(uint256 indexed storylineId, address indexed writer, address tokenAddress, string title, bool hasDeadline, string openingCID, bytes32 openingHash) — line 28-36	✓ Exact match	✓ Exact match
PlotChained	(uint256 indexed storylineId, uint256 indexed plotIndex, address indexed writer, string title, string contentCID, bytes32 contentHash) — line 38-45	✓ Exact match	✓ Exact match
Donation	(uint256 indexed storylineId, address indexed donor, uint256 amount) — line 47	✓ Exact match	✓ Exact match

The Registered event for ERC-8004 was not verifiable from this contracts repo (no ERC-8004 source present in plotlink-contracts). However, both the web app (lib/contracts/erc8004.ts) and SDK copies are identical: Registered(uint256 indexed agentId, string agentURI, address indexed owner).

Upgrading from my original PASS to confirmed PASS — event signatures are now verified against source, not just by inference from decoder behavior.

---

A5: CONCERN → Partial FAIL — Updated with Solidity source findings

StoryFactory functions — all PASS:

Function	Solidity Source	Web ABI	SDK ABI
createStoryline(string, string, bytes32, bool) → uint256 (line 102)	✓	✓	✓
chainPlot(uint256, string, string, bytes32) (line 154)	✓	✓	✓
donate(uint256, uint256) (line 177)	✓	✓	✓

MCV2_Bond functions — mixed:

Function	Solidity Source (IMCV2_Bond.sol)	Web ABI	SDK ABI
priceForNextMint(address) → uint128	✓	✓	✓
tokenBond(address) → (address, uint16, uint16, uint40, address, uint256)	✓	✓	✓
mint(address, uint256, uint256, address) → uint256 (line 31)	✗ web has outputs: []	N/A (SDK)
burn(address, uint256, uint256, address) → uint256 (line 37)	✗ web has outputs: []	N/A (SDK)
getReserveForToken(address, uint256) → (uint256, uint256) (line 40-43)	✗ web has 1 output	N/A (SDK)
getRefundForTokens(address, uint256) → (uint256, uint256) (line 46-49)	✗ web has 1 output	N/A (SDK)

ERC-8004 functions — register, setAgentWallet, agentIdByWallet are not in this contracts repo. Cannot verify against source. Both web/SDK copies are identical, and the setAgentWallet EIP-712 flow works on testnet per other reviewers.

Updated verdict: A5 is now a partial FAIL for the 4 MCV2_Bond function return types that don't match the interface. The getReserveForToken/getRefundForTokens mismatch in particular has functional consequences (see A1 detail above — 5% royalty excluded from estimates, potential buy reverts).

---

Summary of Changes from Original Review

Item	Original Verdict	Updated Verdict	Change Reason
A1	FAIL	FAIL (upgraded severity)	Solidity source confirms getReserveForToken/getRefundForTokens return 2 values including royalty; 5% royalty exclusion from estimates may cause user-facing reverts
A2	FAIL	FAIL — confirmed	getRoyaltyInfo(wallet, reserveToken) verified in MCV2_Royalty; SDK remains wrong
A3	FAIL — BLOCKER	FAIL — BLOCKER confirmed	claimRoyalties(address reserveToken) confirmed in IMCV2_Bond.sol:52; SDK passes wrong token type
A4	PASS	PASS — confirmed	All 3 StoryFactory events verified line-by-line against Solidity source
A5	CONCERN	Partial FAIL	4 MCV2_Bond return types confirmed wrong via IMCV2_Bond.sol; StoryFactory functions all match

New recommended blocker from this re-review: Fix getReserveForToken/getRefundForTokens web ABI to return 2 values and update TradingWidget.tsx to display the royalty-inclusive cost. Without this, buy orders with the current 3% slippage will fail when 5% royalty is applied.

---

T2-1 re-review complete. Verified against realproject7/plotlink-contracts Solidity source as requested.