Skip to content

Operating instructions

Jump to bottom
Francisco Joray edited this page Dec 11, 2025 · 3 revisions

Operating instructions

Previous Next Up
Use-case application Game usage Home

Partnerchain set up and usage

The inclusion of the partner-chain toolkit allows us to create some UTxOs in Cardano that rule some aspects of the partner chain. We’ll briefly go over what these are and then we’ll go through the instructions to set up the partner chain using the wizards.

The UTxOs that will be created on the cardano side are the following;

  • Governance init UTxO: identifies the partner chain, it’s unique for each chain.
  • Permissioned-candidates UTxO: holds the list of permissioned candidates for the list. It can be updated.
  • D-Parameter UTxO: holds the D-Parameter, which is the ratio of permissioned to registered candidates on the committee. It is updatable as well.

Instructions

Build the node

You can build the griffin-partner-chains-node with the following command (recall the convenience of using our rust-toolchain.toml at the repo root):

cargo build --release -p griffin-partner-chains-node

Generate-keys

The first time you set up a chain you’ll need to run the generate-keys command:

./griffin-partner-chains-node wizards generate-keys

This command creates three keys: a partner-chain key, a grandpa key and an aura key. The first one is an identifier for the node and the last two are used for the committee. If you run this command and there are keys present already, it will prompt you to decide whether you want new ones or not.

Prepare-configuration

This command requires Ogmios so make sure to have that service on before running it.

This wizard sets up the initial governance UTxO and also fills the pc-chain-config.json file. Once you start the wizard:

./griffin-partner-chains-node wizards prepare-configuration

It will prompt you to fill out some information:

  1. Update the bootnodes and provide the public IP or host name for your node.
  2. Provide the information to connect to the Ogmios instance.
  3. Provide the required keys and select a UTxO that will be used to initialize the chain.
  4. Provide and confirm initial multisig governance authorities. This can be skipped and confirmed later using other commands, but we won’t document this approach.
  5. Configure native token. Native tokens aren’t supported, so anything set here won’t have any impact on the sidechain.
  6. Store the main chain configuration, this is, the pc-chain-config.json.

After the wizard finishes, you need to include the permissioned candidates on the initial_permissioned_candidates field of the aforementioned file. Here you may include the keys that were generated in the previous step, for example. But you might also need to gather the keys of the other permissioned candidates of the chain. Once the file has been adequately modified, you may move on to the next step.

Setup-main-chain-state

This command requires Ogmios so make sure to have that service on before running it.

This command sets up the DParameter and the Initial Permissioned Candidates list on the main chain.

./griffin-partner-chains-node wizards setup-main-chain-state

It will prompt you to provide the Ogmios instance. Then, as it doesn’t find a UTxO with the permissioned candidates, it will ask whether to create the UTxO or not. If you choose to set the UTxO, it will prompt for the signing key and to choose a UTxO for consumption. Afterwards, the wizard will ask for the DParam values. Firstly, for the Permissioned Candidates and then for the Registered ones. After this is finished, the DParam will be set on the mainchain.

Create-chain-spec

This command is different from the original Partner Chain’s one, as we’ve modified it to build the chain specification that we need for Griffin. The functionality is similar in that it reads the pc-chain-config.json file to obtain the chain information and builds the chain specification, which in our case is the set of genesis UTxOs. Before running this step we need to have the registered candidates’ keys as well, and they need to be added to the permissioned candidate field on the configuration file.

./griffin-partner-chains-node wizards create-chain-spec

After reading the candidates list from the configuration, it will prompt you to choose if you want to use it for the genesis.

Example with Devnet

Before starting testing on Cardano, you might find it useful to follow these previous steps connecting with a local devnet, using test keys. The stack comes with both Substrate and Main chain keys for 5 nodes, but in this example we will be using only 3 of them. For this walkthrough we will be using Docker to set up a stack of utilities needed for the setup. We need to have a functioning instance of a Cardano node, connected to DB-sync and PostgreSQL instances, along with an Ogmios instance.

