stellaranchor

type AnchorClient struct {
	// contains filtered or unexported fields
}

type AnchorConfig struct {
	TransferServerURL string // from TOML's TRANSFER_SERVER_SEP0024
}

type AuthClient struct {
	// contains filtered or unexported fields
}

type AuthConfig struct {
	WebAuthEndpoint   string // from TOML
	ServerSigningKey  string // from TOML — used to verify the challenge signature
	NetworkPassphrase string // from TOML, e.g. "Public Global Stellar Network ; September 2015"
	HomeDomain        string // e.g. "stellar.moneygram.com"
	WebAuthDomain     string // typically equal to HomeDomain unless MG runs the auth server on a different host

	// TreasurySecret is the S... seed of the custodial treasury account.
	// Held in memory only — never logged. The corresponding G... address
	// becomes the SEP-10 `account` parameter.
	TreasurySecret string

	// FallbackTokenTTL is used when the issued JWT has no `exp` claim.
	// Defaults to 23h to stay safely under MG's typical 24h validity.
	FallbackTokenTTL time.Duration

	// HTTPTimeout caps the duration of any single SEP-10 HTTP exchange.
	// Defaults to 15s.
	HTTPTimeout time.Duration
}

type AuthResult struct {
	JWT       string
	ExpiresAt time.Time
}

type Client struct {
	Auth     *AuthClient
	Anchor   *AnchorClient
	JWTCache *JWTCache
	// contains filtered or unexported fields
}

type Config struct {
	HomeDomain        string // e.g. "stellar.moneygram.com"
	WebAuthEndpoint   string // SEP-1 WEB_AUTH_ENDPOINT
	TransferServerURL string // SEP-1 TRANSFER_SERVER_SEP0024
	ServerSigningKey  string // SEP-1 SIGNING_KEY
	NetworkPassphrase string // SEP-1 NETWORK_PASSPHRASE
	USDCIssuer        string // expected USDC issuer (validated against TOML upstream)
	TreasurySecret    string // S... seed of the custodial treasury account

	HTTPClient *http.Client
	Logger     *slog.Logger

	// JWTSafetyMargin tunes the JWT cache. Defaults to 60s.
	JWTSafetyMargin time.Duration
}

type Currency struct {
	Code            string `toml:"code"`
	Issuer          string `toml:"issuer"`
	IsAssetAnchored bool   `toml:"is_asset_anchored"`
	AnchorAssetType string `toml:"anchor_asset_type"`
	AnchorAsset     string `toml:"anchor_asset"`
	Name            string `toml:"name"`
	Desc            string `toml:"desc"`
}

type Customer struct {
	FirstName          string `json:"first_name,omitempty"`
	LastName           string `json:"last_name,omitempty"`
	MobileNumber       string `json:"mobile_number,omitempty"` // E.164, e.g. "+254712345678"
	BirthDate          string `json:"birth_date,omitempty"`    // YYYY-MM-DD
	Address            string `json:"address,omitempty"`       // line1[, line2]
	City               string `json:"city,omitempty"`
	PostalCode         string `json:"postal_code,omitempty"`
	AddressCountryCode string `json:"address_country_code,omitempty"` // ISO-3, e.g. "KEN"
}

type DepositRequest struct {
	AssetCode string   // "USDC"
	Amount    string   // decimal USDC, e.g. "50.00" — required for custodial wallets
	Lang      string   // ISO-639-1, defaults to "en"
	Account   string   // destination wallet G... address the anchor credits
	Customer  Customer // optional SEP-9 prefill

	// Memo asks the anchor to attach a memo to the Stellar payment it makes to
	// Account. SEP-24 offers it precisely so a client can match inbound
	// payments to its own records, and it is independent of the SEP-10 memo:
	// that one identifies the borrower, this one can identify the loan.
	//
	// Optional in the specification, so an anchor may ignore it. MoneyGram
	// does not: the sandbox echoes it on deposit_memo from the first poll, at
	// status incomplete, well before the borrower finishes the webview.
	//
	// Every borrower's deposit lands on the same Account, so without this the
	// payments are distinguishable on-chain only by amount and timing.
	Memo     string
	MemoType string // "text", "id" or "hash"; defaults to "text" when Memo is set
}

type DepositResponse struct {
	Type string `json:"type"` // typically "interactive_customer_info_needed"
	URL  string `json:"url"`  // interactive webview URL — SMS this to the user
	ID   string `json:"id"`   // MoneyGram's transaction ID — persist and poll
}

type FeeDetail struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Amount      string `json:"amount"`
}

type FeeDetails struct {
	Total   string      `json:"total"`
	Asset   string      `json:"asset"`
	Details []FeeDetail `json:"details,omitempty"`
}

type JWTCache struct {
	// contains filtered or unexported fields
}

