Minka Wallet

Wallet simplifies the process of building financial solutions by providing developer friendly interface to build programmable money.

Abstract

Wallet represent entities - people, devices or organizations and simplifies the process of building financial solutions.

The main purpose of a Wallet is to add an abstraction layer on top of the Ledger in order to address the problem of poor usability and long time to market of modern transactional systems (Blockchain).

While Ledger uses digitally signed messages (Actions) between addresses (Signers), a Wallet simplifies the interaction by using handles to represent one or more addresses by a phone number, email or nickname. All interactions between Wallets are represented as Transfers.

A Transfer acts as a state machine that simulates payments - asynchronous operations that usually require several actions to complete.

Wallet

Overview

Wallets represent entities - people, devices or organizations that are interacting with the Cloud. At a low level, a Wallet is represented as a JSON object holding the information about the:

• handle

  • list of person readable handles for the wallet

• signer

  • list of signers used by the wallet

• labels

  • metadata to describe the wallet

Optional information that could be stored in the Wallet:

• bridge

  • that holds the information necessary to process an external system

• keeper

  • key management system in the cloud used to generate signers

Holding Keeper in the Cloud is a security vulnerability and should be used only for testing and development purposes.

Data structure

Field description

Field	Type	Description
wallid	string	a system generated, domain unique id.
handle	JSON array	list of people friendly handles that can be used as a reference.
signer	JSON array	list of reference Signers.
labels	JSON array	list of user-defined key-value pairs.

Example object

{
	"wallid":	"832d3cb1-ea50-4312-b6bb-0a5276544511",
	"handle": [{
			"handid":	"573501234567",
			"nature":	"phone"
			"default":	true, 
			"verifed":	true
		}, 
		{
			"handid":	"[e-mail]",
			"nature":	"email"
			"default":	false, 
			"verifed":	true
		}],
	"signer": [{
			"signid":	"wS1EU4AtgzD6VDtsrJyGKXmkQdvkWt9Qeq",
			"default":	true
		}],
	"labels": {
		"finame":	"Pedro",
		"laname":	"Perez",
		"nature":	"person"
	}
}

Details

handle

A JSON Object used to list the people friendly handles that can be used as a reference to a Wallet. Handles are usually a phone number, an email or a person generated nickname.

Each wallet can hold several handles to reference the wallet.

Field	Description
handid	a person generated ID for the Handle. Unique accross Domain.
nature	a nature (type) of the handle. "email", "facebook", "phone", "nickname"
chosen	a handle is the chosen (default) handle for the wallet.
affirm	status of the handle in regards of 2FA.

Example for a person wallet that holds two handles:

{
    "handid":    "573501234567",
    "nature":    "phone",
    "chosen":    true,
    "affirm":    true
},
{
    "handid":    "[e-mail]",
    "nature":    "email",
    "chosen":    false,
    "affirm":    true
}

User-generated string are unique to the Domain. They are usually reserved for the organizations in the form of tags - $org

signer

An array of JSON objects used reference Signers attributed to a Wallet.

For a more detailed description of a Signer - review the Ledger building block:

Minka Ledger

A Wallet can have many different Signer addresses and a unique address should be used for each transaction. Signer list allows mapping all the related Signers to a specific Wallet.

Field	Description
signid	Signer id - base58 address.
chosen	chosen (default) Signer for the Wallet.

Example of a Signer object stored in the Wallet:

{
    "signid":    "wS1EU4AtgzD6VDtsrJyGKXmkQdvkWt9Qeq",
    "chosen":    true
}

labels

Labels are a set of user-defined key-value pairs associated with a Wallet. Lables allow adding descriptive meta-data and for the purpose of querying and analytics.

For example, Labels can be used to map information about the person necessary for querying:

"labels": {
		"finame":	"Pedro",
		"laname":	"Perez",
		"nature":	"person"
	}

Using Labels to store personal or sensitive information is not recommend. The Labels are visible and can be used for querying across the Domain.

Transfer

Overview

A Transfer acts as a state machine that simulates payments - asynchronous operations that usually require several actions to complete. It uses person readable handles to initiate the transactions and map the status of the transfer.

Basic business logic such as fees and whitelisting/blacklisting can be implemented at the Transfer level. The Ledger manages the lower or upper limits for Signers and time constraints on the action level.

Transfer is basically metadata about a specific financial operations composed of one or many Actions. Action inputs are IOUs. An IOU is a digitally signed document that acknowledges a debt and authorizes an action to clear it. Only signed actions are an acknowledgment of a debt; a Transfer does not influence the balance directly in the system.

Data structure

Field description

Fields	Type	Description
tranid	string	unique hash of the transfer.
source	string	a handle representing the source of the transfer.
target	string	a handle representing the target of the transfer.
amount	string	an amount of the transfer.
symbol	string	a symbol of the transfer (currency).
lables	JSON	list of person defined key-value pairs.

A transfer includes additional internal fields that manage the

Field	Type	Description
status	string	a status of the transfer.
action	JSON array	s list of actions related to the transfer
snapsh	JSON array	snapshot of the labels of source and target int he moment of the transfer

To validate a transfer status one can validate the hashes of the underlying actions.

Example object

{
	"source": "$385916111161", 	
	"target": "$573506111161",	
	"amount": "100.00",
	"symbol": "LUK",			
	"labels": {
		"nature":	"peer2p",
		"detail":	"for espresso in Croatia"
	}	
}