To initialize the stack, you need to navigate to the dev/local-environment.

cd dev/local-environment/

Here we can do docker compose up -d; this might take some time the first time you run it. After it finishes pulling the images and starting the services, it will take a bit to correctly initialize every service. Once every service is initialized, we can start configuring the chain.

We will be starting 3 nodes. The first one will correspond to the chain builder, and the other two will be other permissioned candidates.

Setup

Go back to the repo base path (cd ../../)

We will create three directories, one for each node:

mkdir node1 node2 node3

We need to copy the node executable to each of these folders.

cp target/release/griffin-partner-chains-node node1
cp target/release/griffin-partner-chains-node node2
cp target/release/griffin-partner-chains-node node3

And we also need to create a sub folder chains for each node, that will in turn have a local_testnet sub folder. This will hold the keystore, db and network key of the chain:

mkdir -p node1/chains/local_testnet
mkdir -p node2/chains/local_testnet
mkdir -p node3/chains/local_testnet

We also need to copy the keys for the chain builder. We will copy the keys present in the Cardano folder of the dev environment, as we will use funded_address to sign and pay for the partner chain transactions in Cardano.

cp -r dev/local-environment/configurations/cardano/keys node1

As the other nodes will be permissioned they won’t need to sign any transactions on the Cardano side, so we won’t need any keys for them.

1. Generate-keys

Run the generate-keys command within each node’s sub folder:

cd node1/
./griffin-partner-chains-node wizards generate-keys

Then make sure to appropriately point to the node directory as base path (./):

This 🧙 wizard will generate the following keys and save them to your node's keystore:
→ ecdsa Cross-chain key
→ sr25519 AURA key
→ ed25519 Grandpa key
It will also generate a network key for your node if needed.

> Enter the node base path ./

This will generate a set of 3 keys like the following:

{
  "partner_chains_key": "0x031c995372ba274cd5c88ea22e342b6557d36d7a0adf768fb3fcad8debe1282819",
  "keys": {
    "aura": "0x74691960a862d3fd979b8cd7fbc6802caede3a16850da0a1d972aa292cfe8358",
    "gran": "0x7ae1e582882c736d524199d6fcd82a3644089702733746bed90d121ca9e8ce80"
  }
}

This command creates a partner-chains-public-keys.json file that saves the keys. After repeating this step for each node, we will have the set of keys needed for the configuration of the chain.

2. Prepare configuration

This step must be run within our chain builder’s node folder, in this case node1. We also need to have Ogmios available so if you haven’t initialized the stack yet, it’s time to do so with docker compose up -d on the dev/local-environment folder. Once Ogmios is ready to receive connections we can run the wizard:

./griffin-partner-chains-node wizards prepare-configuration

First we configure the bootnode and its access point. Make sure to select this directory as the node base path (./).

This 🧙 wizard will:
* establish single bootnode configuration (to be later included in chain-spec file)
* choose Genesis UTXO on Cardano
* initialize Partner Chains Governance on Cardano
* establish Partner Chains Smart Contracts addresses and policies (to be later included in chain-spec file)
> Enter the node base path ./
> Do you want to configure a single bootnode with your peer id '12D3KooWCwp2Mnd9xrTjbbu4voHRBMmdyzTqYwQJh9YBsXvq99LP'? Yes
> Your bootnode should be accessible via: hostname
> Enter bootnode TCP port 3033
> Enter bootnode hostname localhost
Bootnode saved successfully. Keep in mind that you can manually modify pc-chain-config.json, to edit bootnodes.

Then we will set up the genesis UTxO. First we need to configure the Ogmios connection:

Now, let's set up the genesis UTXO. It identifies the partner chain. This wizard will query Ogmios for your UTXOs using the address derived from the payment signing key. This signing key will be then used for spending the genesis UTXO in order to initialize the chain governance. Please provide required data.
> Select Ogmios protocol (http/https) http
> Enter the Ogmios hostname localhost
> Enter the Ogmios port 1337

