Tallybox Wallet - Transaction Group Tutorial

Pseudo-Code: Load Wallet

FUNCTION load_wallet(file, password, protocol="https", graph="tallybox.mixoftix.net"):
    TRY:
        xml_content = READ_FILE(file)
        xml_doc = PARSE_XML(xml_content)
        wallet_name = xml_doc.GET_TAG("wallet_name")
        public_key_b58 = xml_doc.GET_TAG("public_key_b58_compressed")
        private_key_aes_b64 = xml_doc.GET_TAG("private_key_aes_b64")
        wallet_address = xml_doc.GET_TAG("wallet_address")

        IF NOT (wallet_name AND public_key_b58 AND private_key_aes_b64 AND wallet_address):
            THROW "Invalid XML format"

        key_components = wallet_name + "~" + password + "~" + wallet_address
        secret = SHA256(key_components.encode('utf-8')).hex()
        private_key_hex = aes256_cbc_decrypt_custom(private_key_aes_b64, secret)

        private_key_int = PARSE_HEX_TO_INT(private_key_hex)
        SECP256R1_ORDER = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551
        IF NOT (1 <= private_key_int < SECP256R1_ORDER):
            THROW "Private key out of range for secp256r1"

        ec = NEW_ELLIPTIC_CURVE("secp256r1")
        key_pair = ec.KEY_FROM_PRIVATE(private_key_int)
        public_key = key_pair.GET_PUBLIC()
        public_key_bytes = public_key.ENCODE("x962", "uncompressed")
        x_bytes = public_key_bytes[1:33]
        y_bytes = public_key_bytes[33:]
        y_parity = PARSE_INT(y_bytes) MOD 2
        suffix = "1" IF y_parity == 1 ELSE "2"
        compressed_key = x_bytes.hex() + "*" + suffix

        result = CREATE_RECORD()
        result.SET_FIELD("key_pair", key_pair)
        result.SET_FIELD("compressed_key", compressed_key)
        result.SET_FIELD("public_key_b58", public_key_b58)
        result.SET_FIELD("wallet_address", wallet_address)
        result.SET_FIELD("wallet_name", wallet_name)
        result.SET_FIELD("protocol", protocol)
        result.SET_FIELD("graph", graph)
        RETURN result
    CATCH error:
        THROW "Decryption failed or invalid file: " + error
END FUNCTION
                

Notice: XML File Structure
The XML file must include <wallet_name>, <public_key_b58_compressed>, <private_key_aes_b64>, and <wallet_address>. The password must match the one used to encrypt the private key, or decryption will fail.

Pseudo-Code: Read and Validate Transaction File

FUNCTION read_transaction_file(file_path):
    TRY:
        content = READ_FILE(file_path).TRIM()
        parts = content.SPLIT("~")
        IF length(parts) < 2 OR parts[0] != "tallybox" OR parts[1] != "parcel_of_transactions":
            THROW "Invalid file format: must start with tallybox~parcel_of_transactions"
        IF (length(parts) - 2) MOD 4 != 0:
            THROW "Invalid number of fields: expected 2 + 4N"
        
        transactions = CREATE_LIST()
        total_wallet_to = ""
        total_amount = 0.0
        wallet_to_set = CREATE_SET()  // For duplicate checking
        
        FOR i = 2 TO length(parts) - 1 STEP 4:
            wallet_to_label = parts[i]
            wallet_to = parts[i + 1]
            order_amount_label = parts[i + 2]
            order_amount = parts[i + 3]
            
            transaction_num = (i - 2) / 4 + 1
            IF wallet_to_label != "wallet_to_" + transaction_num OR
               order_amount_label != "order_amount_" + transaction_num:
                THROW "Invalid field labels for transaction " + transaction_num
            
            IF wallet_to IN wallet_to_set:
                THROW "error~304~duplicate wallet address found~" + wallet_to
            END IF
            wallet_to_set.ADD(wallet_to)
            
            IF NOT VALIDATE_WALLET_ADDRESS(wallet_to):
                THROW "error~301~invalid wallet format~" + wallet_to
            IF NOT IS_NUMBER(order_amount) OR PARSE_NUMBER(order_amount) <= 0:
                THROW "error~303~invalid numeric data~order_amount_" + order_amount
            
            transaction = CREATE_RECORD()
            transaction.SET_FIELD("wallet_to", wallet_to)
            transaction.SET_FIELD("order_amount", order_amount)
            transactions.APPEND(transaction)
            
            total_wallet_to = total_wallet_to + wallet_to + "~" + order_amount + "~"
            total_amount = total_amount + PARSE_NUMBER(order_amount)
        
        IF length(transactions) == 0:
            THROW "No valid transactions found"
        
        RETURN transactions, total_wallet_to, total_amount
    CATCH error:
        THROW "Failed to read transaction file: " + error
