Financial Message Profiles

TREA Financial Message Profiles are executable contracts that model institutional financial instructions. They are not SWIFT parsers or message adapters — they execute typed financial intent with balance effects, lifecycle governance, and auditable receipts.

A profile qualifies for TREA only if it produces at least one of: balance movement, obligation creation or settlement, guarantee lock or release, lifecycle transition, accounting effect, auditable receipt, or policy-gated execution.

> SWIFT transports financial messages. TREA executes financial intent.

Profile Namespace

All profiles live in std.profile.* and are deployed as first-class TREA contracts.

Priority Profiles (Phase 1)

| Profile | SWIFT Analog | Purpose | |---------|-------------|---------| | PaymentInstruction | MT103, MT101 | Single credit transfer with reversal authority | | InterbankSettlement | MT202, MT202 COV | Bank-to-bank fund transfer with optional covered reference | | FXSettlement | MT300, MT304 | FX trade execution from attested external quote | | GuaranteeLifecycle | MT760, MT767 | Full guarantee lifecycle: issue → claim → honor |

Explicitly Excluded

The following categories are read/notify surfaces, not dispositive instructions. They belong in the REST API, receipts, events, or Explorer — not in TREA profiles:

• AccountStatement (MT940/950)
• DebitCreditAdvice (MT900/910)
• BalanceReport (MT941/942)
• SettlementStatus (MT548)
• FreeFormatNotice (MT799/999)
• Generic inquiries

Common Runtime Flow

External instruction
  → Adapter (validates envelope, maps to TREA payload)
  → Simulation (dry-run — shows effects before signing)
  → Execution (signed transaction submitted)
  → Effects plan (balance moves, obligation records)
  → Ledger validation (commit or reject)
  → Receipt (profile, parties, amounts, final state)

Simulation

All profiles support dry-run simulation via the standard TREA simulate endpoint. Simulation shows balance effects, lifecycle transitions, and validation outcomes before any funds move.

Receipt Shape (common fields)

Every profile receipt includes:

profile:          "PaymentInstruction" | "InterbankSettlement" | "FXSettlement" | "GuaranteeLifecycle"
instruction_ref:  reference identifier
parties:          { originator/sender/issuer/..., beneficiary/receiver/... }
token_id:         asset moved
amount:           principal amount
state:            final lifecycle state
executed_at:      block timestamp of execution

PaymentInstruction

Single credit transfer between two parties. Enforces value-date gating and supports post-execution reversal by a designated authority.

Canonical source: `src/stdlib/payment_instruction.trea`

State Machine

Drafted
  │
  │ authorize()   [admin]
  ▼
Authorized
  │
  │ execute()     [originator, after value_date]
  ▼
Executed ──── fund_reversal() [beneficiary] ──── reverse() [reversal_authority] ──→ Reversed

Drafted | Authorized ──── cancel() [admin] ──→ Cancelled

Lifecycle

initialize(admin, reversal_authority)
draft(originator, beneficiary, token, amount, ref_id, value_date)
set_charges(charges_token, charges_amount)   # optional
authorize()
execute()   # originator consents and transfers amount to beneficiary
            # transfers charges_amount to admin if set
fund_reversal()  # beneficiary returns principal to the contract vault
reverse()        # reversal authority releases the funded principal

Key Design Points

Value-date gating — execute() is blocked until block_timestamp >= value_date. Pass value_date = 0 for same-day settlement.

Charges are separate — set_charges() sets an optional fee transfer executed atomically with the principal. Charges go to the admin (correspondent/servicer).

Reversal authority — A separate reversal_authority address releases only funds that the beneficiary first returned with fund_reversal(). It cannot debit the beneficiary directly.

Informative messages rejected — This profile only executes fund movements. Status queries, advice messages, and reporting belong in the API layer.

InterbankSettlement

Bank-to-bank fund transfer with optional covered-payment reference. Setting covered_ref marks the instruction as an MT202 COV analog.

Canonical source: `src/stdlib/interbank_settlement.trea`

State Machine

Drafted
  │
  │ validate()    [admin]
  ▼
Validated
  │
  │ settle()      [sending institution, after value_date]
  ▼
Settled ──── fund_reversal() [receiving institution] ──── reverse() [reversal_authority] ──→ Reversed

Drafted | Validated ──── cancel() [admin] ──→ Cancelled

Lifecycle

initialize(admin, reversal_authority)
draft(sender, receiver, token, amount, ref_id, value_date)
set_covered_ref(cov_ref)       # optional: marks as MT202 COV
set_correspondent(corr_bank)   # optional: routed via correspondent
validate()
settle()         # sender consents and transfers amount to receiver
fund_reversal()  # receiver returns funds to the contract vault
reverse()        # reversal authority releases the funded amount to sender

Key Design Points

Covered reference — set_covered_ref() links this interbank transfer to the underlying customer payment it covers. is_covered() returns true when set, enabling audit correlation.

Correspondent routing — set_correspondent() records the routing institution for nostro/vostro reconciliation. The correspondent address is stored but does not participate in the on-chain transfer.

Validate vs settle — Separation between validate() and settle() allows for an explicit nostro-position / regulatory check step before committing funds.

