Gasless Tx Python Library

Installation

pip install cardano-gasless-tx

Prerequisites

• Python >= 3.8
• Dependencies (automatically installed via pip):
  • requests
  • pycardano
  • blockfrost
  • fastapi
  • uvicorn

Ensure you have a Blockfrost API key, which you can obtain from Blockfrost.

Usage

Importing the Library

Import the main Gasless class from the library:

from cardano_gasless_tx import Gasless

Initialization

The Gasless class is the core of the library. It requires three parameters for initialization:

• wallet: A dictionary specifying wallet credentials and network.
  • key: Wallet credentials, supporting three types:
    • {"type": "mnemonic", "words": List[str]}: A list of mnemonic words (e.g., 15-word phrase).
    • {"type": "root", "bech32": str}: A root key in Bech32 format (e.g., xprv...).
    • {"type": "cli", "payment": str}: A CLI-generated payment key in CBOR hex format.
  • network: An integer indicating the Cardano network (0 for testnet, 1 for mainnet).
• conditions: A dictionary defining transaction sponsorship conditions (optional fields):
  • tokenRequirements: List of token requirements (e.g., [{"unit": "lovelace", "quantity": 1000000, "comparison": "gte"}]) with comparison options: "eq", "neq", "gt", "gte", "lt", "lte".
  • whitelist: List of allowed addresses (e.g., ["addr_test1..."]).
  • corsSettings: List of allowed origins for CORS (e.g., ["<http://example.com>"]).
• api_key: A string containing your Blockfrost API key.

Example

gasless = Gasless(
    wallet={
        "key": {
            "type": "mnemonic",
            "words": ["wood", "bench", "lock", "genuine", "relief", "coral", "guard", "reunion", "follow", "radio", "jewel", "cereal", "actual", "erosion", "recall"]
        },
        "network": 0  # Testnet
    },
    conditions={
        "tokenRequirements": [{"unit": "lovelace", "quantity": 1000000, "comparison": "gte"}],
        "whitelist": ["addr_test1qrs5h59fwz22rzj2fsrlcn7lvqq2wch45h7wmm77n6a5et"],
        "corsSettings": ["<http://example.com>"]
    },
    api_key="your-blockfrost-api-key"
)

This creates a Gasless instance configured for the Cardano testnet, requiring transactions to have at least 1 ADA (1,000,000 lovelace) from a whitelisted address.

Methods

listen(port: int = 8080)

Starts a FastAPI server to handle transaction signing requests and expose pool conditions.

• Parameters:
  • port (optional): The port to run the server on (default: 8080).
• Returns: None. Runs the server until interrupted.
• Behavior:
  • Launches a server at 0.0.0.0:port.
  • Exposes two endpoints:
    • POST /: Signs transactions based on conditions.
    • GET /conditions: Returns the pool’s public key and conditions.

Example

gasless.listen(5050)
# Gasless Server is running on port 5050

sponsor_tx(tx_cbor: str, pool_id: str, utxo: Optional[UTxO] = None) -> str

Sponsors the transaction fee from the pool.

• Parameters:
  • tx_cbor: The CBOR-encoded transaction as a hex string.
  • pool_id: The sponsor pool’s address (e.g., addr_test1...).
  • utxo (optional): A specific UTxO object to use for sponsoring; if None, selects one automatically.
• Returns: The CBOR-encoded sponsored transaction as a hex string.

Example

sponsored_tx = gasless.sponsor_tx(
    tx_cbor="84a4008182582059d435678d1e2484ef42d0022f10e16a5ffc481b0e572fc19f8bfe1f8a862ebb0101828258390033ecacabf249c7419632e0cef2edecf79b01128cc5cbdd9df623d00c897322abe2f5dbf69b42ede7fd14c16131cbff5de2f457151c2fd22b1a000f42408258390033ecacabf249c7419632e0cef2edecf79b01128cc5cbdd9df623d00c897322abe2f5dbf69b42ede7fd14c16131cbff5de2f457151c2fd22b1a0114c8e2020007582022eef6a148c3556e81eb018f5dfc641e108750681e70fafca8fe7ad2f510156ca0f5",
    pool_id=gasless.in_app_wallet.get_address().encode()
)
print(sponsored_tx)

validate_tx(tx_cbor: str, pool_sign_server: str) -> str

Validates a sponsored transaction and requests the pool to sign it.

• Parameters:
  • tx_cbor: The CBOR-encoded sponsored transaction as a hex string.
  • pool_sign_server: The URL of the pool’s signing server (e.g., "<http://localhost:5050>").
• Returns: The CBOR-encoded signed transaction as a hex string.

