TallyBox Tutorial - Treasury Accept

Managing Treasury Records with treasury_accept

This tutorial guides developers through the `treasury_accept` web method in the `broadcast.asmx` C# web service, part of the TallyBox ecosystem. The method adds authorized treasury records to the `tbl_system_treasury` table, allowing assigned wallets to use these records for transactions. It includes a signature verification step to ensure record validity, dropping any records with invalid signatures. This tutorial covers the algorithm, logic, signature verification, and data flow, with pseudo-code and examples to aid implementation.

Step 1: Parse Input Parameters

The `treasury_accept` method receives treasury details as individual parameters. The process involves:

Accept input parameters: `authorized_currency`, `authorized_amount`, `authorized_wallet`, `blockchain_entity`, `blockchain_wallet`, `blockchain_hash`, and a new `signature` field (introduced for record validation).
Validate that required fields (`authorized_currency`, `authorized_amount`, `authorized_wallet`, `blockchain_hash`) are not null or empty.
Assign values to variables for further processing.

This step ensures all necessary treasury details are provided before proceeding.

Pseudo-Code: Parse Input Parameters

FUNCTION parse_inputs(authorized_currency, authorized_amount, authorized_wallet, blockchain_entity, blockchain_wallet, blockchain_hash, signature):
    IF is_empty(authorized_currency) OR is_empty(authorized_amount) OR is_empty(authorized_wallet) OR is_empty(blockchain_hash) OR is_empty(signature) THEN
        RETURN error("301", "Missing required parameters")
    END IF
    treasury_data = {
        "currency": authorized_currency,
        "amount": authorized_amount,
        "wallet": authorized_wallet,
        "entity": blockchain_entity,
        "blockchain_wallet": blockchain_wallet,
        "hash": blockchain_hash,
        "signature": signature
    }
    RETURN treasury_data
END FUNCTION

Example Process:

authorized_currency: IRR
authorized_amount: 10000.00000000
authorized_wallet: boxB2bbc15c8c135W8PzPEZf98cEu2h2muhkeJQS3MwTYUaTHVkFTgihcS7
blockchain_entity: TallyBoxChain
blockchain_wallet: chainA1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef
blockchain_hash: 7c4a8d09ca3762af61e59520943dc26494f8941b
signature: MEYCIQCxzNKhOUXijLr+z2mI9npu/+KZijiEv3//W7Ya3VpvzgIhAI1m7wJLJ9ldP2m5jmYfUreuvoKTjoZmFQmt5e6foakp

Result: All fields provided, proceed to validation

References:
String.IsNullOrEmpty Method (Microsoft Docs)
Data Validation (Wikipedia)

Step 2: Validate Input Formats

Validate the format of input parameters to ensure they meet expected standards. The process involves:

Verify `authorized_currency` is a recognized currency using an `iscurrency` function (e.g., IRR, 2ZR).
Ensure `authorized_amount` is a valid decimal number using an `isnumeric` function.
Confirm `authorized_wallet` and `blockchain_wallet` pass a wallet quality check (`wallet_qc`).
Check `blockchain_hash` is a valid hash format (e.g., 40-character hexadecimal for SHA-1).
Validate `signature` format (e.g., base64-encoded ECDSA signature).

If any check fails, return an error with a specific code (e.g., `302` for invalid currency).

Pseudo-Code: Validate Formats

FUNCTION validate_formats(treasury_data):
    IF NOT iscurrency(treasury_data.currency) THEN
        RETURN error("302", "Invalid currency", treasury_data.currency)
    END IF
    IF NOT isnumeric(treasury_data.amount) THEN
        RETURN error("303", "Invalid amount format", treasury_data.amount)
    END IF
    IF NOT wallet_qc(treasury_data.wallet) THEN
        RETURN error("301", "Invalid wallet format", treasury_data.wallet)
    END IF
    IF NOT is_empty(treasury_data.blockchain_wallet) AND NOT wallet_qc(treasury_data.blockchain_wallet) THEN
        RETURN error("301", "Invalid blockchain wallet format", treasury_data.blockchain_wallet)
    END IF
    IF NOT is_valid_hash(treasury_data.hash) THEN
        RETURN error("304", "Invalid blockchain hash", treasury_data.hash)
    END IF
    IF NOT is_valid_signature_format(treasury_data.signature) THEN
        RETURN error("300", "Invalid signature format", treasury_data.signature)
    END IF
    RETURN success
