PyCardano

A TransactionBuilder is a class that provides a user-friendly interface for constructing and signing Cardano transactions. It automatically manages transaction inputs, outputs, fees, and other technical details based on the provided ChainContext.

Important: The TransactionBuilder is stateful. Once you call the build method, the instance cannot be reused. You must instantiate a new TransactionBuilder for every unique transaction you wish to create.

# Create a transaction builder with a chain context
builder = TransactionBuilder(context)

# Add inputs from an address
builder.add_input_address(address)

# Add an output - sending 100 ADA to a recipient
recipient = Address.from_primitive("addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x")
builder.add_output(TransactionOutput(recipient, Value.from_primitive([100_000_000])))

# Build, sign, and submit
signed_tx = builder.build_and_sign([payment_signing_key], change_address=address)
context.submit_tx(signed_tx)

To work with smart contracts on Cardano, you must understand these key abstractions:

• Plutus script: The validator logic compiled into Plutus Core binary. It evaluates transaction inputs to approve (True) or deny (False) spending a UTxO.
• Script address: The hash of the Plutus script binary. UTxOs held at this address can only be consumed if the script returns True when evaluating the provided datum, redeemer, and script context.
• Datum: Information associated with a UTxO used to "lock" funds. To unlock the funds, a user must provide a datum whose hash matches the one attached to the UTxO.
• Redeemer: An input provided to the script to "unlock" funds. It shares the same data format as a datum but includes specific instructions (actions) and computational resources (execution units) required by the script.
• Script context: Provides metadata about the pending transaction and the specific input triggering the validation.

To register a DRep on-chain, you must create a RegDRepCert certificate. This requires a new stake key pair to represent the DRep's identity. The registration includes a deposit (in Lovelace) and an optional Anchor for off-chain metadata.

Key Requirements:

• DRep Address: Must be constructed using both the payment verification key hash and the DRep's stake verification key hash. This address must be funded before submitting the registration.
• Signing: The transaction must be signed by both the payment key (controlling the UTxOs) and the DRep's stake key.
• Certificate: Use RegDRepCert with a DRepCredential (the stake verification key hash).

# 1.1 Generate or load DRep stake key pair
drep_stake_key_pair = StakeKeyPair.generate()

# 1.2 Create DRep address
drep_address = Address(
    payment_part=main_payment_vkey.hash(),
    staking_part=drep_stake_key_pair.verification_key.hash(),
    network=network,
)

# 1.4 Create DRep registration certificate
drep_credential = DRepCredential(drep_stake_key_pair.verification_key.hash())
anchor = Anchor(
    url="https://pycardano.drep.example.com/info",
    data_hash=AnchorDataHash(bytes.fromhex("00" * 32)),
)
drep_registration_cert = RegDRepCert(
    drep_credential=drep_credential,
    coin=500_000_000, # 500 ADA deposit
    anchor=anchor,
)

# 1.5 Build and submit transaction
builder = TransactionBuilder(context)
builder.add_input_address(str(drep_address))
builder.certificates = [drep_registration_cert]

signed_tx = builder.build_and_sign(
    signing_keys=[main_payment_skey, drep_stake_key_pair.signing_key],
    change_address=drep_address,
)
context.submit_tx(signed_tx)

Ada holders can delegate voting power to a DRep using the StakeRegistrationAndVoteDelegation certificate. This single certificate handles both the registration of a new stake key (and its deposit) and the delegation of votes to a specific DRep.

Workflow:

1. Generate a new StakeKeyPair for the voting identity.
2. Create a DRep object using the target DRep's verification key hash and DRepKind.VERIFICATION_KEY_HASH.
3. Construct a StakeRegistrationAndVoteDelegation certificate with a StakeCredential and the DRep object.
4. Build a transaction using an address that includes the new stake part. The transaction must be signed by both the payment key and the new voting stake key.

# 2.1 Generate a new stake key for the main account's voting delegation
main_voting_stake_key_pair = StakeKeyPair.generate()

# 2.4 Create StakeRegistrationAndVoteDelegation certificate
stake_credential = StakeCredential(main_voting_stake_key_pair.verification_key.hash())

# Create a DRep object pointing to the DRep we created
drep_for_delegation = DRep(
    kind=DRepKind.VERIFICATION_KEY_HASH,
    credential=drep_stake_key_pair.verification_key.hash()
)

delegation_cert = StakeRegistrationAndVoteDelegation(
    stake_credential=stake_credential,
    drep=drep_for_delegation,
    coin=2_000_000, # 2 ADA stake key registration deposit
)

builder = TransactionBuilder(context)
main_full_address = Address(
    payment_part=main_payment_vkey.hash(),
    staking_part=main_voting_stake_key_pair.verification_key.hash(),
    network=network,
)
builder.add_input_address(str(main_full_address))
builder.certificates = [delegation_cert]

signed_tx = builder.build_and_sign(
    signing_keys=[main_payment_skey, main_voting_stake_key_pair.signing_key],
    change_address=main_full_address,
)
context.submit_tx(signed_tx)