Bitmunk Transaction Platform

From DBWiki

Contents 1 Introduction 2 Documentation 3 Components 3.1 Profile Manager 3.2 Download Engine 3.2.1 Contract Processor 3.2.2 Download Manager 3.2.3 Decryption Manager 3.3 Sales Engine 3.3.1 Catalog Manager 3.3.2 Contract Manager 3.3.3 Upload Manager 3.4 Auto-updater 3.5 GUI Plugins 3.5.1 Search (Standard GUI Plugin) 3.5.2 Transaction Management (Standard GUI Plugin) 3.5.3 Catalog Management (Standard GUI Plugin)

Introduction

The Bitmunk Transaction Platform is a set of software used to provide digital content sales and distribution services to content creators, online stores, bloggers and website operators. The software is provided under an open source license for non-commercial purposes to help those that would want to use or extend the software the ability to do so. A different commercial-use license is available for companies that want to modify/extend the software for their own purposes.

Documentation

Full documentation is provided for the entire Bitmunk software stack. You can browse the latest documentation online.

Components

Profile Manager

The Bitmunk Client application generates a "Profile" when a Bitmunk User logs in for the first time. This Profile contains information about the user, specifically their user ID on Bitmunk and their encrypted private key. This private key is used to sign data being transferred over Bitmunk to ensure that it is coming from the correct user and that it has not been tampered with.

The ProfileManager is responsible for generating new Profiles and loading existing Profiles from disk.

Download Engine

The Bitmunk Client's Download Engine enables one Bitmunk User to enter into a Contract to purchase digital content with another Bitmunk User, negotiate the terms of that Contract, accept the Contract, download the content, pay for it, and finally decrypt the content for use.

The Download Engine uses SSL, HTTP, SOAP, and serialized XML Objects to communicate on Bitmunk.

Contract Processor

Every transaction on Bitmunk is done via a Contract. The Contract contains information identifying (according to Bitmunk Username and ID only) the Buyer and Seller involved in the transaction, information identifying the digital content that is to be transacted, and the payment terms. A Contract goes through several step as it is processed from beginning to completion.

The Download Engine uses a ContractProcessor to process each Contract and the steps it goes through. A ContractProcessor automates most of the steps, including contacting the appropriate Seller and updating the Contract with their terms, sending the Contract to the SVA (Sales Verification Authority) for Contract verification and authorization, downloading the Contract content from the Seller and decrypting the Contract content.

When a Contract requires user input, the ContractProcessor will cease processing until the input is supplied. Contracts require input from a user (or an external automated process) before they can be accepted, downloaded, or decrypted.

Several ContractProcessors can be put to use by the Download Engine at once, all of them being managed by a ContractProcessorManager. Each of the ContractProcessors is assigned its own thread from a thread pool so that Contracts may be processed concurrently. ContractProcessors can also be interrupted and/or terminated to put an end to Contract processing as a developer sees fit.

Download Manager

The DownloadManager is utilized by a ContractProcessor once a Contract has been accepted. The DownloadManager is capable of downloading the content from multiple contracts concurrently and can be configured to only download at a certain bandwidth or to download content from a certain number of Contracts at once.

The DownloadManager manages FileDownloaders which are the objects responsible for actually downloading files from a Seller. Downloads can be cancelled, paused, interrupted, and continued if they were previously paused or interrupted. Events are passed up during the download process that can be handled and displayed via a GUI to indicate download status and progress.

Decryption Manager

The DecryptionManager is utilized by a ContractProcessor once a Contract has been downloaded. The DecryptionManager is capable of decrypting the content from multiple contracts concurrently and can be configured to only decrypt content from a certain number of Contracts at once. Since decryption is often quite processing-intensive, it is often recommended that the content from only one Contract be decrypted at once depending on the processing power available.

The DecryptionManager manages FileDecryptors which are the objects responsible for actually decrypting files that were previously downloaded. Decryptions can be cancelled, paused, interrupted, and continued if they were previously paused or interrupted. Events are passed up during the decryption process that can be handled and displayed via a GUI to indicate decryption status and progress.

Sales Engine

The Bitmunk Client's Sales Engine enables a Bitmunk User to sell digital content on Bitmunk. It includes a Micro Web Server that requires only one port to be opened on a user's firewall but allows multiple protocols to be used over incoming connections. The Sales Engine also makes use of a fast Java-based SQL database for storing a Catalog of the user's digital content. The information in this Catalog can be uploaded to Digital Bazaar's SVA (Sales Verification Authority) service for Bitmunk so that Buyers on Bitmunk may browse and search for a Seller's available content.

The Sales Engine uses SSL, HTTP, SOAP, and serialized XML Objects to communicate on Bitmunk.

Catalog Manager

The Sales Engine makes use of a Catalog of Wares. Each Ware represents a single package that a Buyer can purchase from a Seller. A Ware contains 1-N DigitalWorks. A DigitalWork associates media information with a specific file that is stored on the Seller's disk. A Ware with one DigitalWork, for example, could be a song or a movie. A Ware with more than one DigitalWork, for example, could be an album.

