Documentation
¶
Overview ¶
Package rpc waits for a submitted Stellar transaction to be applied to the ledger.
Submitting a transaction only returns an acceptance status; the network applies it a few ledgers later. PollTransaction bridges that gap: it fetches the transaction by hash on an interval until it reaches a terminal state, then reports the outcome. NOT_FOUND means not yet applied and is retried; a transient fetch error is also retried; SUCCESS and FAILED are terminal. The poll ends in failure if the context is cancelled, the attempt budget is exhausted (timeout), or the status is unrecognized.
TransactionGetter is the one-method interface PollTransaction depends on, so any RPC client — or a mock — can drive it. PollConfig sets the attempt budget, interval, and logger; DefaultPollConfig supplies sensible values that callers override as needed.
Index ¶
- func FetchVaultEvents(ctx context.Context, client EventsGetter, contractID string, fromLedger uint32, ...) (protocol.GetEventsResponse, error)
- func PollTransaction(ctx context.Context, client TransactionGetter, txHash string, cfg PollConfig) (protocol.GetTransactionResponse, error)
- type EventsGetter
- type Payment
- type PollConfig
- type TransactionGetter
- type Verifier
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FetchVaultEvents ¶ added in v1.5.0
func FetchVaultEvents(ctx context.Context, client EventsGetter, contractID string, fromLedger uint32, limit uint) (protocol.GetEventsResponse, error)
FetchVaultEvents returns events emitted by contractID from fromLedger onward (inclusive), up to limit events.
This does not walk multiple pages within one call — soroban RPC's cursor is opaque, and at the vault's current volume one page comfortably covers a watch interval. If a returned page is exactly limit-sized there may be more events than were fetched; the caller (pkg/services/vaultwatch) logs that case rather than silently under-counting, since this is a compliance canary and a gap here should be loud.
func PollTransaction ¶
func PollTransaction( ctx context.Context, client TransactionGetter, txHash string, cfg PollConfig, ) (protocol.GetTransactionResponse, error)
PollTransaction polls for transaction completion with proper logging. It returns the full GetTransactionResponse on success and any error encountered.
Types ¶
type EventsGetter ¶ added in v1.5.0
type EventsGetter interface {
GetEvents(ctx context.Context, request protocol.GetEventsRequest) (protocol.GetEventsResponse, error)
}
EventsGetter is the interface for fetching contract events, so tests can stand in for the RPC client the same way TransactionGetter does for PollTransaction.
type Payment ¶ added in v1.0.0
Payment is a classic payment operation extracted from a transaction envelope.
type PollConfig ¶
PollConfig configures the polling behavior
func DefaultPollConfig ¶
func DefaultPollConfig() PollConfig
DefaultPollConfig returns the default polling configuration
type TransactionGetter ¶
type TransactionGetter interface {
GetTransaction(ctx context.Context, req protocol.GetTransactionRequest) (protocol.GetTransactionResponse, error)
}
TransactionGetter is the interface for fetching transaction status
type Verifier ¶ added in v1.0.0
type Verifier struct {
// contains filtered or unexported fields
}
Unlike PollTransaction it does not wait: a single lookup either answers definitively or reports the outcome as unknown, leaving the retry cadence to the caller.
func NewVerifier ¶ added in v1.0.0
func NewVerifier(client TransactionGetter) *Verifier
NewVerifier returns a Verifier backed by the given RPC client.
func (*Verifier) PaymentsTo ¶ added in v1.0.0
func (v *Verifier) PaymentsTo(ctx context.Context, txHash, destination, assetCode, assetIssuer string) ([]Payment, error)
PaymentsTo returns the successful payments in txHash addressed to destination, in the named asset.
func (*Verifier) TransactionSucceeded ¶ added in v1.0.0
TransactionSucceeded reports whether txHash succeeded on-ledger.
The three outcomes are distinct and callers must treat them differently:
- (true, nil) the transaction is on the ledger and succeeded
- (false, nil) it is on the ledger and definitively failed
- (false, err) unknown — not yet visible, outside the RPC's retention window, or the lookup itself failed
An unknown result is never a failure. Soroban RPC only retains recent transactions, so a hash older than the retention window reports NOT_FOUND indefinitely; callers that retry forever on error should bound their retries or escalate to a human.
Source Files