END FUNCTION
                

Pseudo-Code: Validate Wallet Address

FUNCTION VALIDATE_WALLET_ADDRESS(address):
    // Check for null/empty or insufficient length
    IF address IS NULL OR address.LENGTH < 40:
        RETURN FALSE
    END IF
    
    // Check prefix
    IF NOT address.STARTS_WITH("box"):
        RETURN FALSE
    END IF
    
    // Check curve character (4th character)
    curve_char = address[3]
    IF curve_char NOT IN ["A", "B", "C"]:
        RETURN FALSE
    END IF
    
    // Checksum validation
    checksum_md5 = address.SUBSTRING(4, 15) // Characters 4 to 14 (11 characters)
    base58_part = address.SUBSTRING(15)     // From character 15 to end
    computed_md5 = MD5(base58_part.encode()).SUBSTRING(0, 11)
    
    IF checksum_md5 == computed_md5:
        RETURN TRUE
    END IF
    
    RETURN FALSE
END FUNCTION
                

Warning: File Validation
Ensure the transaction file adheres to the specified format. Incorrect labels, invalid wallet addresses, non-positive amounts, or duplicate wallet addresses will cause validation errors.

Pseudo-Code: Prepare Transaction Group

FUNCTION prepare_group_transaction(wallet_state, transactions, total_wallet_to, total_amount):
    token = PROMPT_USER("Select token: [2PN, 2ZR, TLH]")
    graph = wallet_state.graph
    utc_unix = CURRENT_TIMESTAMP_SECONDS()

    IF NOT (token IN ["2PN", "2ZR", "TLH"]):
        THROW "Invalid token"

    wallet_to_hash = SHA256(total_wallet_to.encode('utf-8')).hex()
    order_id = "#" + utc_unix

    transaction_data = graph + "~" + graph + "~" + 
                      wallet_state.wallet_address + "~" + wallet_to_hash + "~" + 
                      token + "~" + FORMAT_DECIMAL(total_amount, 8) + "~" + order_id + "~" + utc_unix
    msg_hash = SHA256(transaction_data.encode('utf-8')).bytes()
    
    signature = wallet_state.key_pair.SIGN_ECDSA(msg_hash, curve="secp256r1", deterministic=RFC6979)
    sig_der = signature.TO_DER()
    sig_base64 = BASE64_ENCODE(sig_der)
    
    broadcast_data = CONCATENATE_WITH_SEPARATOR(
        "tallybox",
        "parcel_of_transaction",
        "number_of_transactions", length(transactions),
        "graph_from", graph,
        "graph_to", graph,
        "wallet_from", wallet_state.wallet_address,
        "wallet_to", wallet_to_hash,
        "order_currency", token,
        "order_amount", FORMAT_DECIMAL(total_amount, 8),
        "order_id", order_id,
        "order_utc_unix", utc_unix,
        "the_sign", sig_base64,
        "publicKey_xy_compressed", wallet_state.public_key_b58,
        separator="~"
    )
    
    timestamp = FORMAT_TIMESTAMP(utc_unix, "YYYY_MM_DD_HH_MM_SS")
    filename = CONCATENATE("sample_tx", "_offline_", token, "_", timestamp, ".txt")
    WRITE_FILE(filename, broadcast_data)
    
    RETURN broadcast_data, token
END FUNCTION
                

Success: Transaction Group Signing
The signed transaction is a tilde-separated string including the number of transactions, hashed wallet_to, signature, and public key, saved to an offline file for later broadcasting. The signature is not URI-encoded in the offline file but will be encoded during broadcasting.

Pseudo-Code: Broadcast Transaction Group

FUNCTION broadcast_group_transaction(wallet_state, broadcast_data, transactions):
    url = wallet_state.protocol + "://" + wallet_state.graph + "/broadcast.asmx/order_accept_multiple"
    
    order_csv_multiple = CONCATENATE_WITH_SEPARATOR(
        "tallybox",
        "parcel_of_transactions",
        FOR EACH transaction IN transactions WITH index:
            "wallet_to_" + index,
            transaction.wallet_to,
            "order_amount_" + index,
            transaction.order_amount,
        separator="~"
    )
    
    broadcast_parts = broadcast_data.SPLIT("~")
    
    tallybox, parcel_type, num_label, num_txs, graph_from_label, graph_from, graph_to_label, graph_to, \
    wallet_from_label, wallet_from, wallet_to_label, wallet_to, order_currency_label, order_currency, \
    order_amount_label, order_amount, order_id_label, order_id, order_utc_unix_label, order_utc_unix, \
    the_sign_label, sig_base64, public_key_label, public_key_b58 = broadcast_parts
    
    IF NOT (tallybox == "tallybox" AND parcel_type == "parcel_of_transaction" AND
            num_label == "number_of_transactions" AND graph_from_label == "graph_from" AND
            graph_to_label == "graph_to" AND wallet_from_label == "wallet_from" AND
            wallet_to_label == "wallet_to" AND order_currency_label == "order_currency" AND
            order_amount_label == "order_amount" AND order_id_label == "order_id" AND
            order_utc_unix_label == "order_utc_unix" AND the_sign_label == "the_sign" AND
            public_key_label == "publicKey_xy_compressed"):
        THROW "Invalid broadcast data structure"
    END IF
    
    broadcast_data_quoted = CONCATENATE_WITH_SEPARATOR(
        tallybox, parcel_type, num_label, num_txs, graph_from_label, graph_from, graph_to_label, graph_to,
        wallet_from_label, wallet_from, wallet_to_label, wallet_to, order_currency_label, order_currency,
        order_amount_label, order_amount, order_id_label, ENCODE_URI_COMPONENT(order_id), order_utc_unix_label, order_utc_unix,
        the_sign_label, ENCODE_URI_COMPONENT(sig_base64), public_key_label, public_key_b58,
        separator="~"
    )
    
    post_data = "app_name=tallybox&app_version=2.0&order_csv=" + broadcast_data_quoted + 
                "&order_csv_multiple=" + order_csv_multiple)
    
    TRY:
        response = POST_REQUEST(url, post_data, headers={"Content-Type": "application/x-www-form-urlencoded"})
        IF response.STARTS_WITH("submitted~200~"):
            RETURN "Group transaction broadcast successfully: " + response
        ELSE:
            parts = response.SPLIT("~")
            error_code = parts[1] OR "unknown"
            error_message = parts[2] OR "no details provided"
            THROW "Broadcast failed with error " + error_code + ": " + error_message
    CATCH error:
        THROW "Failed to broadcast Transaction Group: " + error
END FUNCTION
                

Success: Transaction Group Broadcasting
A successful broadcast returns a response starting with submitted~200~, indicating the Transaction Group was accepted by the DAG node.

Pseudo-Code: Main Workflow

FUNCTION main():
    TRY:
        file_path = PROMPT_USER("Enter wallet XML file path: ")
        password = PROMPT_USER_SECURE("Enter wallet password: ")
        
        log_choice = PROMPT_USER("Show decryption logs? [1] Yes [2] No")
        show_logs = (log_choice == "1")
        
        wallet_state = load_wallet(file_path, password, show_logs=show_logs)
        OUTPUT("Wallet loaded successfully!")
        
        txn_file_path = PROMPT_USER("Enter transaction file path: ")
        transactions, total_wallet_to, total_amount = read_transaction_file(txn_file_path, show_logs=show_logs)
        OUTPUT("Loaded " + length(transactions) + " transactions from " + txn_file_path)
        
        broadcast_data, token = prepare_group_transaction(wallet_state, transactions, total_wallet_to, total_amount, show_logs=show_logs)
        OUTPUT("Group transaction signed: " + broadcast_data)
        OUTPUT("Group transaction saved to " + filename)
        
        action = PROMPT_USER("Select action: [1] Broadcast [2] Quit")
        IF action == "1":
            result = broadcast_group_transaction(wallet_state, broadcast_data, transactions, show_logs=show_logs)
            OUTPUT(result)
        ELSE IF action == "2":
            OUTPUT("Exiting")
            RETURN
        ELSE:
            THROW "Invalid action selected"
    CATCH error:
        OUTPUT("Error: " + error)
END FUNCTION