Manage Permissioned Partition

This tutorial outlines the steps to set up and manage a Permissioned User Token Partition, where only pre-authorized users can send transactions. It covers configuring the admin key and using the CLI wallet to control who can send transactions within the partition.

Prerequisites

You have set up an Alphabill CLI wallet with a key pair to serve as the admin key for the permissioned partition.

Set Up Permissioned Partition

Add Admin Key

1. Go to the alphabill-wallet/build directory and list the public keys of your wallet:

   ./abwallet wallet get-pubkeys
   Example response:

   #1 0x029187dbe17669aa7cc4732248400454edebee8a35aa45d82d345f1bddd7528f63
   #2 0x09187dbe17669aa7cdbe17669aa7cc4732248400454edebee82159aa7cc4732a35

   Choose the public key you want to use as the admin key for the permissioned partition.

2. Generate a P2PKH (Pay to Public Key Hash) predicate for the selected admin key. In the alphabill-wallet directory, run the following command, replacing the PUBLIC_KEY with the actual public key from the previous step:

   go run scripts/templates/create_p2pkh.go --pubkey PUBLIC_KEY
   Example response:

   0x830041025820075057A99CB137A6307B3FCB45923A48FF935A4C92412D255BA209753AC55B7B
   Important

   When using the generated predicate in the ./setup-testab.sh script, remove the 0x prefix.

Run Local Testnet

To enable permissioned mode, include the admin key in the startup scripts. When the admin key is provided, the partition node will operate in permissioned mode with custom fee handling.

1. In the alphabill directory, run the ./setup-testab.sh script, replacing ADMIN_KEY with the output from the create_p2pkh.go script (without the 0x prefix):

   ./setup-testab.sh -m 0 -t 0 -e 0 -o 0 -r 4 -k 3 -a ADMIN_KEY
   Example response:

   clearing 'testab' directory and building Alphabill
   rm -rf build/
   rm -rf testab/
   cd ./cli/alphabill && go build -o ../../build/alphabill
   generating 3 genesis files for tokens-enterprise partition
   generating 4 genesis files for root node

   The script generates testab structure, log configuration, and genesis files for 4 root nodes and 3 tokens-enterprise nodes. It accepts following flags to customize the generated testnet:

   • -m: number of money nodes
   • -t: number of token nodes
   • -e: number of EVM nodes
   • -o: number of orchestration nodes
   • -r: number of root nodes
   • -k: number of enterprise token partition nodes
   • -a: enterprise token partition admin owner predicate

   The configuration files are stored in the testab directory.

2. Once the setup is finished, start the root nodes and tokens-enterprise nodes by running the following script:

   ./start.sh -r -p tokens-enterprise
   Example response:

   starting root nodes...
   started 4 root nodes
   starting tokens-enterprise nodes...
   started 3 tokens-enterprise nodes

   To stop the local test, run the following script to safely shut down root chain and all partition nodes:

   ./stop.sh -a

Manage User Permissions

The CLI wallet provides separate commands to interact with the Permissioned User Token Partition. As the admin of a permissioned partition, you can use the CLI wallet to control who can send transactions to the permissioned partition.

To see available CLI options for managing the permissioned partition, open the help output:

./abwallet wallet permissioned -h

cli for managing permissioned partitions

Usage:
  abwallet wallet permissioned [flags]
  abwallet wallet permissioned [command]

Available Commands:
  add-credit    adds fee credit to a fee credit record owned by the specified owner predicate (admin only command)
  delete-credit deletes fee credit record owned by the specified owner predicate (admin only command)

Flags:
  -h, --help             help for permissioned
  -r, --rpc-url string   RPC URL of a partition node

Global Flags:
      --config string            config file URL (default is $AB_HOME/config.props)
      --home string              set the AB_HOME for this invocation (default is /home/user/.alphabill)
      --log-file string          log file path or one of the special values: stdout, stderr, discard
      --log-format string        log format, one of: text, json, console
      --log-level string         logging level, one of: DEBUG, INFO, WARN, ERROR
  -p, --password                 password (interactive from prompt)
      --pn string                password (non-interactive from args)
  -l, --wallet-location string   wallet home directory (default $AB_HOME/wallet)

Use "abwallet wallet permissioned [command] --help" for more information about a command.

Authorize User Transactions

1. To authorize a user to send transactions to the permissioned partition, use the wallet permissioned add-credit command. Replace the PUBLIC_KEY with the user's public key and the RPC_URL with the actual URL of the partition node:

   ./abwallet wallet permissioned add-credit \
   --amount 10 \
   --target-pubkey PUBLIC_KEY \
   --rpc-url RPC_URL
   Example response:

   Fee credit added successfully
   tip

   When running a local testnet, use the following command to list running tokens-enterprise nodes on your system:

   ps aux | grep alphabill

   The output includes node's --rpc-server-address, which you can use as the --rpc-url value, such as localhost:31866.

2. If the authorization is successful, the user can verify it by running the following command:

   ./abwallet wallet fees list -n enterprise-tokens
   Example response:

   Partition: enterprise-tokens
   Account #1 10.000'000'00
   Account #2 0.000'000'00

Revoke User Authorization

1. To revoke a user's permission to send transactions within the permissioned partition, use the wallet permissioned delete-credit command, replacing the PUBLIC_KEY and RPC_URL with actual values:

   ./abwallet wallet permissioned delete-credit \
   --target-pubkey PUBLIC_KEY \
   --rpc-url RPC_URL
   Example response:

   Fee credit deleted successfully

2. After successful revocation, the user wallet's fee credit balance is empty:

   ./abwallet wallet fees list -n enterprise-tokens
   Example response:

   Partition: enterprise-tokens
   Account #1 0.000'000'00
   Account #2 0.000'000'00