Minka Ledger Docs
Release Notes

v2.3.0

Ledger release v2.3.0

Release date: September 22, 2023

Schemas changes

To support new use cases, we did some changes in the schemas that are not backwards compatible. Here are examples of new schemas, for reference.

Records listed here don’t represent real world use cases but only show how the schemas for records look like. If there are some inconsistencies with data, they can be disregarded.

Intent

{
		"luid": "$int.HVV08sOJOG6sAleUM",
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				"handle": "baC0UUTVW9lzYA25R",
				"schema": "p2p",
				"claims": [{
					"source": {
						"handle": "svgs:84376038789@bankio.do",
						"custom": {
							"name": "Melissa Ruiz",
							"documentType": "ccpt",
							"documentNumber": "814282133995806"
						}
					},
					"target": {
						"handle": "svgs:36477453423583@bink.do",
						"custom": {
							"name": "Dario Rodriguez",
							"documentType": "nidn",
							"documentNumber": "203212949"
						}
					},
			    "symbol": {
						"handle": "dop"
					},
					"amount": 20000
				}],
				"custom": {
					"description": "pagando el almuerzo",
					"purpose": "p2p",
					"type": "send",
					"createdAt": "2023‐07‐20T08:05:58Z",
					"channel": "mobile"
				},
				"access": [ ... ],
    },
    "meta": { ... }
}

Wallet

{
		"luid": "$wlt.uShXhmjN8UsfzqOVn",
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				"handle": "tel:333333",
				"schema": "phone",
				"bridge": "tel",
				"routes": [{
						"action": "forward",
						"filter": { ... },
						"target": "svgs:36477453423583@bink.do"
				}, {
						"action": "accept",
						"filter": { ... }
				}],
				"custom": { ... },
				"access": [ ... ],
    },
    "meta": { ... }
}

Bridge

{
		"luid": "$brg.dnWM5_DnRGpbZ1PVH",
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				"handle": "tel",
				"schema": "rest",
				"config": {
				    "server": "https://tel.do/bridge/v2"
        },
				"secure": [ ... ],
				"custom": { ... },
				"access": [ ... ],
    },
    "meta": { ... }
}

Bridge Entry (prepare)

{
		"luid": "$ben.dnWM5_DnRGpbZ1PVH",
		"hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				"handle": "deb_baC0LUTVW9lzYA284",
				"schema": "debit",
				// note: "action "prepare" is not here any more!
				"source": {
					"handle": "svgs:84376038789@bankio.do",
					"custom": {
						"name": "Melissa Ruiz",
						"documentType": "ccpt",
						"documentNumber": "814282133995806"
					}
				},
				"target": {
					"handle": "svgs:36477453423583@bink.do",
					"custom": {
						"name": "Dario Rodriguez",
						"documentType": "nidn",
						"documentNumber": "203212949"
					}
				},
		    "symbol": {
					"handle": "dop"
				},
				"amount": 20000,
				"intent": {
						"luid": "$int.HVV08sOJOG6sAleUM",
				    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
				    "data": {
								"handle": "baC0UUTVW9lzYA25R",
								"schema": "p2p",
								"claims": [{
									"source": {
										"handle": "svgs:84376038789@bankio.do",
										"custom": {
											"name": "Melissa Ruiz",
											"documentType": "ccpt",
											"documentNumber": "814282133995806"
										}
									},
									"target": {
										"handle": "svgs:36477453423583@bink.do",
										"custom": {
											"name": "Dario Rodriguez",
											"documentType": "nidn",
											"documentNumber": "203212949"
										}
									},
							    "symbol": {
										"handle": "dop"
									},
									"amount": 20000
								}],
								"custom": {
									"description": "pagando el almuerzo",
									"purpose": "p2p",
									"type": "send",
									"createdAt": "2023‐07‐20T08:05:58Z",
									"channel": "mobile"
								},
								"access": [ ... ],
				    },
				    "meta": { ... }
				}
		},
    "meta": { ... }
}

Bridge Entry (commit/abort)

{
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
		"data": {
				"handle": "deb_n839cn24398c23",
				// note: "schema": "debit" is not here any more!
				"action": "commit", // or "abort"
				"intent": {
						"luid": "$int.HVV08sOJOG6sAleUM",
				    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
				    "data": {
								"handle": "baC0UUTVW9lzYA25R",
								"schema": "p2p",
								"claims": [{
									"source": {
										"handle": "svgs:84376038789@bankio.do",
										"custom": {
											"name": "Melissa Ruiz",
											"documentType": "ccpt",
											"documentNumber": "814282133995806"
										}
									},
									"target": {
										"handle": "svgs:36477453423583@bink.do",
										"custom": {
											"name": "Dario Rodriguez",
											"documentType": "nidn",
											"documentNumber": "203212949"
										}
									},
							    "symbol": {
										"handle": "dop"
									},
									"amount": 20000
								}],
								"custom": {
									"description": "pagando el almuerzo",
									"purpose": "p2p",
									"type": "send",
									"createdAt": "2023‐07‐20T08:05:58Z",
									"channel": "mobile"
								},
								"access": [ ... ],
				    },
				    "meta": { ... }
				}
    },
    "meta": { ... }
}

Bridge signature for intent

// SUCCESS
{
	"method": "ed25519-v2",
	"public": "zUkKMByFGfe7UycJadbGsiLjJq/inu5rCoRvxqGzSQs=",
	"digest": "d6d189f21690adb852e870404b3cfd074a804789972b4372d2724b5d2d502c5e",
	"result": "ArX3Jbu2M79EsRlDC3FvjzfGInRZgVmRtd0HRgrQyLLsJf2KKtOneLAeZXR9h+mbPnBELRMRpvuvpGrBoXmqCw==",
	"custom": {
		"handle": "cre_n839cn24398c23",
		"status": "committed",
		"coreId": "bink.cardnet.com.do:k893hf9h93h93ds",
		"moment": "2023-05-20T21:42:10.779Z"
	}
} 
 
// FAIL
{
	"method": "ed25519-v2",
	"public": "zUkKMByFGfe7UycJadbGsiLjJq/inu5rCoRvxqGzSQs=",
	"digest": "d6d189f21690adb852e870404b3cfd074a804789972b4372d2724b5d2d502c5e",
	"result": "ArX3Jbu2M79EsRlDC3FvjzfGInRZgVmRtd0HRgrQyLLsJf2KKtOneLAeZXR9h+mbPnBELRMRpvuvpGrBoXmqCw==",
	"custom": {
		"handle": "cre_n839cn24398c23",
		"status": "failed",
		"reason": "bridge.account-not-found",
		"failId": "ER.1212.677",
		"detail": "kaj hoces koji k....",
		"moment": "2023-05-20T21:42:10.779Z"
	}
}

Anchors and advices

Introduced 2 new concepts for alias directory (used in account2account process).

More about concepts:

About Anchors

About Advices

Anchor

{
		"luid": "$anc.INTlwXYwWCGIdCqZa",
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				// note: "handle" is required but it's not auto populated in cli
				"handle": "n839cn24398c23",
				"schema": "account",
				"source": "tel:333333",
				"target": "svgs:12345@bankio.do",
				"custom": {
					// note: "symbol" is used for advices/alias-resolve request below
					"symbol": "dop",
					"name": "Dario Rodriguez",
					"documentType": "nidn",
					"documentNumber": "203212949"
				}
				"access": [ ... ],
    },
    "meta": { ... }
}

Advice alias-resolve (request)

{
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				"handle": "tel:333333",
				"symbol": "dop",
				// note: there is no "schema" in request!
    },
    "meta": { ... }
}

Advice alias-resolve (response)

{
    "hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945",
    "data": {
				"values": [{
						"handle": "svgs:12345@bankio.do",
						// note: "schema" is mapped from found anchor record
						"schema": "account",
						// note: "custom" is mapped from found anchor record
						"custom": {
							"symbol": "dop",
							"name": "Dario Rodriguez",
							"documentType": "nidn",
							"documentNumber": "203212949"
						}
				}]
    },
    "meta": { ... }
}

Intent expiration

  • implemented intent expiration job, now intents with status pending will be aborted after certain amount of time is passed (by default, 1h)
  • added optional property config to ledger entities with mandatory property intentExpiryThresholdMinutes
    • config property will be mandatory in the future, it’s optional just to be backwards compatible with existent ledgers
  • To read more about intent expiration, refer to this document: About Intents Expiry

Access policies

Policies allows users to define access rules in a centralized manner and reuse them for appropriate records.

  • Added policies API to the ledger v2/policies
  • Allow to reference policies in access rules

To read more about policies: About Policies

System journaling

Journaling keeps track of all incoming and outgoing requests of the ledger, including parameters and response.

  • implemented requests journaling on ledger
    • this feature can be disabled at server level
  • implemented minka request list and minka request show actions in CLI to view journaled requests of the ledger
    • minka request list prompts for the usage of multiple (optional) filters

Alias bridge

Implemented Alias bridge which serves for sending SMS messages for onboarding if the target wallet is not found in the system (when doing account2phone process).

More about this in the document: About Alias Directory

Custom schemas

  • implemented schema records to allow creating custom schemas.
  • added minka schema * commands to CLI for managing schemas
  • implemented validation of records using custom schemas on top of built-in schemas
  • implemented validation of custom schema’s format to prevent broken schemas
  • To read more about custom schemas, refer to this document: About Schemas

LUID

  • added new field for all ledger records: LUID (Ledger Unique Identifier)
  • allow to fetch a record either by its LUID or handle

Certification tests

  • implemented certification tests for verifying if a bridge that connects to ledger is valid and functional

Other important changes

  • implemented max thread size for intents. If routing creates more than 10 intents, it will be aborted
  • added “accept” as valid action for the routes
  • changed behavior of wallets with routes from default to “accept” and now defaults to “reject” if no matching route is found
    • if the wallet doesn’t have any route, it accepts everything
  • changed precision of timestamps from 6 (microsecond) to 3 (millisecond)
  • improved error handling when delivering intents to bridges
    • errors are signed and added as proof to the intents
  • upgraded CLI libraries to decrease security errors and warnings

Improvements & Fixes

  • changed minka bridge start (cli-bridge) to generate JWT token when connecting to ledger
  • fixed changes API to properly return changes of the requested record
  • fixed Cross ledger tutorial inconsistencies

Cross-ledger payments tutorial

  • improved docs about JWTs
  • improved error handling on bridge

Studio

N/A

Previous

v2.4.0

Next

v2.2.0

On this page