[tolgahan-arikan]

Summary

Adds Tron wallet support to the Kotlin SDK, matching the TypeScript SDK (0xPolygon/oms-wallet-typescript-sdk#104): create, import and sign in with Tron wallets, sign and verify, send TRX and TRC-20 transfers, and read balances from the OMS Tron indexer. It also replaces walletAddress with activeWallet and makes session nullable. This is a breaking change; see MIGRATION.md (0.4.0). A separate commit upgrades CBOR Java to 4.5.6 for CVE-2024-23684.

Changes

Tron (feat! commit)

• Generated client: regenerated from upstream waas origin/master @ 54d91262 with webrpc-gen v0.47.0's built-in kotlin target (which replaced gen-kotlin v0.3.2 upstream); apart from the package name (technology.polygon.omswallet.internal.generated.waas), it is identical to upstream's proto/clients/waas.gen.kt. The hand-built Webrpc header now matches (webrpc@v0.47.0;kotlin@v0.47.0;waas@…).
• Wallets and networks: WalletType.Tron, TronNetwork (Mainnet, Nile) / TronNetworks. Tron import (WalletImportPrivateKey.Tron / TronBytes) uses the same secp256k1 key format as Ethereum.
• Transactions: sendTronTransaction and callTronContract, always native mode. data is forwarded exactly: omitted means no data field (plain TRX transfer), "0x" calls the payable fallback.
• Signing: signTronMessage, signTronTypedData, isValidTronMessageSignature and isValidTronTypedDataSignature (networkFamily: tron).
• Balances: getTronBalances calls /v1/TronIndexerGateway/GetTokenBalancesDetails, with the URL derived from the publishable key like the Solana gateway. Models mirror the Solana ones. When a selectFeeOption selector is passed, the fee-option balance lookup uses it for unsponsored Tron fees.
• Wallet-type checks: methods check the stored wallet type instead of the address shape, before any request.
• Contract method names: callContract and callTronContract reject a full signature ("transfer(address,uint256)") locally. WaaS only accepts the bare name and builds the signature from args.
• Wallet responses: an Ethereum wallet whose address isn't valid hex is rejected as an invalid response.

Breaking changes (0.4.0)

• WalletClient.walletAddress is replaced by activeWallet: Wallet?.
• OMSWalletSessionState is renamed to OMSWalletSession; session is nullable, with non-null expiresAt and auth. The internal class that already had that name is now OMSWalletSessionStateMachine.
• walletAddress is removed from the wallet activation result (now WalletActivationResult, see below) and CompleteAuthResult.WalletSelected. The session-expired event gains wallet.
• The persisted session record moves to version 2 and stores the full wallet. Older records are discarded, so users sign in once after upgrading.

Sample apps (feat(app) commit)

• app: an Ethereum/Tron picker in the Wallet card and a Tron panel (Nile by default, with a Nile ↔ Mainnet switch; the Solana panel has a Devnet ↔ Mainnet switch). It shows TRX and USDT balances with faucet links, signs and verifies a message, sends TRX / USDT / custom TRC-20 and shows "Transaction submitted.", and links to Tronscan.
• trails-actions: moved to activeWallet. The explorer button now uses only the on-chain txnHash.

Security (fix(deps) commit)

• Upgrades com.upokecenter:cbor 4.4.4 → 4.5.6 for CVE-2024-23684: crafted CBOR could make decoding use excessive CPU. The SDK decodes CBOR only when verifying wallet-import attestations. This also brings in numbers 1.8.2 and datautilities 1.1.0 as transitive dependencies. The commit only touches gradle/libs.versions.toml, and it ships in the same release as Tron.

Differences from the TypeScript SDK

• Kotlin keeps its single Wallet model rather than a separate Tron wallet type.
• The Tron gateway Webrpc header uses gen-kotlin, like the Kotlin Solana header.

Cross-SDK API alignment (refactor! and feat(app) commits)

Aligns the public API with the TypeScript and Swift SDKs after a cited three-way API review. Breaking changes are made directly, with no deprecated aliases, and each one has a MIGRATION.md 0.4.0 entry.

• Signature verification: all isValid…Signature methods take an optional walletAddress and no longer take walletId. When the address is omitted, the active wallet's address is used. Requests never send a wallet ID.
• contractAddress replaces contract on callContract and callTronContract.
• Renames:
  • WalletActivationResult (was WalletSelectionResult);
  • BalancesResult (was TokenBalancesResult);
  • OidcAuthMode (was OidcRedirectAuthMode; wire values unchanged);
  • the TransactionStatusPollingOptions fields timeoutMs, intervalMs and fastIntervalMs (same defaults).
• Additions:
  • mode on sendTransaction(network, to, value, …);
  • CompleteAuthResult.wallet and credential;
  • balance paging column/before/after/sort, with SortBy and SortOrder;
  • OMSWalletUpstreamService.wireValue.
• Error codes: the new WalletAddressAlreadyImported maps WaaS error 7313 to status 409.
• Parameter order: signInWithOidcIdToken and the custom-provider startOidcRedirectAuth now use the same order as Swift and TypeScript.
• Docs fixes: the includeMetadata default, the Tron balance wording, and the trails-actions session label.
• Sample app: Solana Devnet support (SOL and USDC balances, sign/verify, transfers with fee options) alongside Ethereum and Tron.
• Changes with no compile error, all covered in MIGRATION:
  • verification sends an address and works while signed out when one is given;
  • a mismatched active wallet type now fails locally;
  • the error code for 7313;
  • the polling validation messages;
  • strict parsing of sort in indexer pages;
  • TokenBalancesPage equality now includes the new fields.

Review fixes and cleanup

After an outsider review and a simplicity review, every finding was re-checked against the code before changing it. The commits fall into these groups:

• Fixes:

  • a given but empty or whitespace-only walletAddress in the isValid…Signature methods throws OMSWalletValidationException before any request, as in TypeScript and Swift;
  • the leftover isEthereumAddressValue alias is removed, and isEthereumHexAddress is hidden from Java;
  • MIGRATION notes that wallet is the new first OMSWalletSessionExpiredEvent property;
  • in the sample app, the Tron panel guards against double taps and shows Nile indexer errors instead of 0 balances.

• Cleanup of code this PR added: Solana/Tron fee-balance enrichment is shared, and executePreparedTransaction takes one enricher instead of three nullable networks.

• Compat leftovers removed (0.4.0 is breaking):

  • the indexer parser reads only the gateway's field names (balance, tokenID, metaTxnID, tokenIds, tokenId), dropping old alternate spellings the gateway never sends;
  • default storage names from before storage was scoped per project, which no release ever used, were removed from internal storage classes. The public API is unchanged. The indexer parser no longer reads old alternate field spellings (balanceWei, tokenIDs, metaTxnId) that the gateway never sends.

• Cleanup of code already on master:

  • unused JSON helpers, MonotonicNonceGenerator, synchronizationKey, initialSnapshot and a private OIDC helper removed;
  • always-true clearSession flags removed;
  • the WalletClient polling parameters are folded into TransactionStatusPollingOptions;
  • one writeTextAtomically;
  • OMSWalletHex is reused;
  • small IndexerClient duplications removed;
  • a shared javap runner, and no POM fallbacks (the stale 0.3.2-SNAPSHOT one is gone);
  • small sample-app simplifications.

• Sample apps: the Tron and Solana panels label the WaaS txnId as "Last transaction ID" when no on-chain hash exists yet, and trails-actions no longer opens an explorer link built from txnId.

• Docs pass:

  • MIGRATION corrects the 0.3.x Tron statement and adds the blank walletAddress validation;
  • the README Tron example uses a placeholder recipient, and the README lists Solana and Tron in the capabilities and sample app;
  • the AGENTS.md file reference is fixed.

The public API is unchanged by these commits.

Public API baseline (build commit)

public-api.txt was produced with javap -public, which treats Kotlin internal declarations as public. As a result it listed:

• internal classes such as OMSWalletSessionStateMachine, PersistedSessionRecord and OMSWalletJson;
• private classes' companions and serializers;
• name-mangled internal members and synthetic accessors.

This was already the case on master. The dump now uses the binary-compatibility-validator library (0.18.1, with kotlin-metadata-jvm 2.2.10), which reads Kotlin metadata. It is build-time only and nothing is added to the AAR. The baseline drops from 177 classes on master (188 on this branch before the change) to 122, and no public API is removed. Every top-level type in the new dump matches docs/api.md, and all 65 documented members are present (checked by hand; the build guard compares top-level names).

The validator also keeps three synthetic constructor bridges of non-public constructors, which name internal types. Nothing outside the SDK can call them, so they are dropped.

To keep the baseline from regressing, the dump task fails in three cases:

• it contains mangled internal members or synthetic accessors;
• it mentions an SDK type that isn't itself public, such as a leaked generated WaaS type;
• its top-level declarations differ from the source-generated docs/api.md.

I confirmed the dump task catches a newly public class, a changed docs heading and a leaked generated type, and that the baseline check still catches a new public member.

Alternatives considered:

• the validator's Gradle plugin doesn't apply to AGP 9's built-in Kotlin;
• Kotlin Gradle plugin 2.2.10's built-in abiValidation isn't available for Android modules.

When it is, the dump can switch to it.

Wallet-import attestation fix (fix commit)

The attestation verifier rejected a real AWS Nitro document captured from WaaS, so importWallet could not succeed against live WaaS. This was already the case on master. There were three faults:

• it required CBOR tag 18, but Nitro sends an untagged COSE_Sign1;
• it built the certificate path from the root-first cabundle without reversing the intermediates;
• it checked CA path-length constraints in that same order.

The path now runs from the leaf through the reversed intermediates to the pinned AWS Nitro root, as in TypeScript and Swift. A wrong COSE tag is still rejected. A positive test verifies the real document, using the same fixture as the Swift SDK.

Test audit (test commits)

An audit of every test: test-only commits, then a second mutation-based review pass. Every new or rewritten test was checked to fail when the behaviour it covers is broken. A test was removed or merged only when its partner already asserts everything it checked.

• Exact request bodies now asserted:
  • the Solana transfer (recipient and amount);
  • EVM SignMessage (network);
  • AuthorizeRemoteAccess (grants and credentialId);
  • Solana balance filters.
• The signature-header vectors use literal headers instead of the production builder.
• Wallet response validation: one parameterized test now covers a non-hex Ethereum address and a missing or unknown networkFamily / keyOrigin; each case was checked to fail with its production check removed.
• The projectId derivation test now asserts the derived scope in a real request body.
• Assertions that could not fail were removed (self-comparisons, duplicated lines, defaults the test itself built), and TESTING.md / docs/error-contracts.md now name only tests that exist.
• Count: JVM tests 215 → 192 (200 with the sliding-expiry tests).
• No production code changed in these commits.

Sliding session expiry (chore(waas) and feat(session) commits)

WaaS now extends a login credential while it is in use (0xsequence/waas#144): the requested lifetime is a hard ceiling, and a 10-day idle window slides forward with use. CompleteAuth returns the current (sliding) expiry, and the new GetCredential reads it back (0xsequence/waas#152). Without this change, a session longer than 10 days would be signed out locally on day 10 even while in use.

• Refresh: the SDK reads the current expiry with GetCredential after restoring a session, when the local expiry is reached (before signing out), before an operation on a locally expired session, and in the background at most every 6 hours after successful wallet calls. The new value is saved and the expiry timer rescheduled. Concurrent callers share one request, and a result is applied only while the same session is current.
• Old servers: a server without GetCredential (WebrpcBadRoute, e.g. v1.1.1) keeps the previous behaviour, which is exact there.
• Offline: if WaaS is unreachable at the local expiry, the session is kept and checked again later (60 s, backing off to 15 min); an operation on a locally expired session then fails with the network error, not OMS_SESSION_EXPIRED.
• Server-reported end: 7202 KeyNotFound / 7203 KeyExpired on a request signed with the session credential end the session (expiry notification once) and fail the operation with OMS_SESSION_EXPIRED, with the WaaS error as cause and no upstreamError, the same shape as a local expiry. A rejected Execute reports OMS_SESSION_EXPIRED (the middleware rejects it before execution); a status lookup after submission keeps its transaction error with txnId. Unauthenticated WaasPublic calls are excluded (InspectCredential returns 7202 for an unknown remote credential), and 7207 Unauthorized is not mapped.
• Nonce ordering: WaaS needs strictly increasing nonces per credential, so a background refresh never overlaps another signed request: it starts only when none is in flight, and signed requests wait for an in-flight refresh before signing.
• Lifetime cap: the maximum session lifetime is now 180 days (15_552_000 s); WaaS clamps rather than rejects, so this is safe on older servers.
• Generated client: regenerated from waas origin/master @ 54d91262 (webrpc-gen v0.47.0). Besides GetCredential it adds ClaimWallet, claimable wallets, WalletStatus.Preallocated and error 7208; the SDK does not use them yet and none are public.
• Docs (README, MIGRATION 0.4.0, error contracts, session-expiry-flow.md, docs/api.md) describe expiresAt as the current expiry, extended by use.
• Live check: run on dev with the TypeScript SDK (restore sent GetCredential, saved the server's expiry, and the next signed request waited for it). This SDK's refresh, gate and fallback are covered by unit tests with mutation proofs; not yet exercised live from the demo app.

Release

POM_VERSION_NAME, the README dependency line and the generated module's snapshot fallback are set to 0.4.0 (chore(release): prepare 0.4.0).

Testing

• ./gradlew ktlintCheck passes

• ./gradlew :oms-wallet-kotlin-sdk:testDebugUnitTest passes (200 tests)

• ./gradlew --build-cache verify passes (ktlint, unit tests, Android lint, both apps, API baseline, API docs check)

• tools/check-expo-compatibility.sh minimum passes

• tools/check-expo-compatibility.sh current passes (Expo 58.0.13, after merging the fixture bumps from master)

• Wallet import on an emulator against dev: the CBOR 4.5.6 attestation path works end to end (a unit test also verifies a real Nitro document)

• Instrumented tests (connectedDebugAndroidTest) pass on a Pixel 9 emulator (API 36): 3/3

• Tested by hand on an Android emulator against the dev sandbox: Google sign-in, importWallet with an Ethereum private key (attestation verified, wallet listed as imported), a sponsored 1 TRX send on Nile and a 0.001 SOL send on Devnet (both submitted with a hash).

Related

• TypeScript SDK: feat!: add Tron support and replace walletAddress with activeWallet 0xPolygon/oms-wallet-typescript-sdk#104
• Swift SDK: feat!: add Tron support and replace walletAddress with activeWallet swift-sdk#49