Merge pull request #205 from PracticalParticle/dev

Dev

Author: JaCoderX

.github/workflows/release-please.yml

@@ -41,5 +41,4 @@ jobs:
           manifest-file: .release-please-manifest.json
           token: ${{ secrets.GITHUB_TOKEN }}
 
-  # Note: Contract version constants are automatically synced via the
-  # sync-contract-versions.yml workflow when Release Please creates a PR
+  # Note: sync-contract-versions.yml verifies EngineBlox.VERSION mirror on release-please PRs

.github/workflows/sync-contract-versions.yml

@@ -1,22 +1,21 @@
-name: Sync Contract Versions
+name: Verify Protocol Version
 
 on:
   pull_request:
     types: [opened, synchronize, reopened]
     branches:
       - main
-      # - dev
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
+  pull-requests: read
 
 jobs:
-  sync-contract-versions:
-    # Only run on PRs created by release-please
+  verify-protocol-version:
+    # Release Please PRs: ensure EngineBlox.VERSION matches in .sol and .tsx
     if: "contains(github.event.pull_request.head.ref, 'release-please') || contains(github.event.pull_request.title, 'chore: release')"
     runs-on: ubuntu-latest
-    
+
     steps:
       - name: Checkout PR branch
         uses: actions/checkout@v4
@@ -33,98 +32,5 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Check for uncommitted changes in version files
-        id: check-uncommitted
-        run: |
-          SOL_CHANGED=false
-          TSX_CHANGED=false
-          if ! git diff --quiet HEAD -- contracts/core/lib/EngineBlox.sol; then
-            SOL_CHANGED=true
-          fi
-          if ! git diff --quiet HEAD -- sdk/typescript/lib/EngineBlox.tsx; then
-            TSX_CHANGED=true
-          fi
-          if [ "$SOL_CHANGED" = true ] || [ "$TSX_CHANGED" = true ]; then
-            echo "❌ ERROR: Version files have uncommitted changes!"
-            echo ""
-            echo "The workflow cannot safely update version constants when there are uncommitted changes."
-            echo "Please commit or stash your changes before this workflow runs."
-            echo ""
-            if [ "$SOL_CHANGED" = true ]; then
-              echo "Uncommitted changes in contracts/core/lib/EngineBlox.sol:"
-              git diff HEAD -- contracts/core/lib/EngineBlox.sol
-            fi
-            if [ "$TSX_CHANGED" = true ]; then
-              echo "Uncommitted changes in sdk/typescript/lib/EngineBlox.tsx:"
-              git diff HEAD -- sdk/typescript/lib/EngineBlox.tsx
-            fi
-            exit 1
-          else
-            echo "✓ EngineBlox.sol and EngineBlox.tsx are clean, safe to proceed with version sync"
-            echo "uncommitted=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Sync versions (including contract constants)
-        run: npm run release:sync-versions
-
-      - name: Check for contract version changes
-        id: check-changes
-        run: |
-          SOL_CHANGED=false
-          TSX_CHANGED=false
-          if ! git diff --quiet contracts/core/lib/EngineBlox.sol; then
-            SOL_CHANGED=true
-          fi
-          if ! git diff --quiet sdk/typescript/lib/EngineBlox.tsx; then
-            TSX_CHANGED=true
-          fi
-          if [ "$SOL_CHANGED" = true ] || [ "$TSX_CHANGED" = true ]; then
-            echo "changed=true" >> $GITHUB_OUTPUT
-            echo "Version changes detected:"
-            [ "$SOL_CHANGED" = true ] && git diff contracts/core/lib/EngineBlox.sol
-            [ "$TSX_CHANGED" = true ] && git diff sdk/typescript/lib/EngineBlox.tsx
-          else
-            echo "changed=false" >> $GITHUB_OUTPUT
-            echo "✓ Contract and SDK version constants already in sync"
-          fi
-
-      - name: Verify only version constants changed
-        if: steps.check-changes.outputs.changed == 'true'
-        id: verify-changes
-        run: |
-          # Get the diff for both version files
-          DIFF_OUTPUT=$(git diff contracts/core/lib/EngineBlox.sol sdk/typescript/lib/EngineBlox.tsx)
-          
-          # All added/removed lines must be a VERSION constant change (.sol: constant VERSION = ... or .tsx: static readonly VERSION: string = ...)
-          ADDED_OR_REMOVED=$(echo "$DIFF_OUTPUT" | grep -E "^[-+]" | grep -v -E "^\+\+\+|^---")
-          OTHER_CHANGES=$(echo "$ADDED_OR_REMOVED" | grep -v -E "constant\s+VERSION\s*=" | grep -v -E "static readonly VERSION: string =")
-          
-          if [ -n "$OTHER_CHANGES" ]; then
-            echo "❌ ERROR: Changes are not limited to VERSION constants!"
-            echo ""
-            echo "The workflow detected changes beyond the VERSION constant in EngineBlox.sol or EngineBlox.VERSION in EngineBlox.tsx."
-            echo "This could indicate uncommitted changes were accidentally included."
-            echo ""
-            echo "Full diff:"
-            echo "$DIFF_OUTPUT"
-            exit 1
-          fi
-          
-          # Require at least one VERSION change (sol or tsx)
-          if ! echo "$DIFF_OUTPUT" | grep -qE "^[-+].*constant\s+VERSION\s*=" && \
-             ! echo "$DIFF_OUTPUT" | grep -qE "^[-+].*static readonly VERSION: string ="; then
-            echo "❌ ERROR: No VERSION constant changes found in diff."
-            exit 1
-          fi
-          
-          echo "✓ Only version constants changed (contract + SDK), safe to commit"
-          echo "safe=true" >> $GITHUB_OUTPUT
-
-      - name: Commit and push contract version updates
-        if: steps.check-changes.outputs.changed == 'true' && steps.verify-changes.outputs.safe == 'true'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add contracts/core/lib/EngineBlox.sol sdk/typescript/lib/EngineBlox.tsx
-          git commit -m "chore: sync contract version constants with package version"
-          git push
+      - name: Verify EngineBlox.VERSION mirror
+        run: node scripts/sync-versions.cjs --verify

.release-please-manifest.json

@@ -1,5 +1,4 @@
 {
-  ".": "1.0.0",
   "package": "1.0.0",
   "sdk/typescript": "1.0.0"
 }

AGENTS.md

@@ -167,6 +167,7 @@ When you need more context:
   - `README.md`
   - `docs/index.md`
   - `docs/getting-started.md`
+  - `docs/VERSIONING.md` (npm vs on-chain protocol version)
   - `docs/account-pattern.md`
 - Look at:
   - Existing tests under `scripts/sanity-sdk`

CHANGELOG.md

@@ -1,78 +1,20 @@
-# Changelog
+# Repository changelog (monorepo)
 
-All notable changes to this project will be documented in this file.
+This file is **not** an npm product changelog. Release history for published packages:
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- [@bloxchain/contracts](./package/CHANGELOG.md)
+- [@bloxchain/sdk](./sdk/typescript/CHANGELOG.md)
 
-## [Unreleased]
+See [docs/VERSIONING.md](./docs/VERSIONING.md) for the full versioning model.
 
-### Added
-- Initial changelog automation with Release Please
-- Automated release workflow via GitHub Actions
+## Experimental alpha line (not documented here)
 
-### Changed
-- Version synchronization across monorepo packages
+Prior npm publishes used `1.0.0-alpha.N` with dist-tag `alpha.24` for development and testing only. That line is **not** listed in the per-package changelogs.
 
-## [1.0.0] - 2025-01-26
+## Stable line
 
