Mapping & Labelling

TLDR

Blockchains need complimentary mapping and labelling systems. Vulcan Forge provides one.

For regulated assets (especially) there are a couple of must haves when it comes to reporting and analysis:

At a minimum there must be some way to map a blockchain wallet to an owner / investor identity.

When doing an analysis of onchain trading activity, just a plain public key address says very little to anyone. More metadata about it is needed.

Offchain References

It is either impossible (or at least very inefficient) to hold onchain, all data needed to run proper bookeeping of tradeable assets definitions and movements. Those financial software solutions that integrate with blockhains and have no (or rudimentary) mechanisms to map blockchain entities to offchain systems + label them, can only have very limited support for supporting regulated assets.

At the center of the labelling system in Vulcan Forge is the concept of offchain references - a mechanism to enhance the definition of a blockchain entity by adding to it a number of offchain attributes.

Before covering these offchain attributes we need to define these 2 fields, which are paired with the offchain attributes, and link an onchain item to its offchain twin:

Identifiers

onchainId - the public key (address) of the blockchain entity

offchainId - the corresponding unique identifier of the same entity in Vulcan Forge's offchain store (i.e. a uuid v4 dabatase field for the offchain record of the entity)

Offchain Attributes

Attribute Name	Blockchain Entity Applicability	Description
alId	Financial Instrument	The Alphaledger ID for a financial instrument; a unique identifier assigned by Vulcan Forge, akin to a CUSIP, ISIN or OpenFIGI
externalOrganizationId	Anything other than a Financial Instrument	The code associated with the organization(s) created at the time a new tenant is onboarded in Vulcan Forge
accountNumber	Anything other than a Financial Instrument	An account number assigned/autogenerated by Alphaledger at the request of the tenant; typically used in conjuction with wallets

Note that one and only one of the alId, organizationExternalId or accountNumber attributes can be specified for an entity's offchain references.

Visit the Tenants page for more details on how the offchain references fit within a tenant's entities hierarchy.

Blockchain Account Type

The type is an essential piece of the labelling system.

Below is a full list that we found useful for organizing blockchain entities that Vulcan Forge can interact with. While we think the list is quite comprehensive, we expect that a few more will be added over time - especially as a result of integrations with more defi protocols.

For more background on the first set of types from this list, see Regulated Assets

Type	Description
WALLET	Wallet to hold currencies and/or assets
CURRENCIES_WALLET	Wallet to hold currencies only
ASSETS_WALLET	Wallet to hold assets only
DEFI_SETTLEMENT_WALLET	Passthrough wallet for integrations with Defi platforms. Can hold both Currencies and Assets Tokens
ASSET_TOKEN	Tokens that are assets
ASSET_POSITION	Position for an asset token
CURRENCY_TOKEN	Tokens that are funds (e.g. stablecoins)
CURRENCY_POSITION	Position for a Currency Token
AUTHORITY	Generic authority that can be used in any place an authority is required
TOKEN_MANAGEMENT_AUTHORITY	Authority attached to financial instruments
TOKEN_ACCOUNT_MANAGEMENT_AUTHORITY	Authorities to be attached to positions
NONCE_AUTHORITY	Authority to be used for updating hashes on Nonce accounts
NONCE	Nonce account that holds a hash
ADDRESS_LOOKUP_TABLE	Address that holds a list of addresses that can be looked up in transactions - helps keep transactions size smaller
FI_METADATA_ACCOUNT	Accounts that hold Financial Instruments Metadata
SYSTEM_ACCOUNT	System accounds - e.g. Sysvar account
PROGRAM	Accounts that represent programs on Solana
LOAN_ESCROW	Loan accounts that hold pledged assets
LOAN_LENDER	Accounts that act a source for financing loans
DATA_ACCOUNT	General data account
ORACLE_FEED	Feed to hold market data on an onchain oracle
ORACLE_QUEUE	Infrastructure oracle component need to feed updates (see Switchboard queues for examples)
NETWORK_MEMBERSHIP_FUNDING	Account used primarily for paying Solana network (txns and rent) fees
VULCAN_FORGE_FUNDING	Account used for paying Vulcan Forge fees

Blockchain Account Code

The mandatory code is a free form field that the VF client can use to uniquely identify a blockchain account within the context of an offchain reference. E.g. if for a particular offchain account (e.g. accountNumber: SMO2-0000001), 2 separate ASSETS_WALLETs have to be setup, one to hold equities and another one to hold bonds, then these 2 combinations would be setup:

Offchain Attribute (i.e. accountNumber)	Blockchain Account Type	Blockchain Account Code
SMO2-0000001	ASSETS_WALLET	equities
SMO2-0000001	ASSETS_WALLET	bonds

Blockchain Account Name

An optional field that can be used to provide some description / name for the blockchain entity that is being onboarded.

Blockchain Account Lookup

The schema expression of Idenfifiers, Offchain Attributes, Blockchain Account Type and Blockchain Account Code can found in the Account Lookup. A very frequently used block of fields to lookup a blockchain entity throughout the majority of the API endpoints request bodies.

The lookup can be done by either specifying the onchainId, offchainId or the combination of offchainReferences.

Note too that the offchain references and offchainId only apply to entities that are onboarded on the Vulcan Forge platorm.

Interactions with off-platform blockchain entities are possible too and the account lookup supports those by using the offPlatform flag and requiring the onchainId identifiers, for these type of lookups.

Off vs On platform accounts

Off-platform accounts are blockchain accounts that already exist onchain and are not onboarded into Vulcan Forge (i.e. they have not been created inside the Vulcan Forge offchain database).

On-platform accounts are all those accounts that exist in the Vulcan Forge offchain database.

Off-platform accounts can be still used as part of transactions (e.g. when an on platform Vulcan Forge wallet transfers out an asset to off-platform accounts). See the offPlatform flag in the Account Lookup schema.

At any point in time the System Tenant or any other tenant can onboard an off-platform account by calling the appropriate onboarding endpoint (e.g. Create Account, Create Financial Instrument, Create Address Lookup, etc) and passing the alreadyOnchain field as true in the request body.

Reasons for onboarding an off-platform account:

As part of the read layer endpoints responses, an on-platform account will have more onchain and offchain metadata details attached to it than what an off-platform account would have (i.e. just the public key address)

The account can be setup with subcribeToNetworkEvents=true and as a result, off-platform transactions (i.e. not submitted through Vulcan Forge) that involve this account will be captured by the VF ingestor and be made available for query through the Vulcan Forge apis.

Due to the high volume of transactions typically associated with program accounts, a program account can be onboarded with subcribeToNetworkEvents=true only by the System Tenant.

Uniqueness Rules

There are 2 main kinds of uniqueness rules that are enforced for each blockchain account/entity:

Offchain references uniqueness - the combination of these 4 fields has to be unique:

tenant organization associated with the Auth API Key

blockchain account type

blockchain account code

internal blockchain id

Public key (address) uniqueness - the combination of these 2 fields has to be unique:

public key address

internal blockchain id

For testing purposes, when onboarding a new entity, typically the easiest way to bypass the first uniqueness rule is to change the code.

TLDR#

Offchain References#

Identifiers#

Offchain Attributes#

Blockchain Account Type#

Blockchain Account Code#

Blockchain Account Name#

Blockchain Account Lookup#

Off vs On platform accounts#

Uniqueness Rules#