Skip to main content

Stake Pool Operations

Overview​

Stake pools are a core part of Cardano's Proof of Stake system. The Rosetta API supports stake pool registration, retirement, and SPO governance voting operations.

Pool Operation Types​

In addition to standard transaction operations, the following operations are available for stake pool management:

Operation TypeDescription
poolRegistrationRegister a new stake pool
poolRegistrationWithCertRegister a pool using a pre-created certificate
poolRetirementRetire an existing stake pool
poolGovernanceVoteSubmit an SPO governance vote

Input Rules​

  • For all pool operations, the cold key is required for signing and is passed as the operation account.address.
  • poolRegistration requires poolRegistrationParams in metadata.
  • poolRegistrationWithCert requires poolRegistrationCert (hex-encoded certificate) in metadata.
  • poolRetirement requires epoch in metadata.
  • poolGovernanceVote requires poolGovernanceVoteParams; vote_rationale is optional.

Construction Examples​

A pool registration operation requires poolRegistrationParams as metadata. The pool registration deposit amount is taken from the protocol parameters.

{
  "network_identifier": {
    "blockchain": "cardano",
    "network": "mainnet"
  },
  "operations": [
    {
      "operation_identifier": {
        "index": 3
      },
      "type": "poolRegistration",
      "account": {
        "address": "1b268f4cba3faa7e36d8a0cc4adca2096fb856119412ee7330f692b5"
      },
      "metadata": {
        "poolRegistrationParams": {
          "vrfKeyHash": "8dd154228946bd12967c12bedb1cb6038b78f8b84a1760b1a788fa72a4af3db0",
          "rewardAddress": "stake1uxa5pudxg77g3sdaddecmw8tvc6hmynywn49lltt4fmvn7caek7a5",
          "pledge": "5000000",
          "cost": "3000000",
          "poolOwners": [
            "stake1uxly0q2cnpxrjrqm9vpnr9dwkr0j945gulhhgs3dx33l47sweg9er"
          ],
          "relays": [
            {
              "type": "single_host_addr",
              "ipv4": "127.0.0.1",
              "ipv6": "2345:0425:2ca1:0000:0000:0567:5673:23b5",
              "port": "32"
            }
          ],
          "margin": {
            "numerator": "1",
            "denominator": "1"
          },
          "poolMetadata": {
            "url": "poolMetadataUrl",
            "hash": "9ac2217288d1ae0b4e15c41b58d3e05a13206fd9ab81cb15943e4174bf30c90b"
          }
        }
      }
    }
  ],
  "metadata": {
    "ttl": "1000"
  }
}

Required Signatures​

For pool registration, the following signatures are required:

  • Cold key signature - Used to sign the transaction
  • Reward address signature - For the creator's reward address
  • Pool owner signatures - For each pool owner's reward address

These signatures will be specifically requested in the /construction/payloads response and must be provided at the /construction/combine endpoint.

Relay Configuration​

When registering a stake pool, relay information must be provided in a specific format:

IPv4 Format​

Each segment must be a number between 0 and 255:

###.###.###.###
Example: 127.0.0.1

IPv6 Format​

Each segment must be a hexadecimal number between 0000 and FFFF:

####:####:####:####:####:####:####:####
Example: 2345:0425:2ca1:0000:0000:0567:5673:23b5

Data API Representation​

Rosetta Data API responses include pool operations in /block and /block/transaction.

{
  "transaction_identifier": {
    "hash": "dcbff41c50c5b4012d49be5be75b11a0c5289515258ef4cf108eb6ec4ed5f37a"
  },
  "operations": [
    {
      "operation_identifier": { "index": 0 },
      "type": "poolRetirement",
      "status": "success",
      "account": {
        "address": "d6aafa5358b98373449434542e3da3564bc71635ae3247dc1a2b7b0e"
      },
      "metadata": {
        "epoch": 676,
        "refundAmount": {
          "value": "-500000000",
          "currency": { "symbol": "ADA", "decimals": 6 }
        }
      }
    }
  ]
}