Skip to main content



Settlement in Polymesh is the process by which assets are transferred between identities in a regulated and compliant fashion.

It requires all counterparties of a transaction to affirm (agree) an instruction (a set of asset transfers) before the instruction settles (completes).

Any counterparty to the instruction can unilaterally reject the instruction.

If an instruction is fully affirmed, but settlement fails (for example as a result of compliance rules) the instruction can be manually executed again at a later date by any one of the counterparties, once the failure cause has been remediated.

Once an instruction has been affirmed by a counterparty, the associated assets are locked in the counterparties account. If the instruction is subsequently rejected, these assets are unlocked and can be used in another settlement instruction.

Instructions can be settled either via:

  • on-chain movement of assets

  • an off-chain payment receipt

Payment receipts are small pieces of data signed by an authorised signatory (determined by the venue on which the instruction is settling) which allege that the corresponding assets have moved off-chain. They can only be used for instruction legs that do not correspond to on-chain tickers.


Asset Issuer

The asset issuer (or agent on their behalf) controls the set of identities that are allowed to create instructions that reference their asset. They can also choose to leave this open.

Venue Creator

Only the creator of a venue is allowed to create instructions underneath it.

The creator of a venue can cancel any pending instruction underneath it.

The venue creator controls the set of identities that are allowed to sign payment receipts for instructions underneath it.


A counterparty is relative to an instruction, and is any identity that is referenced as a payer / receiver in a leg within that instruction.

Each counterparty must authorise any instruction where they appear as a counterparty, before the instruction can settle.

Authorisation can be via an on-chain transaction, or signed data.

Once an instruction is authorised by a counterparty, their assets are locked, and the instruction will settle once all counterparties have authorised.

A counterparty can cancel a pending instruction. If any counterparty cancels, the entire instruction should be marked as cancelled (and everyone's assets unlocked).

Legs, Instructions and Venues

Instructions and Legs are always concrete - specify all details at the point of creation and are immutable.

For an instruction to be executed, all counterparties of the instruction must signal their authorisation and lock any necessary asset / provide appropriate receipts.

Only the creator of a venue can add instructions underneath it.

Authorisation can only be provided before the instructions expiry data, and after its valid_from date.

Asset issuers can restrict who can post an instruction that references their asset, or leave it unrestricted.

Once all counterparties have authorised an instruction, it is automatically executed. At that point, if the execution fails (e.g. due to compliance on the assets) then instruction is marked as failed, if it succeeds it is stamped with the time of the successful execution.

Any counterparty to an instruction can reject it, marking it as rejected immediately, or simply wait until it expires.

A counterparty's authorisation is only valid if they either lock the relevant amount of assets to the instruction to cover any of their obligations across all legs, or provide a signed receipt that the transaction has occurred off-chain.

Payment receipts which are used to authorise an instruction are specific to a given instruction, and cannot be used for other instructions.

If an instruction fails, is rejected or expires, all asset locks are removed.

If an instruction is executed, assets are transferred between counterparties for on-chain assets (i.e. excluding legs which are settled via a payment receipt that can only reference off-chain assets).

Exempt Assets

For certain types of assets, e.g. stable coins, it may not be appropriate to require all users to explicitly affirm transactions where they receive the asset (either directly or via their custodian).

In this case Polymesh allows users to "pre-approve" certain tickers meaning that explicit affirmations are no longer required. Certain tickers can also be excluded from requiring affirmation on receipt globally via the Polymesh governing council.

Affirming and Custody

If a custodian has been granted access to a users portfolio, the custodian is able to affirm any instructions that reference that portfolio on behalf of their client.

This allows control to be handed to a custodian, whilst the record of beneficial ownership remains with the owner of the assets.


Peer to Peer Transfer

Alice wants to transfer 10 ACME tokens to Bob as a gift.

She uses her “default” venue (or any venue that she has previously created) to generate an instruction, with a single leg.

If Bob has provided pre-authorisation via signed data to Alice, she can submit it alongside the transaction as Bobs authorisation, and her own authorisation is implicit (since she is creating the instruction). Alice's ACME tokens are locked until Bob authorises the instruction (or Alice cancels), assuming he has not pre-authorised.

Once the instruction has been fully authorised (which can happen upon creation if pre-authorised) it settles with Bob receiving 10 ACME tokens.

Peer to peer

Exchange Mediated Transfer

ExchangeCo matches Alice, a seller of ACME, with Bob, a buyer of ACME, and coordinates an agreed price to exchange assets - 100 ACME for 10 USDC.

ExchangeCo creates a venue, adds a single instruction, with two legs, and an expiry time of T + 1 hour.

Bob authorises the instruction, locking 10 USDC.

Alice authorises the instruction, locking 100 ACME.

The instruction is executed with Alice receiving 10 USDC and Bob receiving 100 ACME.

Asset vs. Asset

Exchange Mediated Transfer with Authorisation

ExchangeCo matches Alice, a seller of ACME, with Bob, a buyer of ACME, and coordinates an agreed price to exchange assets - 100 ACME for 10 USDC.

ExchangeCo collects a signed authorisation from Alice and Bob indicating that they agree a specific instruction.

Bob's authorisation includes a signed receipt that he has transferred funds to Alice, meaning that no additional funds are locked from Bob into the instruction, and instead his receipt signed data is marked as locked.

ExchangeCo creates a venue, with a single instruction with two legs, providing the authorisation data from Alice and Bob.

The instruction is authorised upon creation, and immediately settles, transferring 100 ACME from Alice to Bob and marking Bob's receipt as used.

Netting Process

ClearCo, with a pre-agreed netting contract with BankCo's, collects trade data from BankCo_1, BankCo_2, BankCo_3 and BankCo_4 and calculates an optimal netting strategy.

ClearCo creates a venue with an instruction containing four legs representing the netting trades between BankCo's and an expiry time of T + 24 hours.

Each BankCo individually authorises the instruction - when all BankCo's have authorised the netting settlement is automatically executed.


Security Token Offering

AcmeCo wishes to distribute 1000 ACME tokens to investors.

AcmeCo creates a Venue defining the start and end date of their issuance.

Alice provides AcmeCo with an authorisation to buy 100 ACME tokens at 10 USDC (i.e. an authorisation for an instruction with these two legs).

AcmeCo creates an instruction under their settlement passing along Alice's authorisation, along with their own. The instruction is executed with Alice receiving her ACME tokens, and AcmeCo receiving their assets.

Primary Distribution / Funding