Then it will prompt for the signing key file, and make you choose from that address one UTxO to use as Genesis:

> Enter the path to the payment signing key file keys/funded_address.skey
⚙️ Querying UTXOs of addr_test1vr5vxqpnpl3325cu4zw55tnapjqzzx78pdrnk8k5j7wl72c6y08nd from Ogmios at http://localhost:1337...
> Select an UTXO to use as the genesis UTXO f8fbe7316561e57de9ecd1c86ee8f8b512a314ba86499ba9a584bfa8fe2edc8d#0 (1000000000 lovelace)

And for the initial governance set:

Please provide the initial chain governance key hashes:
> Enter the space separated keys hashes of the initial Multisig Governance Authorities 0xe8c300330fe315531ca89d4a2e7d0c80211bc70b473b1ed4979dff2b
> Enter the Initial Multisig Governance Threshold 1
> Governance will be initialized with:
Governance authorities:
	0xe8c300330fe315531ca89d4a2e7d0c80211bc70b473b1ed4979dff2b
Threshold: 1
Do you want to continue? Yes

We are using a default address in this case, so the commands’ default prompt is good. If you wanted to use another address, you’d need to input the corresponding public key.

Moreover, if you input more than one public key, or if you input a public key that doesn’t correspond with the signing key, the wizard will create a multisig governance for the rest of the governance commands. For the sake of simplicity, we won’t show this approach here.

After agreeing to continue, the wizard will submit the initial governance transaction:

2025-10-23T17:38:44.073757719-03:00 INFO partner_chains_cardano_offchain::init_governance - ✉️ Submitter address: addr_test1vr5vxqpnpl3325cu4zw55tnapjqzzx78pdrnk8k5j7wl72c6y08nd
2025-10-23T17:38:44.073782826-03:00 INFO partner_chains_cardano_offchain::init_governance - 💱 4 UTXOs available
2025-10-23T17:38:44.240917905-03:00 INFO partner_chains_cardano_offchain::init_governance - ✅ Transaction submitted. ID: 611b0f6cbcdf0f137f2018e2774ba4390b96200baec879a3e71a43cb6d4c9e2c
2025-10-23T17:38:44.241007204-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output '611b0f6cbcdf0f137f2018e2774ba4390b96200baec879a3e71a43cb6d4c9e2c#0'
2025-10-23T17:38:49.246943249-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output '611b0f6cbcdf0f137f2018e2774ba4390b96200baec879a3e71a43cb6d4c9e2c#0'
2025-10-23T17:38:49.251409241-03:00 INFO partner_chains_cardano_offchain::await_tx - Transaction output '611b0f6cbcdf0f137f2018e2774ba4390b96200baec879a3e71a43cb6d4c9e2c'
Governance initialized successfully for UTXO: f8fbe7316561e57de9ecd1c86ee8f8b512a314ba86499ba9a584bfa8fe2edc8d#0

A file will be created as well (pc-chain-config.json), with the chain configuration:

{
  "bootnodes": [
    "/dns/localhost/tcp/3033/p2p/12D3KooWCwp2Mnd9xrTjbbu4voHRBMmdyzTqYwQJh9YBsXvq99LP"
  ],
  "cardano": {
    "active_slots_coeff": 0.4,
    "epoch_duration_millis": 120000,
    "first_epoch_number": 0,
    "first_epoch_timestamp_millis": 1761249030000,
    "first_slot_number": 0,
    "security_parameter": 5,
    "slot_duration_millis": 1000
  },
  "cardano_addresses": {
    "bridge": {
      "asset": {
        "asset_name": "0x",
        "policy_id": "0x00000000000000000000000000000000000000000000000000000000"
      },
      "illiquid_circulation_supply_validator_address": "addr_test1wptv33aalq7dpnkd8fpgnelsxn0sa49h2dqw0wzj3g7e97cnm4p0v"
    },
    "committee_candidates_address": "addr_test1wrnxhtkrgseddsx90c99c0g6kwprm6l8ztay50qfxwtyamg56ulc7",
    "d_parameter_policy_id": "0x984d9f65827b0ecaf407725aa8a2bfdd8086ccaf684179a5ece6b21e",
    "governed_map": {
      "policy_id": "0x72c20375b1429c39cfe01c88065a5110ac7592f31cf57ebcff4d5498",
      "validator_address": "addr_test1wqnwyett6a4squsfe0zyns65dhtsrf8cjkqug7pg5n0g2ucgnwaj0"
    },
    "permissioned_candidates_policy_id": "0xa5dce5600d8c898c72d69928db3731c6efd0368bf4402f0a1ae68d2c"
  },
  "chain_parameters": {
    "genesis_utxo": "f8fbe7316561e57de9ecd1c86ee8f8b512a314ba86499ba9a584bfa8fe2edc8d#0"
  },
  "initial_governance": {
    "authorities": [
      "0xe8c300330fe315531ca89d4a2e7d0c80211bc70b473b1ed4979dff2b"
    ],
    "threshold": 1
  },
  "initial_permissioned_candidates": []
}

3. Setup-main-chain-state

Before running this wizard, we need to modify the previously mentioned file to include our permissioned candidates’ keys (the keys we generated at the beginning):

"initial_permissioned_candidates": [
  {
    "partner_chains_key": "0x036195477f75452bc298b3bfc9bb3e84f33cbd3fc95c9d2a1fcf8980493f3c0a1a",
    "keys": {
      "aura": "0x9a18472abce2625ed1c042909c802f5bb28bcb6821b39115be35fdc8ad3fd947",
      "gran": "0xd9eac2dadcfe5c339a5fe7bd2edb1ed81bd6885ebe6df061fe0459b186894648"
    }
  },
  {
    "partner_chains_key": "0x036336457437fa2cf806bc830007a24949fa2751f856b67501e2992eea9c155b35",
    "keys": {
      "aura": "0x503d1c528caa6e251d6f0704c8c123f8dc2b406d76cfde71ee1c1b578df8b734",
      "gran": "0x47b7b6682795111d59ebefd41fd5261e2a23b756e9a89361e333ab5def653b3e"
    }
  },
  {
    "partner_chains_key": "0x020aa543bb236cd1f10baf98fdb5d978e0cec5ce9e0ef26e5a202bd6d6ea3fc940",
    "keys": {
      "aura": "0x2658f7871b44d5bfaec78697672febd7972d1bf80ac13a3235d38e5a6e19692e",
      "gran": "0xdfa706f73659f51a659a405f622f0bba65a0822e068e230349936d0a1d4eecf6"
    }
  }
]

This is an example of what it looks like with the keys I generated.

Once we have this we can run the next wizard (also within node1/):

./griffin-partner-chains-node wizards setup-main-chain-state

You should still have an Ogmios instance running, this is the first thing the wizard asks for:

This wizard will set or update D-Parameter and Permissioned Candidates on the main chain. Setting either of these costs ADA!
Will read the current D-Parameter and Permissioned Candidates from the main chain using Ogmios client.
> Select Ogmios protocol (http/https) http
> Enter the Ogmios hostname localhost
> Enter the Ogmios port 1337

Since this is the first time running this command for this chain, the permissioned candidates list on chain is empty, and the wizard asks if you want to update it with the candidates on the configuration file. Here we need to use the same signing key that we used for the chain setup.