END FUNCTION

Example Process:

authorized_currency: IRR (Valid: recognized currency)
authorized_amount: 10000.00000000 (Valid: numeric decimal)
authorized_wallet: boxB2bbc15c8c135... (Valid: passes wallet_qc)
blockchain_wallet: chainA1b2c3d4e5f... (Valid: passes wallet_qc)
blockchain_hash: 7c4a8d09ca3762af61e59520943dc26494f8941b (Valid: 40-character hex)
signature: MEYCIQCxzNKhOUXijLr+z2mI9npu... (Valid: base64 ECDSA format)

Result: Proceed to signature verification

References:
Decimal Type (Microsoft Docs)
Hash Functions (Wikipedia)

Step 3: Verify Cryptographic Signature

Verify the authenticity of the treasury record using an ECDSA signature on the secp256r1 curve. The process involves:

Construct the treasury string: `authorized_currency~authorized_amount~authorized_wallet~blockchain_entity~blockchain_wallet~blockchain_hash`.
Retrieve the public key associated with `authorized_wallet` from `tbl_tallybox_wallet_pubkey`.
Verify the `signature` against the treasury string using ECDSA on secp256r1.
If the signature is invalid, drop the record and return an error (`300`).

Pseudo-Code: Verify Signature

FUNCTION verify_signature(treasury_data):
    treasury_string = join([treasury_data.currency, treasury_data.amount, treasury_data.wallet, 
                            treasury_data.entity, treasury_data.blockchain_wallet, treasury_data.hash], "~")
    public_key = sql_find_record("tbl_tallybox_wallet_pubkey", "public_key", "wallet_id", 
                                 sql_find_record("tbl_tallybox_wallet", "wallet_id", "the_wallet", treasury_data.wallet))
    IF public_key == "no_record" THEN
        RETURN error("301", "Wallet not found", treasury_data.wallet)
    END IF
    IF NOT sign_data_b64_check(treasury_string, treasury_data.signature, public_key, "secp256r1") THEN
        RETURN error("300", "Invalid signature", "Signature verification failed")
    END IF
    RETURN success
END FUNCTION

Example Process:

Treasury String: IRR~10000.00000000~boxB2bbc15c8c135W8PzPEZf98cEu2h2muhkeJQS3MwTYUaTHVkFTgihcS7~TallyBoxChain~chainA1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef~7c4a8d09ca3762af61e59520943dc26494f8941b

Public Key Query: SELECT public_key FROM tbl_tallybox_wallet_pubkey WHERE wallet_id = (SELECT wallet_id FROM tbl_tallybox_wallet WHERE the_wallet = 'boxB2bbc15c8c135...')
Public Key: 2C7SVvEj45VMWwbd8UQNoYYWMeCMeyKm6qfDNQXhHkKK

Signature: MEYCIQCxzNKhOUXijLr+z2mI9npu/+KZijiEv3//W7Ya3VpvzgIhAI1m7wJLJ9ldP2m5jmYfUreuvoKTjoZmFQmt5e6foakp

Signature Verification Result: Valid

References:
ECDSA Algorithm (Wikipedia)
SEC 2: Recommended Elliptic Curve Domain Parameters (secp256r1)

Step 4: Verify Database Records

Ensure that the treasury record is valid by checking database records. The process involves:

Verify `authorized_currency` exists in `tbl_system_currency` using a `sql_find_record` function.
Confirm `authorized_wallet` exists in `tbl_tallybox_wallet`.
Check that `treasury_id` (generated as `$` + Unix timestamp) does not already exist in `tbl_system_treasury` to prevent duplicates.

If any check fails, return an error (e.g., `302` for invalid currency, `301` for invalid wallet, `305` for duplicate treasury ID).

Pseudo-Code: Verify Database Records

FUNCTION verify_database_records(treasury_data, treasury_id):
    currency_id = sql_find_record("tbl_system_currency", "currency_id", "currency_name", treasury_data.currency)
    IF currency_id == "no_record" THEN
        RETURN error("302", "Invalid currency", treasury_data.currency)
    END IF
    wallet_id = sql_find_record("tbl_tallybox_wallet", "wallet_id", "the_wallet", treasury_data.wallet)
    IF wallet_id == "no_record" THEN
        RETURN error("301", "Invalid wallet", treasury_data.wallet)
    END IF
    existing_treasury = sql_find_record("tbl_system_treasury", "treasury_id", "treasury_id", treasury_id)
    IF existing_treasury != "no_record" THEN
        RETURN error("305", "Duplicate treasury ID", treasury_id)
    END IF
    RETURN success
END FUNCTION

Example Process:

authorized_currency: IRR
Database Query: SELECT currency_id FROM tbl_system_currency WHERE currency_name = 'IRR'
Result: currency_id = 1 (Valid)

authorized_wallet: boxB2bbc15c8c135...
Database Query: SELECT wallet_id FROM tbl_tallybox_wallet WHERE the_wallet = 'boxB2bbc15c8c135...'
Result: wallet_id = 1001 (Valid)

treasury_id: $1741675600
Database Query: SELECT treasury_id FROM tbl_system_treasury WHERE treasury_id = '$1741675600'
Result: No record (Valid)

Result: Proceed to save record

References:
Database Concepts (Microsoft Docs)
SQL (Wikipedia)

Step 5: Save Treasury Record to Database

Store the validated treasury record in the `tbl_system_treasury` table. The process involves:

Generate a unique `treasury_id` by concatenating `$` with the current Unix timestamp (`local_utc_unix`).
Construct an SQL INSERT statement with all parameters, including `local_utc_unix`.
Execute the SQL statement using the `Tallybox.run_sqlstr` method.
Return the `treasury_id` as the response.

If the signature is invalid, the record is not saved, and an error is returned in Step 3.

Pseudo-Code: Save Treasury Record

FUNCTION save_treasury_record(treasury_data):
    local_utc_unix = get_current_unix_timestamp()
    treasury_id = "$" + local_utc_unix
    sql = "INSERT INTO tbl_system_treasury " +
          "(treasury_id, authorized_currency, authorized_amount, authorized_wallet, " +
          "blockchain_entity, blockchain_wallet, blockchain_hash, local_utc_unix) " +
          "VALUES ('" + treasury_id + "', '" + treasury_data.currency + "', '" +
          treasury_data.amount + "', '" + treasury_data.wallet + "', '" +
          treasury_data.entity + "', '" + treasury_data.blockchain_wallet + "', '" +
          treasury_data.hash + "', '" + local_utc_unix + "')"
    run_sql(sql)
    RETURN treasury_id
END FUNCTION

Example Output:

$1741675600

References:
SQL INSERT Statement (Microsoft Docs)
Unix Time (Wikipedia)

Step 6: Dropping Invalid Signatures

Records with invalid signatures are dropped to maintain the integrity of the `tbl_system_treasury` table. The process involves:

Signature verification in Step 3 ensures only valid records proceed to the database insertion step.
If a record fails signature verification, it is not inserted, and an error (`300`) is returned to the caller.
Periodic maintenance (e.g., via a stored procedure or job) can query `tbl_system_treasury` and re-verify signatures, deleting records with invalid signatures.

This ensures that only authorized and cryptographically verified treasury records are available for use.

Pseudo-Code: Periodic Signature Verification

PROCEDURE cleanup_invalid_treasury_records():
    FOR EACH record IN tbl_system_treasury:
        treasury_string = join([record.authorized_currency, record.authorized_amount, 
                                record.authorized_wallet, record.blockchain_entity, 
                                record.blockchain_wallet, record.blockchain_hash], "~")
        public_key = sql_find_record("tbl_tallybox_wallet_pubkey", "public_key", "wallet_id", 
                                     sql_find_record("tbl_tallybox_wallet", "wallet_id", "the_wallet", record.authorized_wallet))
        IF public_key == "no_record" OR NOT sign_data_b64_check(treasury_string, record.signature, public_key, "secp256r1") THEN
            DELETE FROM tbl_system_treasury WHERE treasury_id = record.treasury_id
        END IF
    END FOR
END PROCEDURE

Example Process:

Treasury Record: treasury_id = $1741675590, authorized_wallet = boxB2bbc15c8c135..., signature = invalid_signature
Verification: Fails ECDSA check
Action: DELETE FROM tbl_system_treasury WHERE treasury_id = '$1741675590'

Result: Record dropped

References:
SQL DELETE Statement (Microsoft Docs)
Data Integrity (Wikipedia)

Acknowledgments

Special thanks to Grok, for its invaluable assistance in creating this TallyBox treasury accept tutorial.