Partner Chains v1.8.1

Changed

• Updated polkadot-sdk dependency to polkadot-stable2509.
  Partner Chains Aura modification follows changes regarding checking inherents that are also present in the new polkadot-sdk release.
  Pallet Session new parameters should be set as: type KeyDeposit = (); and type Currency = Balances;.

Fixed

• Fixed offchain error when irrelevant utxos were present while updating d-param and permissioned candidates
• Improper weights for set_main_chain_scripts in pallet_session_validator_management

Compatibility matrix

partner-chains-node	cardano-node	cardano-db-sync	ogmios
v1.8.1	10.5.1	13.6.0.4	v6.13.0

How to Use

Refer to the documentation
for detailed instructions on using the node and CLI tools.

Support

You can visit our issues page for support, feature requests, or to report a bug.

Full Changelog: v1.8.0...v1.8.1-rc1

Partner Chains Node v1.8.0

Generic keys feature

Up to v1.7.x the toolkit has supported only a triplet of keys: Partner-Chain keys, AURA, and Grandpa. Partner Chain key's special meaning and presence is preserved, but the number and types of the remaining keys can be configured according to the needs of a particular Partner Chain.

This enables use of additional pallets that require other keys.

Integration with the wizards CLI is done by means of PartnerChainRuntime trait implementation. See Update Guide for more details.

On Cardano side the Plutus Data format has been changed from [Partner-chain, AURA, Grandpa], to [Partner-chain, [[key_1_id, key_1_bytes],...,[key_n_id, key_n_bytes]]], where key_i_id is 4 bytes encoding key type. This is present in version 1 of datums that are now used in place of version 0.

In SCALE encoding of inherent data custom implementations of Encode and Decode have been added to make this transition backward and forward compatible and transparent for the toolkit users. This change does not imply any order of nodes and runtime upgrade.

getAriadneParameters and getRegistrations RPC results format has changed, auraPubKey and grandpaPubKey are replaced by "keys": {"aura": "...", "gran": "..."}.

Unidirectional Token Bridge

A set of modules implementing observability layer, runtime pallet and offchain commands for a trustless token bridge moving tokens from Cardano to the Partner Chain.

This bridge feature works by monitoring an illiquid circulation supply validator address on Cardano for new UTXOs. These UTXOs are interpreted as being either user-initiated
transfers sent to a specified address on the Partner Chain, or reserve transfers made as part of the chain's operations for the purposes of distributing them as
block producer rewards on-chain. Handling of the transfers is left to the chain builders themselves to implement according to their business needs and ledger structure.

---

Important:

• BREAKING: partner-chains-smart-contracts (raw-scripts) updated to v8.1.0. You must re-initialize on Cardano (new deployment + re-registration).
• BREAKING: Native Token Management feature removed (crates deleted).
• Security: Block producer metadata now uses a constant fee/burn and valid_before to mitigate replay/front-run and storage abuse.
• SDK/Tooling: Rust toolchain 1.90 (2024 edition) and target wasm32v1-none.
• Polkadot SDK: multiple bumps; type RuntimeEvent removed—update your runtime accordingly.
• See the migration guide for operational steps from v1.7.x → v1.8.0.

Changed

• Governance & Wizards: multisig flows (governance, d-param, permissioned candidates, reserve ops); simpler params; improved defaults and UX (Ctrl-C/ESC handling).
• Networking: litep2p default for demo node (libp2p still available via --network-backend).
• Mainchain address I/O: serialized as string (hex accepted on input).
• Ogmios/data sources: WebSocket client; configurable URL/timeouts; clearer errors; CARDANO_DATA_SOURCE env; optional tx-in.value = "consumed" support.
• Selection/Ariadne v2: input robustness and guaranteed-seats algorithm; committee data now also carries candidate type and MC pubkey.
• Benchmarks/weights refreshed (e.g., block-producer-fees, governed-map).
• CI/CD & Local Env: faster builds, cache validation/locking, optional chain wipe, host-mode single node option, streamlined local Cardano topology.

Fixed

• Governance actions initiated by non-governance wallets (redundant signature) no longer fail.
• Ogmios large responses and Plutus script decoding edge cases.
• Reserve release overflow/panics; ExUnits ordering/fee issues.
• Intermittent empty registration results and cache invalidation on script changes.
• Numerous CI/e2e stabilizations (timeouts, staging configs, deterministic D-param, stale log reads).

Added

