# The deployment-info.json Specification Ty Everett () ## 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:** ```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": "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**: ```json { "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)**: ```json { "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**: ```json "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**: ```json "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: ```json { "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**: ```json { "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` ```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` ```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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bsv.brc.dev/apps/0102.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.