Trade booking

A set of rows that one service owns is written in one unit_of_work: one connection, one transaction, one commit. A set that several services own is never one transaction. The sequence between the owners is the consistency mechanism. See the bundle catalogue, the database per service pattern and the rule that writes go through the repositories.

Trading owns every table of a trade. The catalogue names the two sets as bundles B7 (the trade and its parts) and B8 (the trade's instrument and legs). The booking operation writes both in one unit of work.

The trade and the security are two units of work. The security is shared by many trades and has its own life, so it cannot belong to one trade's transaction. A security with no trade is a valid state. A trade with no security is not, and the database refuses it. The order is therefore fixed: the security first, the trade second.

No state in this table is half-written. For that reason the service has no repair step, and a caller has no check for a half-booked trade. A caller that finds its trade id booked treats the trade as present.

A read made with the unit of work's context runs on its transaction and does not end it, so the booking's reads see its own writes. See A repository works inside an open transaction and never holds credentials.

A refusal by the database rolls the whole unit back. The service reports the database's own words. It does not map them to a second set of codes.

The ORE import writes refdata rows and trading rows. It is a workflow with one step for each owner. See workflows, failure, compensation and retry and package transport. Each trade of the import is atomic. The import as a whole is not. A user may roll an import back. That rollback is a deliberate act on whole trades, and it is not the repair of a half-booked trade. A sandbox holds an import that a person wants to examine before it goes live.

A bond issue is the security. A bond trade is a position in it. The trade holds a reference to the security and its own size, date, counterparty and book. The security holds the terms that every holder shares: issuer, issue date, maturity, currency, coupon and schedule.

• Two aggregates. The bond issue and its children are one aggregate. The bond instrument is part of the trade. The instrument names the issue with issue_id and states the trade's notional.
• The issue has legs. The legs, amounts, rates, schedules and dates sit on the issue's leg, not on the trade. Call dates and conversion targets sit on the issue. A swap differs: its legs belong to the trade.
• One table for ten trade types. Bond, ForwardBond, BondFuture, BondOption, BondRepo, BondTRS, BondPosition, CallableBond, ConvertibleBond and Ascot all route to the bond instrument table, and each names an issue.
• Security operation. One operation creates the issue with its children in one unit of work. The issue is create-only. A second creation of an issue id answers already_exists when the terms are equal and content_differs when they are not. The stored issue stays as it was. An issue is therefore whole or absent, and its existence proves its completeness.
• Order. A caller creates the issue before it books a trade that names it. The database refuses a bond instrument whose issue does not exist.
• Sharing. A security belongs to the tenant. It does not belong to a book or a party. A currency belongs to the security, so every book that holds the security has that currency.
• Resolution. A caller names a security by its security identifier and sends the issue. The service compares the terms. No caller holds comparison code. A caller refuses its trade when the answer is content_differs.
• Concurrency. Two callers may create the same issue at the same time. One creation succeeds and the other answers already_exists. The second caller books its trade.

The browser app sends the request through the BFF to the trading service. The page is one form with four tabs. Each tab fills a part of the request: the Trade tab fills the anchor and the booking, the Instrument tab fills the batch, the Identifiers tab fills identifiers and classification, and the Review tab shows the request before it is sent. The person chooses live or draft. The two choices differ in the activity type only. The person gets the refusal in the form and keeps the input. The web component owns the transport. The booking journey owns the steps.

The REST gateway ores.http terminates HTTP, authenticates the caller and forwards the request to the owning service over NATS. The booking operations become routes in the same way as the refdata and IAM operations. The route takes the request body unchanged. The gateway adds no booking logic. An outside system uses the trade id as its idempotency key, so a retry after a timeout is safe.

The ORE component reads the XML and plans the import. The plan lists the trades, the securities and the references each needs. The execute step runs in this order:

1. Create the missing refdata rows through refdata's operations.
2. Create each missing security through the security operation.
3. Book each trade through the booking operation.

The import turns an ORE trade into the request. It maps the ORE trade id to an identifier under the ORE scheme and the envelope to classification rows. It holds no code that writes a part of a trade. It states the origin ore_import and the import id as the origin reference. Its rollback closes whole bookings, and it finds them by the origin reference. The result states how many trades it booked and how many it refused. See the import journey and the export journey. The export reads back what the import wrote.

The synthetic component generates trades and nothing else. A planner draws a pool of securities and a set of trades from a config. Every trade id is derived from the config, so the plan is the same on every run. The component turns each planned security into a security request and each planned trade into a booking request. It sends them through the client that every caller uses.

Synthetic holds no booking logic. It does not decide the order of writes. It does not detect a half-booked trade, because none exists. A trade is present when its trade id is booked, so a second run books nothing and moves no version. The entry channel is stp. The origin is synthetic and the origin reference is the config id. A report that must exclude generated trades filters on the origin. The service treats the origin like any other data.

Synthetic generation covers every asset class. A generation config names one asset class, and the asset class decides the trade types and the instrument terms that the plan draws. The generator is extensible: a new asset class adds a planner and changes nothing else.

• One planner for each asset class. The planner reads the config and draws the plan. The plan holds the securities, if the asset class has any, and the trades. A planner is a pure function of the config and of a snapshot of the references in the config's scope. A shared step reads the snapshot. The planner does not call the network and does not write.
• One output. Every planner produces the same booking requests and the same security requests that the other callers send. A planner has no private request and no private writer.
• One writer. A single writer takes a plan and sends it through the shared client. It holds no knowledge of any asset class. The booking service already accepts every instrument kind through the typed batch.
• Deterministic. Each planner derives every id from the config. A second run books nothing.
• No change to booking. A new asset class touches no service code, no booking operation and no other planner. The conformance rules apply to every planner without exception.

The shared parts are the writer, the plan type and the id derivation. The parts that differ are the draw from the config and the mapping from a drawn trade to a typed instrument batch. A model can generate the mapping when the instrument writer for every kind is generated.

1. Book each leg as a draft. A leg is an ordinary trade. The caller books it with the booking operation and the activity draft_capture. The leg is atomic, as every trade is. The caller may book the legs one at a time or in parallel, and a retry of a leg answers already_exists. A draft contributes to no risk and no P&L, so a half-built structure affects no number.
2. Complete the structure. The caller sends one request that names the structure and lists its leg trade ids and their roles. It states the leg count. The request holds ids only, so its size does not depend on the size of the legs.
3. Go live in one unit of work. The service checks that every leg exists, that every leg is still a draft held for this structure, and that the count and the roles agree. It then writes the structure, the members and the links. For each leg it writes the next state with the activity execution. All of this commits once. Either every leg is live and the structure exists, or no leg has changed.

The unit of work in step 3 writes small rows, and the instrument rows were written in step 1. Its size still grows with the leg count. The size limit of a message and of a transaction is an open decision.

The step uses the trade lifecycle as it is. It adds no state.

• A leg enters at draft through draft_capture. That is the machine's own entry for a trade that is recorded and not yet agreed. The lifecycle names the case: an agreement that exists with details missing is a draft, told apart by its reason.
• A leg goes from draft to live through the event Execute, which is the activity execution. The state trigger takes the transition only from the state the leg starts from, so a leg that is not a draft cannot be activated.
• The legs arrive live and unauthorised, as every live trade does. The authorisation and the confirmation then follow the normal queues.
• The activity execution is confirmable and economic. A leg that goes live through it would take an external version of its own. A structure is confirmed as a whole and holds the external version, as trade structures requires. How the two fit is an open decision.
• A caller that gives up discards each draft leg. The machine allows draft to cancelled through Discard. That is a deliberate act and not a repair.

A structure is never visible half-live. Its members do not exist until step 3, and the state of its legs changes in the one transaction.

The caller finishes the structure by booking the missing legs again and sending the completion again. Draft legs that wait too long show in the draft report, with their age and their reason.

• A draft reason. The lifecycle states that a draft carries a reason that names who must unblock it. The models have no such field. Structure booking needs a reason such as structure_incomplete, so that a report separates these drafts from a trade that waits for an agreement.
• A hold on the legs. A draft has a reason code and an optional reason subject. For structure_incomplete the subject is the structure id. The completion refuses a leg whose reason is not structure_incomplete for that structure, so it can never execute a draft that a trader holds on purpose.
• The completion operation. It owns step 3. It is the only operation that writes members and links for a new structure.

• Whole or in parts. The three steps suit a strategy that confirms as one deal. A package binds nothing economic, so its legs could go live one by one and be grouped later. The rule for choosing is not set.
• The external version. The structure table has no column for the external version. The activation must either leave the external version of each leg unmoved and create the structure's version, or use an activity that is not confirmable. The choice is open.
• The composite trade. A composite trade holds its own legs. A package links separate trades. The two overlap, and a decision must say whether a composite trade becomes a package.
• The reply. The structure's internal version is read from its legs and is not stored. The completion must return it.