FXSettlement

FX trade execution from an attested external quote. Price discovery happens entirely outside the contract; the configured quote source submits accept_quote() as a signed transaction and includes an Ed25519 QuoteLock signature over the current draft terms.

Canonical source: `src/stdlib/fx_settlement.trea`

State Machine

Drafted
  │
  │ accept_quote(quote_id, quote_lock_id, institution, signature, expires_at)
  │   [authorized quote source + valid QuoteLock]
  ▼
QuoteAccepted
  │
  │ lock_sell_position() [seller] + lock_buy_position() [buyer, while quote valid]
  ▼
PositionsLocked
  │
  │ fix(fixing_ref)    [admin]
  ▼
Fixed
  │
  │ settle()           [admin, after value_date]
  ▼
Settled ──── fund_sell_reversal() + fund_buy_reversal() ──── reverse() [reversal_authority] ──→ Reversed

Drafted | QuoteAccepted | PositionsLocked ──── cancel() [admin] ──→ Cancelled

Lifecycle

initialize(admin, contract_vault, reversal_authority, authorized_quote_source, authorized_quote_public_key)
draft(sell_party, buy_party, sell_token, buy_token, sell_amount, buy_amount, value_date)
accept_quote(quote_id, quote_lock_id, institution, signature, expires_at)
lock_sell_position()  # seller consents to lock the sell leg
lock_buy_position()   # buyer consents to lock the buy leg
fix(fixing_reference)
settle()   # transfers sell_amount from sell_party to buy_party
           # transfers buy_amount  from buy_party  to sell_party

Key Design Points

TREA is not a price engine — draft() takes explicit sell_amount and buy_amount. The ratio encodes the agreed rate. TREA validates execution eligibility; it never queries a rate feed.

Quote source is authenticated — only a transaction signed by the immutable authorized_quote_source configured at construction can execute accept_quote(). The admin cannot assert a source address on its behalf.

Quote terms are signed — accept_quote() verifies fx.verify_quote_lock(authorized_quote_public_key, signature, quote_lock_id, institution, sell_token, buy_token, sell_amount, buy_amount, expires_at). A signature over different assets, amounts, institution, lock id, or expiry is rejected.

Quote expiry enforced — Both lock operations reject if block_timestamp >= quote_expires_at. A cancelled or expired quote cannot proceed to fixing.

Fixing is distinct from settlement — fix() records the agreed fixing reference before value date. settle() executes the exchange on or after value date. These are separate steps to support T+2 and similar settlement conventions.

Atomic exchange — settle() calls ctx.transfer for both legs in the same transaction. There is no partial settlement.

GuaranteeLifecycle

Full lifecycle management for a bank guarantee or standby letter of credit. Collateral is locked on issuance and released only on honor, expiry, release, or cancellation.

Canonical source: `src/stdlib/guarantee_lifecycle.trea`

State Machine

Drafted
  │
  │ issue()       [issuer] — locks collateral
  ▼
Issued
  │
  │ advise(bank)  [admin]
  ▼
Advised
  │
  │ accept()      [beneficiary or admin]
  ▼
Accepted
  │
  │ activate()    [admin]
  ▼
Active ──── amend() [admin] ──→ Active (amendment_count++)
  │  │
  │  │ claim()    [beneficiary or admin]
  │  ▼
  │ Claimed
  │   │
  │   │ honor()          ──→ Honored ──── fund_reversal() [beneficiary] ──── reverse() ──→ Reversed
  │   │ reject_claim()   ──→ Active
  │
  │ expire()      [admin, after expiry_date] ──→ Expired
  │ release()     [admin, mutual agreement]  ──→ Released

Issued | Advised | Accepted ──── cancel() [admin] ──→ Cancelled

Lifecycle

initialize(admin, reversal_authority)
draft(issuer, beneficiary, applicant, token, collateral_amount, guarantee_amount, ref, expiry)
issue()          # locks collateral_amount from issuer into contract
advise(bank)     # optional: sets advising bank
accept()         # beneficiary confirms terms
activate()       # guarantee is now live and claimable
amend()          # records amendment (amendment_count++)
claim()          # beneficiary files a claim
honor()          # releases collateral to beneficiary

Key Design Points

Collateral is locked at issuance — issue() calls ctx.transfer from the issuer to the contract address and credits Balance[GUARANTEE_COLLATERAL]. Funds are held in escrow until honor, expiry, release, or cancellation.

Twelve states — The full lifecycle covers Drafted → Issued → Advised → Accepted → Active → Claimed → Honored plus Expired, Cancelled, Released, Reversed, and back-to-Active via reject_claim(). Each state transition is guarded.

Claim rejection returns to Active — A rejected sinistro returns the guarantee to Active, allowing further claims within the validity window. Expiry date is re-checked on each claim.

Amendment does not change state — amend() increments amendment_count without moving the state machine. Amendment details (new expiry, new amount) are applied via separate admin calls before the amend() acknowledgement is recorded.

Reversal authority — reverse() after Honored requires a dedicated authority and can release only funds the beneficiary first returned to the contract vault.