• Governed Map: pallet + inherent data provider + data source + CLI (insert/get/list/update/remove) with caching & change-list API.
• Block Production Log pallet and Block Producer Fees pallet; RPC: pc_getBlockProducerFees.
• Address Associations pallet (with burn fee) + CLI; OnNewAssociation hook.
• CLI enhancements: sign-tx, assemble-tx, governance policy queries, reserve ops suite (init/create/deposit/release/update-settings), multisig flags; expanded CSL helpers.
• Config via env: PC_CHAIN_CONFIG_FILE, PC_RESOURCES_CONFIG_FILE, CARDANO_DATA_SOURCE; Ogmios URL/timeouts.

Compatibility matrix

partner-chains-node	cardano-node	cardano-db-sync	ogmios
v1.8.0	10.5.1	13.6.0.4	v6.13.0

Docker

You can also pull the Docker image of the partner-chains-node from GitHub Container Registry:

docker pull ghcr.io/input-output-hk/partner-chains/partner-chains-node:v1.8.0

How to Use

Refer to the documentation
for detailed instructions on using the node and CLI tools.

Support

You can visit our issues page for support, feature requests, or to report a bug.

Partner Chains v1.7.1

v1.7.1

polkadot-sdk dependency update

Toolkit is now based on polkadot-stable2506. Following deprecation in polkadot-sdk, type RuntimeEvent has been removed from pallet-native-token-management, pallet-partner-chains-session, and pallet-session-validator-management Config trait.
Please follow with their removal in you Runtime wiring.

Smart contracts update

BREAKING

partner-chains-smart-contracts dependency has been updated to v8.0.0. Smart contracts embedded in wizards (partner-chains-cli) and smart-contracts commands are not the same contracts as in v1.7.0 or earlier. This requires creating a new Partner Chains on Cardano and setting all the data, including registrations.

Full Changelog: v1.7.0...v1.7.1

Partner Chains v1.7.0

This release brings two major additions: support for multiple authorities governance and governed map, several bug-fixes and a lot of changes in toolkit to make it more flexible.

Added MultiSig Governance support in the user interface

Now, Governance mechanism uses Cardano ALeastN Native Script, instead of custom policy implemented as Plutus Script in partner-chains-smart-contracts. This policy doesn't require to set required_signers field in the transaction making it more user friendly - set of signers doesn't need to be known upfront.

governance init and governance update now accept multiple key hashes for the -g/--governance-authority parameter. These commands now also require -t/threshold parameter to set the number of required signatures.

All the smart-contracts sub-commands that require Governance: governance update, upsert-d-parameter, upsert-permissioned-candidates, reserve init, reserve create, reserve deposit, and reserve handover will now submit the transaction only if governance is "1 of 1". Otherwise these commands return a transaction CBOR that can be submitted with the new command assemble-and-submit-tx. Signatures can be obtained using sign-tx.

wizards prepare-configuration is adjusted to set initial governance authorities different to just a single key. wizards setup-main-chain-state is adjusted to print out transactions to sign if multiple governance authorities are used, in such a case it is unable to submit transaction, because of missing signatures.

See governance manual for instructions.

Governed Map

Governed Map feature is an implementation of key-value store on Cardano that can be update only by the PC governance. On the toolkit side, there is a DB-Sync follower implementation that can track changes to the related Cardano state, and a Pallet that reflects Cardano changes in the Partner Chain ledger.
smart-contracts governed-map --help provides required information for Cardano side operations.
For the pallet documentation, please see readme

wizards create-chain-spec is adjusted to set governedMap.MainChainScripts in the chain-spec file.

Fixes

• [BREAKING CHANGE]: Updated partner-chains-smart-contracts (raw-scripts) dependency to v7.2.2. This changes Version Oracle Validator script and is not compatible with the previous versions. smart-contracts and wizards will use different addresses, new Partner Chains have to be initialized. New registrations are requried.
• smart-contracts governance init could fail when genesis utxo had a script attached, because the transaction fee could be calculated incorrectly.
• [SECURITY FIX] Vulnerability of multiple crates, where a malicious block producing node could put multiple copies of the inherent in the block. This was because Substrate only checks whether an inherent is valid and doesn't ensure its uniqueness. This issue was fixed by including checks within the inherents themselves. Affected pallets that were patched are: session-validator-management, block-participation, native-token-management.
• wizards prepare-configuration updates existing chain_parameters.genesis_utxo field in pc-chain-config.json, prior to this fix it was not updating field that was once set.

Other changes

