Add wallet classes

examples/automatic_royalty_token.py

@@ -0,0 +1,210 @@
+import datetime as dt
+import logging
+import time
+from pprint import pformat
+
+from pycardano import wallet
+
+# This script mints and burns an NFT royalty token based off of CIP-0027 (https://github.com/cardano-foundation/CIPs/tree/master/CIP-0027)
+
+# 1. Make sure to create a wallet for the policy, with name POLICY_WALLET_NAME
+# 2. Create your policy with the name POLICY_NAME and the above wallet as a signer
+# 3. Fill out the details below and run the script, make sure your BlockFrost ENV variables are set.
+
+POLICY_NAME = "myPolicy"
+POLICY_WALLET_NAME = "myPolicyWallet"
+
+ROYALTY_ADDRESS = "addr_test1qpxh0m34vqkzsaucxx6venpnetgay6ylacuwvrdfdv5wnmw34uylg63pcm2dmsjzx8rrndy0lhwhht2h9f0kt8kv2qrswzxgy0"
+ROYALTY_PERCENT = "0.05"
+
+WALLET_NAME = "royaltytest"  # This is a temporary wallet generated by the script to mint the token.
+CODED_AMOUNT = wallet.Ada(3.555432)  # pick a random amount between 3 and 4 ADA
+NETWORK = "preprod"
+
+# Set up logging!
+root = logging.getLogger()
+root.setLevel(logging.DEBUG)
+
+logging_timestamp = dt.datetime.now(tz=dt.timezone.utc).strftime("%Y-%m-%d-%H-%M-%S")
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s %(name)-12s %(levelname)-8s %(message)s",
+    datefmt="%m-%d %H:%M",
+    filename=f"./{WALLET_NAME}.log",
+    filemode="a",
+)
+
+fh = logging.FileHandler(filename=f"./{WALLET_NAME}.log")
+fh.name = "File Logger"
+fh.setLevel(logging.DEBUG)
+root.addHandler(fh)
+
+# define a Handler which writes INFO messages or higher to the sys.stderr
+console = logging.StreamHandler()
+console.name = "Console Logger"
+console.setLevel(logging.INFO)
+# set a format which is simpler for console use
+formatter = logging.Formatter("%(name)-12s: %(levelname)-8s %(message)s")
+# tell the handler to use this format
+console.setFormatter(formatter)
+# add the handler to the root logger
+root.addHandler(console)
+
+
+def chunkstring(string, length):
+    return (string[0 + i : length + i] for i in range(0, len(string), length))
+
+
+def create_royalty_metadata(royalty_address: str, royalty_percent: str):
+    """Write royalty metadata to a file"""
+
+    metadata = {"777": {}}
+    metadata["777"] = {}
+
+    # add rate
+    metadata["777"]["rate"] = royalty_percent
+
+    # add address, and split it longer than 64 characters
+    if len(royalty_address) > 64:
+        metadata["777"]["addr"] = list(chunkstring(royalty_address, 64))
+    else:
+        metadata["777"]["addr"] = royalty_address
+
+    return metadata
+
+
+def launch():
+    logger = logging.getLogger(__name__)
+
+    logger.info("Welcome to the royalty NFT generation script!")
+    logger.info(f"Network: {NETWORK}")
+
+    ORIGINAL_SENDER = None
+    DONE = False
+
+    # generate royalty metadata
+    royalty_metadata = create_royalty_metadata(ROYALTY_ADDRESS, ROYALTY_PERCENT)
+
+    # create receiving wallet
+    tmp_wallet = wallet.Wallet(name="tmp_royalty_wallet", network=NETWORK)
+    policy_wallet = wallet.Wallet(name=POLICY_WALLET_NAME, network=NETWORK)
+    policy = wallet.TokenPolicy(name=POLICY_NAME)
+
+    logger.info(
+        f"Generating a 777 royalty NFT with {ROYALTY_PERCENT}/1 ({float(ROYALTY_PERCENT)*100}%) to address {ROYALTY_ADDRESS}"
+    )
+    logger.info("Metadata:")
+    logger.info(pformat(royalty_metadata))
+    time.sleep(2)
+
+    logger.info(
+        f"If this looks right, please send exactly {CODED_AMOUNT.ada} ADA to\n {tmp_wallet.address}"
+    )
+    time.sleep(2)
+
+    while not DONE:
+        loop_start_time = dt.datetime.now(dt.timezone.utc)
+        logger.info(f"Starting loop {loop_start_time}")
+
+        tmp_wallet.sync()
+        tmp_wallet.get_utxo_creators()
+
+        for utxo in tmp_wallet.utxos:
+            # check whether or not to mint
+            can_mint = False
+            if wallet.Lovelace(utxo.output.amount.coin) == CODED_AMOUNT:
+                logger.info(
+                    f"Coded amount of {CODED_AMOUNT.ada} ADA recieved: can mint 777 token!"
+                )
+                can_mint = True
+            else:
+                logger.info(
+                    f"Please send exactly {CODED_AMOUNT.ada} ADA to\n {tmp_wallet.address}"
+                )
+
+            if can_mint:
+                ORIGINAL_SENDER = utxo.creator
+                logger.info(
+                    f"Original sender of {CODED_AMOUNT.ada} ADA is {ORIGINAL_SENDER}"
+                )
+
+                token = wallet.Token(
+                    policy=policy, amount=1, name="", metadata=royalty_metadata
+                )
+
+                logger.info("Minting token, please wait for confirmation...")
+
+                mint_tx = tmp_wallet.mint_tokens(
+                    to=tmp_wallet,
+                    mints=token,
+                    utxos=utxo,
+                    signers=[tmp_wallet, policy_wallet],
+                    await_confirmation=True,
+                )
+
+                logger.info(f"Mint successful: Tx ID {mint_tx}")
+                logger.info(
+                    "DO NOT STOP SCRIPT YET! Please wait so we can burn the token."
+                )
+
+                continue
+
+            # check if we can burn the token
+            can_burn = False
+            utxo_tokens = utxo.output.amount.multi_asset
+
+            if utxo_tokens:
+                if (
+                    len(utxo_tokens) == 1
+                    and str(list(utxo_tokens.keys())[0]) == policy.id
+                ):
+                    logger.info(f"No name token found: can burn 777 token!")
+                    logger.info(
+                        f"Will send change to original sender: {ORIGINAL_SENDER}"
+                    )
+                    can_burn = True
+
+            if can_burn:
+                # get original sender
+                utxo_info = tmp_wallet.context.api.transaction_utxos(
+                    str(utxo.input.transaction_id)
+                )
+                input_utxo = utxo_info.inputs[0].tx_hash
+                ORIGINAL_SENDER = (
+                    tmp_wallet.context.api.transaction_utxos(str(input_utxo))
+                    .inputs[0]
+                    .address
+                )
+
+                token = wallet.Token(
+                    policy=policy,
+                    amount=-1,
+                    name="",
+                )
+
+                logger.info(
+                    "Burning the royalty token. Please wait for confirmation..."
+                )
+                burn_tx = tmp_wallet.mint_tokens(
+                    to=ORIGINAL_SENDER,
+                    mints=token,
+                    signers=[tmp_wallet, policy_wallet],
+                    utxos=utxo,
+                    change_address=ORIGINAL_SENDER,
+                    await_confirmation=True,
+                )
+
+                logger.info(f"Burn successful! Tx ID: {burn_tx}")
+
+                DONE = True
+
+                continue
+
+        time.sleep(5)
+
+    logger.info("Your royalties are ready!")
+    logger.info(f"https://cardanoscan.io/tokenPolicy/{policy.id}")
+
+
+if __name__ == "__main__":
+    launch()

