sendico/api/proto/gateway/chain/v1/chain.proto

syntax = "proto3";

package chain.gateway.v1;

option go_package = "github.com/tech/sendico/pkg/proto/gateway/chain/v1;chainv1";

import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "api/proto/common/money/v1/money.proto";
import "api/proto/common/pagination/v1/cursor.proto";
import "api/proto/common/describable/v1/describable.proto";

// Supported blockchain networks for the managed wallets.
enum ChainNetwork {
  // CHAIN_NETWORK_UNSPECIFIED is the default zero value.
  CHAIN_NETWORK_UNSPECIFIED = 0;
  // CHAIN_NETWORK_ETHEREUM_MAINNET is Ethereum layer-1 mainnet.
  CHAIN_NETWORK_ETHEREUM_MAINNET = 1;
  // CHAIN_NETWORK_ARBITRUM_ONE is the Arbitrum One rollup.
  CHAIN_NETWORK_ARBITRUM_ONE = 2;
  // CHAIN_NETWORK_TRON_MAINNET is the TRON mainnet.
  CHAIN_NETWORK_TRON_MAINNET = 4;
  // CHAIN_NETWORK_TRON_NILE is the TRON Nile testnet.
  CHAIN_NETWORK_TRON_NILE = 5;
  // CHAIN_NETWORK_ARBITRUM_SEPOLIA is the Arbitrum Sepolia testnet.
  CHAIN_NETWORK_ARBITRUM_SEPOLIA = 6;
}

// ManagedWalletStatus represents the lifecycle state of a managed wallet.
enum ManagedWalletStatus {
  // MANAGED_WALLET_STATUS_UNSPECIFIED is the default zero value.
  MANAGED_WALLET_STATUS_UNSPECIFIED = 0;
  // MANAGED_WALLET_ACTIVE means the wallet is open and operational.
  MANAGED_WALLET_ACTIVE = 1;
  // MANAGED_WALLET_SUSPENDED means the wallet is temporarily disabled.
  MANAGED_WALLET_SUSPENDED = 2;
  // MANAGED_WALLET_CLOSED means the wallet is permanently closed.
  MANAGED_WALLET_CLOSED = 3;
}

// DepositStatus tracks the confirmation state of an inbound deposit.
enum DepositStatus {
  // DEPOSIT_STATUS_UNSPECIFIED is the default zero value.
  DEPOSIT_STATUS_UNSPECIFIED = 0;
  // DEPOSIT_PENDING means the deposit has been observed but not yet confirmed.
  DEPOSIT_PENDING = 1;
  // DEPOSIT_CONFIRMED means the deposit has been confirmed on-chain.
  DEPOSIT_CONFIRMED = 2;
  // DEPOSIT_FAILED means the deposit could not be confirmed.
  DEPOSIT_FAILED = 3;
}

// TransferStatus tracks the lifecycle of an outbound transfer.
enum TransferStatus {
  // TRANSFER_STATUS_UNSPECIFIED is the default zero value.
  TRANSFER_STATUS_UNSPECIFIED = 0;

  TRANSFER_CREATED    = 1; // record exists, not started
  TRANSFER_PROCESSING = 2; // we are working on it (signing, building tx, etc)
  TRANSFER_WAITING    = 3; // waiting external world (network/provider)

  TRANSFER_SUCCESS    = 4; // final success
  TRANSFER_FAILED     = 5; // final failure
  TRANSFER_CANCELLED  = 6; // final cancelled
}


// Asset captures the chain/token pair so downstream systems can route correctly.
message Asset {
  ChainNetwork chain = 1;
  string token_symbol = 2;
  string contract_address = 3; // optional override when multiple contracts exist per chain
}

// ManagedWallet represents a platform-managed blockchain wallet.
message ManagedWallet {
  string wallet_ref = 1;
  string organization_ref = 2;
  string owner_ref = 3;
  Asset asset = 4;
  string deposit_address = 5;
  ManagedWalletStatus status = 6;
  map<string, string> metadata = 7;
  google.protobuf.Timestamp created_at = 8;
  google.protobuf.Timestamp updated_at = 9;
  common.describable.v1.Describable describable = 10;
}

// CreateManagedWalletRequest is the request to create a new managed wallet.
message CreateManagedWalletRequest {
  string idempotency_key = 1;
  string organization_ref = 2;
  string owner_ref = 3;
  Asset asset = 4;
  map<string, string> metadata = 5;
  common.describable.v1.Describable describable = 6;
}

// CreateManagedWalletResponse is the response for CreateManagedWallet.
message CreateManagedWalletResponse {
  ManagedWallet wallet = 1;
}

// GetManagedWalletRequest is the request to retrieve a wallet by reference.
message GetManagedWalletRequest {
  string wallet_ref = 1;
}

// GetManagedWalletResponse is the response for GetManagedWallet.
message GetManagedWalletResponse {
  ManagedWallet wallet = 1;
}

// ListManagedWalletsRequest is the request to list wallets with optional filters.
message ListManagedWalletsRequest {
  string organization_ref = 1;
  reserved 2;
  reserved "owner_ref";
  Asset asset = 3;
  common.pagination.v1.CursorPageRequest page = 4;
  // Optional owner filter with 3-state semantics:
  // - not set: return all wallets within organization
  // - set to empty string: return wallets where owner_ref is null/empty
  // - set to a value: return wallets where owner_ref matches
  google.protobuf.StringValue owner_ref_filter = 5;
}

// ListManagedWalletsResponse is the response for ListManagedWallets.
message ListManagedWalletsResponse {
  repeated ManagedWallet wallets = 1;
  common.pagination.v1.CursorPageResponse page = 2;
}

// WalletBalance holds the balance breakdown for a managed wallet.
message WalletBalance {
  common.money.v1.Money available = 1;
  common.money.v1.Money pending_inbound = 2;
  common.money.v1.Money pending_outbound = 3;
  google.protobuf.Timestamp calculated_at = 4;
  common.money.v1.Money native_available = 5;
}

// GetWalletBalanceRequest is the request to retrieve a wallet's balance.
message GetWalletBalanceRequest {
  string wallet_ref = 1;
}

// GetWalletBalanceResponse is the response for GetWalletBalance.
message GetWalletBalanceResponse {
  WalletBalance balance = 1;
}

// ServiceFeeBreakdown describes a single fee line item applied to a transfer.
message ServiceFeeBreakdown {
  string fee_code = 1;
  common.money.v1.Money amount = 2;
  string description = 3;
}

// TransferDestination identifies where a transfer should be sent.
message TransferDestination {
  oneof destination {
    string managed_wallet_ref = 1;
    string external_address = 2;
  }
  string memo = 3; // chain-specific memo/tag when required by the destination
}

// Transfer represents an outbound blockchain transfer.
message Transfer {
  string transfer_ref = 1;
  string idempotency_key = 2;
  string organization_ref = 3;
  string source_wallet_ref = 4;
  TransferDestination destination = 5;
  Asset asset = 6;
  common.money.v1.Money requested_amount = 7;
  common.money.v1.Money net_amount = 8;
  repeated ServiceFeeBreakdown fees = 9;
  TransferStatus status = 10;
  string transaction_hash = 11;
  string failure_reason = 12;
  google.protobuf.Timestamp created_at = 13;
  google.protobuf.Timestamp updated_at = 14;
  string intent_ref = 15;
  string payment_ref = 16;
  string operation_ref = 17;
}

// SubmitTransferRequest is the request to submit an outbound transfer.
message SubmitTransferRequest {
  string idempotency_key = 1;
  string organization_ref = 2;
  string source_wallet_ref = 3;
  TransferDestination destination = 4;
  common.money.v1.Money amount = 5;
  repeated ServiceFeeBreakdown fees = 6;
  map<string, string> metadata = 7;
  string operation_ref = 8;
  string intent_ref = 9;
  string payment_ref = 10;
}

// SubmitTransferResponse is the response for SubmitTransfer.
message SubmitTransferResponse {
  Transfer transfer = 1;
}

// GetTransferRequest is the request to retrieve a transfer by reference.
message GetTransferRequest {
  string transfer_ref = 1;
}

// GetTransferResponse is the response for GetTransfer.
message GetTransferResponse {
  Transfer transfer = 1;
}

// ListTransfersRequest is the request to list transfers with optional filters.
message ListTransfersRequest {
  string source_wallet_ref = 1;
  string destination_wallet_ref = 2;
  TransferStatus status = 3;
  common.pagination.v1.CursorPageRequest page = 4;
}

// ListTransfersResponse is the response for ListTransfers.
message ListTransfersResponse {
  repeated Transfer transfers = 1;
  common.pagination.v1.CursorPageResponse page = 2;
}

// EstimateTransferFeeRequest is the request to estimate network fees for a transfer.
message EstimateTransferFeeRequest {
  string source_wallet_ref = 1;
  TransferDestination destination = 2;
  common.money.v1.Money amount = 3;
  Asset asset = 4;
}

// EstimateTransferFeeResponse is the response for EstimateTransferFee.
message EstimateTransferFeeResponse {
  common.money.v1.Money network_fee = 1;
  string estimation_context = 2;
}

// ComputeGasTopUpRequest is the request to calculate the gas top-up needed.
message ComputeGasTopUpRequest {
  string wallet_ref = 1;
  common.money.v1.Money estimated_total_fee = 2;
}

// ComputeGasTopUpResponse is the response for ComputeGasTopUp.
message ComputeGasTopUpResponse {
  common.money.v1.Money topup_amount = 1;
  bool cap_hit = 2;
}

// EnsureGasTopUpRequest is the request to top up gas for a wallet if needed.
message EnsureGasTopUpRequest {
  string idempotency_key = 1;
  string organization_ref = 2;
  string source_wallet_ref = 3;
  string target_wallet_ref = 4;
  common.money.v1.Money estimated_total_fee = 5;
  map<string, string> metadata = 6;
  string payment_ref = 7;
  string intent_ref = 8;
  string operation_ref = 9;
}

// EnsureGasTopUpResponse is the response for EnsureGasTopUp.
message EnsureGasTopUpResponse {
  common.money.v1.Money topup_amount = 1;
  bool cap_hit = 2;
  Transfer transfer = 3;
}

// WalletDepositObservedEvent is emitted when a deposit is detected on-chain.
message WalletDepositObservedEvent {
  string deposit_ref = 1;
  string wallet_ref = 2;
  Asset asset = 3;
  common.money.v1.Money amount = 4;
  string source_address = 5;
  string transaction_hash = 6;
  string block_id = 7;
  DepositStatus status = 8;
  google.protobuf.Timestamp observed_at = 9;
}

// TransferStatusChangedEvent is emitted when a transfer changes status.
message TransferStatusChangedEvent {
  Transfer transfer = 1;
  string reason = 2;
}