The CatalogManager provides the basic implementation for communicating with the SQL database that stores the Seller's Wares. It allows Wares in the Catalog to be updated and retrieved. Wares are updated or removed from the Catalog using CatalogUpdateRequests. Each CatalogUpdateRequest can update and/or remove a set of Wares from the Catalog. This allows a small number of Wares to be modified at a time and makes synchronizing changes made while a Seller is offline with the SVA easier and less data intensive.

This Catalog of Wares can be edited via the Sales Engine's Java interface or remotely (given the proper security credentials) over SOAP. Information from the Catalog can be retrieved in the same fashion, though any Bitmunk User may retrieve a Seller's Catalog so that they can determine if they want to make a purchase.

Contract Manager

The Sales Engine's ContractManager handles incoming Contract requests from Buyers and automates the entire encryption, upload, and payment process. When a Buyer wants to purchase digital content from a Seller, they create a new Contract and send it to the Seller's Sales Engine which will populate that Contract with the Seller's preset terms for the particular requested digital content. If the Buyer accepts the Seller's terms, then the content is encrypted and uploaded to the Buyer. The Sales Engine sends the decryption keys to the SVA. Once the Buyer has paid for the content, the decryption keys are released to the Buyer so that they can decrypt and use their new content.

Upload Manager

The Sales Engine's UploadManager manages several FileUploader objects. Each one of these FileUploaders is responsible for servicing requests to download a file that is part of a Contract that has been agreed upon and authorized by the SVA. The FileUploader handles encrypting the data as it is being uploaded to a Buyer.

The number of files that can be uploaded at once as well as the total amount of upload bandwidth can be limited.

Auto-updater

The Bitmunk Client's GUI is bundled along with an AutoUpdater. Whenever the GUI client is run, its AutoUpdater is started and will check for updates periodically.

The Bitmunk Client's AutoUpdater is an extension of DB core's autoupdater package and it makes use of a basic auto-update script. This source of the script is the SVA. Each upgradable version of the Bitmunk Client is assigned an auto-update script that is downloaded by the AutoUpdater when it finds an update. When an update arrives, its script is checked for validity. If the script is valid, a dialog box is displayed for the user where they can decide whether or not to apply the update at the given time.

The update script can download new files, remove existing files and directories, and apply patches. Before any file can be installed or any patch can be executed, its digital signature must be verified. The Bitmunk Client AutoUpdater will automate the entire update process, including shutting down the Bitmunk Client before processing an update and restarting it afterwards if appropriate.

GUI Plugins

The Bitmunk Client's GUI is designed with a plugin architecture. The core GUI provides basic tools for communicating on Bitmunk and communicating with the underlying engine. The core GUI has a "workspace" where other views can be plugged in to allow for more functionality. The core GUI also has a built in area for setting the options for the core GUI and any of its plugins.

A GUI plugin must be digitally signed by a trusted authority before it can be loaded into the Bitmunk Client. Each plugin must provide a main view (which can have any number of child views) and may optionally include an option page for the plugin.

Search (Standard GUI Plugin)

The Search GUI plugin provides a user with the ability to perform a search for digital content on Bitmunk via a set of terms (word search) or by browsing a set of media categories. As the user searches or browses, up to date information is dynamically loaded from Bitmunk. A user may enter several different term searches at once, each of which will be assigned a tab with the search results.

If the user wishes to make a purchase, they can select one of their search results and view its available sellers. The seller list will display the seller's rating (which includes information about their reputation and transfer rate) along with the seller's price and information about the digital content. Once a seller is selected, a new Contract will be created and the seller will be contacted so that they can specify their terms. Once the seller responds, the Download Engine will fire an event indicating that a Contract is ready to be examined for acceptance. The Transaction Plugin (or another custom plugin) handles this event.

Transaction Management (Standard GUI Plugin)

The Transaction plugin has several views that organize Contracts for transactions into groups. The groups are for current Contracts, cancelled or failed Contracts, and completed Contracts.

When a new Contract is available to be examined for purchase the Transaction plugin will grab the Buyer's attention and display the Contract under current Contracts. All of the pertinent Contract information will be displayed which includes what the Contract is for and what the price will be -- including an entire price breakdown.

The Buyer can then accept or cancel the Contract. If the Buyer elects to cancel the Contract it will be placed in the failed/cancelled Contracts group. It can be retried later if so desired. Otherwise, the Contract will start and display progress information, including the current download/decryption status and progress. The user can also pause and unpause downloading and decryption. Once the Contract has completed, it will be moved to the completed Contracts group. If the Contract fails, it will be placed in the failed Contracts group and can be retried at a later time if the user desires.

Catalog Management (Standard GUI Plugin)

The Catalog Management plugin provides a view on a seller's Catalog of Wares. This GUI plugin allows a user to add or remove Wares from their Catalog and view the Wares that are currently in their Catalog.

A wizard is available for creating new Wares. The wizard will guide the user through the Ware creation process allowing them to pick the media they want to sell, associate it with a file on their disk, and set their price. The wizard will include the content creator's pricing information as well as Bitmunk's transaction fee so that the user can see the total price that a Buyer will pay when they make a purchase.

When a new Ware is created, it is uploaded to the SVA so that Buyers can easily browse and search the seller's Catalog.

Whenever a user logs into the Bitmunk Client and the Catalog Management plugin is loaded, it will automatically upload any changes made to the seller's Catalog to the SVA. This ensures that the seller's Catalog is kept in sync with the SVA.