From 699c1a315070b85bb96878ef42abfdfcd1f0401f Mon Sep 17 00:00:00 2001
From: Joshua <vsg@Joshuas-Mac-Studio.local>
Date: Tue, 17 Feb 2026 14:38:53 -0800
Subject: [PATCH] Seed contracts repo scaffold and interface notes

---
 README.md                    | 14 ++++++++++++++
 docs/contract-roadmap.md     | 14 ++++++++++++++
 docs/deployment-checklist.md |  8 ++++++++
 docs/interfaces.md           | 19 +++++++++++++++++++
 4 files changed, 55 insertions(+)
 create mode 100644 README.md
 create mode 100644 docs/contract-roadmap.md
 create mode 100644 docs/deployment-checklist.md
 create mode 100644 docs/interfaces.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d792fe9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,14 @@
+# EDUT Contracts
+
+On-chain contracts and deployment artifacts for membership and entitlements.
+
+## Scope
+
+1. Membership contract (soulbound utility access).
+2. Offer registry contract interfaces.
+3. Entitlement contract interfaces.
+4. ABI and deployment artifact publication.
+
+## Boundary
+
+Contracts are settlement primitives. Runtime execution remains off-chain and fail-closed by entitlement state.
diff --git a/docs/contract-roadmap.md b/docs/contract-roadmap.md
new file mode 100644
index 0000000..7d23b00
--- /dev/null
+++ b/docs/contract-roadmap.md
@@ -0,0 +1,14 @@
+# Contracts Roadmap
+
+## Scope
+
+1. Membership contract (soulbound).
+2. Offer registry contract.
+3. Entitlement contract.
+
+## Requirements
+
+1. One ownership wallet can hold membership + multiple entitlements.
+2. Membership contract supports deterministic pricing policy inputs.
+3. Entitlement minting records recipient ownership wallet.
+4. Contract events are sufficient for backend reconciliation.
diff --git a/docs/deployment-checklist.md b/docs/deployment-checklist.md
new file mode 100644
index 0000000..2f5f33a
--- /dev/null
+++ b/docs/deployment-checklist.md
@@ -0,0 +1,8 @@
+# Contracts Deployment Checklist
+
+1. Compile and verify bytecode reproducibility.
+2. Deploy contracts to target chain.
+3. Publish contract addresses and ABI.
+4. Verify source on block explorer.
+5. Record deployment evidence and policy hash snapshot.
+6. Update dependent repos with versioned addresses.
diff --git a/docs/interfaces.md b/docs/interfaces.md
new file mode 100644
index 0000000..ead2b0c
--- /dev/null
+++ b/docs/interfaces.md
@@ -0,0 +1,19 @@
+# Contracts Interface Notes
+
+## Core Contracts
+
+1. Membership contract (soulbound utility access).
+2. Offer registry contract.
+3. Entitlement contract.
+
+## Required Events
+
+1. `MembershipMinted`
+2. `MembershipStatusUpdated`
+3. `OfferUpserted`
+4. `EntitlementMinted`
+5. `EntitlementStateChanged`
+
+## Backend Dependency
+
+Backend must reconcile on-chain events into deterministic membership/entitlement status for runtime gates.