Tutorials/Basic Access Tutorial

Managing wallet access

Ensuring only the wallet owner has the control over the wallet

Now that we demonstrated how things should not work, let's see how we can improve our clearinghouse Ledger system.

Removing all access

Only clearinghouse signer that created the ledger record should have complete control over that entire ledger.

While we were creating the ledger record we were presented with these JSON access rules:

[
  {
    "action": "any",
    "record": "any"
  }
]

These rules allowed anyone to do anything (and this helped us simplify the tutorial).

But now we will only grant full access to the clearinghouse signer and everyone else will have zero access.

This way we're setting up our system with maximum security and then we'll slowly add permissions to others.

We can edit access rules using the update command:

$ minka ledger update 

Ledger summary:
---------------------------------------------------------------------------
Handle: tutorial-ledger

Intent expiry threshold (minutes): 60
Wallet required before creating an anchor: true
Schedule policy processor enabled: false

Access rules:
#0
  - Action: any
  - Record: any

Status: created


Updates:
------------------------------------------
? Select the field to update, select Finish to save changes. 
  Finish 
  Config 
  Custom 
❯ Access

Select Access and update the JSON rules so that only clearinghouse signer can have total control.

[
  {
    "action": "any",
    "record": "any",
    "signer": {
      "public": "eIHlrG0Wr5vl3pDi5Vgqzu5WGE7q/60jsysBmehYKtg="
    }
  }
]

public is actually signer's public key which you can get using the following command:

$ minka signer show clearinghouse

Signer summary:
---------------------------------------------------------------------------
Handle: clearinghouse
Public: eIHlrG0Wr5vl3pDi5Vgqzu5WGE7q/60jsysBmehYKtg=


⚠️  WARNING::  Secret or private key is critical data that should be handled
with care. Private keys are used to modify balances and it is important to
understand that anyone who has access to that key can perform sensitive
ledger operations.

Now, aside from clearinghouse signer no one can do anything.

Testing clearinghouse access

Let's start with any command. For example, listing all wallets:

$ minka wallet list

Reason: auth.forbidden
Cannot query wallet.

Since access is no longer open to everyone, the Ledger system needs to verify the identity of the signer before allowing any kind of access or modification.

To do that, we will login using our clearinghouse signer:

$ minka ledger login
! Remote signers not available.
? Signer: clearinghouse
? Signer password for clearinghouse [hidden]

✅ Logged in as clearinghouse.

Now when we repeat the previous command we will see the list of all the wallets in the ledger:

$ minka wallet list

╔═════════════════════╤══════════╤══════════╤══════════╗
║  Handle             │  Bridge  │  Custom  │  Routes  ║
╟─────────────────────┼──────────┼──────────┼──────────╢
║  demo-bank-wallet   │  None    │          │  None    ║
╟─────────────────────┼──────────┼──────────┼──────────╢
║  settlement-wallet  │  None    │          │  None    ║
╚═════════════════════╧══════════╧══════════╧══════════╝

Showing page 1 (additional pages may be available.).

Adding access

Having completely restricted rules (below) makes the Ledger useless because no one can access it or use it (except the clearinghouse).

{
  "action": "any",
  "record": "any",
  "signer": {
    "public": "eIHlrG0Wr5vl3pDi5Vgqzu5WGE7q/60jsysBmehYKtg="
  }
}

So let's start by editing ledger rules once again and allow each signer to access its own data:

{
  "action": "access"
}

And also, let's allow owners of the wallet to change wallet balance:

{
  "action": "spend",
  "record": "wallet",
  "signer": {
    "$record": "owner"
  }
}

And finally, let's allow demo-bank signer to create intents/transactions (using its public key):

{
  "action": "create",
  "record": "intent",
  "signer": {
    "public": "demo-bank-signer-public-key-..."
  }
}

Here is how the full ledger access rules look like:

[
  {
    "action": "any",
    "record": "any",
    "signer": {
      "public": "eIHlrG0Wr5vl3pDi5Vgqzu5WGE7q/60jsysBmehYKtg="
    }
  },
  {
    "action": "access"
  },
  {
    "action": "spend",
    "record": "wallet",
    "signer": {
      "$record": "owner"
    }
  },
  {
    "action": "create",
    "record": "intent",
    "signer": {
      "public": "RiQu4adTcR1elbgSSSOW84rviHLofGhXJQpOYdvHcQc="
    }
  }
]

Use minka ledger update command to set these new access rules.

Testing demo bank access

First we need to logout from our clearinghouse signer using minka ledger logout command.

Now, let's say we just want to list wallets in the ledger:

$ minka wallet list

Reason: auth.forbidden
Cannot query wallet.

As expected we cannot see the wallets without a proper signer.

So let's login with our demo-bank signer:

minka ledger login
! Remote signers not available.
? Signer: demo-bank
? Signer password for demo-bank [hidden]

✅ Logged in as demo-bank.

Now when we list the wallets, demo-bank can only see the records that belong to it:

minka wallet list

╔════════════════════╤══════════╤══════════╤══════════╗
║  Handle            │  Bridge  │  Custom  │  Routes  ║
╟────────────────────┼──────────┼──────────┼──────────╢
║  demo-bank-wallet  │  None    │          │  None    ║
╚════════════════════╧══════════╧══════════╧══════════╝

Showing page 1 (additional pages may be available.).

Notice how we were able to see all the wallets when we were logged in as a clearinghouse.

Testing balance transfer (fail)

We will again try to make a transfer from settlement-wallet that doesn't belong to demo-bank and see if it goes through:

$ minka intent create
? Handle: 5usjn3eBuqu8X431DGgHa
? Action: transfer
? Source: settlement-wallet
? Target: demo-bank-wallet
? Symbol: usd
? Amount: 20
? Add another action? No
? Add custom data for this intent? No
? Signers: demo-bank
? Signer password for demo-bank [hidden]

Intent summary:
---------------------------------------------------------------------------
Handle: 5usjn3eBuqu8X431DGgHa

Action: transfer
 - Source: settlement-wallet
 - Target: demo-bank-wallet
 - Symbol: usd
 - Amount: $20


? Sign this intent using signer demo-bank? Yes

✅ Intent signed and sent to ledger tutorial-ledger-2

Intent summary:
---------------------------------------------------------------------------
Handle: 5usjn3eBuqu8X431DGgHa

Action: transfer
 - Source: settlement-wallet
 - Target: demo-bank-wallet
 - Symbol: usd
 - Amount: $20


Access rules:
#0
  - Action: any
  - Signer:
    - public: RiQu4adTcR1elbgSSSOW84rviHLofGhXJQpOYdvHcQc=
Luid: $int.-089ChY4ocQFyZWIr

As you can see, demo-bank wallet managed to create intent but that doesn't mean the balance was transferred.

If we list the intents, we can see it's pending and will eventually timeout without making a transfer.

minka intent list

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  Handle                     Action               Source               Target        Amount         Status    ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  5usjn3eBuqu8X431DGgHa    Transfer    settlement-wallet     demo-bank-wallet        $20    usd     pending   ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  BJgB1yDLFKnfHIGnlVKnR    Transfer    settlement-wallet     demo-bank-wallet       $100    usd    completed  ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  qz30sjjHv5ti7wjuAgYrS    Transfer     demo-bank-wallet    settlement-wallet       $200    usd    completed  ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  uslP0M2CUwxtTiaKIQspr    Transfer     demo-bank-wallet    settlement-wallet       $300    usd    completed  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

This means, demo-bank no longer controls the settlement-wallet balance and we successfully limited the access that was previously completely unrestricted.

$ minka wallet balances demo-bank-wallet
Balances:
$600.00 (usd)

Testing balance transfer (success)

Another case we need to verify is whether the demo-bank signer can transfer balance from its own demo-bank-wallet:

minka intent create                    
? Handle: JCWiBS823cKzXTU6MQqoG
? Action: transfer
? Source: demo-bank-wallet
? Target: settlement-wallet
? Symbol: usd
? Amount: 30
? Add another action? No
? Add custom data for this intent? No
? Signers: demo-bank
? Signer password for demo-bank [hidden]

Intent summary:
---------------------------------------------------------------------------
Handle: JCWiBS823cKzXTU6MQqoG

Action: transfer
 - Source: demo-bank-wallet
 - Target: settlement-wallet
 - Symbol: usd
 - Amount: $30


? Sign this intent using signer demo-bank? Yes

✅ Intent signed and sent to ledger tutorial-ledger-2

Intent summary:
---------------------------------------------------------------------------
Handle: JCWiBS823cKzXTU6MQqoG

Action: transfer
 - Source: demo-bank-wallet
 - Target: settlement-wallet
 - Symbol: usd
 - Amount: $30


Access rules:
#0
  - Action: any
  - Signer:
    - public: RiQu4adTcR1elbgSSSOW84rviHLofGhXJQpOYdvHcQc=
Luid: $int.-089ExLCSdwyalJOv

If we take a look at intents, we can see that this transfer was successful:

$ minka intent list                      

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║  Handle                     Action               Source               Target        Amount         Status    ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  JCWiBS823cKzXTU6MQqoG    Transfer     demo-bank-wallet    settlement-wallet        $30    usd    completed  ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  5usjn3eBuqu8X431DGgHa    Transfer    settlement-wallet     demo-bank-wallet        $20    usd     pending   ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  BJgB1yDLFKnfHIGnlVKnR    Transfer    settlement-wallet     demo-bank-wallet       $100    usd    completed  ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  qz30sjjHv5ti7wjuAgYrS    Transfer     demo-bank-wallet    settlement-wallet       $200    usd    completed  ║
╟──────────────────────────────────────────────────────────────────────────────────────────────────────────────╢
║  uslP0M2CUwxtTiaKIQspr    Transfer     demo-bank-wallet    settlement-wallet       $300    usd    completed  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

And we can also see that demo-bank-wallet balance is now changed:

$ minka wallet balances demo-bank-wallet 
Balances:
$570.00 (usd)

Unrestricted wallet access

Showcasing unrestricted behavior we had so far in this tutorial

Private keys security

How to properly manage your keys' security

On this page

Removing all access
Testing clearinghouse access
Adding access
Testing demo bank access
Testing balance transfer (fail)
Testing balance transfer (success)