LogoLogo
  • README
  • Contribute
    • Discuss on Github
  • Example
    • Banana-Powered Bitcoin Wallet Control Protocol
  • Apps
    • The deployment-info.json Specification
  • Wallet
    • Transaction Creation
    • Data Encryption and Decryption
    • Digital Signature Creation and Verification
    • Input Redemption
    • HTTP Wallet Communications Substrate
    • XDM Wallet Communications Substrate
    • Window Wallet Communication Substrate
    • Wallet Transaction Output Tracking (Output Baskets)
    • Submitting Received Payments to a Wallet
    • Certificate Creation and Revelation
    • Unified Abstract Wallet-to-Application Messaging Layer
    • Transaction Labels and List Actions
    • Output Basket Removal and Certificate Deletion
    • Group Permissions for App Access
    • Extensible Proof-Type Format for Specific Key Linkage Claims
    • P Protocols: Allowing future wallet protocol permission schemes
    • P Baskets: Allowing Future Wallet Basket and Digital Asset Permission Schemes
    • Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface
  • Transactions
    • Everett-style Transaction Envelopes
    • Simplified Payment Verification
    • Merkle proof standardised format
    • TSC Proof Format with Heights
    • Raw Transaction Format
    • TXO Transaction Object Format
    • Transaction Extended Format (EF)
    • Merkle Path JSON format
    • Compound Merkle Path Format
    • Background Evaluation Extended Format (BEEF) Transactions
    • Simplified Payment Verification
    • Merkle Path Binary Format
    • BSV Unified Merkle Path (BUMP) Format
    • Graph Aware Sync Protocol
    • Scalable Transaction Processing in the BSV Network
    • Atomic BEEF Transactions
    • BEEF V2 Txid Only Extension
  • Scripts
    • Bitcoin Script Binary, Hex and ASM Formats
    • Bitcoin Script Assembly Language
    • Pay to Public Key Hash
    • Pay to R Puzzle Hash
    • Pay to False Return
    • Pay to True Return
    • Push TX
    • Bare Multi-Signature
    • Pay to Push Drop
  • Tokens
    • There is no BRC-20
    • Definition of UTXOs as Bitcoin Tokens
    • Token Exchange Protocol for UTXO-based Overlay Networks
    • Mandala Token Protocol
  • Overlays
    • Overlay Network Data Synchronization
    • Confederacy Host Interconnect Protocol (CHIP)
    • Overlay Network Lookup Services
    • Confederacy Lookup Availability Protocol (CLAP)
    • Universal Hash Resolution Protocol
    • Overlay Network Transaction History Tracking
    • Private Overlays with P2PKH Transactions
    • Standardized Naming Conventions for BRC-22 Topic Managers and BRC-24 Lookup Services
    • Overlay Services Synchronization Architecture
    • Diverse Facilitators and URL Protocols for SHIP and SLAP Overlay Advertisements
  • Payments
    • Direct Payment Protocol (DPP)
    • Paymail Payment Destinations
    • Simple Authenticated BSV P2PKH Payment Protocol
    • PacketPay HTTP Payment Mechanism
    • Hybrid Payment Mode for DPP
    • HTTPS Transport Mechanism for DPP
    • Paymail BEEF Transaction
    • HTTP Service Monetization Framework
  • Peer-to-Peer
    • Authrite Mutual Authentication
    • PeerServ Message Relay Interface
    • PeerServ Host Interconnect Protocol
    • Identity Certificates
    • Genealogical Identity Protocol
    • Publishing Trust Anchor Details at an Internet Domain
    • Message Signature Creation and Verification
    • Serialization Format for Portable Encrypted Messages
    • Defining a Scalable IPv6 Multicast Protocol for Blockchain Transaction Broadcast and Update Delivery
    • Proven Identity Key Exchange (PIKE)
    • Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol
    • HTTP Transport for BRC-103 Mutual Authentication
  • Key Derivation
    • BIP32 Key Derivation Scheme
    • BSV Key Derivation Scheme (BKDS)
    • Security Levels, Protocol IDs, Key IDs and Counterparties
    • Admin-reserved and Prohibited Key Derivation Protocols
    • Revealing Key Linkages
    • Protecting BRC-69 Key Linkage Information in Transit
    • Mnemonic For Master Private Key
    • Linked Key Derivation Scheme
    • Bidirectionally Authenticated Derivation of Privacy Restricted Type 42 Keys
    • Limitations of BRC-69 Key Linkage Revelation
    • Verifiable Revelation of Shared Secrets Using Schnorr Protocol
  • Outpoints
    • Format for Bitcoin Outpoints
    • Spending Instructions Extension for UTXO Storage Format
  • Opinions
    • Users should never see an address
    • List of user experiences
    • Legitimate Uses for mAPI
    • Security and Scalability Benefits of UTXO-based Overlay Networks
    • Improving on MLD for BSV Multicast Services
    • Web 3.0 Standard (at a high level)
    • Thoughts on the Mandala Network
    • Outputs, Overlays, and Scripts in the Mandala Network
  • State Machines
    • Simplifying State Machine Event Chains in Bitcoin
Powered by GitBook
On this page
  • Abstract
  • Specification
  • Top-Level Schema
  • Fields
  • schema (string)
  • schemaVersion (string)
  • topicManagers (object)
  • lookupServices (object)
  • frontend (object)
  • contracts (object)
  • configs (array)
  • Additional Notes on configs:
  • Integration With LARS and CARS
  • Compatibility and Future-Proofing
  • Example Minimal deployment-info.json
  • Example More Complex deployment-info.json
  • Conclusion

Was this helpful?

Edit on GitHub
Export as PDF
  1. Apps

The deployment-info.json Specification

Ty Everett (ty@projectbabbage.com)

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.

PreviousBanana-Powered Bitcoin Wallet Control ProtocolNextTransaction Creation

Last updated 4 months ago

Was this helpful?