feat: add Tx dsl

[lmcmz]

Closes: #???

Description

---

For contributor use:

• Targeted PR against master branch
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Updated relevant documentation
• Re-reviewed Files changed in the Github PR explorer
• Added appropriate labels

[github-actions]

Unit Test Results

  12 files    12 suites   1m 8s ⏱️
117 tests 109 ✔️ 1 💤 7 ❌

For more details on these failures, see this check.

Results for commit 0d20757.

♻️ This comment has been updated with latest results.

[github-actions]

PR Summary

Introduced a Kotlin DSL for building and sending Flow transactions, mirroring the flow-swift builder style. Added helper extensions for extracting created account addresses from transaction results, new Cadence scripts for child accounts, EVM operations, staking, and token balances. Refactored the Signer interface signature, improved address registry import resolution with case-insensitive matching, and added HYBRID_CUSTODY contract support.

Changes

File	Summary
.gitignore	Added /.kotlin and /.kotlin/metadata entries to the gitignore file.
flow/src/androidMain/kotlin/org/onflow/flow/crypto/Crypto.kt	Consolidated the two sign overloads into a single sign(bytes, transaction?) method, removing the separate sign(transaction?, bytes) variant.
flow/src/androidMain/kotlin/org/onflow/flow/infrastructure/scripts/ContractAddressRegister.kt	Normalized contract keys to uppercase during loading and lookup. Updated resolveImports to use case-insensitive regex replacement for 0x<Contract> placeholders.
flow/src/androidMain/resources/scripts/common/addresses.json	Added trailing newline to the JSON file.
flow/src/androidMain/resources/scripts/common/child/get_child_account_meta.cdc	New file. Cadence script that retrieves child account metadata from a HybridCustody.Manager for a given parent address.
flow/src/androidMain/resources/scripts/common/child/get_child_addresses.cdc	New file. Cadence script that returns the list of child addresses managed by a HybridCustody.Manager.
flow/src/androidMain/resources/scripts/common/evm/call_contract.cdc	New file. Cadence transaction that calls an EVM contract from a COA, transferring FLOW and invoking the target with provided data and gas limit.
flow/src/androidMain/resources/scripts/common/evm/evm_run.cdc	New file. Cadence transaction that executes an RLP-encoded EVM transaction via EVM.run.
flow/src/androidMain/resources/scripts/common/staking/get_delegator_info.cdc	New file. Cadence script that retrieves delegator staking info from FlowStakingCollection.
flow/src/androidMain/resources/scripts/common/token/get_token_balance_storage.cdc	New file. Cadence script that queries all FungibleToken.Vault balances in an account's storage.
flow/src/commonMain/kotlin/org/onflow/flow/AddressRegistry.kt	Added HYBRID_CUSTODY constant and registered its addresses for Testnet and Mainnet. Changed defaultChainId type from ChainId to ChainIdProvider.
flow/src/commonMain/kotlin/org/onflow/flow/CadenceTarget.kt	New file. Introduces CadenceTarget data class and CadenceTargetType enum. Provides query and sendTransaction extension functions on FlowApi for base64-encoded Cadence scripts.
flow/src/commonMain/kotlin/org/onflow/flow/FlowApi.kt	Added trailing newline to the file.
flow/src/commonMain/kotlin/org/onflow/flow/TransactionDSL.kt	New file. Implements TransactionDSLBuilder with methods for setting script, arguments, gas limit, payer, proposer, authorizers, and reference block. Provides buildTransaction, signTransaction, and sendTransaction extension functions on FlowApi.
flow/src/commonMain/kotlin/org/onflow/flow/TransactionResultExtensions.kt	New file. Adds findEvent, getField, getCreatedAddress, getCreatedAccountAddress, and waitForCreatedAccountAddress extension functions for extracting data from TransactionResult and Event.
flow/src/commonMain/kotlin/org/onflow/flow/apis/TransactionsApi.kt	Added removePrefix("0x") normalization to transaction ID parameters in requestTransactionResultById, requestTransactionById, getTransactionResult, getTransaction, and waitForSeal.
flow/src/commonMain/kotlin/org/onflow/flow/cadence/CadenceQueries.kt	New file. Defines ChildAccountMetadata, StakingNode data classes and provides getChildAddresses, getChildAccountMetadata, getTokenBalances, and getDelegatorInfo extension functions on FlowApi.
flow/src/commonMain/kotlin/org/onflow/flow/evm/EVMManager.kt	Added runEVMTransaction and callEVMContract methods. Refactored createCOAAccount to use the new FlowApi.sendTransaction DSL. Moved ChildAccountMetadata import to cadence package.
flow/src/commonMain/kotlin/org/onflow/flow/models/Address.kt	Added hex property as an alias for base16Value on FlowAddress.
flow/src/commonMain/kotlin/org/onflow/flow/models/Signer.kt	Changed sign to sign(bytes, transaction?). Updated signWithDomain and signAsTransaction to accept optional transaction parameter.
flow/src/commonMain/kotlin/org/onflow/flow/websocket/FlowWebSocketClient.kt	Removed unused JsonArray and JsonObject imports.
flow/src/commonMain/resources/scripts/common/addresses.json	Added trailing newline to the JSON file.
flow/src/commonMain/resources/scripts/common/child/get_child_account_meta.cdc	New file. Cadence script that retrieves child account metadata from a HybridCustody.Manager for a given parent address.
flow/src/commonMain/resources/scripts/common/child/get_child_addresses.cdc	New file. Cadence script that returns the list of child addresses managed by a HybridCustody.Manager.
flow/src/commonMain/resources/scripts/common/evm/call_contract.cdc	New file. Cadence transaction that calls an EVM contract from a COA, transferring FLOW and invoking the target with provided data and gas limit.
flow/src/commonMain/resources/scripts/common/evm/evm_run.cdc	New file. Cadence transaction that executes an RLP-encoded EVM transaction via EVM.run.
flow/src/commonMain/resources/scripts/common/staking/get_delegator_info.cdc	New file. Cadence script that retrieves delegator staking info from FlowStakingCollection.
flow/src/commonMain/resources/scripts/common/token/get_token_balance_storage.cdc	New file. Cadence script that queries all FungibleToken.Vault balances in an account's storage.
flow/src/commonTest/kotlin/org/onflow/flow/TransactionResultExtensionsTest.kt	New file. Tests getCreatedAddress for present and missing events, and waitForCreatedAccountAddress against a mainnet transaction.

---

autogenerated by presubmit.ai

[github-actions]

🚨 Pull request needs attention.

Review Summary

Commits Considered (3)

• 0d20757: fix: unit test
• 3bc8ee9: feat: add helper func for getCreatedAccountAddress
• 58bd773: feat: add tx dsl

Files Processed (29)

• .gitignore (1 hunk)
• flow/src/androidMain/kotlin/org/onflow/flow/crypto/Crypto.kt (2 hunks)
• flow/src/androidMain/kotlin/org/onflow/flow/infrastructure/scripts/ContractAddressRegister.kt (3 hunks)
• flow/src/androidMain/resources/scripts/common/addresses.json (1 hunk)
• flow/src/androidMain/resources/scripts/common/child/get_child_account_meta.cdc (1 hunk)
• flow/src/androidMain/resources/scripts/common/child/get_child_addresses.cdc (1 hunk)
• flow/src/androidMain/resources/scripts/common/evm/call_contract.cdc (1 hunk)
• flow/src/androidMain/resources/scripts/common/evm/evm_run.cdc (1 hunk)
• flow/src/androidMain/resources/scripts/common/staking/get_delegator_info.cdc (1 hunk)
• flow/src/androidMain/resources/scripts/common/token/get_token_balance_storage.cdc (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/AddressRegistry.kt (3 hunks)
• flow/src/commonMain/kotlin/org/onflow/flow/CadenceTarget.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/FlowApi.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/TransactionDSL.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/TransactionResultExtensions.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/apis/TransactionsApi.kt (4 hunks)
• flow/src/commonMain/kotlin/org/onflow/flow/cadence/CadenceQueries.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/evm/EVMManager.kt (6 hunks)
• flow/src/commonMain/kotlin/org/onflow/flow/models/Address.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/models/Signer.kt (1 hunk)
• flow/src/commonMain/kotlin/org/onflow/flow/websocket/FlowWebSocketClient.kt (1 hunk)
• flow/src/commonMain/resources/scripts/common/addresses.json (1 hunk)
• flow/src/commonMain/resources/scripts/common/child/get_child_account_meta.cdc (1 hunk)
• flow/src/commonMain/resources/scripts/common/child/get_child_addresses.cdc (1 hunk)
• flow/src/commonMain/resources/scripts/common/evm/call_contract.cdc (1 hunk)
• flow/src/commonMain/resources/scripts/common/evm/evm_run.cdc (1 hunk)
• flow/src/commonMain/resources/scripts/common/staking/get_delegator_info.cdc (1 hunk)
• flow/src/commonMain/resources/scripts/common/token/get_token_balance_storage.cdc (1 hunk)
• flow/src/commonTest/kotlin/org/onflow/flow/TransactionResultExtensionsTest.kt (1 hunk)

Actionable Comments (1)

• flow/src/commonMain/kotlin/org/onflow/flow/evm/EVMManager.kt [168-168]

  possible bug: "Potential overflow when converting ULong to Long for gasLimit."

Skipped Comments (5)

• flow/src/commonMain/kotlin/org/onflow/flow/TransactionDSL.kt [77-78]

  possible bug: "Inconsistent default values for keyIndex in proposer overloads."

• flow/src/commonMain/kotlin/org/onflow/flow/TransactionDSL.kt [113-117]

  possible issue: "Key lookup logic may fail when default keyIndex is used but no key exists at index 0."

• flow/src/commonMain/kotlin/org/onflow/flow/TransactionResultExtensions.kt [21-24]

  maintainability: "Function name shadows imported function."

• flow/src/commonMain/kotlin/org/onflow/flow/CadenceTarget.kt [27-28]

  possible issue: "AddressRegistry may not use the provided chainId."

• flow/src/commonMain/kotlin/org/onflow/flow/cadence/CadenceQueries.kt [55-61]

  readability: "Force unwrap after null filter could be simplified."

[github-actions]

Converting ULong to Long via toLong() can cause overflow for values greater than Long.MAX_VALUE. If gasLimit exceeds 9223372036854775807, this will produce incorrect negative values.

[lealobanov]

I noticed there are some failing tests, are these already failing on main?

[lmcmz]

I noticed there are some failing tests, are these already failing on main?

Yeah, most of the failing test case are relating with websockets.

Task :flow:testDebugUnitTest

EVMManagerTests > testCreateCOAAccount FAILED
    java.lang.AssertionError at EVMManagerTests.kt:23
        Caused by: io.ktor.serialization.JsonConvertException at CoroutineDebugging.kt:42
            Caused by: io.ktor.serialization.JsonConvertException at KotlinxSerializationConverter.kt:90
                Caused by: io.ktor.serialization.JsonConvertException at EVMManagerTests.kt:23
                    Caused by: kotlinx.serialization.MissingFieldException at EVMManagerTests.kt:23
                        Caused by: kotlinx.serialization.MissingFieldException at EVMManagerTests.kt:23

FlowWebSocketClientTest > testSubscribeToEvents FAILED
    kotlinx.coroutines.TimeoutCancellationException at CoroutineDebugging.kt:42
        Caused by: kotlinx.coroutines.TimeoutCancellationException at Timeout.kt:188

FlowWebSocketClientTest > testSubscribeToAccountStatuses FAILED
    kotlinx.coroutines.TimeoutCancellationException at CoroutineDebugging.kt:42
        Caused by: kotlinx.coroutines.TimeoutCancellationException at Timeout.kt:188

FlowWebSocketClientTest > testSubscribeToTransactionStatuses FAILED
    kotlinx.coroutines.TimeoutCancellationException at CoroutineDebugging.kt:42
        Caused by: kotlinx.coroutines.TimeoutCancellationException at Timeout.kt:188

114 tests completed, 4 failed, 1 skipped