Virtual Reference Numbers (VRNs)

Brokerage Accounts in Marketgrid have a VRN associated with this. This VRN is issued by the External Account Provider (e.g. JP Morgan) and use to correlate transactions to/from Carta's operating account to individual customer accounts.

VRNs

VRNs are stored in the VirtualReferenceNumber table. A VRN's states are:

  • Available when the Account FK is unset and it's Status has Normal set.
  • In use when the Account FK is unset and it's status has Normal set.
  • Suspended when the status does not have Normal set.

An account is assigned a VRN on creation, the next available VRN is picked.

When a VRN is suspended, the account is assigned the next available VRN and the old VRN has it's status changed (Normal unset) but still indicates the Account it was assigned to.

If no VRNs are available, the Account.NeedsNewVirtualReferenceNumber is true and VRNs will be assigned when added.

Monitoring VRN Usage

The transaction VirtualReferenceNumberCount will trigger a count to be amitted on kafka as VRNCountStatus.

This can be adhoc initiated by sending a VRNCount message.

On the ExternalAccountProvider, a schedule can be configured to regularly emit VRNCountStatus messages.

Adding VRNs

VRNs are bought in bulk from the ExternalAccountProvider (e.g. JP Morgan).

The Operator can import VRNs in bulk using an CSV import from the Admin UI. The CSV file can have two columns, virtualreferencenumber,account and thus also assign new VRNs directly to accounts.

This can be adhoc done by sending a NewVirtualReferenceNumber kafka message.

Internally they are added via the VirtualReferenceNumberNew message.

It will not allow duplicate VRNs nor assigning a VRN to an account that already has one.

Operators must have the Administer permission for the VirtualReferenceNumber table.

VRNs and tests

Since accounts are assigned the next available VRN on creation, tests have to create a VRN before accounts when the test relies on specific VRNs.

Tests do this either by a nq transaction.

.tx VirtualReferenceNumberNew { virtualreferencenumber: "100" }
.tx StaticUpdate Account { Id: 0, AccountCode: "FACEX", AccountName: "FaceX", Firm: "FACEX", ExternalFK: 100, ParentAccount: "Customer-Omnibus", SettlementCurrency: "USD", AccountType: "CCMX_ISSUER" }

Or a kafka message

{"headers":"sender_id=mg-test-client,id=0ebd2a47-6d5a-4b59-8833-109b50c425df,timestamp=2021-01-04T21:59:01.659000000+00:00,message_type=NewVirtualReferenceNumber","value":{"VirtualReferenceNumber":"1000"}}
{"headers":"sender_id=mg-test-client,id=75c048b9-4b1a-496f-bb16-5c8d3dc35450,timestamp=2022-10-20T12:10:17.761000000+00:00,message_type=CreateIssuer","value":{"IssuerId":1000,"IssuerCode":"FIRM-1","Name":"Firm-1","SettlementCurrencyCode":"USD","CountryCode":"USA","MetaData":{}}}

And in some cases, the datasets' account.tsv and virtualreferencenumber.tsv files are crafted to setup VRN FKs in both for the initial setup. Eg. Customer-Fees account with VRN 98 occurs regularly.

Implementation

VRN assignment is handled in te_statics and only there, since this flow also manages account activation via Status and WorkingStatus.

Suspending an account uses TE_field_update_Account to generate a StaticChange.

Likewise on EndOfImport of a CSV file, each account that needs a VRN uses TE_field_update_Account to generate a StaticChange.

Notes

The names VRN and VirtualReferenceNumber are used somewhat interchangably. The reasons are

  • Due to KDB migration, Account.VirtualReferenceNumber could not be retyped from a string to a FK, so instead Account.VRN was added.
  • VirtualReferenceNumber.VirtualReferenceNumber was picked since all schema fields must have same type if they have same name. So VirtualReferenceNumber.VRN was not ideal, and VirtualReferenceNumber.Number was too generic.

Post KDB deprecation, the Account.VirtualReferenceNumber column can be removed, and messages that emit VirtualReferenceNumber in kafka can be updated to copy the string from Account.VRN.VirtualReferenceNumber.

Columns in tests baselines and datasets will have to be updated too.

Meanwhile, Account.VirtualReferenceNumber is a string and kept maintained with the value of Account.VRN.VirtualReferenceNumber.

← Actor hierarchy
Limits Tracking →