security: replace legacy Basis contracts with reviewed v2 generation

AGENTS.md

@@ -6,7 +6,22 @@ This document describes the agent-based architecture of the ChainCash protocol -
 
 ChainCash implements a decentralized monetary system where different agents manage the lifecycle of digital notes backed by collateral and trust. The system enables self-sovereign banking where each participant can issue, transfer, and redeem digital currency.
 
-## Core On-Chain Agents
+## Current Lifecycle Boundary
+
+Only the Basis v2 and Basis-token v2 candidate sources remain in the production
+contract surface. Basis v1, the original `contracts/onchain` family, the
+`contracts/layer2-old` experiments, their transaction builders, participant
+secret helpers, and their address/scan-rule printers are retired. Exact old
+source snapshots now live under `src/test/resources` solely for historical
+regression tests; never use them to derive an address, build a transaction, or
+infer deployment status. The removed Scala helpers remain available in Git
+history at the pinned commit below.
+
+The sections describing the original ChainCash on-chain agents and flows below
+are historical design context. Their old paths refer to the source layout at
+commit `78475e30362571acf56e4e38276a9d6c0a84ce0c`, not active production files.
+
+## Historical On-Chain Agents
 
 ### Reserve Contract Agent
 **File**: `contracts/onchain/reserve.es`
@@ -57,6 +72,10 @@ ChainCash implements a decentralized monetary system where different agents mana
 
 ## Off-Chain Management Agents
 
+The legacy reserve/note construction helpers described in this section are
+historical and are no longer compiled. Read-only tracking code remains only to
+support a future, separately reviewed inventory of any old state.
+
 ### Wallet Agent
 **File**: `src/main/scala/chaincash/offchain/WalletUtils.scala`
 
@@ -114,7 +133,10 @@ ChainCash implements a decentralized monetary system where different agents mana
 - Event processing and persistence
 
 ### Basis Tracker Agent
-**File**: `contracts/offchain/tracker.md` (documentation), `demo/basis/simple/src/TrackerBoxSetup.scala` (setup)
+**Historical files**:
+`src/test/resources/contracts/historical/offchain/tracker.md`. The former
+`demo/basis/simple/src/TrackerBoxSetup.scala` walkthrough is available only in
+Git history at commit `78475e30362571acf56e4e38276a9d6c0a84ce0c`.
 
 **Responsibilities**:
 - Tracks complete state of debt for all issuers (with or without on-chain reserves)
@@ -141,7 +163,9 @@ ChainCash implements a decentralized monetary system where different agents mana
   - Enables true escape from tracker unavailability
 - Anti-censorship protection (previously witnessed notes can still be redeemed)
 
-**See Also**: `contracts/offchain/basis.md` for Basis protocol design, `contracts/offchain/tracker.md` for detailed tracker architecture
+**See Also**: the test-only `offchain/basis.md` and `offchain/tracker.md`
+fixtures for the historical v1 design; use `contracts/offchain/basis-v2.md` for
+the active candidate ABI.
 
 ## Server Agent
 