• smart-contracts commands accept optional parameter to configure Ogmios requests timeout, increased default timeout from 2 mintues to 5 minutes.
• Renamed environment variable MAIN_CHAIN_FOLLOWER_MOCK_REGISTRATIONS_FILE used by the mock data source has been changed to MOCK_REGISTRATIONS_FILE to match.
  Prometheus metrics mc_follower_method_time_elapsed and mc_follower_method_call_count were also renamed to
  partner_chains_data_source_method_time_elapsed and partner_chains_data_source_method_call_count respectively.

Cardano DB-Sync follower

• Automatically creates required index on tx_out table address column. Constructor signatures have changed - this change is not source compatible. This index was present in DB-Sync in the past, but recent versions do not include it anymore by default. This toolkit uses queries that query tx_out table by output address, so the index is required for decent performance.

Wizards

• [BREAKING CHANGE]: Wizards are not generating keys nor looking for them in <base_path>/chains/partner_chains_template, but use <base_path> instead.
• wizards setup-main-chain-state wizard uses Ogmios and offchain crate for getting the current D-parameter and Permissioned Candidates instead of invoking <node-executable> ariadne-parameters command. This change requires users that generated keystores and network key using previous versions of the wizards to move their keys two directories up.

Toolkit codebase

• [BREAKING CHANGE] Removed block-rewards pallet and its companion primitives crate. Block authorship information can be tracked using the block-production-log pallet instead.
• Added ariadne_v2 selection algorithm that selects committee respecting D-parameter and candidates weights, but has much less variance, thanks to assigning guaranteed seats to candidates with expected number of seats greater or equal 1.
• Updated polkadot-sdk dependency to polkadot-stable2503-5.
• MC Hash inherent data provider will not propose older MC state than one already present in the ledger, this enables using BLOCK_STABILITY_MARGIN greater than 0.
• partner-chains-db-sync-data-sources and partner-chains-mock-data-sources crates now exports all its public members from the root
• McHashInherentDataProvider now also exposes the Cardano block hash referenced by the previous block. It can be accessed through previous_mc_hash function. NativeTokenManagementInherentDataProvider now expects to be passed the previous main chain reference block hash on construction instead of retrieving it by itself. Use McHashInherentDataProvider::previous_mc_hash to provide it in your IDP stack.
• Added implementation of FindAccountFromAuthorIndex trait for pallet_partner_chains_session.
• Renamed sidechain-runtime to partner-chains-demo-runtime, sidechain-node to partner-chains-demo-node, and moved both to demo/ directory.
  Renamed db-sync-follower to partner-chains-db-sync-data-sources, main-chain-follower-mock to partner-chains-mock-data-sources.
• Introduced customization of root origin for few pallets via MainChainScriptsOrigin trait.
• Added pallet-block-producer-fees - with settings for the rewards payout logic.
• Added sign-block-producer-metadata command to cli-commands for signing block producer metadata upsert message.
• Removed crate pallet-session-runtime-stub which provided stub config for Substrate's pallet-session when using pallet-partner-chains-session. Its functionality was merged into pallet-partner-chains-session under the feature pallet-session-compat.
• Removed crate session-manager. Its functionality was merged into pallet-session-validator-management under the feature pallet-session-compat.
• Removed TryFrom<&serde_json::Value> for Datum and From<&Datum> for serde_json::Value instances from plutus.
• Removed ATMSPlainAggregatePubKey, ValidatorHash and SidechainPublicKeysSorted types from domain.
• Removed SidechainApi trait from sp-sidechain and its return type SidechainStatus. Code that uses it should directly use the APIs that were grouped into this trait or ideally define its own runtime API instead (see deprecation of GetSidechainStatus).
• Added db-sync-sqlx crate containing Rust types representing Cardano primitives present in postgres tables populated by Db-Sync.

Compatibility matrix

polkadot-sdk	cardano-node	cardano-db-sync	ogmios
stable2503-5	10.4.1	13.6.0.4	6.12.0

Full Changelog: v1.6.1...v1.7.0

Partner Chains Node v1.6.1

Changed

• Default smart-contracts timeout from 2 minutes to 5 minutes

Fixed

• governance init when genesis utxo had a script attached, then transaction fee was sometimes calculated incorrectly

Removed

• Removed unnecessary default dependencies from multiple crates

Compatibility matrix

partner-chains-node	polkadot-sdk	cardano-node	cardano-db-sync	ogmios
1.6.1	stable2412-1	10.1.4	13.6.0.4	6.11.0

Docker image

The docker image for of our test/demo partner-chain-node is available in GHCR:

docker pull ghcr.io/input-output-hk/partner-chains/partner-chains-node:v1.6.1

Full Changelog: v1.6.0...v1.6.1

Partner Chains Node v1.5.1

Known issues

• governance init may fail when genesis utxo has a script attached (fixed in v1.6.1)

Changed

• Default smart-contracts timeout from 2 minutes to 5 minutes

Fixed

• Failure of smart-contracts reserve release command when releasing all tokens in the reserve
• Failure of smart-contracts reserve handover command when reserve is empty

Removed

• Removed unnecessary default dependencies from multiple crates

Compatibility matrix

partner-chains-node	polkadot-sdk	cardano-node	cardano-db-sync	ogmios
1.5.1	stable2409-4	10.1.4	13.6.0.4	6.11.0

Docker image

The docker image for of our test/demo partner-chain-node is available in GHCR:

docker pull ghcr.io/input-output-hk/partner-chains/partner-chains-node:v1.5.1

Full Changelog: v1.5.0...v1.5.1

Partner Chains Node v1.6.0

Changed

• Split MainchainPublicKey to StakePoolPublicKey and StakePublicKey. Some parameters names have been changed as well, which can break compilation of downstream projects.
• Updated polkadot-sdk to polkadot-stable2412-1 : WARNING: Benchmarking command has been removed, because frame-benchmarking-cli crate became GPLv3 without any exception.
• Made Cardano slot duration configurable with default of 1000ms. If your partner chain's main chain is Cardano mainnet or one of the official testnets, you don't need to change anything. Otherwise, the duration can be set through MC__SLOT_DURATION_MILLIS environment variable.
• Committee member data stored by the Session Validator Management Pallet is now fully generic. To migrate to this version, define your own CommitteeMember type and implement the trait CommitteeMember for it and schedule a storage migration. See the CommitteeMember type implemented in node/runtime/src/lib.rs for reference using Ariadne. This is a critical breaking change. Please consult toolkit/pallets/session-validator-management/src/migrations/README.md before attempting upgrade.
• Merged functionality of NativeTokenManagementInherentDataProvider::new_if_pallet_present into NativeTokenManagementInherentDataProvider::new. Use this single constructor from now on.
• smart-contracts reserve deposit command parameter token has been removed, because it was redundant.

Fixed

• Failure of smart-contracts reserve release command when releasing all tokens in the reserve
• Failure of smart-contracts reserve handover command when reserve is empty

Added

• block-production-log pallet, see toolkit/pallets/block-participation for more details.
• Block participation pallet and inherent data provider, making available data on block producers and their delegators. This feature is meant to be used by Partner Chains developers to implement block production reward payouts in their own runtimes. See toolkit/primitives/block-participation/README.md for more information.

Compatibility matrix

partner-chains-node	polkadot-sdk	cardano-node	cardano-db-sync	ogmios
1.6.0	stable2412-1	10.1.4	13.6.0.4	6.11.0

Docker image

The docker image for of our test/demo partner-chain-node is available in GHCR:

docker pull ghcr.io/input-output-hk/partner-chains/partner-chains-node:v1.6.0

Full Changelog: v1.5.0...v1.6.0

Partner Chains Node v1.5.0

Known issues

• smart-contracts reserve release command fails when releasing all tokens in the reserve (fixed in v1.6.0)
• smart-contracts reserve handover command fails when reserve is empty (fixed in v1.6.0)

Changed

partner-chains-cli application is replaced by wizards node command

• The partner-chains-cli tool has been replaced by wizards subcommand from partner-chains-node-commands crate.
• Configuration files names has been changed to pc-chain-config.json and pc-resources-config.json.
  Please rename your existing configuration files accordingly.

pc-contracts-cli application is no longer used

• Because the transactions building and submission (so-called offchain code) has been implemented in Rust, the pc-contracts-cli tool is no longer used by wizards.
• kupo is no longer required by Partner Chains, because the Rust implementation requires only Ogmios. Its usage has been cleaned up in this repository.
• Combined with the fact that partner-chains-cli tool is replaced by wizards subcommand, the only required executable is the node itself.

Other changes

• polkadot depenedency has been updated from polkadot-stable-2409 to polkadot-stable-2409-4.
• node/runtime custom weighs has been replaced with ones from polkadot crates.

Added

Partner Chains Smart Contracts transactions building and sumbission is implemented in a partner-chains-cardano-offchain crate

The code to interact with Partner Chains Smart Contracts (so-called offchain code) has been implemented in Rust.

• Command smart-contracts has been added in partner-chains-smart-contracts-commands crate.
• smart-contracts command is integrated into partner-chains-node-commands crate.
  Please run <node executable> smart-contracts --help for listing of available commands of your node.
  There are cosmetic changes it the commands names and required parameters.
• smart-contracts command has replaced pc-contracts-cli application.

Extended keys support

<node executable> wizards and <node executable> smart-contracts now supports extended payment keys: PaymentExtendedSigningKeyShelley_ed25519_bip32 and PaymentExtendedVerificationKeyShelley_ed25519_bip32.

Compatibility matrix

partner-chains-node	cardano-node	cardano-db-sync	ogmios
1.5.0	10.1.4	13.6.0.4	6.11.0

Docker image

The docker image for of our test/demo partner-chain-node is available in GHCR:

docker pull ghcr.io/input-output-hk/partner-chains/partner-chains-node:v1.5.0

Full Changelog: v1.4.0...v1.5.0

Partner Chains Node v1.4.0

Important: Chains running earlier versions should follow the 1.4.0 migration guide

Changed

• genesis_utxo and registration_utxo no longer have to have no native tokens.
• Update ogmios to v6.11.0
• Organized Rust sources into two directories: toolkit and node.
• Implemented transaction balancing with CSL in offchain code.
• Update offchain code dependencies: pallas, ulpc and cardano-serialization-lib.
• Updated to partner-chains-smart-contracts v7.0.2
• • chain-params crate that provided SidechainParam is removed, because there are no SidechainParams anymore
• • partner-chains-cli is changed, so prepare-config wizard sets genesis_utxo and does not set sidechain parameters
• • pallets are not generic on SidechainParams anymore, they use UtxoId (genesis_utxo) instead
• • migration of pallet_sidechain storage is not present in this update, it has to be done before v1.4, so as for now it is a very breaking change

Fixed

• CardanoNetwork bug in partner-chains-cli, that would cause the CLI to fail with the mainnet.

Added

• Added smart-contracts command to the node with first command init-governance.

Compatibility matrix

partner-chains-node	partner-chains-smart-contracts	cardano-node	cardano-db-sync	kupo	ogmios
1.4.0	7.0.2	10.1.4	13.6.0.4	2.10.0	6.11.0

Binaries

PC smart contracts CLI can be downloaded from here.

Docker

You can also pull the Docker image of the partner-chains-node from GitHub Container Registry:

docker pull ghcr.io/input-output-hk/partner-chains/partner-chains-node:v1.4.0

How to Use

Refer to the documentation for detailed instructions on using the node and CLI tools.

Support

You can visit our issues page for support, feature requests, or to report a bug.

Partner Chains Node v1.3.1

Critical: Runtime Migration Guide for v1.3.1

Features

This patch version extends the Sidechain pallet with a new extrinsic sidechain/upgrade_and_set_addresses
which allows the on-chain governance to atomically upgrade the runtime and set the genesis utxo and new main chain scripts to observe.

1. Update Partner Chains SDK dependencies in your Cargo.toml to v1.3.1

2. Add the following configuration to your runtime configuration:

   impl pallet_sidechain::Config for Runtime {
       // ... other parameters
     type MainChainScripts = sp_session_validator_management::MainChainScripts;
   
     fn set_main_chain_scripts(scripts: Self::MainChainScripts) {
       pallet_session_validator_management::MainChainScriptsConfiguration::<Runtime>::set(scripts);
     }
   }

   This will allow the upgrade_and_set_addresses extrinsic to update configuration of the SessionValidatorManagement
   pallet together with the Runtime code.

3. Increment the spec_version in your runtime configuration.

4. Build the new Runtime WASM (you can do it by running cargo build --release)

5. Upgrade the runtime of the chain using the newly built WASM (it can be found in $CARGO_TARGET_DIR/release/wbuild/<runtime name>/<runtime name>.compressed.wasm) and the
   extrinsic system/setCode.

After these steps the chain should be running the runtime using Partner Chains SDK v1.3.1. This version is fully backwards-compatible and is a preparatory step towards v1.4.0

Bug fixes

Native-token queries cache was failing - giving wrong results - when native token scripts addresses were being updated. This has been fixed.

Compatibility matrix

partner-chains-node	partner-chains-smart-contracts	cardano-node	cardano-db-sync	kupo	ogmios
1.3.1	6.2.2	10.1.2	13.5.0.2	2.9.0	6.8.0

Full Changelog: v1.3.0...v1.3.1