List of permissioned candidates is not set on Cardano yet.
> Do you want to set/update the permissioned candidates on the main chain with values from configuration file? Yes
> Enter the path to the payment signing key file keys/funded_address.skey
2025-10-23T17:49:32.257962365-03:00 INFO partner_chains_cardano_offchain::permissioned_candidates - There aren't any permissioned candidates. Preparing transaction to insert.
2025-10-23T17:49:32.391697248-03:00 INFO partner_chains_cardano_offchain::multisig - 'Insert Permissioned Candidates' transaction submitted: b7df75650d53865422534c8e14ea32b386ad4626ad1d79c61626aa7b7d501ab5
2025-10-23T17:49:32.391776440-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output 'b7df75650d53865422534c8e14ea32b386ad4626ad1d79c61626aa7b7d501ab5#0'
2025-10-23T17:49:37.397929702-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output 'b7df75650d53865422534c8e14ea32b386ad4626ad1d79c61626aa7b7d501ab5#0'
2025-10-23T17:49:37.401745736-03:00 INFO partner_chains_cardano_offchain::await_tx - Transaction output 'b7df75650d53865422534c8e14ea32b386ad4626ad1d79c61626aa7b7d501ab5'
Permissioned candidates updated. The change will be effective in two main chain epochs.

Afterwards, it checks for the D-Parameter and again, it’s not set. So we will be prompted to fill it out if we want to. Here we set a ratio of 3 permissioned candidates and 0 registered, simply because that’s the amount of nodes we will be turning on.

> Do you want to set/update the D-parameter on the main chain? Yes
> Enter P, the number of permissioned candidates seats, as a non-negative integer. 3
> Enter R, the number of registered candidates seats, as a non-negative integer. 0
> Enter the path to the payment signing key file keys/funded_address.skey
2025-10-23T17:50:23.428976515-03:00 INFO partner_chains_cardano_offchain::d_param - There is no D-parameter set. Inserting new one.
2025-10-23T17:50:23.572951836-03:00 INFO partner_chains_cardano_offchain::multisig - 'Insert D-parameter' transaction submitted: 29b848247023a18cb97ddb39ee8ef3c859b2b34be59160527e3e44a87945155e
2025-10-23T17:50:23.573049815-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output '29b848247023a18cb97ddb39ee8ef3c859b2b34be59160527e3e44a87945155e#0'
2025-10-23T17:50:28.578153078-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output '29b848247023a18cb97ddb39ee8ef3c859b2b34be59160527e3e44a87945155e#0'
2025-10-23T17:50:28.585816840-03:00 INFO partner_chains_cardano_offchain::await_tx - Transaction output '29b848247023a18cb97ddb39ee8ef3c859b2b34be59160527e3e44a87945155e'
2025-10-23T17:50:28.585873149-03:00 INFO partner_chains_cardano_offchain::await_tx - Probing for transaction output '29b848247023a18cb97ddb39ee8ef3c859b2b34be59160527e3e44a87945155e#0'
2025-10-23T17:50:28.589846603-03:00 INFO partner_chains_cardano_offchain::await_tx - Transaction output '29b848247023a18cb97ddb39ee8ef3c859b2b34be59160527e3e44a87945155e'
D-parameter updated to (3, 0). The change will be effective in two main chain epochs.
Done. Please remember that any changes to the Cardano state can be observed immediately, but from the Partner Chain point of view they will be effective in two main chain epochs.

4. Create-chain-spec

The last step of the wizard helps us create the genesis file that we will need to start the chain. This wizard reads the candidates from the list in the configuration file and adds them to a UTxO in the genesis set for the chain. Within node1/ run:

./griffin-partner-chains-node wizards create-chain-spec

Then confirm the provided values:

