Skip to content

protocol-installation.md

Latest commit

 

History

History
196 lines (169 loc) · 5.21 KB

protocol-installation.md

File metadata and controls

196 lines (169 loc) · 5.21 KB
Raw

Protocol Installation Metadata

This SDK now separates protocol identity from deployment-time routing.

That split matters because module artifacts are portable, compiled, and signable, while deployment endpoints are environment-specific.

Canonical Manifest

Hosted protocol declarations belong in manifest.protocols.

Those declarations describe what a module can host or dial:

  • protocolId
  • methodId
  • inputPortId
  • outputPortId
  • wireId
  • transportKind
  • role
  • specUri
  • autoInstall
  • advertise
  • discoveryKey
  • defaultPort
  • requireSecureTransport

These fields are embedded in the compiled PluginManifest.fbs bytes and are part of the canonical module contract.

Deployment Metadata

Concrete deployment routing does not belong in the canonical manifest.

Examples:

  • concrete multiaddrs
  • resolved listen ports
  • selected peer IDs
  • deployment URLs
  • interface-keyed input bindings
  • scheduler bindings
  • hosted service bindings
  • request-time auth policy
  • publication, pinning, retention, and archive policy

Those values vary per environment and should not change the identity of a signed .wasm artifact.

Instead, attach them as a deployment-plan payload inside the bundle MBL record carried by the appended REC trailer.

Deployment plans should use protocolId as the required identifier for a resolved protocol installation. wireId is optional deployment metadata for legacy transports that still expose it, not a required routing key.

Deployment input and publication bindings should reference manifest.externalInterfaces[].interfaceId. That keeps deployment routing tied to the declared module contract instead of transport-specific topic or wireId hints.

The standard bundle entry is:

  • entryId: deployment-plan
  • sectionName: sds.deployment
  • payloadEncoding: json-utf8
  • mediaType: application/vnd.space-data.module.deployment+json

Public Helpers

Use space-data-module-sdk/deployment to work with that payload:

  • normalizeDeploymentPlan(...)
  • validateDeploymentPlan(...)
  • createDeploymentPlanBundleEntry(...)
  • findDeploymentPlanEntry(...)
  • readDeploymentPlanFromBundle(...)

Example Manifest Protocol

{
  "protocols": [
    {
      "protocolId": "sgp4-stream",
      "methodId": "propagate",
      "inputPortId": "request",
      "outputPortId": "state",
      "wireId": "/sdn/sgp4/1.0.0",
      "transportKind": "libp2p",
      "role": "handle",
      "specUri": "https://spacedatastandards.org/#/schemas/PNM",
      "autoInstall": true,
      "advertise": true,
      "discoveryKey": "sgp4-stream",
      "defaultPort": 443,
      "requireSecureTransport": true
    }
  ]
}

Example Deployment Plan

{
  "formatVersion": 1,
  "pluginId": "com.example.sgp4",
  "version": "1.2.3",
  "protocolInstallations": [
    {
      "protocolId": "sgp4-stream",
      "transportKind": "libp2p",
      "role": "handle",
      "peerId": "12D3KooW...",
      "listenMultiaddrs": [
        "/ip4/127.0.0.1/tcp/14080/ws/p2p/12D3KooW..."
      ],
      "advertisedMultiaddrs": [
        "/dns4/sgp4.example.test/tcp/443/wss/p2p/12D3KooW..."
      ],
      "nodeInfoUrl": "https://sgp4.example.test/api/node/info"
    }
  ],
  "inputBindings": [
    {
      "bindingId": "catalog-feed",
      "interfaceId": "catalog-pubsub",
      "targetMethodId": "propagate",
      "targetInputPortId": "request",
      "sourceKind": "pubsub"
    }
  ],
  "scheduleBindings": [
    {
      "scheduleId": "poll-upstream",
      "bindingMode": "local",
      "targetMethodId": "propagate",
      "targetInputPortId": "request",
      "scheduleKind": "cron",
      "cron": "*/15 * * * *"
    }
  ],
  "serviceBindings": [
    {
      "serviceId": "https-query",
      "bindingMode": "delegated",
      "serviceKind": "http-server",
      "routePath": "/api/sgp4",
      "method": "GET",
      "remoteUrl": "https://gateway.example.test/api/sgp4",
      "authPolicyId": "approved-keys"
    }
  ],
  "authPolicies": [
    {
      "policyId": "approved-keys",
      "bindingMode": "delegated",
      "targetKind": "service",
      "targetId": "https-query",
      "walletProfileId": "orbpro-default",
      "trustMapId": "approved-operators",
      "allowServerKeys": ["ed25519:..."]
    }
  ],
  "publicationBindings": [
    {
      "publicationId": "state-catalog",
      "interfaceId": "state-catalog-pubsub",
      "bindingMode": "local",
      "sourceKind": "method-output",
      "sourceMethodId": "propagate",
      "sourceOutputPortId": "state",
      "schemaName": "CAT.fbs",
      "emitPnm": true,
      "emitFlatbufferArchive": true,
      "archivePath": "/data/catalog/cat.bin",
      "queryInterfaceId": "state-query-api",
      "recordRangeStartField": "startIndex",
      "recordRangeStopField": "stopIndex"
    }
  ]
}

Identity Rules

  • wireId identifies the network protocol.
  • specUri identifies the message or schema contract.
  • multiaddrs identify one deployment instance of that protocol.
  • interfaceId identifies the declared module boundary used by deployment input/publication bindings.
  • deployment plans should resolve installed protocol surfaces by protocolId; include wireId only when a host integration still needs that legacy hint.

Do not treat those as interchangeable.