"""
Documentation for the autogenerated bindings.py module.

This module contains documentation for the classes and functions defined in the
autogenerated bindings.py file. These docstrings can be used by documentation
generators to provide proper documentation for the bindings.py module without
modifying the autogenerated file itself.
"""

# Base class and collection documentation
BINDINGS_MODULE_DOC = """
Python bindings for the Saline blockchain transaction types and operations.

This module is auto-generated from the Saline codebase and provides
the necessary classes and functions to interact with the Saline blockchain at a low level.

The module includes:
- Data structures for transactions, instructions, and intents
- Serialization and deserialization functions
- Enumeration types for tokens, relations, etc.
"""

NON_EMPTY_DOC = """
A non-empty list type that guarantees at least one element.

This type is used in many Saline data structures where an empty collection is invalid,
such as transaction instructions or signers lists.

Attributes:
    list: The internal standard python list
"""

NON_EMPTY_INIT_DOC = """
Initialize a new NonEmpty collection.

Args:
    head: The first element of the collection
    tail: A list of additional elements
"""

NON_EMPTY_FROM_LIST_DOC = """
Create a NonEmpty collection from a regular list.

Args:
    elements: A list with at least one element

Returns:
    A new NonEmpty collection

Raises:
    ValueError: If the input list is empty
"""

# Enum documentation
RELATION_DOC = """
Enumeration of comparison relations used in conditional expressions.

Members:
    EQ: Equal to (==)
    LT: Less than (<)
    LE: Less than or equal to (<=)
    GT: Greater than (>)
    GE: Greater than or equal to (>=)
"""

TOKEN_DOC = """
Enumeration of supported token types in the Saline blockchain.

Members:
    BTC: Bitcoin
    ETH: Ethereum
    USDC: USD Coin
    USDT: Tether
    SALT: Saline native token
"""

ARITHMETIC_DOC = """
Enumeration of arithmetic operations used in expressions.

Members:
    Add: Addition (+)
    Div: Division (/)
    Mul: Multiplication (*)
    Sub: Subtraction (-)
"""

# Witness documentation
WITNESS_DOC = """
Base class for transaction witnesses.

Witnesses are used to provide evidence for non-trivial validations.
For instance, given a multi-level multi-sig, witnesses specify the paths of
the tree that are valid, which means the verification engine can avoid
evaluating all the false paths.
This allows doing less computation on-chain, where it's more expensive.
"""

ALLW_DOC = """
A witness for an All intent

Attributes:
    children: List of child witnesses
"""

ANYW_DOC = """
A witness for an Any intent. Should have exactly as many children as the
required threshold

Attributes:
    children: Dictionary of child witnesses keyed by the index of the matching intent
"""

AUTOW_DOC = """
A witness to prove validation of trivial or unambiguous intents
"""

# Expression documentation
EXPR_DOC = """
Base class for expressions in the Saline blockchain.

Expressions represent values, variables, calculations, as well as references
to data from transactions, wallets or oracles, that can be evaluated
at the time of verification.
"""

LIT_DOC = """
A literal value expression.

Attributes:
    value: The literal value (number, string, etc.)
"""

RECEIVE_DOC = """
An expression representing the amount of tokens received

Attributes:
    token: The selected token
"""

SEND_DOC = """
An expression representing the amount of tokens sent

Attributes:
    token: The selected token
"""

VAR_DOC = """
A variable reference expression.
"""

ARITHMETIC2_DOC = """
An arithmetic operation between two expressions.

Attributes:
    lhs: Left-hand side expression
    operation: The arithmetic operation type
    rhs: Right-hand side expression
"""

# Intent documentation
INTENT_DOC = """
Base class for intents in the Saline blockchain.

Intents represent conditions or requirements that must be satisfied
for a transaction to be valid.
"""

ALL_DOC = """
An intent that requires all child intents to be satisfied.

This is similar to an AND logical operation for intents.

Attributes:
    children: List of child intents that must all be satisfied
"""

ANY_DOC = """
An intent that requires a threshold number of child intents to be satisfied.

Attributes:
    threshold: Minimum number of child intents that must be satisfied
    children: List of child intents
"""

RESTRICTION_DOC = """
An intent that enforces a specific relationship between expressions.

Attributes:
    lhs: Left-hand side expression
    relation: The relation type (e.g., EQ, LT, GT)
    rhs: Right-hand side expression
"""

FINITE_DOC = """
An intent wrapper that restricts it to a certain number of uses
"""

TEMPORARY_DOC = """
An intent wrapper that restricts it to a timeframe
"""

SIGNATURE_DOC = """
An intent that requires a specific signature.

Attributes:
    signer: The public key of the required signer
"""

# Bridge instruction documentation
BRIDGE_INSTRUCTION_DOC = """
Base class for bridge instructions in the Saline blockchain.

Bridge instructions allow interaction with other blockchains.
"""

BURN_DOC = """
A bridge instruction to burn tokens.

Attributes:
    token: The token type to burn
    amount: The amount to burn
"""

MINT_DOC = """
A bridge instruction to mint tokens.

Attributes:
    prover: The account that proves the minting operation
    token: The token type to mint
    amount: The amount to mint
"""

# Instruction documentation
INSTRUCTION_DOC = """
Base class for instructions in the Saline blockchain.

Instructions are the fundamental operations that can be performed
in transactions.
"""

TRANSFER_FUNDS_DOC = """
An instruction to transfer funds between accounts.

Args:
    source (str): The sender account's public key
    target (str): The recipient account's public key
    funds (Dict[str, float]): Dictionary mapping token types to amounts

Attributes:
    source: The sender account
    target: The recipient account
    funds: Dictionary mapping token types to amounts
"""

OR_INTENT_DOC = """
An instruction to add to, rather than replace an account's intent.
For instance, to post multiple limit orders.

Attributes:
    host: The account to add the intent to
    intent: The intent to add
"""

SET_INTENT_DOC = """
An instruction to set the intent for an account.

Attributes:
    host: The account to set the intent for
    intent: The intent to set
"""

DELETE_DOC = """
An instruction to reset an account to the default intent.

Attributes:
    host: The account whose intent will be deleted
"""

BRIDGE_DOC = """
An instruction to perform a bridge operation.

Attributes:
    bridgedAccount: The account involved in the bridge operation
    instruction: The bridge instruction to execute
"""

# Transaction documentation
TRANSACTION_DOC = """
Represents a transaction on the Saline blockchain.

A transaction consists of one or more instructions to be executed atomically.

Args:
    instructions (List[Instruction]): List of instructions to execute

Attributes:
    instructions: Non-empty list of instructions to execute
"""

SIGNED_DOC = """
Represents a signed transaction ready for submission.

Args:
    nonce (str): Unique identifier for this transaction
    signature (str): The cryptographic signature
    signee (Transaction): The transaction being signed
    signers (List[str]): List of public keys that signed the transaction

Attributes:
    nonce: Unique identifier for this transaction
    signature: The cryptographic signature
    signee: The transaction being signed
    signers: Non-empty list of public keys that signed the transaction
"""
