@bsv/overlay 0.1.0-alpha.1

package/LICENSE.txt

@@ -0,0 +1,28 @@
+Open BSV License version 4
+
+Copyright (c) 2023 BSV Blockchain Association ("Bitcoin Association")
+ 
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+ 
+1 - The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+2 - The Software, and any software that is derived from the Software or parts thereof,
+can only be used on the Bitcoin SV blockchains. The Bitcoin SV blockchains are defined,
+for purposes of this license, as the Bitcoin blockchain containing block height #556767
+with the hash "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
+that contains the longest persistent chain of blocks accepted by this Software and which are valid under the rules set forth in the Bitcoin white paper (S. Nakamoto, Bitcoin: A Peer-to-Peer Electronic Cash System, posted online October 2008) and the latest version of this Software available in this repository or another repository designated by Bitcoin Association,
+as well as the test blockchains that contain the longest persistent chains of blocks accepted by this Software and which are valid under the rules set forth in the Bitcoin whitepaper (S. Nakamoto, Bitcoin: A Peer-to-Peer Electronic Cash System, posted online October 2008) and the latest version of this Software available in this repository, or another repository designated by Bitcoin Association
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# BSV Overlay Services Engine
+
+BSV BLOCKCHAIN | Overlay Services Engine
+
+The Overlay Services Engine enables dynamic tracking and management of UTXO-based systems that work on top of the BSV blockchain.
+
+## Table of Contents
+
+1. [Objective](#objective)
+2. [Getting Started](#getting-started)
+3. [Features & Deliverables](#features--deliverables)
+4. [Documentation](#documentation)
+5. [Contribution Guidelines](#contribution-guidelines)
+6. [Support & Contacts](#support--contacts)
+
+## Objective
+
+- Enable a general-purpose system for tracking UTXOs
+- Let each service decide what UTXOs get into the system
+- Provide an efficient global storage engine for UTXO data
+- Let each lookup service dynamically respond to different types of queries
+- Let each lookup service have its own, specialized storage engine for its unique needs
+
+## Getting Started
+
+### Installation
+
+You'll usually want to wrap the Engine within an HTTP server. To get set up with Express, create a new project and install everything you'll need:
+
+```
+npm i express body-parser @bsv/sdk @bsv/overlay hello-services knex
+```
+
+### Basic Usage
+
+In your server's main file, you can set everything up. Create a new Engine to run the overlay services you want, then expose some routes over HTTP. For example:
+
+```js
+const express = require('express')
+const bodyparser = require('body-parser')
+const { Engine, KnexStorage, HelloTopicManager, HelloLookupService, HelloStorageEngine } = require('@bsv/overlay')
+const { WoChain } = require('@bsv/sdk')
+// Populate a Knexfile with your database credentials
+const knex = require('knex')(require('../knexfile.js'))
+const app = express()
+app.use(bodyparser.json({ limit: '1gb', type: 'application/json' }))
+
+const engine = new Engine(
+    {
+      hello: new HelloTopicManager(),
+    },
+    {
+      hello: new HelloLookupService({
+        storageEngine: new HelloStorageEngine({
+          knex
+        })
+      }),
+    },
+    new KnexStorageEngine({
+      knex
+    })
+  )
+
+// This allows the API to be used everywhere when CORS is enforced
+app.use((req, res, next) => {
+  res.header('Access-Control-Allow-Origin', '*')
+  res.header('Access-Control-Allow-Headers', '*')
+  res.header('Access-Control-Allow-Methods', '*')
+  res.header('Access-Control-Expose-Headers', '*')
+  res.header('Access-Control-Allow-Private-Network', 'true')
+  if (req.method === 'OPTIONS') {
+    res.sendStatus(200)
+  } else {
+    next()
+  }
+})
+
+// Serve a static documentstion site, if you have one.
+app.use(express.static('public'))
+
+// List hosted topic managers and lookup services
+app.get(`/listTopicManagers`, async (req, res) => {
+  try {
+    const result = await engine.listTopicManagers()
+    return res.status(200).json(result)
+  } catch (error) {
+    return res.status(400).json({
+      status: 'error',
+      code: error.code,
+      description: error.message
+    })
+  }
+})
+app.get(`/listLookupServiceProviders`, async (req, res) => {
+  try {
+    const result = await engine.listLookupServiceProviders()
+    return res.status(200).json(result)
+  } catch (error) {
+    return res.status(400).json({
+      status: 'error',
+      code: error.code,
+      description: error.message
+    })
+  }
+})
+
+// Host documentation for the services
+app.get(`/getDocumentationForTopicManager`, async (req, res) => {
+  try {
+    const result = await engine.getDocumentationForTopicManger(req.query.manager)
+    return res.status(200).json(result)
+  } catch (error) {
+    return res.status(400).json({
+      status: 'error',
+      code: error.code,
+      description: error.message
+    })
+  }
+})
+app.get(`/getDocumentationForLookupServiceProvider`, async (req, res) => {
+  try {
+    const result = await engine.getDocumentationForLookupServiceProvider(req.query.lookupServices)
+    return res.status(200).json(result)
+  } catch (error) {
+    return res.status(400).json({
+      status: 'error',
+      code: error.code,
+      description: error.message
+    })
+  }
+})
+
+// Submit transactions and facilitate lookup requests
+app.post(`/submit`, async (req, res) => {
+  try {
+    const result = await engine.submit(req.body)
+    return res.status(200).json(result)
+  } catch (error) {
+    return res.status(400).json({
+      status: 'error',
+      code: error.code,
+      description: error.message
+    })
+  }
+})
+app.post(`/lookup`, async (req, res) => {
+  try {
+    const result = await engine.lookup(req.body)
+    return res.status(200).json(result)
+  } catch (error) {
+    return res.status(400).json({
+      status: 'error',
+      code: error.code,
+      description: error.message
+    })
+  }
+})
+
+// 404, all other routes are not found.
+app.use((req, res) => {
+  console.log('404', req.url)
+  res.status(404).json({
+    status: 'error',
+    code: 'ERR_ROUTE_NOT_FOUND',
+    description: 'Route not found.'
+  })
+})
+
+// Start your Engines!
+  app.listen(8080, () => {
+    console.log('BSV Overlay Services Engine is listening on port', 8080)
+  })
+```
+
+For more detailed tutorials and examples, check out the [full documentation](#documentation).
+
+The Overlay Services Engine is also richly documented with code-level annotations. This should show up well within editors like VSCode. 
+
+<!-- ## Documentation
+
+[links to conceptsexamples and internals] -->
+
+## Features & Deliverables
+
+- UTXO Tracking
+- History management and state tracking
+- Lookup Services
+- Storage engine abstractions
+- [WIP] Examples, HTTP wrapper and Docs
+- [WIP] Arc Proof Acquisition
+- [WIP] Distributed Overlay Availability Advertisements
+- [WIP] Federated Transaction Synchronization
+
+## Contribution Guidelines
+
+We're always looking for contributors to help us improve the Engine. Whether it's bug reports, feature requests, or pull requests - all contributions are welcome.
+
+1. **Fork & Clone**: Fork this repository and clone it to your local machine.
+2. **Set Up**: Run `npm i` to install all dependencies.
+3. **Make Changes**: Create a new branch and make your changes.
+4. **Test**: Ensure all tests pass by running `npm test`.
+5. **Commit**: Commit your changes and push to your fork.
+6. **Pull Request**: Open a pull request from your fork to this repository.
+For more details, check the [contribution guidelines](./CONTRIBUTING.md).
+
+For information on past releases, check out the [changelog](./CHANGELOG.md). For future plans, check the [roadmap](./ROADMAP.md)!
+
+## Support & Contacts
+
+Project Owners: Thomas Giacomo, Darren Kellenschwiler, Jake Jones
+
+Development Team Lead: Ty Everett
+
+For questions, bug reports, or feature requests, please open an issue on GitHub or contact us directly.
+
+## License
+
+The license for the code in this repository is the Open BSV License. Refer to [LICENSE.txt](./LICENSE.txt) for the license text.
+
+Thank you for being a part of the BSV Blockchain Overlay Services Project. Let's build the future of BSV Blockchain together!

package/dist/cjs/mod.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnexStorageMigrations = exports.KnexStorage = exports.LookupAnswer = exports.LookupFormula = exports.LookupQuestion = exports.STEAK = exports.TaggedBEEF = exports.AdmittanceInstructions = exports.Output = exports.Storage = exports.TopicManager = exports.LookupService = exports.Engine = void 0;
+// Fundamentals
+exports.Engine = __importStar(require("./src/Engine.js"));
+exports.LookupService = __importStar(require("./src/LookupService.js"));
+exports.TopicManager = __importStar(require("./src/TopicManager.js"));
+// Interfaces and structures
+exports.Storage = __importStar(require("./src/storage/Storage.js"));
+exports.Output = __importStar(require("./src/Output.js"));
+exports.AdmittanceInstructions = __importStar(require("./src/AdmittanceInstructions.js"));
+exports.TaggedBEEF = __importStar(require("./src/TaggedBEEF.js"));
+exports.STEAK = __importStar(require("./src/STEAK.js"));
+exports.LookupQuestion = __importStar(require("./src/LookupQuestion.js"));
+exports.LookupFormula = __importStar(require("./src/LookupFormula.js"));
+exports.LookupAnswer = __importStar(require("./src/LookupAnswer.js"));
+// The Knex storage system
+exports.KnexStorage = __importStar(require("./src/storage/knex/KnexStorage.js"));
+exports.KnexStorageMigrations = __importStar(require("./src/storage/knex/all-migrations.js"));
+//# sourceMappingURL=mod.js.map

package/dist/cjs/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../mod.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,eAAe;AACf,0DAAyC;AACzC,wEAAuD;AACvD,sEAAqD;AAErD,4BAA4B;AAC5B,oEAAmD;AACnD,0DAAyC;AACzC,0FAAyE;AACzE,kEAAiD;AACjD,wDAAuC;AACvC,0EAAyD;AACzD,wEAAuD;AACvD,sEAAqD;AAErD,0BAA0B;AAC1B,iFAAgE;AAChE,8FAA6E"}

package/dist/cjs/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@bsv/overlay",
+  "version": "0.1.0-alpha.1",
+  "type": "commonjs",
+  "description": "BSV Blockchain Overlay Services Engine",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "mod.ts",
+    "LICENSE.txt"
+  ],
+  "scripts": {
+    "test": "npm run build && jest",
+    "test:watch": "npm run build && jest --watch",
+    "test:coverage": "npm run build && jest --coverage",
+    "lint": "ts-standard --fix src/**/*.ts",
+    "build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
+    "dev": "tsc -b -w",
+    "prepublish": "npm run build",
+    "doc": "ts2md --inputFilename=mod.ts --outputFilename=docs/API.md --filenameSubstring=API --firstHeadingLevel=1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitcoin-sv/overlay-services.git"
+  },
+  "keywords": [
+    "BSV",
+    "Blockchain",
+    "Overlay",
+    "Bitcoin",
+    "SV"
+  ],
+  "author": "BSV Association",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "bugs": {
+    "url": "https://github.com/bitcoin-sv/overlay-services/issues"
+  },
+  "homepage": "https://github.com/bitcoin-sv/overlay-services#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-standard": "^12.0.2",
+    "ts2md": "^0.2.0",
+    "tsconfig-to-dual-package": "^1.2.0",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "@bsv/sdk": "^1.0.20",
+    "knex": "^3.1.0"
+  }
+}

package/dist/cjs/src/AdmittanceInstructions.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=AdmittanceInstructions.js.map

package/dist/cjs/src/AdmittanceInstructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdmittanceInstructions.js","sourceRoot":"","sources":["../../../src/AdmittanceInstructions.ts"],"names":[],"mappings":""}