Blueprint Builder Skill

Sorcha blueprints define multi-participant workflows as JSON documents. Each blueprint has participants, actions (with data schemas), and routes that determine the action flow. Templates wrap blueprints with parameterization for reuse.

Quick Start

Minimal Blueprint (Two-Party, No Cycles)

{
  "id": "my-blueprint",
  "title": "My Workflow",
  "description": "A simple two-participant workflow (min 5 chars)",
  "version": 1,
  "metadata": { "category": "demo" },
  "participants": [
    { "id": "sender", "name": "Sender", "description": "Initiates the workflow" },
    { "id": "receiver", "name": "Receiver", "description": "Receives and completes" }
  ],
  "actions": [
    {
      "id": 0,
      "title": "Submit",
      "sender": "sender",
      "isStartingAction": true,
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "message": { "type": "string", "minLength": 1 }
          },
          "required": ["message"]
        }
      ],
      "routes": [
        { "id": "to-receiver", "nextActionIds": [1], "isDefault": true }
      ]
    },
    {
      "id": 1,
      "title": "Complete",
      "sender": "receiver",
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "status": { "type": "string", "enum": ["accepted", "rejected"] }
          },
          "required": ["status"]
        }
      ],
      "routes": []
    }
  ]
}

Cyclic Blueprint (Looping Workflow)

{
  "metadata": { "hasCycles": "true" },
  "actions": [
    {
      "id": 0, "title": "Ping", "sender": "ping", "isStartingAction": true,
      "routes": [{ "id": "ping-to-pong", "nextActionIds": [1], "isDefault": true }]
    },
    {
      "id": 1, "title": "Pong", "sender": "pong",
      "routes": [{ "id": "pong-to-ping", "nextActionIds": [0], "isDefault": true }]
    }
  ]
}

Cycle detection produces warnings (not errors). Cyclic blueprints publish with metadata["hasCycles"] = "true".

Key Concepts

Blueprint Validation Rules

1. Participant references: Every action.sender must reference a valid participant.id
2. Action count: At least 1 action required
3. Participant count: At least 2 participants required (enforced by BlueprintBuilder.Build())
4. Description length: Min 5 characters
5. Title length: Min 3 characters
6. Cycles: Detected but allowed — produce warnings, not errors

Route Types

Default Route (Always Taken)

{ "id": "always", "nextActionIds": [1], "isDefault": true }

Conditional Route (JSON Logic)

{
  "id": "approve-route",
  "nextActionIds": [2],
  "condition": { "==": [{ "var": "decision" }, "approved"] }
}

Terminal Route (Workflow Ends)

{ "id": "complete", "nextActionIds": [], "isDefault": true }

Parallel Branch (Multiple Next Actions)

{
  "id": "parallel-review",
  "nextActionIds": [2, 3],
  "isDefault": true,
  "branchDeadline": "P7D"
}

Route Precedence

Route-based routing (via Action.Routes) takes precedence over legacy condition-based routing (via Action.Participants). Always use routes for new blueprints.

DataSchema Patterns

String Field with Validation

{ "type": "string", "minLength": 1, "maxLength": 500, "title": "Message" }

Integer with Minimum

{ "type": "integer", "minimum": 1, "title": "Counter" }

Enum (Fixed Choices)

{ "type": "string", "enum": ["approved", "rejected", "escalate"], "title": "Decision" }

Number with Threshold

{ "type": "number", "minimum": 0, "title": "Amount" }

Template Wrapper

Templates wrap blueprints for reuse with optional parameterization:

{
  "id": "template-id",
  "title": "Template Title",
  "description": "What this template does (min 5 chars)",
  "version": 1,
  "category": "demo|approval|finance|supply-chain",
  "tags": ["tag1", "tag2"],
  "author": "Sorcha Team",
  "published": true,
  "template": { /* raw blueprint JSON or JSON-e template */ },
  "parameterSchema": null,
  "defaultParameters": null,
  "examples": []
}

Fixed Template (No Parameters)

Set parameterSchema: null — the template field contains the raw blueprint JSON directly. Used for simple blueprints like Ping-Pong.

Parameterized Template (JSON-e)

Uses JSON-e expressions ($eval, $if, $flattenDeep) in the template field. Requires parameterSchema (JSON Schema), defaultParameters, and examples.

JSON-e expressions:

• { "$eval": "paramName" } — substitute parameter value
• { "$if": "condition", "then": ..., "else": ... } — conditional inclusion
• { "$flattenDeep": [...] } — flatten nested arrays (for conditional participants/actions)

Blueprint Publishing Flow

1. POST /api/blueprints/ — Create draft blueprint
2. POST /api/blueprints/{id}/publish — Publish (validates, returns warnings for cycles)
3. POST /api/instances/ — Create instance with participant wallet mappings

Publish Response (with cycle warning)

{
  "blueprintId": "...",
  "version": 1,
  "publishedAt": "...",
  "warnings": ["Cyclic route detected: action 0 → action 1 → action 0. This blueprint will loop indefinitely unless routing conditions provide a termination path."]
}

Action Execution

POST /api/instances/{id}/actions/{actionId}/execute
Headers: Authorization: Bearer <token>, X-Delegation-Token: <token>
Body: {
  "blueprintId": "string",
  "actionId": "string",
  "instanceId": "string",
  "senderWallet": "string",
  "registerAddress": "string",
  "payloadData": { "message": "hello", "counter": 1 }
}

Engine pipeline: validate (schema check) → calculate (JSON Logic) → route (determine next) → disclose (visibility rules)

Common Patterns

Approval Chain (Linear)

Submit(requester) → Review(manager) → Approve(director) → Complete

Ping-Pong (Cyclic)

Ping(A) → Pong(B) → Ping(A) → Pong(B) → ... (indefinite)

Conditional Branching

Submit → [amount > 10000] → Director Approval
Submit → [amount <= 10000] → Manager Approval
Both → Complete

File Locations

See Also

• patterns – Blueprint design patterns and examples
• workflows – Publishing and execution workflows

Related Skills

• dotnet – .NET 10 / C# 13 patterns
• minimal-apis – Blueprint Service endpoint definitions
• xunit – Testing blueprint validation
• blazor – Template library UI pages