-### Added
-- Initial release of Bloxchain Protocol
-- Core state machine engine (EngineBlox)
-- Base state machine contract (BaseStateMachine)
-- Secure ownership implementation (SecureOwnable)
-- Dynamic RBAC system (RuntimeRBAC)
-- Guard controller for execution protection
-- TypeScript SDK for contract interaction
-- Comprehensive test suite with fuzzing and invariant testing
-- Documentation and examples
+The first documented stable releases are **`1.0.0`** on dist-tag **`latest`** for both packages. On-chain `EngineBlox.VERSION` remains **`"1.0.0"`** for the v1 protocol line until a deliberate protocol version change.
 
-### Security
-- Multi-phase security operations with time-locks
-- Reentrancy protection patterns
-- Input validation with custom errors
-- Comprehensive security testing
+## Protocol version (`EngineBlox.VERSION`)
 
----
-
-## Release Types
-
-- **Major** (x.0.0): Breaking changes that require migration
-- **Minor** (x.y.0): New features, backward compatible
-- **Patch** (x.y.z): Bug fixes, backward compatible
-
-## Commit Message Format
-
-This project uses [Conventional Commits](https://www.conventionalcommits.org/) for automated changelog generation via [Release Please](https://github.com/googleapis/release-please).
-
-**Version Bumps** (Release Please default behavior for `node` release type):
-- `feat:` New features **[Minor]** - Triggers version bump
-- `feat!:` Breaking changes **[Major]** - Triggers version bump
-- `fix:` Bug fixes **[Patch]** - Triggers version bump
-- `BREAKING CHANGE:` in commit footer **[Major]** - Triggers version bump
-
-**No Version Bump** (appear in changelog but don't trigger releases):
-- `docs:` Documentation changes
-- `style:` Code style changes (formatting, etc.)
-- `refactor:` Code refactoring
-- `perf:` Performance improvements
-- `test:` Test additions or changes
-- `chore:` Maintenance tasks
-- `ci:` CI/CD changes
-- `build:` Build system changes
-- `revert:` Revert previous commit
-
-**Breaking Changes:**
-
-Breaking changes can be indicated in two ways:
-1. Use `!` after the type: `feat!: change API signature`
-2. Include `BREAKING CHANGE:` in the commit footer:
-   ```text
-   feat(contracts): update interface
-   
-   BREAKING CHANGE: The transferOwnership function now requires an additional parameter
-   ```
-
-**Note:** This follows Release Please's default configuration for the `node` release type, which implements the [Conventional Commits](https://www.conventionalcommits.org/) specification. Releases are only created when there are commits that trigger version bumps (`feat`, `fix`, or breaking changes). Other commit types are included in the changelog but don't trigger new releases on their own.
-
-Example: `feat(contracts): add PayBlox contract implementation`
+On-chain / EIP-712 protocol version bumps are **manual** and rare. Document them here when they occur (in addition to updating `contracts/core/lib/EngineBlox.sol` and `sdk/typescript/lib/EngineBlox.tsx`).

CONTRIBUTING.md

@@ -615,14 +615,30 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/) f
 - **`build`**: Build system or external dependencies changes
 - **`revert`**: Revert a previous commit
 
-### Scope (Optional)
+### Scope (recommended for publishable changes)
 
-The scope should be the name of the package or area affected:
-- `contracts`: Smart contract changes
-- `sdk`: TypeScript SDK changes
-- `docs`: Documentation changes
-- `ci`: CI/CD changes
-- `scripts`: Script changes
+Use a **scope** on every commit that affects a release-managed npm package so history and Release Please attribution stay clear. Allowed scopes (enforced by commitlint): `contracts`, `sdk`, `examples`, `docs`, `ci`, `scripts`, `deps`, `release`.
+
+| Scope | Use when you change… | Release Please package |
+|-------|-------------------|-------------------------|
+| **`contracts`** | `contracts/`, `package/`, Foundry tests for core Solidity, ABI extract affecting the contracts npm artifact | `@bloxchain/contracts` → [package/CHANGELOG.md](./package/CHANGELOG.md) |
+| **`sdk`** | `sdk/typescript/` (sources, build, SDK tests) | `@bloxchain/sdk` → [sdk/typescript/CHANGELOG.md](./sdk/typescript/CHANGELOG.md) |
+| **`examples`** | `contracts/examples/` (sample apps, templates, example tests) | — (not an npm package; no Release Please bump alone) |
+| **`docs`** | `docs/`, root or package README (no semver bump alone) | — |
+| **`ci`** | `.github/workflows/`, CI config | — |
+| **`scripts`** | `scripts/` (release, deploy, sanity runners) | — |
+| **`deps`** | Dependency version bumps at root or in packages | Usually no release unless combined with `feat`/`fix` on a package path |
+| **`release`** | Version manifests, release-please config, changelog policy | — |
+
+Release Please also uses **changed file paths**. If a single commit touches both `package/` and `sdk/typescript/`, both packages may receive changelog entries when their release PRs are cut. Prefer **focused commits** per package when possible.
+
+**Avoid** unscoped `feat:` / `fix:` on publishable paths — use `feat(contracts):` or `feat(sdk):` instead.
+
+### Release attribution (Release Please)
+
+- **Independent semver:** `@bloxchain/contracts` and `@bloxchain/sdk` version separately within major `1` ([docs/VERSIONING.md](./docs/VERSIONING.md)).
+- **On-chain protocol** `EngineBlox.VERSION` is **not** bumped by npm patch releases; it is updated only for deliberate protocol releases.
+- **Changelogs:** npm consumers should read package changelogs, not the repo root [CHANGELOG.md](./CHANGELOG.md).
 
 ### Examples
 
@@ -663,7 +679,7 @@ BREAKING CHANGE: The transferOwnership function now requires an additional param
 
 ### Benefits
 
-- **Automatic changelog generation**: Your commits automatically populate the CHANGELOG.md
+- **Automatic changelog generation**: Release Please updates [package/CHANGELOG.md](./package/CHANGELOG.md) and [sdk/typescript/CHANGELOG.md](./sdk/typescript/CHANGELOG.md) per publishable package (use scopes like `feat(contracts):` or `feat(sdk):`)
 - **Semantic versioning**: Version bumps are determined by commit types
 - **Better git history**: Clear, searchable commit history
 - **Automated releases**: Release PRs are created automatically
@@ -683,26 +699,28 @@ npm run test:truffle
 
 # Commit changes
 git add .
-git commit -m "feat: add new feature"
+git commit -m "feat(sdk): add new feature"
 
 # Push and create PR
 git push origin feature/new-feature
 ```
 
 ### Release Process
 
-Releases are **automated** using Release Please. The process works as follows:
+Releases use **Release Please** on `main`, then **human npm publish** after the release line is on `main`.
+
+1. **Merge feature/fix PRs to `main`** using scoped conventional commits (`feat(contracts):`, `fix(sdk):`, etc.).
+2. **Release Please** opens one or two release PRs (`@bloxchain/contracts`, `@bloxchain/sdk`) with updated versions and per-package changelogs.
+3. **Review and merge** the release PR(s) on `main`. Tags/GitHub releases are created per package.
+4. **Publish to npm** (maintainers, after `main` contains the release versions) — three commands only:
+
+   ```bash
+   npm run release:prepare      # gate: protocol VERSION, build, tests
+   npm run publish:contracts    # @bloxchain/contracts @ latest
+   npm run publish:sdk          # @bloxchain/sdk @ latest
+   ```
 
-1. **Merge PRs to main**: All PRs merged to `main` are analyzed for conventional commits
-2. **Automatic release PR**: Release Please creates a release PR with:
-   - Updated version numbers (semantic versioning based on commit types)
-   - Generated changelog entries
-   - All package versions synchronized
-3. **Review and merge**: Review the release PR, ensure changelog is accurate
-4. **Automatic tag and release**: When the release PR is merged:
-   - A git tag is created
-   - GitHub release is created
-   - Package versions are synced across monorepo
+   The first stable **`1.0.0`** npm publish happens **after** the versioning baseline PR is on `main`, not from long-lived feature branches. See [docs/VERSIONING.md](./docs/VERSIONING.md#publishing-stable-100-to-npm).
 
 #### Manual Release (if needed)
 
@@ -713,8 +731,9 @@ If you need to create a release manually:
 git checkout main
 git pull
 
-# Run release-please locally (requires token)
-npx release-please release-pr --repo-url=github.com/PracticalParticle/Bloxchain-Protocol --token=YOUR_TOKEN
+# Preview Release Please release PR locally (requires token)
+npm run release:please-pr
+# or: npx release-please release-pr --repo-url=github.com/PracticalParticle/Bloxchain-Protocol --token=YOUR_TOKEN
 ```
 
 #### Version Bumping Rules

README.md

@@ -229,6 +229,7 @@ npm run docgen                  # docs
 ## 📚 Documentation
 
 - **[Codebase documentation process & audit checklist](CODEBASE_DOCUMENTATION.md)** – Source of truth, how to update docs, audit-ready checklist
+- **[Versioning & releases](docs/VERSIONING.md)** – npm packages, on-chain `EngineBlox.VERSION`, Release Please
 - [Protocol Architecture](./docs/bloxchain-architecture.md) · [State Machine](./docs/state-machine-engine.md) · [Getting Started](./docs/getting-started.md) · [API Reference](./docs/api-reference.md) · [SecureOwnable](./docs/secure-ownable.md) · [RuntimeRBAC](./docs/runtime-rbac.md) · [Best Practices](./docs/best-practices.md) · [Examples](./docs/examples-basic.md)
 - **Contract API (generated):** [docs/](docs/) – generated from Solidity NatSpec via `npm run docgen`
 

SETUP.md

@@ -1,6 +1,6 @@
 # Bloxchain Setup Guide
 
-> **Note:** This file is legacy-oriented. For current protocol + SDK setup, prefer **[docs/getting-started.md](./docs/getting-started.md)**, **`env.example`**, and **`npm run release:prepare`** before publishing `@bloxchain/contracts` / `@bloxchain/sdk`.
+> **Note:** This file is legacy-oriented. For current protocol + SDK setup, prefer **[docs/getting-started.md](./docs/getting-started.md)**, **[docs/VERSIONING.md](./docs/VERSIONING.md)** (npm vs on-chain version), **`env.example`**, and **`npm run release:prepare`** before publishing `@bloxchain/contracts` / `@bloxchain/sdk` on `main`.
 
 ## Quick Start
 

commitlint.config.cjs

@@ -28,5 +28,11 @@ module.exports = {
     'body-max-line-length': [2, 'always', 1000],
     'body-leading-blank': [2, 'always'],
     'footer-leading-blank': [2, 'always'],
+    // Scopes for Release Please / per-package changelogs
+    'scope-enum': [
+      2,
+      'always',
+      ['contracts', 'sdk', 'examples', 'docs', 'ci', 'scripts', 'deps', 'release'],
+    ],
   },
 };

docs/README.md

@@ -5,6 +5,7 @@ Welcome to the Bloxchain TypeScript SDK documentation. This guide covers SDK usa
 ## 📚 **Documentation Structure**
 
 ### **Core SDK**
+- [**Versioning & releases**](./VERSIONING.md) – npm `@bloxchain/contracts` / `@bloxchain/sdk`, on-chain protocol version, publishing
 - [**Getting Started**](./getting-started.md) – Quick setup, basic usage, and [deployment / initializer checklist](./getting-started.md#deployment-and-initialization) (upgradeable Account contracts)
 - [**API Reference**](./api-reference.md) – Core SDK classes and types
 - [**SecureOwnable**](./secure-ownable.md) – SecureOwnable contract integration
@@ -78,5 +79,5 @@ console.log('Contract owner:', owner)
 
 ---
 
-**Version**: 1.0.0-alpha.16 (see [package.json](../sdk/typescript/package.json))  
+**Version**: 1.x stable line (see [sdk/typescript/package.json](../sdk/typescript/package.json) and [VERSIONING.md](./VERSIONING.md))  
 **License**: MPL-2.0