Example

signed_tx = gasless.validate_tx(
    tx_cbor=sponsored_tx,
    pool_sign_server="<http://localhost:5050>"
)
print(signed_tx)

Server Endpoints

When running via listen, the library exposes a FastAPI server with two endpoints:

POST /

• Purpose: Processes transaction signing requests.
• Request Body: JSON with txCbor (e.g., {"txCbor": "hex-string"}).
• Response: JSON with:
  • data: Signed transaction CBOR hex (if successful).
  • error: Error message (if failed).
  • success: Boolean indicating success.

Example Request

curl -X POST "<http://localhost:5050/>" -H "Content-Type: application/json" -d '{"txCbor": "84a400..."}'

GET /conditions

• Purpose: Retrieves the pool’s public key and conditions.
• Response: JSON with:
  • pubKey: The pool’s payment verification key hash.
  • conditions: The pool’s conditions dictionary.

Example Response

{
  "pubKey": "ab78e8acf6a9ba6ce0d38e7d2d1cb4f9fb0597f5feacaf6dcbd96ed4",
  "conditions": {
    "tokenRequirements": [{"unit": "lovelace", "quantity": 1000000, "comparison": "gte"}]
  }
}

Examples

Complete Workflow

This example demonstrates initializing the library, sponsoring a transaction, and validating it:

from gasless_lib import Gasless
import threading

# Initialize Gasless
gasless = Gasless(
    wallet={
        "key": {
            "type": "mnemonic",
            "words": ["wood", "bench", "lock", "genuine", "relief", "coral", "guard", "reunion", "follow", "radio", "jewel", "cereal", "actual", "erosion", "recall"]
        },
        "network": 0
    },
    conditions={
        "tokenRequirements": [{"unit": "lovelace", "quantity": 1000000, "comparison": "gte"}]
    },
    api_key="your-blockfrost-api-key"
)

# Start the server in a background thread
server_thread = threading.Thread(target=gasless.listen, args=(5050,))
server_thread.daemon = True
server_thread.start()

# Sample unsigned transaction CBOR (simplified for example)
unsigned_tx_cbor = "84a4008182582059d435678d1e2484ef42d0022f10e16a5ffc481b0e572fc19f8bfe1f8a862ebb0101828258390033ecacabf249c7419632e0cef2edecf79b01128cc5cbdd9df623d00c897322abe2f5dbf69b42ede7fd14c16131cbff5de2f457151c2fd22b1a000f42408258390033ecacabf249c7419632e0cef2edecf79b01128cc5cbdd9df623d00c897322abe2f5dbf69b42ede7fd14c16131cbff5de2f457151c2fd22b1a0114c8e2020007582022eef6a148c3556e81eb018f5dfc641e108750681e70fafca8fe7ad2f510156ca0f5"

# Sponsor the transaction
sponsored_tx = gasless.sponsor_tx(
    tx_cbor=unsigned_tx_cbor,
    pool_id=gasless.in_app_wallet.get_address().encode()
)

# Validate and sign the transaction
signed_tx = gasless.validate_tx(
    tx_cbor=sponsored_tx,
    pool_sign_server="<http://localhost:5050>"
)

print("Signed Transaction CBOR:", signed_tx)

Running as a Pool Server

To run gaslesspy as a standalone pool server:

from gasless_lib import Gasless

gasless = Gasless(
    wallet={"key": {"type": "cli", "payment": "5820aaca553a7b95b38b5d9b82a5daa7a27ac8e34f3cf27152a978f4576520dd"}, "network": 0},
    conditions={"whitelist": ["addr_test1qrs5h59fwz22rzj2fsrlcn7lvqq2wch45h7wmm77n6a5et"]},
    api_key="your-blockfrost-api-key"
)

gasless.listen(port=5050)

This starts a server that signs transactions from whitelisted addresses.

Advanced Usage

Internal Validation Methods

These methods are used internally but can be useful for debugging or customization:

• validate_token_requirements(base_tx: Transaction, sponsored_pool_hash: VerificationKeyHash):
  • Validates if transaction inputs meet token requirements.
  • Raises ValueError if conditions are not met.
• validate_whitelist(base_tx: Transaction):
  • Checks if transaction input addresses are in the whitelist.
  • Raises ValueError if no match is found.

Notes

• Error Handling: Methods like sponsor_tx and validate_tx raise exceptions on invalid inputs or failed operations. Wrap calls in try-except blocks for robust applications.
• Network: Use network=0 for testnet during development to avoid spending real ADA.
• CORS: Configure corsSettings if the server will be accessed from web applications.