This wizard will create a genesis.json to use as chain spec, using the candidates found in the the provided configuration
If the chain includes registered candidates, you need to obtain their keys and add them to the permissioned candidates list in the configuration as well, to set up the genesis accordingly. You need to have all the candidate's keys before moving on, or else they won't be able to participate in the chain.
Chain parameters:
- Genesis UTXO: f8fbe7316561e57de9ecd1c86ee8f8b512a314ba86499ba9a584bfa8fe2edc8d#0
Candidates:
- Partner Chains Key: 0x036195477f75452bc298b3bfc9bb3e84f33cbd3fc95c9d2a1fcf8980493f3c0a1a, aura: 0x9a18472abce2625ed1c042909c802f5bb28bcb6821b39115be35fdc8ad3fd947, gran: 0xd9eac2dadcfe5c339a5fe7bd2edb1ed81bd6885ebe6df061fe0459b186894648
- Partner Chains Key: 0x036336457437fa2cf806bc830007a24949fa2751f856b67501e2992eea9c155b35, aura: 0x503d1c528caa6e251d6f0704c8c123f8dc2b406d76cfde71ee1c1b578df8b734, gran: 0x47b7b6682795111d59ebefd41fd5261e2a23b756e9a89361e333ab5def653b3e
- Partner Chains Key: 0x020aa543bb236cd1f10baf98fdb5d978e0cec5ce9e0ef26e5a202bd6d6ea3fc940, aura: 0x2658f7871b44d5bfaec78697672febd7972d1bf80ac13a3235d38e5a6e19692e, gran: 0xdfa706f73659f51a659a405f622f0bba65a0822e068e230349936d0a1d4eecf6
> Do you want to continue? Yes
genesis.json file has been created.
Committee candidates will be found at 0000000000000000000000000000000000000000000000000000000000, with the corresponding Authorities token
The rest of the UTxOs can be modified to have the genesis set you need.
If you are the governance authority, you can distribute it to the validators.

The genesis file, called new-genesis.json by the wizard, has to be shared with the rest of the nodes.

cp new-genesis.json ../node2/
cp new-genesis.json ../node3/

5. Start the nodes

First we need to move the network and keystore folders from each node base path to the corresponding chains/local_testnet/ folder, as that is where the node will look for them before executing.

mv node1/network node1/chains/local_testnet/
mv node1/keystore node1/chains/local_testnet/
mv node2/network node2/chains/local_testnet/
mv node2/keystore node2/chains/local_testnet/
mv node3/network node3/chains/local_testnet/
mv node3/keystore node3/chains/local_testnet/

To initialize node1, run (within node1/):

./griffin-partner-chains-node \
 --validator \
 --chain=new-genesis.json \
 --base-path . \
 --port 3033 \
 --rpc-port=9944 \
 --rpc-cors=all \
 --unsafe-rpc-external \
 --prometheus-port=9615 \
 --prometheus-external

To initialize node2, you will need to copy the ID of node1, the bootnode we are connecting to. You can find it in the output of the previous command, or by checking the pc-chain-config.json file within node1’s base path. In this case it is 12D3KooWCwp2Mnd9xrTjbbu4voHRBMmdyzTqYwQJh9YBsXvq99LP. Now run (within node2/):

./griffin-partner-chains-node \
 --validator \
 --chain=new-genesis.json \
 --base-path . \
 --port 3034 \
 --rpc-port=9945 \
 --rpc-cors=all \
 --unsafe-rpc-external \
 --prometheus-port=9616 \
 --prometheus-external \
 --bootnodes /dns/localhost/tcp/3033/p2p/12D3KooWCwp2Mnd9xrTjbbu4voHRBMmdyzTqYwQJh9YBsXvq99LP

To initialize node3 connecting to node1, we proceed similarly (within node3/):

./griffin-partner-chains-node \
 --validator \
 --chain=new-genesis.json \
 --base-path . \
 --port 3035 \
 --rpc-port=9946 \
 --rpc-cors=all \
 --unsafe-rpc-external \
 --prometheus-port=9617 \
 --prometheus-external \
 --bootnodes /dns/localhost/tcp/3033/p2p/12D3KooWCwp2Mnd9xrTjbbu4voHRBMmdyzTqYwQJh9YBsXvq99LP

You may need to modify the port numbers if they’re already in use by some other service on your computer, just make sure to change the mentions appropriately.

Restarting the chain

If you wish to scrub the previous chain, you can use the purge-chain command:

./griffin-partner-chains-node purge-chain -d .

This command removes the database stored at chains/local_testnet located in the current directory.

./griffin-partner-chains-node purge-chain -d . 
Are you sure to remove "./chains/local_testnet/paritydb"? [y/N]: y
"./chains/local_testnet/paritydb" removed.
Previous Next Up
Use-case application Game usage Home

Clone this wiki locally