Flow

Blueprints

Declarative network provisioning - one JSON document, one command, full network setup.

Overview

A blueprint is a single JSON document that describes an entire enterprise network: its name, join rule, policies, identity provider, webhooks, audit export, role pre-assignments, and admin token. Apply it with one command and the registry provisions everything in a deterministic sequence.

Blueprints are designed for infrastructure-as-code workflows. Store them in version control, review changes in pull requests, and apply them through CI/CD pipelines.

Blueprint format

{
  "name": "prod-fleet",
  "join_rule": "invite_only",
  "enterprise": true,
  "policy": {
    "max_members": 100,
    "allowed_ports": [80, 443, 1001],
    "description": "Production fleet - US East"
  },
  "identity_provider": {
    "type": "oidc",
    "url": "https://accounts.example.com/.well-known/openid-configuration",
    "client_id": "pilot-prod"
  },
  "webhooks": [
    {
      "url": "https://ops.example.com/pilot-events",
      "events": ["member.kicked", "network.policy_changed"]
    }
  ],
  "audit_export": {
    "format": "splunk_hec",
    "endpoint": "https://splunk.example.com:8088/services/collector",
    "token": "hec-token-here"
  },
  "roles": {
    "42": "admin",
    "108": "admin"
  },
  "network_admin_token": "network-specific-secret"
}

Fields reference

Field	Type	Required	Description
name	string	Yes	Network name. Lowercase alphanumeric with hyphens. Used for idempotent lookup.
join_rule	string	No	One of open, invite_only, or token. Defaults to open.
enterprise	bool	No	Enable enterprise features. Defaults to false.
policy	object	No	Network policy: max_members, allowed_ports, description. See Network Policies.
identity_provider	object	No	IDP configuration: type, url, client_id. See Identity & SSO.
webhooks	array	No	Webhook endpoints: url and events filter.
audit_export	object	No	Export config: format, endpoint, token. See Audit Export.
roles	object	No	Map of node ID (string) → role (admin or member). Pre-assigns RBAC roles.
network_admin_token	string	No	Per-network admin token for delegated administration.

Apply sequence

When a blueprint is applied, the registry executes these steps in order:

1. Find or create - look up the network by name. If it exists, use it. If not, create it with the specified join rule.
2. Enable enterprise - if enterprise: true and the network is not yet enterprise, enable it.
3. Set policies - apply the policy object using merge-on-update semantics.
4. Configure IDP - set the identity provider configuration if specified.
5. Configure audit export - set the audit export endpoint and format if specified.
6. Configure webhooks - register webhook endpoints if specified.
7. Assign roles - for each entry in roles, set the RBAC role. Nodes must already be members of the network.

Each step is independent - if a later step fails, earlier steps are not rolled back. The result includes which actions were taken and which failed.

Idempotency

Blueprints are idempotent. Applying the same blueprint twice produces the same result. The registry looks up the network by name:

• If a network with that name exists, it is updated (not duplicated)
• If no network with that name exists, a new one is created

This makes blueprints safe to apply repeatedly in CI/CD pipelines. Re-applying after a partial failure completes the remaining steps without duplicating already-completed ones.

Validation

The registry validates the blueprint before applying any changes:

• name is required and must match the network name rules (lowercase alphanumeric with hyphens)
• join_rule must be one of open, invite_only, or token
• policy.max_members must be a non-negative integer
• policy.allowed_ports must have ≤ 100 entries
• policy.description must be ≤ 256 characters
• identity_provider.type must be a valid provider type (oidc, saml, entra_id, ldap, webhook)
• roles values must be admin or member (not owner - ownership is assigned to the creator)

If validation fails, no changes are made and the error is returned immediately.

Protocol command

Apply a blueprint

{
  "command": "provision_network",
  "blueprint": {
    "name": "prod-fleet",
    "enterprise": true,
    "policy": { "max_members": 100 }
  },
  "admin_token": "your-admin-token"
}

The blueprint is the only payload field besides admin_token. Ownership of a newly-created network is assigned to the registry node that the admin token authorizes — there is no explicit node_id on the RPC.

Result format

{
  "network_id": 5,
  "name": "prod-fleet",
  "created": true,
  "actions": [
    "network created",
    "enterprise enabled",
    "policy set",
    "audit export configured"
  ]
}

The created field indicates whether a new network was created (true) or an existing one was updated (false).

File-based blueprints

For programmatic use, load a blueprint from a JSON file using the helper in pkg/registry/wire, then convert to the map shape ProvisionNetwork expects:

// Go SDK — pkg/registry/wire has the typed loader
import "github.com/TeoSlayer/pilotprotocol/pkg/registry/wire"
import "github.com/TeoSlayer/pilotprotocol/pkg/registry"

bp, err := wire.LoadBlueprint("network.json")        // *wire.NetworkBlueprint
result, err := client.ProvisionNetwork(bp.ToMap(), adminToken)

wire.LoadBlueprint reads and validates the JSON file, returning a typed struct. registry.Client.ProvisionNetwork(blueprint, adminToken) takes the blueprint as a map[string]interface{} and the admin token — the network owner is the node already authenticated on the client connection (no explicit nodeID argument).

Status query

Inspect the provisioning state of a network:

{
  "command": "get_provision_status",
  "network_id": 5,
  "admin_token": "your-admin-token"
}

Returns the network’s current configuration as seen by the registry: enterprise status, policies, IDP config, webhook endpoints, audit export, and role assignments. Use this to verify that a blueprint was applied correctly or to diff the current state against a desired state.