@@ -227,8 +251,9 @@ Creditor → Reserve Agent (after timeout)
 ```
 
 ### Reserve Owner Refund (Censorship-Resistant Exit)
-Implemented in both `contracts/offchain/basis.es` (ERG reserve) and
-`contracts/offchain/basis-token.es` (token reserve).
+Historically implemented in the test-only fixtures
+`src/test/resources/contracts/historical/offchain/basis.es` (ERG reserve) and
+`src/test/resources/contracts/historical/offchain/basis-token.es` (token reserve).
 ```
 Reserve Owner (two-phase, unilateral)
 1. Initiate refund (action #2): owner signs tx setting R7 to initiation height
@@ -307,4 +332,4 @@ See test files in `src/test/scala/chaincash/` for detailed agent testing.
 
 ---
 
-*This architecture enables a global monetary system with decentralized issuance where each participant can define their own acceptance rules while maintaining collective backing through the spending chain.*
+*This architecture enables a global monetary system with decentralized issuance where each participant can define their own acceptance rules while maintaining collective backing through the spending chain.*

README.md

@@ -4,6 +4,18 @@ This repository contains whitepaper and some prototyping code for
 ChainCash, a protocol to create money in self-sovereign way via trust or collateral, with collective backing and 
 individual acceptance. 
 
+## Protocol Lifecycle
+
+The original on-chain reserve/note/receipt prototype and the experimental
+Layer-2 prototype are historical, test-only sources. They are not compiled,
+addressed, or activated by production code. See
+[`docs/legacy-contract-retirement.md`](docs/legacy-contract-retirement.md).
+
+The production-code contract surface contains only the reviewed Basis v2
+candidate sources and their frozen full-ErgoTree goldens. Basis v1 is also
+retired to test-only fixtures. No deployment, signing, submission, broadcast
+or in-place migration path is provided.
+
 ## Intro 
 
 We consider money as a set of digital notes, and every note is collectively backed 
@@ -47,21 +59,12 @@ More introductory materials:
 * [Video presentation from Ergo Summit](https://www.youtube.com/watch?v=NxIlIpO6ZVI)
 * [Video: ChainCash, part two](https://www.youtube.com/watch?v=fk8ZFvNFDYc)
 
-## Basis Demo
-
-A simple demonstration of the Basis reserve protocol is available in `demo/basis/simple/`:
+## Retired Basis v1 demos
 
-```bash
-cd demo/basis/simple
-
-# Generate redemption transaction
-sbt "runMain chaincash.contracts.BasisNoteRedeemer --note-json note.json --reserve-box auto --tracker-box auto --fee-box <box1>,<box2>,<box3>,<box4> --output sign_request.json"
-
-# Sign with Ergo node
-curl -X POST "http://localhost:9053/wallet/transaction/sign" -H "api_key: hello" -d @sign_request.json
-```
-
-See `demo/basis/simple/README.md` for detailed instructions.
+The former Basis v1 examples and operational walkthroughs are removed from the
+working tree so they cannot be mistaken for supported execution or deployment
+paths. They remain recoverable from Git history at commit
+`78475e30362571acf56e4e38276a9d6c0a84ce0c` for historical research.
 
 ## ChainCash Server
 
@@ -74,15 +77,19 @@ Initial version of [design document](docs/server.md) is also available. The serv
 * Whitepaper - https://github.com/ChainCashLabs/chaincash/blob/master/docs/conf/conf.pdf
 High-level description of ChainCash protocol and its implementation
 
-* Contracts - https://github.com/kushti/chaincash/tree/master/contracts - note and reserve contracts in ErgoScript
+* Contracts - `contracts/offchain/` contains only the Basis v2 candidate family
+  and its exact `.p2s` goldens. Basis v1 and the former on-chain and Layer-2
+  prototypes are pinned historical fixtures under
+  `src/test/resources/contracts/historical/`.
 
 * Modelling - https://github.com/kushti/chaincash/tree/master/src/main/scala/chaincash/model
 Contract-less and blockchain-less models of ChainCash entities and one of notes collateralization 
 estimation options.
-* Tests - https://github.com/kushti/chaincash/blob/master/src/test/scala/kiosk/ChainCashSpec.scala - Kiosk-based tests for transactions involving note
- contracts (note creation, spending, redemption)
-* Offchain part - https://github.com/kushti/chaincash/tree/master/src/main/scala/chaincash/offchain - on-chain data tracking,
-  persistence, transaction builders. This is very rough prototype, at the moment better to look into ChainCash Server which 
+* Tests - `src/test/scala/chaincash/ChainCashSpec.scala` replays the historical
+  note-contract transitions through test-only fixtures.
+* Offchain part - `src/main/scala/chaincash/offchain/` retains rough prototype
+  tracking and persistence code, but no production legacy transaction builder.
+  For application development, prefer ChainCash Server, which
  is available at [https://github.com/BetterMoneyLabs/chaincash-rs](https://github.com/BetterMoneyLabs/chaincash-rs) .
 
 ## Communications
@@ -91,33 +98,16 @@ Join discussion groups for developers and users:
 
 * Telegram: [https://t.me/chaincashtalks](https://t.me/chaincashtalks)
 
-## Deployment Utilities
-
-### Basis Reserve Contract Deployment
+## Candidate-byte inspection
 
-The repository includes deployment utilities for the Basis reserve contract:
+The production commands print only the v2 candidate addresses and the
+source-to-ErgoTree receipt material:
 
 ```scala
-// Run deployment utility
-sbt 'runMain chaincash.contracts.BasisDeployer'
-
-// Or use the contract printer
-sbt 'runMain chaincash.contracts.Constants$Printer'
+sbt 'runMain chaincash.contracts.Printer'
+sbt 'runMain chaincash.contracts.BasisV2ReceiptPrinter'
 ```
 
-This generates deployment requests for the Basis reserve contract, which supports:
-- Off-chain payments with credit creation
-- Redemption with 2% fee
-- Emergency redemption after 7 days
-- Tracker-based debt tracking
-
-See `src/main/scala/chaincash/contracts/README.md` for detailed usage.
-
-## TODO
-
-* update ReserveData.liabilities and reserveKeys in offchain code
-* offchain code for note redemption
-* support few spendings of a note in the same block (offchain tracking of it)
-* support other tokens in reserves, e.g. SigUSD
-* efficient persistence for own notes (currently, all the notes in the system are iterated over)
-* check ERG preservation in note contracts
+These commands do not generate transactions. The printer emits only entries in
+`Constants.publishedContracts`; all v1 and legacy addresses and builders are
+deliberately unavailable from production tooling.

build.sbt

@@ -1,11 +1,11 @@
+import scala.collection.JavaConverters._
+
 name := "chaincash"
 
 version := "0.2.1"
 organization := "org.ergoplatform"
 scalaVersion := "2.12.17"
 
-Compile / unmanagedClasspath += baseDirectory.value / "contracts"
-
 resolvers ++= Seq(
   "Sonatype Releases" at "https://oss.sonatype.org/content/repositories/releases/",
   "SonaType" at "https://oss.sonatype.org/content/groups/public",
@@ -39,3 +39,55 @@ libraryDependencies ++= Seq(
 )
 
 dependencyOverrides += "org.ergoplatform" %% "ergo-appkit" % "6.0.0"
+
+lazy val verifyMainJarRetirement = taskKey[Unit](
+  "Fail if the production JAR contains retired ChainCash or Basis v1 classes/resources"
+)
+
+verifyMainJarRetirement := {
+  val jarPath = (Compile / packageBin).value
+  val log = streams.value.log
+  val jar = new java.util.jar.JarFile(jarPath)
+  try {
+    val entries = jar.entries().asScala.map(_.getName).toVector
+    val forbiddenClassPrefixes = Vector(
+      "chaincash/contracts/BasisDeployer",
+      "chaincash/contracts/BasisConstants",
+      "chaincash/contracts/BasisNoteCreator",
+      "chaincash/contracts/ContractsPrinter",
+      "chaincash/contracts/ParticipantKeys",
+      "chaincash/contracts/ParticipantSecretsReader",
+      "chaincash/offchain/NoteUtils",
+      "chaincash/offchain/ReserveUtils",
+      "chaincash/offchain/Tester"
+    )
+    val forbiddenResources = Set(
+      "contracts/offchain/basis.es",
+      "contracts/offchain/basis-token.es"
+    )
+    val forbiddenResourcePrefixes = Vector(
+      "contracts/historical/",
+      "contracts/onchain/",
+      "contracts/layer2-old/"
+    )
+
+    val forbiddenEntries = entries.filter { entry =>
+      forbiddenClassPrefixes.exists(entry.startsWith) ||
+      forbiddenResources.contains(entry) ||
+      forbiddenResourcePrefixes.exists(entry.startsWith)
+    }
+
+    if (forbiddenEntries.nonEmpty) {
+      sys.error(
+        "Retired ChainCash/Basis v1 entries leaked into the production JAR: " +
+          forbiddenEntries.sorted.mkString(", ")
+      )
+    }
+
+    log.info(s"Verified ${entries.size} production JAR entries: no retired ChainCash/Basis v1 surface")
+  } finally {
+    jar.close()
+  }
+}
+
+Test / test := (Test / test).dependsOn(verifyMainJarRetirement).value

contracts/offchain/README.md

@@ -1,4 +1,24 @@
-Different ChainCash variants for offchain applications.
+# ChainCash off-chain contract candidates
 
+## Active source family
 
-In most cases, reserves are on-chain, notes are created and making progress offchain.
+`basis-v2.es` and `basis-token-v2.es` are the only contract sources exposed by
+production compilation and address tooling. Their committed `.p2s` files are
+the exact full-ErgoTree goldens for this candidate generation.
+
+See `basis-v2.md` for the register and transition ABI, and
+`basis-v2-reproducibility.md` for the source, compiler and full-byte receipt.
+The repository provides no v2 deployment, signing, submission or migration
+builder. A compiled address is not evidence of deployment or production
+readiness.
+
+## Historical sources
+
+The exact Basis v1 contract sources are retained only under
+`src/test/resources/contracts/historical/` for regression tests. Its former
+demos and operational walkthroughs are removed from the working tree and remain
+recoverable at commit `78475e30362571acf56e4e38276a9d6c0a84ce0c`.
+Production `Constants`, printers, classes and the main JAR cannot load or expose
+that generation. Moving the sources does not change the authorization of any
+immutable v1 box; recovery would require a separate inventory and an exit
+already authorized by its exact old ErgoTree.