type RefundPayment struct {
	// ID is the Stellar transaction hash when IDType is "stellar", or an
	// anchor-internal identifier when it is "external".
	ID     string `json:"id"`
	IDType string `json:"id_type"`
	Amount string `json:"amount"`
	Fee    string `json:"fee"`
}

type Refunds struct {
	AmountRefunded string          `json:"amount_refunded"`
	AmountFee      string          `json:"amount_fee"`
	Payments       []RefundPayment `json:"payments"`
}

type Status string

type TOML struct {
	Version             string     `toml:"VERSION"`
	NetworkPassphrase   string     `toml:"NETWORK_PASSPHRASE"`
	SigningKey          string     `toml:"SIGNING_KEY"`
	WebAuthEndpoint     string     `toml:"WEB_AUTH_ENDPOINT"`
	TransferServerSEP24 string     `toml:"TRANSFER_SERVER_SEP0024"`
	Accounts            []string   `toml:"ACCOUNTS"`
	Currencies          []Currency `toml:"CURRENCIES"`
}

type Transaction struct {
	ID                    string `json:"id"`
	Kind                  string `json:"kind"` // "deposit" | "withdrawal"
	Status                Status `json:"status"`
	StatusEta             int64  `json:"status_eta,omitempty"`
	AmountIn              string `json:"amount_in,omitempty"`
	AmountInAsset         string `json:"amount_in_asset,omitempty"`
	AmountOut             string `json:"amount_out,omitempty"`
	AmountOutAsset        string `json:"amount_out_asset,omitempty"`
	AmountFee             string `json:"amount_fee,omitempty"`
	AmountFeeAsset        string `json:"amount_fee_asset,omitempty"`
	StartedAt             string `json:"started_at,omitempty"`
	CompletedAt           string `json:"completed_at,omitempty"`
	StellarTransactionID  string `json:"stellar_transaction_id,omitempty"`
	ExternalTransactionID string `json:"external_transaction_id,omitempty"` // cash-pickup reference
	WithdrawAnchorAccount string `json:"withdraw_anchor_account,omitempty"`
	WithdrawMemo          string `json:"withdraw_memo,omitempty"`
	WithdrawMemoType      string `json:"withdraw_memo_type,omitempty"` // typically "id"
	MoreInfoURL           string `json:"more_info_url,omitempty"`
	Message               string `json:"message,omitempty"`

	// Deposit-side fields. DepositMemo is the memo the anchor will use to
	// transfer the asset to To, and MoneyGram populates it with whatever
	// DepositRequest.Memo asked for — verified against the sandbox, which
	// echoed "LR-1A03C985D8A-61ce" at status incomplete.
	//
	// It is a statement of intent until a payment actually exists: the field
	// says what the anchor means to attach, not what landed on the ledger.
	//
	// This is never ChildAccountMemo. That one scopes the SEP-10 session and
	// identifies the borrower; this one is per-transaction and is what makes
	// concurrent deposits to a shared account distinguishable on-chain.
	To              string `json:"to,omitempty"` // account the anchor credits
	DepositMemo     string `json:"deposit_memo,omitempty"`
	DepositMemoType string `json:"deposit_memo_type,omitempty"`

	// UserActionRequiredBy is MoneyGram's own deadline for the borrower to act.
	// It is theirs, not ours: a deposit lapses on this timestamp whatever our
	// configured window says, so it is the figure to schedule and quote against.
	UserActionRequiredBy string `json:"user_action_required_by,omitempty"`

	// FeeDetails is what the borrower pays on top of the amount. SEP-24 carries
	// it separately from amount_in, so a quote that ignores it understates what
	// they hand over at the counter.
	FeeDetails *FeeDetails `json:"fee_details,omitempty"`

	// Refunded is the deprecated SEP-24 boolean, kept because some anchors
	// still emit it. Refunds is the authoritative field.
	Refunded bool     `json:"refunded,omitempty"`
	Refunds  *Refunds `json:"refunds,omitempty"`
}

type ValidateOptions struct {
	ExpectedNetworkPassphrase string
	ExpectedSigningKey        string // optional; "" disables the check
	ExpectedUSDCIssuer        string // optional; "" disables the check
}

type WithdrawRequest struct {
	AssetCode string   // "USDC"
	Amount    string   // decimal USD, e.g. "50.00" — required for custodial wallets
	Lang      string   // ISO-639-1, defaults to "en"
	Account   string   // funds wallet G... address — the withdrawal payment source
	Customer  Customer // optional SEP-9 prefill
}

type WithdrawResponse struct {
	Type string `json:"type"` // typically "interactive_customer_info_needed"
	URL  string `json:"url"`  // interactive webview URL — SMS this to the user
	ID   string `json:"id"`   // MoneyGram's transaction ID — persist and poll
}