🎥 Demo Video

This project is a fork of the general go-overlay-services framework, extended with specific support for Asset21 tokens on the Bitcoin SV blockchain. It adds Asset21 token recognition, validation, and management capabilities while leveraging the core overlay service infrastructure.

This project extends the core concepts of Bitcoin SV Overlay Services to specifically handle Asset21 tokens. At its heart, it leverages an engine.Engine to process blockchain transactions, treating each unique Asset21 token symbol as a distinct "topic".

Key Concepts:

• Asset21 Tokens: These are custom tokens defined by a specific inscription format within Bitcoin SV transactions. Our service parses and validates these inscriptions.
• Topics: In the context of the overlay engine, a "topic" represents a distinct asset type. Here, each unique Asset21 token symbol (e.g., "T2056", "MYTOKEN") is registered as its own topic. This allows the system to manage multiple Asset21 token types concurrently.
• Topic Managers (engine.TopicManager): For each registered Asset21 token topic, a dedicated Asset21TopicManager instance is responsible for:
  • Identifying Admissible Outputs: Parsing transaction outputs to detect valid Asset21 inscriptions and extracting their details.
  • Validating Asset21 Rules: Ensuring that the detected Asset21 tokens conform to their defined protocol (e.g., correct inscription format, valid locking script).
• MongoDB Persistence (engine.Storage): The service uses MongoDB to persistently store and retrieve the state of Asset21 UTXOs (Unspent Transaction Outputs) for each topic. This includes the token's inscription data and its associated metadata.
• Transaction Processing: When a transaction (in BEEF format) is submitted to the engine, it undergoes:
  1. Parsing & Validation: The Asset21TopicManager checks the transaction's outputs for valid Asset21 inscriptions.
  2. State Update: Validated Asset21 UTXOs are recorded in MongoDB, and any spent Asset21 inputs are updated.

By focusing on Asset21, this project demonstrates a concrete application of overlay services for custom token management.

• Native Asset21 Token Support: Full recognition, parsing, and validation of Asset21 token inscriptions.
• Dynamic Token Topic Management: Each unique Asset21 token symbol is managed as a distinct topic, allowing for flexible support of multiple token types.
• MongoDB Persistence: Robust storage and retrieval of Asset21 UTXOs and their metadata using a MongoDB backend.

• Go (v1.24+): Download here
• Docker: For running MongoDB locally Install Docker

1. Clone the repository:

   git clone https://github.com/shainilps/asset21-overlay.git
   cd go-overlay-services

2. Start MongoDB using Docker: Ensure Docker is installed and running. This command will pull the MongoDB image and start a container named asset21-mongodb accessible on localhost:27017.

   docker run --name asset21-mongodb -p 27017:27017 -d --rm mongo:latest

   Verify the container is running with docker ps.

3. Install Go Dependencies: From the project root:

   go mod tidy

1. Clone and Setup:

   git clone https://github.com/bsv-blockchain/go-overlay-services.git
   cd go-overlay-services

2. Start MongoDB:

   docker run --name asset21-mongodb -p 27017:27017 -d --rm mongo:latest

3. Install Dependencies:

   go mod tidy

4. Run Tests (Recommended):

   go test ./... -failfast -vet=all -count=1

   All tests should pass, confirming the project is working correctly.

5. Run the Service:

   go run main.go

Expected Output:

You will see log messages indicating:

• The service startup and successful connection to MongoDB.
• Dynamic registration of Asset21 token topics (e.g., "T2056").
• A conceptual transaction submission. This submission is performed with dummy BEEF data and a mocked blockchain ChainTracker, so it will likely fail during SPV verification. However, the MongoDB persistence logic for handling Asset21 UTXOs is active.

The main.go file contains a hardcoded asset21Tokens map where you can define the Asset21 token symbols you wish to manage.

	asset21Tokens := map[string]Asset21Config{
		"T2056": {
			ApproverPubKeyHex: "034ddd5b89fd8b87ff1152a353dbe7ae79ab0320de63c1228d9558af00e115107e",
			ExpectedProtocol:  "asset-21",
			ExpectedOperation: "transfer",
			ExpectedSymbol:    "T2056",
			ExpectedTokenID:   "8668cb38ec83847b7d04694aac32b126dfdc450416a3e3c8e5c7f271e2092a9c_0",
		},
		// Add more asset21 symbols here (e.g., for different genesis or operations)
		// "MYTOKEN": {
		// 	ApproverPubKeyHex: "...",
		// 	ExpectedProtocol:  "asset-21",
		// 	ExpectedOperation: "mint",
		// 	ExpectedSymbol:    "MYTOKEN",
		// 	ExpectedTokenID:   "...",
		// },
	}

The service provides HTTP API endpoints for interacting with the overlay services. The server runs on http://localhost:3000 by default and loads configuration from app-config.yaml on startup.

Note: After making code changes, rebuild and restart the server for changes to take effect.

Admin endpoints require a Bearer token configured in app-config.yaml. The default token is super-secret-admin-token. Update this value in production.

To include the token in requests:

-H "Authorization: Bearer super-secret-admin-token"

curl http://localhost:3000/api/v1/listLookupServiceProviders

curl "http://localhost:3000/api/v1/getDocumentationForLookupServiceProvider?lookupService=asset21"

curl "http://localhost:3000/api/v1/getDocumentationForTopicManager?topicManager=T2056"

curl -X POST http://localhost:3000/api/v1/submit \
  -H "x-topics: T2056" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @transaction.beef

To create a transaction.beef file for testing, convert the provided hex data:

echo "01010101a2cbd00fd6734262dfda246a9246b1ea078554301f54d4d43875dd4ed0d822030200beef0001000100000000010100000000000000d900630561737365744c927b22616d74223a22313030222c22646563223a22222c2267656e65736973223a22383636386362333865633833383437623764303436393461616333326231323664666463343530343136613365336338653563376632373165323039326139635f30222c226f70223a227472616e73666572222c2270223a2261737365742d3231222c2273796d223a225432303536227d6876a914000000000000000000000000000000000000000088ad21034ddd5b89fd8b87ff1152a353dbe7ae79ab0320de63c1228d9558af00e115107eac00000000" | xxd -r -p > transaction.beef

curl -X POST http://localhost:3000/api/v1/requestForeignGASPNode \
  -H "Content-Type: application/json" \
  -H "X-BSV-Topic: T2056" \
  -d '{
    "graphID": "0322d8d04edd7538d4d4541f30548507eab146926a24dadf624273d60fd0cba2.0",
    "txID": "0322d8d04edd7538d4d4541f30548507eab146926a24dadf624273d60fd0cba2",
    "outputIndex": 0
  }'

Note: Use a real transaction ID from a submitted transaction for the graphID and txID fields.

curl -X POST http://localhost:3000/api/v1/requestSyncResponse \
  -H "Content-Type: application/json" \
  -H "X-BSV-Topic: T2056" \
  -d '{
    "version": 1,
    "since": 1
  }'

curl -X POST http://localhost:3000/api/v1/lookup \
  -H "Content-Type: application/json" \
  -d '{
    "service": "asset21",
    "query": {
      "topic": "T2056",
      "since": 0,
      "limit": 10
    }
  }'

Note: The since parameter filters UTXOs by their timestamp score. Use since: 0 for recent UTXOs, or since: -1 to include all UTXOs.

curl -X POST http://localhost:3000/api/v1/admin/syncAdvertisements \
  -H "Authorization: Bearer super-secret-admin-token"

curl -X POST http://localhost:3000/api/v1/admin/startGASPSync \
  -H "Authorization: Bearer super-secret-admin-token"

curl -X POST http://localhost:3000/api/v1/arc-ingest \
  -H "Authorization: Bearer super-secret-admin-token" \
  --data-binary @data.arc

Note: This endpoint is not currently supported by the service configuration.

• Some endpoints may return internal errors if not fully implemented (e.g., documentation endpoints, submit endpoint).
• Certain POST endpoints require the X-BSV-Topic header.
• The arc-ingest endpoint is not supported in the current configuration.
• For transaction submission, use BEEF format data.

This project provides a strong foundation for Asset21 token management. Areas for further development include:

• Real ChainTracker Integration: Replacing the mocked ChainTracker with a connection to a live Bitcoin SV node or service to enable full SPV verification and blockchain interaction.
• API Endpoints: Implementing HTTP API endpoints to submit Asset21 transactions or query Asset21 UTXO states.
• Advanced Asset21 Operations: Expanding Asset21TopicManager to support more complex Asset21 operations (e.g., minting, burning, freezing) beyond basic transfers.
• User Interface: Developing a user interface for easier interaction with the Asset21 overlay service.

Contributions are welcome! Please refer to the original go-overlay-services project's guidelines for contributing if you intend to integrate these changes back.

This project is licensed under the OpenBSV License (as per the original go-overlay-services project).