How to Migrate Ledger Access Strategy to Policy-Based

How to Migrate Ledger Access Strategy to Policy-Based

This guide explains how to update a ledger's access strategy from the default record-based to policy-based using the Minka CLI.

Overview

Minka ledgers support two access strategies:

• record-based (default): Access control rules are defined directly on individual records (ledger, domains, etc.)
• policy-based: Access control is managed globally through policies without requiring attachment to specific records

Prerequisites

Before starting the migration, ensure you have:

1. Minka CLI installed and configured
2. Active ledger connection with appropriate permissions
3. Signer access to update the ledger configuration

Step-by-Step Migration

1. Connect to your server and ledger

First, ensure you're connected to the correct ledger:

# Connect to your server
minka server connect <server-url>

# Select the target ledger
minka ledger select <ledger-handle>

# Verify the current ledger
minka ledger show

2. Login with appropriate permissions

Make sure you're authenticated with a signer that has ledger update permissions:

# Login to the ledger
minka ledger login

# Verify you're logged in
minka ledger show

3. Update the ledger configuration

You can update the access strategy using either interactive mode or editor mode:

Option A: Interactive Mode (Recommended)

# Start the interactive ledger update
minka ledger update

The CLI will present a menu-driven interface:

1. Select "Config" from the update options
2. When prompted for "Access strategy:", choose policy-based
3. Configure other settings as needed (or keep defaults)
4. Select "Finish" to proceed with the update
5. Choose your signer when prompted
6. Confirm the update

Option B: Editor Mode

# Update using external editor
minka ledger update --editor

In the editor, modify the configuration:

{
  "handle": "your-ledger-handle",
  "config": {
    "access.strategy": "policy-based"
  }
  // ... other existing configuration
}

4. Verify the Migration

After the update completes, verify the access strategy has been changed:

# Check the updated ledger configuration
minka ledger show

Look for the access.strategy field in the configuration section to confirm it shows policy-based.

What Happens During Migration

When you migrate to policy-based access strategy, the system automatically:

1. Switches access control evaluation to use policies instead of record-level rules
2. Stops storing owners on new records (as they're managed by policies)

Understanding policy-based access strategy

After migration, your ledger will:

• Evaluate policies globally instead of checking individual record access rules
• Use active policies to determine access permissions
• Ignore access rules defined directly on records like domains, wallets, etc.
• Require policy management for access control changes