vledger v1.0.16

Installation

Using npm:

npm i vledger

Description

VLedger is a Express and MongoDB library that can be installed to enable a database ledger storing balances for individual user accounts. Balances managed by VLedger can be backed by any real world currency via API connectors written by the developer. VLedger uses a safe mathematics library to perform transactions between user accounts. VLedger is the perfect choice for your web or finance application

Requirements

VLedger works on MongoDB, it doesnt handle any authentication and must be passed a MongoClient() created by the developer. VLedger requires the developer to run a single setup to install some necessary data into the database(s), this is handled automatically in the VLedger demo which you can run yourself. VLedger can work on any developers database as it can be passed an object denoting the database and collection names to use. Importantly VLedger can connect to any external ledger such as a merchant bank API. In order to do this the developer must write some functions to interact with said API and then pass them to VLedger. VLesger also requires Node environmental variables via process.env .

Demo

let vledger=require('vledger')

async function test()
{
        //USE YOUR MONGODB CONNECTION STRING HERE
        let URI='mongodb://localhost:27017'
        let vl=new vledger()
        let s=await vl.testsetup(URI)
        let l=await vl.testledger(URI)
}

test()

This should run successfully with no errors. Make sure to use your own correct MongoDB connection string.

Usage

VLedger works with MongoDB, to setup VLedger you must define database names and collections for VLedger to use. These names must not be the same as other names used in your application. The databse configuration is stored in process.env.vl.

process.env.vl=JSON.stringify({
	config:{
		db:{
			tokens:{d:"main",c:"tokens"},
			plan:{d:"main",c:"plan"},
			fees:{d:"main",c:"fees"},
			wdconfig:{d:"main",c:"wdconfig"},
			common:{d:"main",c:"common"},  //store , user
			users:{d:"main",c:"users"},
			transit:{d:"main",c:"transit"},
			process:{d:"main",c:"process"}		
		}	
	}
})

VLedger can connect to practically any external ledger system to enable the management of currencies that exist on those systems within your own server running VLedger. In order to connect to another ledger you must write functions that:

• create accounts
• read balance
• transfer assets
• confirm transactions are complete

/*
	A DEMO CODE TO CONNECT VLEDGER TO AN API PROVIDED BY MYBANK.
	THE CODE USES THE SECRET KEY TO TRANSFER CURRENCY

*/

let _=require('lodash')


let CorpBank={
	IBAN:"djvnkdjnvvkj",
	AN:0384893,
	country:"United Kingdom",
	bank:"Gold Bank Ltd"
}

let APIKEY="SECRETKEY"

module.exports={
	mybank:{
	getDeposit:async (params)=>{
		//IGNORE
	},
	create:async (params)=>{
		//CREATE A RANDOM REFERENCE FOR AN INDIVIDUAL USER DEPOSIT ACCOUNT
		if(params.type=="deposit"){
			let ref="NKC489U38EJNVKJDNK"
			console.log("DEPOSIT")
			//VLedger uses the key "address" to discriminate accounts
			let ret={
				address:ref,
				fiat:_.assign(CorpBank,{reference:ref})			
			}
			return ret
		}
		else if(params.type=="common"){
			//VLedger needs address to discriminate between accounts
			let ret={
				address:CorpBank.IBAN,
				fiat:CorpBank			
			}
			return ret
		}
		return undefined
	},
	getBalance:async (params)=>{
		//read balance of a deposit account by checking new transactions on the reference
		if(params.type=="deposit")
		{
			
			//READ BALANCE OF ALL INCOME TRANSACTIONS
			//TEST MODE IGNORES THIS FUNCTION AND INCREASES THE BALANCE
			return '0' 
		}
		else if(params.type=="common")
		{
			return '0'
		}
	},
	transfer:async (params)=>{
		if(params.type=="deposit")
		{
			//GET TRANSACTION CONFIRMATION FOR THE DEPOSIT
			return "A DEPOSIT"
		}
		else if(params.type=="withdraw")
		{
			return "A TRANSFER"
		}		
		//transfer from a common account using the external API
		//Should return an object on success, and undefined on failure
	},
	confirm:async (params)=>{
		let fields={
			confirmation:params.confirmation		
		}
		// CALL BANK
		return {status:"OK"}
	}
}
}

You can use VLedger to enable the use of a currency in a ledger on another server for example a merchant bank or other digital currency. In order to use a particular currency with VLedger the currency must be installed into your database. In addition you must install a collections defining transaction fees and the withdrawal fees you want to use on your server.

const tokens=[
	{platform:"mybank",network:"main",class:"fiat",address:"GBP"}
]

const fees=[
	{platform:"mybank",network:"main",fee_unit:"1"}
]

const wd=[
	{
		token:{
			currency:{
				platform:"mybank",
				class:"fiat",
				network:"main",
				address:"GBP"
			}		
		},
		minimum:"10",
		fees:{
			free:{type:"q",amount:0.05},
			bronze:{type:"q",amount:0.03},
			silver:{type:"q",amount:0.02},
			gold:{type:"q",amount:0.01}
		}
	}
]

Next you must enable the use of the installed currency by users on your server. First by creating ledger accounts for the users ,then creating deposit accounts for each user where they can transfer funds into the server. Finally you must create a subscription plan for each user to set their withdrawal fees. This works with the general withdrawal fes object set above.

let plan={
	accountID:"user01",
	subscription:{
		planID:"free",
		status:"active"
	}
}

Here is the full setup script which can be used: