Skip to content

feat(tron): add settlement pending receipt handling - #98

Merged
roger-gan merged 11 commits into
developfrom
feat/tron-settlement-pending
Sep 3, 2026
Merged

roger-gan merged 11 commits into
developfrom
feat/tron-settlement-pending

Conversation

@roger-gan

Copy link
Copy Markdown
Contributor

Description

Align TRON settlement_pending behavior with the existing EVM receipt handling model.

  • Preserve valid broadcast transaction IDs when receipt confirmation is indeterminate.
  • Wait for a low-latency packed execution receipt without adding solidified/finality reconciliation.
  • Return terminal failure for explicit reverts while keeping incomplete receipt data pending.
  • Validate GasFree relayer transaction IDs and preserve a known hash when later polling fails.
  • Remove reconciliation APIs, persisted reconciliation contexts, and Facilitator worker coupling.

Supersedes #97 after the feature branch was renamed.

Tests

  • pnpm test -- --reporter=dot — 25 files, 275 tests passed
  • pnpm lint:check
  • pnpm format:check
  • pnpm build

Branch route

  • Normal development targets develop
  • Only release_* or hotfix/* targets main

Checklist

  • Runtime behavior covered by unit tests
  • Scheme specifications updated
  • Changeset included

Comment thread specs/schemes/batch-settlement/scheme_batch_settlement_tron.md
Comment thread typescript/packages/mechanisms/tron/src/shared/settleReceipt.ts
Comment thread typescript/packages/mechanisms/tron/src/shared/gasfree/api.ts Outdated
Comment thread specs/schemes/batch-settlement/scheme_batch_settlement_tron.md
@Will-Guan

Copy link
Copy Markdown
Contributor

This review identified six issues: three P1, two P2, and one P3.

The main problem is that settlement_pending has been introduced at the facilitator layer without fully updating the state machines and public consumers that receive it:

  • CR-001 / P1: A post-broadcast Batch reservation can expire under its ordinary TTL, allowing another request to replace it before the original transaction reaches a terminal state.
  • CR-002 / P1: ChannelManager treats pending responses as ordinary failures, allowing automatic claim, settle, and refund jobs to rebroadcast unresolved operations.
  • CR-004 / P1: The public refund helper converts a pending 402 response into a plain error and discards the refund transaction ID.
  • CR-008 / P2: The generic HTTP client exposes a non-terminal pending result as settle_failed.
  • CR-009 / P2: A GasFree SUCCEED response without a hash is converted into a delayed dynamic timeout instead of the stable missing-hash error.
  • CR-011 / P3: The Batch specification’s declared authoritative error list does not contain the new settlement_pending code.

Together, the P1 issues allow unresolved on-chain operations to lose their reconciliation identity, become eligible for replacement, or be broadcast again. This can produce duplicate transaction attempts, additional fees, repeated resource execution, and divergence between local and on-chain state.

The existing relevant tests pass, but they do not cover these cross-layer pending-state scenarios.

Review recommendation: Request changes.

@roger-gan
roger-gan merged commit 467d8c6 into develop Sep 3, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants