feat: automated blueprint validation CI pipeline

.github/ISSUE_TEMPLATE/blueprint_contribution.md

@@ -0,0 +1,24 @@
+---
+name: Blueprint Contribution
+about: Propose a new contract translation blueprint
+labels: "Type: Blueprint, good first issue"
+---
+
+## Contract details
+
+- **Contract ID:** `C...`
+- **Contract name:** e.g. Soroswap Router
+- **Network:** mainnet / testnet
+- **Source / docs:** https://
+
+## Events to translate
+
+<!-- List each event type you plan to support -->
+
+| Event topic | Fields | Example plain-English output |
+|-------------|--------|------------------------------|
+| `transfer` | from, to, amount | `GABC...1234 transferred 100.00 USDC to GXYZ...5678` |
+
+## Notes
+
+<!-- Any edge cases, token symbols, or contract upgrade history the reviewer should know about -->

.github/workflows/blueprint-validation.yml

@@ -0,0 +1,106 @@
+name: Blueprint Validation
+
+on:
+  pull_request:
+    paths:
+      - "lib/translator/blueprints/**"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+
+      - name: Get changed blueprint files
+        id: changed
+        run: |
+          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD \
+            | grep '^lib/translator/blueprints/.*\.json$' \
+            | tr '\n' ' ')
+          echo "files=$FILES" >> $GITHUB_OUTPUT
+          echo "Changed blueprints: $FILES"
+
+      - name: Validate blueprints
+        id: validate
+        run: |
+          if [ -z "${{ steps.changed.outputs.files }}" ]; then
+            echo "No blueprint JSON files changed."
+            echo "success=true" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          node scripts/validate-blueprint.js ${{ steps.changed.outputs.files }}
+          EXIT=$?
+
+          echo "success=$( [ $EXIT -eq 0 ] && echo true || echo false )" >> $GITHUB_OUTPUT
+          exit 0  # let the comment step always run
+
+      - name: Lint
+        if: steps.validate.outputs.success == 'true'
+        run: npm run lint
+
+      - name: Run tests
+        if: steps.validate.outputs.success == 'true'
+        run: npm test
+
+      - name: Post PR comment
+        uses: actions/github-script@v7
+        if: always()
+        with:
+          script: |
+            const fs = require('fs');
+            const marker = '<!-- blueprint-validation -->';
+
+            let body;
+            try {
+              body = fs.readFileSync('blueprint-validation-report.md', 'utf8');
+            } catch {
+              body = steps.validate.outputs.success === 'true'
+                ? '✅ Blueprint validation passed.'
+                : '❌ Blueprint validation failed — see job logs for details.';
+            }
+
+            const comment = `${marker}\n${body}\n\n### Reviewer checklist\n- [ ] Contract ID is correct and verifiable on-chain\n- [ ] Template reads naturally in plain English\n- [ ] Field types match the actual XDR schema\n- [ ] At least one test vector is included`;
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const existing = comments.find(c => c.body.startsWith(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body: comment,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: comment,
+              });
+            }
+
+      - name: Fail if validation failed
+        if: steps.validate.outputs.success == 'false'
+        run: |
+          echo "Blueprint validation failed. See the PR comment for details."
+          exit 1

docs/blueprint.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Open-Audit Translation Blueprint",
+  "description": "Schema for a community-contributed contract translation blueprint.",
+  "type": "object",
+  "required": ["contractId", "name", "description", "version", "events"],
+  "additionalProperties": false,
+  "properties": {
+    "contractId": {
+      "type": "string",
+      "description": "Soroban contract address (56-char Stellar strkey starting with C)",
+      "pattern": "^C[A-Z2-7]{55}$"
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "version": {
+      "type": "string",
+      "description": "Semver string, e.g. 1.0.0",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "network": {
+      "type": "string",
+      "enum": ["mainnet", "testnet", "futurenet"],
+      "default": "mainnet"
+    },
+    "events": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["topic", "template", "fields"],
+        "additionalProperties": false,
+        "properties": {
+          "topic": { "type": "string", "minLength": 1 },
+          "template": { "type": "string", "minLength": 1 },
+          "fields": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["name", "type", "source", "index"],
+              "additionalProperties": false,
+              "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "type": { "type": "string", "enum": ["address", "amount", "asset", "string", "integer", "boolean"] },
+                "source": { "type": "string", "enum": ["topic", "data"] },
+                "index": { "type": "integer", "minimum": 0 }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}