Body:
Summary
Contributing a new translation blueprint to lib/translator/blueprints/ is one of the most common contribution types Open-Audit expects from the community. Currently there is no automated CI check that validates a new blueprint before it is merged — a contributor can submit a blueprint with broken template references, an invalid contract ID, or a missing field and it will pass CI silently. This issue adds an automated pipeline specifically for blueprint contributions.
Required work
- Blueprint JSON schema (docs/blueprint.schema.json):
Define and publish a strict JSON Schema (draft-07) that every blueprint must conform to:
Required top-level fields: contractId (Stellar contract ID regex), name (string), description (string), version (semver string), events (array, min 1 item)
Each event requires: topic (string), template (string with {field} placeholders), fields (array of field definitions)
Each field definition requires: name (matches a {name} placeholder in template), type (enum: address | amount | asset | string | integer | boolean), source (enum: topic | data), index (integer)
No {placeholder} in template may reference a name not present in fields (enforce this in the Vitest validation test added in Issue 4)
- New CI job (.github/workflows/blueprint-validation.yml):
Trigger on: pull_request where any file in lib/translator/blueprints/ is added or modified.
Steps:
Validate each changed blueprint file against docs/blueprint.schema.json using ajv-cli
Run the existing npm run lint:registry check
Run a dry-run translation test: for each event defined in the blueprint, generate a synthetic XDR payload matching the blueprint's field definitions and assert the translation engine produces a non-empty, non-error output string
Run the full npm test suite
- PR comment bot:
After the blueprint validation job runs, post a structured comment on the PR summarising:
Which blueprints were added or modified
Validation result for each (pass / fail with specific error)
A preview of the translated output for each event type defined in the blueprint (from the dry-run test)
A checklist of reviewer actions
Use the official actions/github-script action to post the comment — no third-party bots.
4. Blueprint contribution template:
Add .github/ISSUE_TEMPLATE/blueprint_contribution.md — a structured issue template for proposing a new contract blueprint before implementation, including: contract ID, contract name, network, link to contract source or documentation, and a list of event types to translate.
Acceptance criteria
A PR adding a valid blueprint passes all three checks and receives a formatted comment with translation previews
A PR adding a blueprint with a broken {placeholder} reference fails the validation job with a clear error message identifying the offending field
A PR adding a blueprint with an invalid contractId format fails schema validation
The CI job completes in under 3 minutes for a single blueprint change
No changes to existing source files or tests are required for the job to run
Body:
Summary
Contributing a new translation blueprint to lib/translator/blueprints/ is one of the most common contribution types Open-Audit expects from the community. Currently there is no automated CI check that validates a new blueprint before it is merged — a contributor can submit a blueprint with broken template references, an invalid contract ID, or a missing field and it will pass CI silently. This issue adds an automated pipeline specifically for blueprint contributions.
Required work
Define and publish a strict JSON Schema (draft-07) that every blueprint must conform to:
Required top-level fields: contractId (Stellar contract ID regex), name (string), description (string), version (semver string), events (array, min 1 item)
Each event requires: topic (string), template (string with {field} placeholders), fields (array of field definitions)
Each field definition requires: name (matches a {name} placeholder in template), type (enum: address | amount | asset | string | integer | boolean), source (enum: topic | data), index (integer)
No {placeholder} in template may reference a name not present in fields (enforce this in the Vitest validation test added in Issue 4)
Trigger on: pull_request where any file in lib/translator/blueprints/ is added or modified.
Steps:
Validate each changed blueprint file against docs/blueprint.schema.json using ajv-cli
Run the existing npm run lint:registry check
Run a dry-run translation test: for each event defined in the blueprint, generate a synthetic XDR payload matching the blueprint's field definitions and assert the translation engine produces a non-empty, non-error output string
Run the full npm test suite
After the blueprint validation job runs, post a structured comment on the PR summarising:
Which blueprints were added or modified
Validation result for each (pass / fail with specific error)
A preview of the translated output for each event type defined in the blueprint (from the dry-run test)
A checklist of reviewer actions
Use the official actions/github-script action to post the comment — no third-party bots.
4. Blueprint contribution template:
Add .github/ISSUE_TEMPLATE/blueprint_contribution.md — a structured issue template for proposing a new contract blueprint before implementation, including: contract ID, contract name, network, link to contract source or documentation, and a list of event types to translate.
Acceptance criteria
A PR adding a valid blueprint passes all three checks and receives a formatted comment with translation previews
A PR adding a blueprint with a broken {placeholder} reference fails the validation job with a clear error message identifying the offending field
A PR adding a blueprint with an invalid contractId format fails schema validation
The CI job completes in under 3 minutes for a single blueprint change
No changes to existing source files or tests are required for the job to run