Tallybox Wallet - Transaction Tutorial

Sample Pseudo-Code: Load Wallet

FUNCTION load_wallet(file, password, protocol, graph):
    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):
            RETURN ERROR("Invalid XML format")

        key_components = wallet_name + "~" + password + "~" + wallet_address
        local_key = SHA256(key_components)
        private_key = aes256_cbc_decrypt_custom(private_key_aes_b64, local_key)

        ec = NEW_ELLIPTIC_CURVE("p256")
        key_pair = ec.KEY_FROM_PRIVATE(private_key, "hex")
        public_key = key_pair.GET_PUBLIC()
        x_hex = public_key.GET_X().TO_HEX().PAD_START(64, "0")
        y_hex = public_key.GET_Y().TO_HEX().PAD_START(64, "0")
        y_parity = public_key.GET_Y().MOD(2)
        suffix = IF y_parity == 0 THEN "2" ELSE "1"
        compressed_key = x_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)
        RETURN result
    CATCH error:
        RETURN ERROR("Decryption failed or invalid file: " + error)
END FUNCTION
                

Notice: XML File Structure
The XML file must include , , , and . Ensure the password matches the one used to encrypt the private key, or decryption will fail.

Sample Pseudo-Code: User Choice

FUNCTION prompt_user_action(wallet_state):
    IF NOT wallet_state.wallet_address:
        RETURN ERROR("No wallet loaded. Load a wallet first.")

    action = PROMPT_USER("Select action: [1] View History, [2] Send Transaction")
    IF action == "1":
        CALL fetch_balances(wallet_state)
    ELSE IF action == "2":
        CALL prepare_transaction(wallet_state)
    ELSE
        RETURN ERROR("Invalid action selected")
END FUNCTION
                

Warning: Wallet Validation
Always verify that a wallet is loaded (i.e., wallet_address is not empty) before allowing history or transaction actions. Attempting to proceed without a loaded wallet will result in errors.

Sample Pseudo-Code: Fetch Balances

FUNCTION fetch_balances(wallet_state):
    url = wallet_state.protocol + "://" + wallet_state.graph + "/archive.asmx/order_history"
    post_data = "app_name=tallybox&app_version=2.0&in_graph=" + ENCODE_URI_COMPONENT(wallet_state.graph) + "&wallet_address=" + ENCODE_URI_COMPONENT(wallet_state.wallet_address)
    
    TRY:
        response = POST_REQUEST(url, post_data)
        parts = response.SPLIT("~")
        balances = CREATE_RECORD()
        balances.SET_FIELD("2PN", "0.00000000")
        balances.SET_FIELD("2ZR", "0.00000000")
        balances.SET_FIELD("TLH", "0.00000000")
        FOR i = 6 TO parts.LENGTH - 2 STEP 2
            token = parts[i]
            amount = parts[i + 1]
            IF token IN ["2PN", "2ZR", "TLH"] AND amount AND IS_NUMBER(amount):
                balances.SET_FIELD(token, FORMAT_DECIMAL(amount, 8))
            END IF
        END FOR
        RETURN balances
    CATCH error:
        RETURN ERROR("Failed to fetch balances: " + error)
END FUNCTION
                

Info: API Endpoint
The default graph is tallybox.mixoftix.net, and the protocol is typically https. The API returns a tilde-separated string where token balances appear as pairs (e.g., 2PN~123.456789).

Sample Pseudo-Code: Prepare Transaction

FUNCTION prepare_transaction(wallet_state):
    target_address = PROMPT_USER("Enter target wallet address")
    token = PROMPT_USER("Select token: [2PN, 2ZR, TLH]")
    amount = PROMPT_USER("Enter amount (positive number)")
    order_id = PROMPT_USER("Enter optional order ID", optional=true)
    graph = wallet_state.graph
    utc_unix = CURRENT_TIMESTAMP_SECONDS()

    IF NOT VALIDATE_WALLET_ADDRESS(target_address):
        RETURN ERROR("Invalid target wallet address")
    IF NOT (token IN ["2PN", "2ZR", "TLH"]):
        RETURN ERROR("Invalid token")
    IF NOT IS_NUMBER(amount) OR amount <= 0:
        RETURN ERROR("Invalid amount")

    transaction_data = ENCODE_URI_COMPONENT(graph) + "~" + ENCODE_URI_COMPONENT(graph) + "~" + 
                       ENCODE_URI_COMPONENT(wallet_state.wallet_address) + "~" + 
                       ENCODE_URI_COMPONENT(target_address) + "~" + ENCODE_URI_COMPONENT(token) + "~" + 
                       FORMAT_DECIMAL(amount, 8) + "~" + ENCODE_URI_COMPONENT(order_id) + "~" + utc_unix
    msg_hash = SHA256(transaction_data)
    ec = NEW_ELLIPTIC_CURVE("p256")
    signature = wallet_state.key_pair.SIGN_ECDSA(msg_hash, RFC6979) // Produces (r, s) pair, deterministic per RFC 6979
    sig_der = signature.TO_DER("hex")                              // Encode (r, s) as DER, hex string
    sig_base64 = BASE64_ENCODE(HEX_TO_BYTES(sig_der))             // Convert hex to bytes, encode as Base64
    broadcast_data = CONCATENATE_WITH_SEPARATOR(
        "tallybox",
        "parcel_of_transaction",
        "graph_from", ENCODE_URI_COMPONENT(graph),
        "graph_to", ENCODE_URI_COMPONENT(graph),
        "wallet_from", ENCODE_URI_COMPONENT(wallet_state.wallet_address),
        "wallet_to", ENCODE_URI_COMPONENT(target_address),
        "order_currency", ENCODE_URI_COMPONENT(token),
        "order_amount", FORMAT_DECIMAL(amount, 8),
        "order_id", ENCODE_URI_COMPONENT(order_id),
        "order_utc_unix", utc_unix,
        "the_sign", ENCODE_URI_COMPONENT(sig_base64),
        "publicKey_xy_compressed", ENCODE_URI_COMPONENT(wallet_state.public_key_b58),
        separator="~"
    )

    RETURN broadcast_data
END FUNCTION
				

Sample 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
				

Success: Transaction Signing
A successful offline signature produces a tilde-separated string containing the transaction details, signature, and public key, ready for broadcasting to the DAG node.

Note: The ECDSA signing process must comply with RFC 6979 to ensure deterministic signatures, enhancing security and reproducibility.

Sample Pseudo-Code: Broadcast Transaction

FUNCTION broadcast_transaction(wallet_state, broadcast_data):
    url = wallet_state.protocol + "://" + wallet_state.graph + "/broadcast.asmx/order_accept"
    post_data = "app_name=tallybox&app_version=2.0&order_csv=" + ENCODE_URI_COMPONENT(broadcast_data.REPLACE("\n", "").REPLACE("\r", ""))
    
    TRY:
        response = POST_REQUEST(url, post_data)
        IF response.STARTS_WITH("submitted~200~"):
            RETURN SUCCESS("Transaction broadcast successfully: " + response)
        ELSE
            RETURN ERROR("Broadcast failed: " + response)
    CATCH error:
        RETURN ERROR("Failed to broadcast transaction: " + error)
END FUNCTION
                

Success: Transaction Broadcasting
A successful broadcast returns a response starting with submitted~200~, indicating the transaction was accepted by the DAG node. The response includes a transaction ID for tracking.