tech/sendico
2
0
Fork 0
Code Issues 30 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

refactored notificatoin / tgsettle responsibility boundaries

Browse Source
This commit is contained in:
Stephan D
2026-02-19 18:56:59 +01:00
parent 47f0a3d890
commit 2fd8a6ebb7
73 changed files with 3705 additions and 681 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
api/proto/payments/orchestration/v1/orchestration.proto
View File

@@ -10,6 +10,8 @@ import "api/proto/gateway/chain/v1/chain.proto";
import "api/proto/gateway/mntx/v1/mntx.proto";
import "api/proto/payments/shared/v1/shared.proto";
// InitiatePaymentsRequest triggers execution of all payment intents within
// a previously accepted quote.
message InitiatePaymentsRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
@@ -17,10 +19,12 @@ message InitiatePaymentsRequest {
map<string, string> metadata = 4;
}
// InitiatePaymentsResponse returns the created payments.
message InitiatePaymentsResponse {
repeated payments.shared.v1.Payment payments = 1;
}
// InitiatePaymentRequest creates a single payment from a standalone intent.
message InitiatePaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
@@ -29,19 +33,23 @@ message InitiatePaymentRequest {
string quote_ref = 5;
}
// InitiatePaymentResponse returns the created payment.
message InitiatePaymentResponse {
payments.shared.v1.Payment payment = 1;
}
// GetPaymentRequest fetches a payment by its reference.
message GetPaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string payment_ref = 2;
}
// GetPaymentResponse returns the requested payment.
message GetPaymentResponse {
payments.shared.v1.Payment payment = 1;
}
// ListPaymentsRequest queries payments with optional state and endpoint filters.
message ListPaymentsRequest {
payments.shared.v1.RequestMeta meta = 1;
repeated payments.shared.v1.PaymentState filter_states = 2;
@@ -51,48 +59,63 @@ message ListPaymentsRequest {
string organization_ref = 6;
}
// ListPaymentsResponse returns a page of matching payments.
message ListPaymentsResponse {
repeated payments.shared.v1.Payment payments = 1;
common.pagination.v1.CursorPageResponse page = 2;
}
// CancelPaymentRequest requests cancellation of a payment that has not yet
// been settled.
message CancelPaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string payment_ref = 2;
string reason = 3;
}
// CancelPaymentResponse returns the updated payment after cancellation.
message CancelPaymentResponse {
payments.shared.v1.Payment payment = 1;
}
// ProcessTransferUpdateRequest handles a blockchain transfer status change
// event from the chain gateway.
message ProcessTransferUpdateRequest {
payments.shared.v1.RequestMeta meta = 1;
chain.gateway.v1.TransferStatusChangedEvent event = 2;
}
// ProcessTransferUpdateResponse returns the payment after processing.
message ProcessTransferUpdateResponse {
payments.shared.v1.Payment payment = 1;
}
// ProcessDepositObservedRequest handles a wallet deposit observation event
// from the chain gateway.
message ProcessDepositObservedRequest {
payments.shared.v1.RequestMeta meta = 1;
chain.gateway.v1.WalletDepositObservedEvent event = 2;
}
// ProcessDepositObservedResponse returns the payment after processing.
message ProcessDepositObservedResponse {
payments.shared.v1.Payment payment = 1;
}
// ProcessCardPayoutUpdateRequest handles a card payout status change event
// from the card gateway.
message ProcessCardPayoutUpdateRequest {
payments.shared.v1.RequestMeta meta = 1;
mntx.gateway.v1.CardPayoutStatusChangedEvent event = 2;
}
// ProcessCardPayoutUpdateResponse returns the payment after processing.
message ProcessCardPayoutUpdateResponse {
payments.shared.v1.Payment payment = 1;
}
// InitiateConversionRequest creates an FX conversion payment between two
// ledger endpoints.
message InitiateConversionRequest {
payments.shared.v1.RequestMeta meta = 1;
string idempotency_key = 2;
@@ -103,18 +126,30 @@ message InitiateConversionRequest {
map<string, string> metadata = 7;
}
// InitiateConversionResponse returns the created conversion payment.
message InitiateConversionResponse {
payments.shared.v1.Payment conversion = 1;
}
// PaymentExecutionService orchestrates payment lifecycle operations across
// ledger, blockchain, card, and FX rails.
service PaymentExecutionService {
// InitiatePayments executes all intents within a quote.
rpc InitiatePayments(InitiatePaymentsRequest) returns (InitiatePaymentsResponse);
// InitiatePayment creates and executes a single payment.
rpc InitiatePayment(InitiatePaymentRequest) returns (InitiatePaymentResponse);
// CancelPayment cancels a pending payment.
rpc CancelPayment(CancelPaymentRequest) returns (CancelPaymentResponse);
// GetPayment retrieves a payment by reference.
rpc GetPayment(GetPaymentRequest) returns (GetPaymentResponse);
// ListPayments queries payments with filters and pagination.
rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
// InitiateConversion creates an FX conversion payment.
rpc InitiateConversion(InitiateConversionRequest) returns (InitiateConversionResponse);
// ProcessTransferUpdate handles blockchain transfer status callbacks.
rpc ProcessTransferUpdate(ProcessTransferUpdateRequest) returns (ProcessTransferUpdateResponse);
// ProcessDepositObserved handles deposit observation callbacks.
rpc ProcessDepositObserved(ProcessDepositObservedRequest) returns (ProcessDepositObservedResponse);
// ProcessCardPayoutUpdate handles card payout status callbacks.
rpc ProcessCardPayoutUpdate(ProcessCardPayoutUpdateRequest) returns (ProcessCardPayoutUpdateResponse);
}

193
api/proto/payments/orchestration/v2/orchestration.proto Normal file
View File

@@ -0,0 +1,193 @@
syntax = "proto3";
package payments.orchestration.v2;
option go_package = "github.com/tech/sendico/pkg/proto/payments/orchestration/v2;orchestrationv2";
import "google/protobuf/timestamp.proto";
import "api/proto/common/gateway/v1/gateway.proto";
import "api/proto/common/pagination/v1/cursor.proto";
import "api/proto/payments/shared/v1/shared.proto";
import "api/proto/payments/quotation/v2/quotation.proto";
import "api/proto/payments/quotation/v2/interface.proto";
// PaymentOrchestratorService executes quotation-backed payments and exposes
// orchestration-focused read APIs.
//
// Notes:
// - Execution input is quotation_ref (not an execution plan).
// - Returned Payment contains immutable quote/intent snapshots, so reads remain
// meaningful after quote storage TTL expiry.
service PaymentOrchestratorService {
// ExecutePayment creates/starts payment execution from an accepted quote.
rpc ExecutePayment(ExecutePaymentRequest) returns (ExecutePaymentResponse);
// GetPayment returns one payment by reference.
rpc GetPayment(GetPaymentRequest) returns (GetPaymentResponse);
// ListPayments returns payments filtered by orchestration lifecycle.
rpc ListPayments(ListPaymentsRequest) returns (ListPaymentsResponse);
}
// ExecutePaymentRequest starts orchestration for one accepted quote.
message ExecutePaymentRequest {
// Organization and trace context; idempotency should be supplied via
// meta.trace.idempotency_key.
payments.shared.v1.RequestMeta meta = 1;
// Required accepted quotation reference.
string quotation_ref = 2;
// Optional caller-side correlation key.
string client_payment_ref = 3;
}
// ExecutePaymentResponse returns the created or deduplicated payment.
message ExecutePaymentResponse {
Payment payment = 1;
}
// GetPaymentRequest fetches one payment by payment_ref.
message GetPaymentRequest {
payments.shared.v1.RequestMeta meta = 1;
string payment_ref = 2;
}
// GetPaymentResponse returns one orchestration payment aggregate.
message GetPaymentResponse {
Payment payment = 1;
}
// ListPaymentsRequest lists payments within the caller organization scope.
message ListPaymentsRequest {
payments.shared.v1.RequestMeta meta = 1;
// Optional state filter. Empty means all states.
repeated OrchestrationState states = 2;
// Optional filter by source quotation.
string quotation_ref = 3;
// Optional creation-time range filter.
// Semantics: created_from is inclusive, created_to is exclusive.
google.protobuf.Timestamp created_from = 4;
google.protobuf.Timestamp created_to = 5;
// Cursor pagination controls.
common.pagination.v1.CursorPageRequest page = 6;
}
// ListPaymentsResponse returns one cursor page of payments.
message ListPaymentsResponse {
repeated Payment payments = 1;
common.pagination.v1.CursorPageResponse page = 2;
}
// Payment is the orchestration runtime aggregate.
// It is designed to be self-contained for post-factum analysis and support.
message Payment {
// Stable payment reference.
string payment_ref = 1;
// Quote used to initiate the payment.
string quotation_ref = 2;
// Immutable snapshot of the execution intent used to create this payment.
payments.quotation.v2.QuoteIntent intent_snapshot = 3;
// Immutable quote snapshot used for execution pricing/route context.
payments.quotation.v2.PaymentQuote quote_snapshot = 4;
string client_payment_ref = 5;
// Current orchestration runtime state.
OrchestrationState state = 6;
// Monotonic aggregate version for optimistic concurrency control.
uint64 version = 7;
// Step-level execution telemetry.
repeated StepExecution step_executions = 8;
// Aggregate timestamps.
google.protobuf.Timestamp created_at = 9;
google.protobuf.Timestamp updated_at = 10;
}
// Kept local on purpose: payments.shared.v1.PaymentState models product-level
// payment lifecycle and does not cover orchestration runtime states.
enum OrchestrationState {
// Default zero value.
ORCHESTRATION_STATE_UNSPECIFIED = 0;
// Payment record created, execution not started yet.
ORCHESTRATION_STATE_CREATED = 1;
// Runtime is actively executing steps.
ORCHESTRATION_STATE_EXECUTING = 2;
// Runtime requires operator/system attention.
ORCHESTRATION_STATE_NEEDS_ATTENTION = 3;
// Execution finished successfully.
ORCHESTRATION_STATE_SETTLED = 4;
// Execution reached terminal failure.
ORCHESTRATION_STATE_FAILED = 5;
}
// StepExecution is telemetry for one orchestration step attempt stream.
message StepExecution {
// Stable step reference inside orchestration runtime.
string step_ref = 1;
// Logical step code/type label (planner/executor-defined).
string step_code = 2;
// Current state of this step.
StepExecutionState state = 3;
// Monotonic attempt number, starts at 1.
uint32 attempt = 4;
// Step timing.
google.protobuf.Timestamp started_at = 5;
google.protobuf.Timestamp completed_at = 6;
// Failure details when state is FAILED/NEEDS_ATTENTION.
Failure failure = 7;
// External references produced by the step.
repeated ExternalReference refs = 8;
}
// Kept local on purpose: no shared enum exists for orchestration step runtime.
enum StepExecutionState {
// Default zero value.
STEP_EXECUTION_STATE_UNSPECIFIED = 0;
// Not started yet.
STEP_EXECUTION_STATE_PENDING = 1;
// Currently running.
STEP_EXECUTION_STATE_RUNNING = 2;
// Finished successfully.
STEP_EXECUTION_STATE_COMPLETED = 3;
// Finished with terminal error.
STEP_EXECUTION_STATE_FAILED = 4;
// Blocked and requires attention/intervention.
STEP_EXECUTION_STATE_NEEDS_ATTENTION = 5;
// Not executed because it became irrelevant/unreachable.
STEP_EXECUTION_STATE_SKIPPED = 6;
}
// Failure describes a normalized step failure.
message Failure {
// Broad, shared failure category.
payments.shared.v1.PaymentFailureCode category = 1;
// Machine-readable, executor-specific code.
string code = 2;
// Human-readable message.
string message = 3;
}
// ExternalReference links step execution to external systems/operations.
message ExternalReference {
// Rail where external side effect happened.
common.gateway.v1.Rail rail = 1;
// Gateway instance that owns the referenced operation/entity.
// This is the discovery key for fetching details on demand.
string gateway_instance_id = 2;
// Reference classifier. Keep values stable and namespaced:
// e.g. "ledger.journal", "ledger.hold", "chain.tx", "provider.payout".
string kind = 3;
// External operation/entity reference id in the owner system.
string ref = 4;
}