The deployment-info.json Specification

Ty Everett ([email protected])

Abstract

We define a comprehensive and authoritative specification of the deployment-info.json schema. It is intended to serve as a reference for developers building BSV blockchain applications that integrate with the LARS (Local Automated Runtime System) and CARS (Cloud Automated Runtime System) tooling and beyond. By following this specification, projects can ensure a standardized and interoperable structure that other tools and workflows can rely upon.

Specification

The deployment-info.json file defines the structure and metadata of a BSV-based application for both local development (via LARS) and cloud deployment (via CARS). It describes the app’s topic managers, lookup services, frontend build configuration, contract compilation requirements, and various deployment configurations.

Top-Level Schema

Example:

{
  "schema": "bsv-app",
  "schemaVersion": "1.0",
  "topicManagers": {
    "tm_meter": "./backend/src/topic-managers/MeterTopicManager.ts"
  },
  "lookupServices": {
    "ls_meter": {
      "serviceFactory": "./backend/src/lookup-services/MeterLookupServiceFactory.ts",
      "hydrateWith": "mongo"
    }
  },
  "frontend": {
    "language": "react",
    "sourceDirectory": "./frontend"
  },
  "contracts": {
    "language": "sCrypt",
    "baseDirectory": "./backend"
  },
  "configs": [
    {
      "name": "Local LARS",
      "network": "testnet",
      "provider": "LARS",
      "run": [
        "backend"
      ]
    },
    {
      "name": "production",
      "provider": "CARS",
      "CARSCloudURL": "http://some-cloud.example.com",
      "projectID": "your-project-id",
      "network": "mainnet",
      "deploy": [
        "frontend",
        "backend"
      ],
      "frontendHostingMethod": "HTTPS"
    }
  ]
}

Fields

schema (string)

• Required: Yes

• Valid Values: "bsv-app"

• A fixed string identifying the schema type for this file. Must be "bsv-app".

schemaVersion (string)

• Required: Yes

• Indicates the version of this schema. Example: "1.0".

• As the schema evolves, this can help tooling handle backward compatibility.

topicManagers (object)

• Required: No (You may have no Topic Managers if your app does not define an overlay.)

• Maps topic manager names (strings) to paths of their implementing modules.

• Key (Topic Manager Name): A unique name (string) identifying the Topic Manager within the app. For example, "tm_meter", as per BRC-87.

• Value (Path): A relative file path (string) to a .ts module with a default export for a class that implements the TopicManager interface from @bsv/overlay.

• Example:

  {
    "tm_meter": "./backend/src/topic-managers/MeterTopicManager.ts"
  }

lookupServices (object)

• Required: No (Only if your app needs overlay retrieval/lookup functionalities.)

• Maps lookup service names (strings) to configuration objects describing how to instantiate them.

• Key (Lookup Service Name): A unique name (e.g., "ls_meter"), as per BRC-87.

• Value (Service Config Object):

  {
    "serviceFactory": "./backend/src/lookup-services/MeterLookupServiceFactory.ts",
    "hydrateWith": "mongo"
  }

• Fields in the Service Config Object:

  • serviceFactory (string, required): A path to a .ts module containing a default export of a factory function that creates a LookupService instance. The factory function may accept database connections (e.g., a MongoDB Db object) and return a class that implements the LookupService interface from @bsv/overlay.

  • hydrateWith (string, required): Defines how the service should be backed by persistent storage. Accepted values:

    • "mongo": Indicates that the lookup service’s storage uses a MongoDB database. LARS/CARS will provide a mongoDb instance.

    • "knex": Indicates that the service uses a SQL-based storage via Knex. LARS/CARS will provide a knex instance.

frontend (object)

• Required: No (Only if your project has a frontend.)

• Describes how the frontend portion of the app is set up.

• Fields:

  • language (string): The frontend tech stack. Common values: "react", "html", etc. Tools can use this to know how to build or deploy the frontend.

  • sourceDirectory (string): Path to the frontend source files relative to the project root.

Example:

"frontend": {
  "language": "react",
  "sourceDirectory": "./frontend"
}

contracts (object)

• Required: No (Only if your project uses on-chain contracts.)

• Describes contract language and location for source and artifacts.

• Fields:

  • language (string): The contract language. Common values: "sCrypt".

  • baseDirectory (string): Path to the directory containing contract source code and related build outputs, depending on the language.

Example:

"contracts": {
  "language": "sCrypt",
  "baseDirectory": "./backend"
}

If contracts is present and language is "sCrypt", LARS/CARS can trigger automatic contract compilation steps when contracts change.

configs (array)

• Required: Yes (although it can be empty initially)

• An array of configuration objects defining different deployment targets or modes for the project.

• Each config object corresponds to either:

  • LARS: A local development environment configuration.

  • CARS: A cloud deployment configuration.

• You can have multiple CARS configs (e.g., "staging", "production") and at most one LARS config (by convention, though not strictly enforced).

Common Fields in Each Config:

• name (string, required): A human-readable name for the configuration. E.g., "Local LARS", "production", "staging".

