General style guidelines are as specified in the buf style guide and are enforced with the buf cli linting tool.
# run from repository root
buf lint
2.1. Additional Style Rules
The following style rules are to be followed in addition to the basic linting rules enforced by the buf cli tool.
2.1.1 Comments
Documentation for the protobuf files are generated using this auto doc generation tool. Additional rules need to be followed when writing comments to deal with limitations of this tool.
Comments should be specified with block/multi-line comments instead of inline:
/*
Block comment for this message.
*/ <--- GOOD STYLE
message Client {
/*
Block Comment for this field.
*/ <--- GOOD STYLE
string name = 1;
// Inline comment for this field. <--- BAD STYLE
string email = 2;
}
Comments should be WITHOUT any empty lines. This is necessary also due to a limitation in the
/*
Line 1
Line 2
Line 3
*/ <--- GOOD STYLE
message Client {
/*
Line 1
Line 2
Line 3
*/ <--- GOOD STYLE
string name = 1;
/*
Line 1
Line 2
Line 3
*/ <--- BAD STYLE
string email = 2;
}
CompanyRepresentativeRole defines the capacity in which a natural person represents a legal entity. These roles are crucial for Know Your Business (KYB) and Anti-Money Laundering (AML) checks.
Name
Number
Description
COMPANY_REPRESENTATIVE_ROLE_UNSPECIFIED
0
Unknown or not specified. This is a default value to prevent accidental assignment and should not be used.
An Ultimate Beneficial Owner (UBO). A UBO is a person who ultimately owns or controls a company, often through share ownership, voting rights, or other forms of influence. The threshold for UBO status (e.g., >25% ownership) is defined by local regulations.
COMPANY_REPRESENTATIVE_ROLE_SHAREHOLDER
2
A person who owns shares in the company but may not meet the threshold to be a UBO. This role is for identifying all shareholders, while UBO is for those with significant control.
COMPANY_REPRESENTATIVE_ROLE_SOLE_PROPRIETOR
3
The sole owner and operator of an unincorporated business (a sole proprietorship). This person is legally indistinct from the business itself.
COMPANY_REPRESENTATIVE_ROLE_PARTNER
4
An individual who is a co-owner of a partnership form of business.
COMPANY_REPRESENTATIVE_ROLE_DIRECTOR
5
An individual appointed to the board who directs the company's business affairs.
COMPANY_REPRESENTATIVE_ROLE_MANAGER
6
A senior employee responsible for managing the company or a specific department. This role has operational control but not necessarily ownership.
COMPANY_REPRESENTATIVE_ROLE_AUTHORIZED_SIGNATORY
7
An individual with legal authority to sign documents and act on behalf of the company. This is often a specific power granted to a director, manager, or other officer.
COMPANY_REPRESENTATIVE_ROLE_PRIMARY_CONTACT
8
A primary contact person for communication purposes who may not have legal or managerial authority.
Holds tax residency information for a single jurisdiction. Note on Required Fields: Fields marked as 'Required' are essential for a successful compliance check, but are not mandatory for creation.
The ISO 3166-1 alpha-2 country code of the tax jurisdiction. This is the two-letter country code (e.g., "ZA" for South Africa, "NL" for the Netherlands). The value should be in uppercase. See https://www.iso.org/iso-3166-country-codes.html for a full list. Required for verification.
Address is a physical postal address. It is designed to be flexible enough to accommodate various international address formats. Validation rules given are a guideline. A conclusive set of validation rules for an address can be found with the service/type using this entity.
The unstructured lines of the address. This typically includes the street name, house number, apartment or suite number, and building name. It is recommended to have the most specific details (e.g., apartment number) in the first lines and the more general ones (e.g., street address) in the subsequent lines. Example: address_lines: 456 Oak Avenue, Apartment 3B, 123 Main Street. Required
The ISO 3166-1 alpha-2 country code. This is the two-letter country code (e.g. "ZA" for South Africa, "NL" for the Netherlands). The value should be in uppercase. See https://www.iso.org/iso-3166-country-codes.html for a full list. Required
Phone number in E.164 international format. This consists of a '+' sign followed by the country code and subscriber number. Example: "+14155552671" Must be valid if provided.
Mobile phone number in E.164 international format. This consists of a '+' sign followed by the country code and subscriber number. Example: "+14155552671" Must be valid if provided.
The domain name of the website without the protocol (http or https). Any provided protocol will be stripped by services processing this entity. Example: "www.mesh.trade".
LinkedIn profile ID. This is the unique identifier found in the profile URL. Example for an individual: "in/john-doe-12345678" Example for a company: "company/mesh-trade"
NaturalPerson is the identity of an individual person. It contains the core, verifiable components of an individual's identity. which are verified against their passport, utility bills, government records etc. during Know Your Client (KYC) checks. Note on Required Fields: Fields marked as 'Required' are essential for a successful compliance check, but are not mandatory for creation.
The ISO 3166-1 alpha-2 country code of the client's nationality/citizenship. This is the two-letter country code (e.g., "ZA" for South Africa, "NL" for the Netherlands). The value should be in uppercase. See https://www.iso.org/iso-3166-country-codes.html for a full list. Required for verification.
An identification number for the client, as found on the provided document. The format is dependent on the identification_document_type. Required for verification.
The type of identification document provided to prove the correctness of the given identification_number (e.g., Passport, Driver's License). Required for verification.
The client's primary physical residential address. If postal_address is not provided, this address will also be used for postal mail. Required for verification.
The origins of the client's total net worth or assets (e.g., inheritance, investments). This is distinct from the source of income. Required for verification.
The client's tax residency information, required for CRS/FATCA reporting. A client can be a tax resident in multiple jurisdictions. Required for verification.
CompanyRepresentative models an individual acting in an official capacity for a legal entity. This person is typically subject to KYC verification as part of the overall KYB process for the legal entity they represent. Note on Field Requirements: Fields marked as 'Required for verification' are essential for a successful compliance check, but are not mandatory for creation.
Details of the natural person that is the company representative. This contains the core personal identity information (name, residential address, ID document, personal contact details, etc.) required for their individual KYC check. Required for verification.
For UBOs and Shareholders, this specifies the percentage of ownership or voting rights. Should be a value between 0.0 and 100.0. Required by business logic if the role is ULTIMATE_BENEFICIAL_OWNER or SHAREHOLDER. Optional for verification.
Defines a Fund as a legal entity. It contains the core, verifiable components of a fund's identity required for Know Your Fund (KYF) compliance checks. Fields essential for verification are noted but are not strictly mandatory for creating the record.
The unique registration or identification number assigned by a regulatory body or authority. Examples: SEC CIK number, LEI (Legal Entity Identifier). Required for verification.
The ISO 3166-1 alpha-2 country code where the fund is domiciled (e.g., "KY" for Cayman Islands, "LU" for Luxembourg). The value must be the uppercase, two-letter code. See: https://www.iso.org/iso-3166-country-codes.html Required for verification.
IndustryClassification holds the detailed industry classification for a business entity using the GICS (Global Industry Classification Standard) hierarchy. GICS is a four-tiered, hierarchical industry classification system. Capturing all four levels provides a complete and precise profile for risk assessment.
Defines a Trust as a legal entity. It contains the core, verifiable components of a trust's identity required for Know Your Trust (KYT) compliance checks. Fields essential for verification are noted but are not strictly mandatory for creating the record.
The unique registration or identification number assigned by a regulatory body or authority. Examples: SEC CIK number, LEI (Legal Entity Identifier). Required for verification.
The ISO 3166-1 alpha-2 country code where the trust is domiciled (e.g., "KY" for Cayman Islands, "LU" for Luxembourg). The value must be the uppercase, two-letter code. See: https://www.iso.org/iso-3166-country-codes.html Required for verification.
Defines a legal company entity. It contains the core, verifiable components of a company's identity required for Know Your Business (KYB) compliance checks. Fields essential for verification are noted but are not strictly mandatory for creating the record.
The unique number assigned by the relevant companies registry upon incorporation. Examples: UK Companies House number, NL KVK-nummer, US EIN. Required for verification.
The ISO 3166-1 alpha-2 country code where the company was incorporated (e.g., "ZA", "NL"). The value must be the uppercase, two-letter code. See: https://www.iso.org/iso-3166-country-codes.html Required for verification.
The official, legal address of the entity as recorded with the incorporation registry. This is the primary address used for verification. Required for verification.
A list of individuals empowered to act on behalf of the company (e.g., Directors, CEO). This field defines who has operational control and representation rights. Required for verification.
A list of all other legal persons (companies, trusts, etc.) in the ownership structure. This is used to perform recursive KYB checks and map the full ownership hierarchy. IMPORTANT: Only add legal persons here if they are NOT already clients on the Mesh platform. Required for verification if the ownership structure includes off-platform entities.
The ticker symbol for the company on the specified stock exchange (e.g., "GOOGL").
ConnectedLegalPerson
ConnectedLegalPerson is a legal person and how they are connected to the company.
Note on Field Requirements: Fields marked as 'Required for verification' are essential for a successful compliance check, but are not mandatory for creation.
The percentage of direct or indirect ownership this person holds. e.g. a value of 25.5 represents 25.5% ownership. Required for verification (if the connection_types includes LEGAL_PERSON_CONNECTION_TYPE_SHAREHOLDER or similar ownership role)
The percentage of voting rights this person holds, which can differ from ownership. e.g. a value of 25.5 represents 25.5% ownership. Optional for verification.
A plain text description of the relationship. Optional for verification.
LegalPersonConnectionType
LegalPersonConnectionType describes how a legal person is connected to a business, which is essential for understanding corporate ownership and control structures in KYB.
Name
Number
Description
LEGAL_PERSON_CONNECTION_TYPE_UNSPECIFIED
0
Unknown or not specified. This is a default value to prevent accidental assignment and should not be used.
LEGAL_PERSON_CONNECTION_TYPE_SHAREHOLDER
1
The legal person is a direct shareholder in the company, but may not have a controlling stake. This is a general ownership connection.
LEGAL_PERSON_CONNECTION_TYPE_PARENT_COMPANY
2
The legal person has a controlling ownership stake in the company, making the company its subsidiary.
LEGAL_PERSON_CONNECTION_TYPE_CORPORATE_DIRECTOR
3
The legal person (often a trust or specialized firm) acts as a director on the board of the company. This represents a connection of control.
LEGAL_PERSON_CONNECTION_TYPE_TRUST
4
The legal person is a trust that holds shares or has a controlling interest in the company on behalf of its beneficiaries.
LEGAL_PERSON_CONNECTION_TYPE_GENERAL_PARTNER
5
The legal person is a general partner in a partnership structure (e.g., LP/LLP), typically implying management control and unlimited liability.
LEGAL_PERSON_CONNECTION_TYPE_GUARANTOR
6
The legal person guarantees the financial obligations or performance of the company, indicating a significant financial connection.
VerificationStatus defines the possible states of a KYC/KYB verification process.
Name
Number
Description
VERIFICATION_STATUS_UNSPECIFIED
0
Unknown or not specified. This is a default value to prevent accidental assignment and should not be used.
VERIFICATION_STATUS_NOT_STARTED
1
No verification has been initiated yet, or no information has been submitted. This is the initial state for a new client.
VERIFICATION_STATUS_PENDING
2
The client has submitted their information, and it is pending review. The client should wait for the review to be completed.
VERIFICATION_STATUS_VERIFIED
3
The client's information has been successfully reviewed and verified.
VERIFICATION_STATUS_FAILED
4
The verification has failed. This could be due to invalid documents, mismatched information, or other compliance reasons. The client may need to resubmit information.
Client represents an authorized legal entity, which can be either an individual (KYC) or a business (KYB). It serves as the central resource for all compliance information and verification status related to a single party.
The unique, immutable, and canonical name of the client resource in the format clients/{client_id}. The {client_id} is a system-generated unique identifier (e.g., UUID) that will never change. This name field will never change and should be used as the permanent primary key for this resource in all systems. System set on creation.
The resource name of the group that owns this client in the format groups/{group_id}. This field establishes the ownership link and can be updated if the client's ownership changes, without affecting the client's stable name. The executing user needs to have permission to perform client.Create in this group. Required on creation.
The resource name of the client (acting as a verifier) that last set the verification_status. This provides an audit trail for status changes. System set when verification_status changes.
The timestamp when the verification_status was last set to a conclusive state, specifically VERIFICATION_STATUS_VERIFIED. System set when verification_status changes to VERIFICATION_STATUS_VERIFIED.
The timestamp indicating when the client's next periodic compliance review is due. This field drives re-verification workflows. Optional for Verification.
NaturalPersonConnectionType describes how a natural person is connected to a business or to another key individual (like a PEP). It covers primary roles for KYB (ownership, control) as well as secondary relationships for screening (familial, professional).
Name
Number
Description
NATURAL_PERSON_CONNECTION_TYPE_UNSPECIFIED
0
Unknown or not specified. This is a a default value to prevent accidental assignment and should not be used.
The person is an Ultimate Beneficial Owner as defined by AML regulations (e.g., >25% ownership/voting rights). This is the most critical connection type for KYB.
NATURAL_PERSON_CONNECTION_TYPE_SHAREHOLDER
2
The person owns shares but may be below the UBO threshold.
NATURAL_PERSON_CONNECTION_TYPE_DIRECTOR
3
The person is a formal Director on the company's board.
NATURAL_PERSON_CONNECTION_TYPE_SENIOR_MANAGEMENT
4
The person holds a senior management position with significant operational control (e.g., CEO, CFO, COO).
The unique resource name of the client to be retrieved. The name serves as the primary identifier for the client resource. Format: "clients/{client_id}"
GetClientResponse
GetClientResponse contains the client resource requested.
A repeated field containing the client resource objects.
ClientService
Service manages client profiles for compliance and Know Your Customer (KYC) purposes.
The main entity managed by this service is the Client resource. A client can be a natural person, company, or trust. This service allows you to retrieve the compliance profiles for these clients.
Get retrieves a single client's compliance profile by its unique resource name.
This allows for fetching the complete compliance details of a specific client, including all associated information like identification documents, tax residencies, and company structures.
Ledger represents the various distributed and centralized systems that Mesh interacts with where value is accounted for. The term "Ledger" is used inclusively to cover both blockchain and other value-tracking systems. Note that numbering is not sequential for legacy reasons.
Name
Number
Description
LEDGER_UNSPECIFIED
0
Indicates an unknown or unspecified ledger. This default value helps prevent accidental assignment and should not be used in practice.
LEDGER_STELLAR
3
The Stellar public ledger network. See: https://stellar.org
LEDGER_BITCOIN
5
The Bitcoin public ledger network. See: https://bitcoin.org
LEDGER_LITECOIN
7
The Litecoin public ledger network. See: https://litecoin.org
LEDGER_ETHEREUM
9
The Ethereum public ledger network. See: https://ethereum.org
LEDGER_XRP
11
The XRP Ledger (formerly Ripple). See: https://xrpl.org
LEDGER_SA_STOCK_BROKERS
15
The proprietary ledger for the SA Stockbrokers platform.
LEDGER_NULL
16
A null ledger, used as a placeholder for assets that do not have an external or on-chain accounting ledger.
Token is Mesh's canonical model for uniquely and unambiguously identifying any digital asset across any supported ledger. It provides a powerful abstraction layer that resolves the complexities of multi-chain/ledger asset representation. This allows any part of the Mesh system to work with a single, universal concept of a token, regardless of the underlying ledger's specific implementation.
The commonly accepted symbol, ticker, or code for the token (e.g., "BTC", "ETH", "USDC"). It is not unique without the issuer and ledger. Required field.
Issuer is a reference to issuing entity of the token. For NATIVE assets on a ledger (e.g., ETH on Ethereum), the issuer is the ledger itself, represented by the reserved string LEDGER. For ALL other issued assets (e.g., ERC-20 tokens), this is the unique identifier of the issuing entity, such as a smart contract address on Ethereum or an issuance account public key on Stellar. Required field.
The ledger ledger on which the token exists. This field disambiguates assets that may share a code and issuer across different chains (e.g., USDC on Ethereum vs. USDC on Polygon). Required field.
A canonical structure for representing a precise quantity of a specific digital asset. An Amount is a self-describing monetary value, pairing a Universal Token Identifier (the 'what') with a high-precision Decimal value (the 'how much'). This model ensures that a quantity of an asset is never ambiguous.
Value is the magnitude of the amount, representing HOW MUCH of the specified token this value holds. CRITICAL: To prevent precision errors, this decimal value MUST be truncated to the exact number of decimal places supported by the token's native ledger.
StandardRole defines a named collection of permissions. This allows for the creation of business-level roles (e.g., "AccountReader", "AccountAdmin") that group a set of granular, string-based permissions. Roles are defined at the file level in a service's .proto file.
The list of permissions this role contains. Each string corresponds to a full gRPC method path, e.g., "meshtrade.wallet.account.v1.Service/GetAccount".