examples/wallet.py

@@ -0,0 +1,158 @@
+"""
+This is a walk through of the Wallet class in pycardano.
+This class offers a number of methods which simplify many basic use cases, 
+and abstracts away some of the lower level details.
+If you need more advanced functionality, you can directly use the lower level classes and methods, 
+sometimes in tandem with the Wallet class.
+
+Note: If you plan to use Blockfrost as your chain context, you can set the following environment variables:
+    `BLOCKFROST_ID_MAINNET` for mainnet
+    `BLOCKFROST_ID_PREPROD` for preprod
+    `BLOCKFROST_ID_PREVIEW` for preview
+
+
+"""
+
+from datetime import datetime
+from multiprocessing import pool
+
+from pycardano import *
+from pycardano.wallet import Ada, Output, Token, TokenPolicy, Wallet
+
+"""Create a new wallet"""
+# Make sure to provide a name so you can easily load it later
+# this will save the keys to ./keys/my_wallet.*
+# payment and staking keys will be automatically generated, or loaded a wallet of the given name already exists
+w = Wallet(
+    name="my_wallet"
+)  # set the parameter `network` to mainnet, preprod, or preview
+
+
+w.sync()  # query the wallet for its balance
+
+w.utxos  # list of wallets UTXOs
+w.ada  # view total amount of ADA
+w.lovelace  # view total amount of lovelace
+w.tokens  # get a list of all tokens in the wallet
+
+
+"""Send ADA using the wallet"""
+
+receiver = Address("addr_test1vrm9x2zsux7va6w892g38tvchnzahvcd9tykqf3ygnmwtaqyfg52x")
+
+tx_id = w.send_ada(receiver, Ada(2))  # send 2 ADA to the receiver
+
+
+"""Sending an entire UTxO"""
+# useful if you have to send a refund, for example
+tx_id = w.send_utxo(
+    receiver, w.utxos[0]
+)  # send the first UTXO in the wallet to the receiver
+
+
+"""Empty an entire wallet"""
+# Careful with this one!
+tx_id = w.empty_wallet(receiver)
+
+
+"""Sign data"""
+# can sign a message with either the payment or stake keys
+signed_message = w.sign_data(
+    "Hello world!", mode="payment"
+)  # default mode is "payment"
+
+
+"""Mint a token"""
+
+# first generate a policy
+my_policy = TokenPolicy(name="my_policy")  # give it a descriptive name
+
+# generate a locking policy with expiration
+# note: the actual policy locking time might be slightly off from the datetime provided
+# this will save a file to ./policy/my_policy.policy
+my_policy.generate_minting_policy(signers=w, expiration=datetime(2025, 5, 12, 12, 0, 0))
+
+# create a token with metadata
+metadata = {
+    "description": "This is my first NFT thanks to PyCardano",
+    "name": "PyCardano NFT example token 1",
+    "id": 1,
+    "image": "ipfs://QmRhTTbUrPYEw3mJGGhQqQST9k86v1DPBiTTWJGKDJsVFw",
+}
+
+my_nft = Token(policy=my_policy, amount=2, name="MY_NFT_1", metadata=metadata)
+
+tx_id = w.mint_tokens(
+    to=receiver,
+    mints=my_nft,  # can be a single Token or list of multiple
+)
+
+
+"""Burn a token"""
+# Oops, we minted two. Let's burn one.
+# There are two ways to do this:
+
+# Method 2
+# create a token object with the quantity you want to burn
+# note you don't have to include metadata here since it's only relevant for minting, not burning
+my_nft = Token(policy=my_policy, amount=1, name="MY_NFT_1")
+
+# this will automatically switch the amount to negative and burn them
+tx_id = w.burn_tokens(my_nft)
+
+# Method 2
+# this method might be relevant in case you want to mint and burn multiple tokens in one transaction
+# set amount to negative integer to burn
+my_nft = Token(policy=my_policy, amount=-1, name="MY_NFT_1")
+
+# then use the mint_tokens method
+tx_id = w.mint_tokens(
+    to=receiver,
+    mints=my_nft,  # can be a single Token or list of multiple
+)
+
+
+"""Register a stake address and delegate to a pool"""
+
+pool_hash = "pool17arkxvwwh8rx0ldrzc54ysmpq4pd6gwzl66qe84a0nmh7qx7ze5"
+
+tx_id = w.delegate(pool_hash)
+
+
+"""Withdraw staking rewards"""
+# withdraws all rewards by default, otherwise set `withdraw_amount` to a specific quantity
+tx_id = w.withdraw()
+
+"""Fully Manual Transaction"""
+# Let's make a monster transaction with all the bells and whistles
+# Note: All the above examples are based on the following `transact` method
+#       so you can also pass any of the following parameters to the above methods as well as **kwargs
+#       e.g. `change_address`, `signers`, `message`, `await_confirmation`, etc.
+
+my_nft = Token(policy=my_policy, amount=1, name="MY_NFT_1", metadata=metadata)
+your_nft = Token(
+    policy=my_policy, amount=1, name="YOUR_NFT_1", metadata={"Name": "Your NFT"}
+)
+
+
+tx_id = w.transact(
+    inputs=w,  # use all UTXOs in the wallet, can also specify unique UTxOs or addresses
+    outputs=[
+        Output(
+            w, Ada(0), [my_nft]
+        ),  # mint an NFT to myself, setting Ada(0) will automatically calculate the minimum amount of ADA needed
+        Output(receiver, Ada(10), [my_nft]),  # send 10 ADA and an NFT to the receiver
+    ],
+    mints=[
+        my_nft,
+        your_nft,
+    ],  # must list all mints/burns here, even if they are sent to yourself
+    # signers = [w, other_w],                 # if you want to sign with multiple wallets or keys, specify them here
+    delegations=pool_hash,  # delegate to a pool
+    withdrawals=Ada(2),  # withdraw 2 ADA
+    # change_address=w,                       # specify a change address, will default to itself if not specified
+    message="I love PyCardano",  # attach a message to the transaction metadata [CIP-0020]
+    other_metadata={"247": {"random": "metadata"}},  # attach any other metadata
+    # submit=True                             # set to False to return the transaction body as CBOR
+    await_confirmation=True,  # set to True to block the code and periodically check until the transaction is confirmed
+)