• provider (string, required): Indicates whether this config uses LARS or CARS. Common values:

  • "LARS": Local environment config

  • "CARS": Cloud environment config

• network (string, optional): "mainnet" or "testnet". Specifies which BSV network this config targets.

  • For LARS: Required to know if the local environment simulates mainnet or testnet conditions.

  • For CARS: Determines which network the release should be associated with.

LARS-Specific Fields:

• run (array of strings, optional): Which parts of the project to run locally. Usually ["backend"], may include "frontend" if supported, but often the frontend is served separately. Example:

  {
    "name": "Local LARS",
    "network": "testnet",
    "provider": "LARS",
    "run": ["backend"]
  }

CARS-Specific Fields:

• CARSCloudURL (string, required for CARS): URL of the CARS cloud service. E.g., "https://cars-cloud.example.com".

• projectID (string, required for CARS): The Project ID on the CARS Cloud. Used for managing deployments, logs, admins, etc.

• deploy (array of strings, required): Which parts of the application to deploy to the cloud. E.g., ["frontend", "backend"].

• frontendHostingMethod (string, optional): How the frontend is hosted in the cloud. Common values:

  • "HTTPS": Host frontend over HTTPS (CDN or static hosting, default)

  • "UHRP": Host via the UHRP protocol (if integrated and supported by the specific CARS Cloud)

Example CARS Config:

{
  "name": "production",
  "provider": "CARS",
  "CARSCloudURL": "http://cloud.example.com",
  "projectID": "abc123",
  "network": "mainnet",
  "deploy": ["frontend", "backend"],
  "frontendHostingMethod": "HTTPS"
}

Additional Notes on configs:

• Multiple CARS configs can coexist (e.g., one for "staging", one for "production", different networks, resilient deployment across clouds).

• Only one LARS config is typically present (local dev environment). Tools like LARS assume a single local configuration.

• Tools like CARS will prompt or require the user to pick a configuration if multiple apply.

---

Integration With LARS and CARS

• LARS uses deployment-info.json to:

  • Determine which topic managers and lookup services to load locally.

  • Compile contracts if specified under contracts.

  • Identify a LARS config in configs to know what network to run, what keys to use, and what parts of the app to start.

• CARS uses deployment-info.json to:

  • Identify CARS configs and connect to the specified CARS Cloud environment.

  • Build and upload artifacts, define which components to deploy.

  • Manage projects, logs, admins, and releases in a cloud environment based on project ID.

By maintaining a consistent deployment-info.json schema, both local and cloud tools can parse and understand the application’s structure, enabling smooth transitions from local dev (LARS) to production deployments (CARS).

---

Compatibility and Future-Proofing

• schema and schemaVersion: Future updates to the schema may introduce new fields or optional properties. Always check if your tools (LARS, CARS, or others) support the version you’re using.

• Optional Fields: Many fields are optional, allowing minimal setups. For example, you can omit frontend if you have no frontend. You can omit lookupServices if you have no shared state coordination needs.

• Custom Fields: It’s possible tools or future expansions add custom fields. Such fields should not conflict with the specified ones and should be namespaced or documented externally. Primary LARS/CARS tooling will typically ignore unknown fields.

---

Example Minimal deployment-info.json

{
  "schema": "bsv-app",
  "schemaVersion": "1.0",
  "topicManagers": {},
  "lookupServices": {},
  "configs": [
    {
      "name": "Local LARS",
      "provider": "LARS",
      "network": "testnet",
      "run": ["backend"]
    }
  ]
}

No frontend, no contracts, no lookup services, and a single LARS config.

---

Example More Complex deployment-info.json

{
  "schema": "bsv-app",
  "schemaVersion": "1.0",
  "topicManagers": {
    "tm_meter": "./backend/src/topic-managers/MeterTopicManager.ts"
  },
  "lookupServices": {
    "ls_meter": {
      "serviceFactory": "./backend/src/lookup-services/MeterLookupServiceFactory.ts",
      "hydrateWith": "mongo"
    }
  },
  "frontend": {
    "language": "react",
    "sourceDirectory": "./frontend"
  },
  "contracts": {
    "language": "sCrypt",
    "baseDirectory": "./backend"
  },
  "configs": [
    {
      "name": "Local LARS",
      "network": "testnet",
      "provider": "LARS",
      "run": ["backend"]
    },
    {
      "name": "staging",
      "provider": "CARS",
      "CARSCloudURL": "http://staging-cloud.example.com",
      "projectID": "staging-project-id",
      "network": "testnet",
      "deploy": ["frontend", "backend"],
      "frontendHostingMethod": "HTTPS"
    },
    {
      "name": "production",
      "provider": "CARS",
      "CARSCloudURL": "https://cars-cloud.example.com",
      "projectID": "your-production-project-id",
      "network": "mainnet",
      "deploy": ["frontend", "backend"],
      "frontendHostingMethod": "HTTPS"
    }
  ]
}

---

Conclusion

This reference provides a complete specification of the deployment-info.json schema used by LARS, CARS, and related tooling. By adhering to this schema, developers create a consistent and predictable environment, enabling a smooth, automated workflow from local development to production deployment.