Off-Chain Settlement

Overview

Off-chain settlement legs in Polymesh enable the representation and verification of asset transfers that occur outside the blockchain. This can include traditional financial transactions like bank transfers, physical asset deliveries, transfers on other blockchain networks, or cross-chain settlement processes. This mechanism is essential for integrating both traditional financial infrastructure and other digital systems with Polymesh's on-chain settlement process.

Each off-chain leg requires verification through a receipt signed by an authorized venue signer, providing cryptographic proof that the external transfer has occurred.

Common Use Cases

Off-chain settlement legs and receipts enable various integration scenarios:

• Traditional Banking: Coordinating bank wire transfers or other fiat currency payments
• Physical Settlement: Managing delivery of physical assets, securities certificates, or commodities
• Payment Systems: Integration with traditional payment networks or financial messaging systems
• Cross-Chain Settlement: Coordinating settlements across multiple blockchain networks where assets on different chains are exchanged
• Cross-Chain Bridges: Facilitating asset transfers or wrapped token minting/burning between networks
• External Trading Platforms: Integrating with existing trading or settlement systems

Off-Chain Legs

An off-chain leg represents any transfer or payment that happens outside of Polymesh. Common examples include:

• Bank wire transfers or ACH payments
• Cash payments or deposits
• Physical asset or certificate deliveries
• Credit card or payment processor transactions
• Cross-chain settlements and token transfers
• Bridge protocol operations

When creating a settlement instruction that includes off-chain legs, each leg must specify:

• The venue that will validate the transfer
• The parties involved (sender and receiver)
• The asset and amount being transferred
• Any additional metadata about the transfer

note

Settlement instructions containing off-chain legs must be associated with a specific venue - they cannot use the default global venue. This ensures proper authorization and receipt validation.

Receipt Signers

Receipt signers are keys authorized by a venue owner to validate off-chain transfers by signing receipts. They serve several key functions:

• Transfer Validation: Verifying that off-chain transfers have occurred
• Receipt Generation: Creating signed proofs of transfer completion
• Settlement Integration: Bridging external systems with on-chain settlement

Managing Receipt Signers

Venue owners can manage receipt signers using:

• settlement::set_venue_signers: Add or remove authorized receipt signers for a venue
• A signing key does not need to be associated with a Polymesh identity however the cryptographic proof generated by the signer must be submitted by a key with a valid Polymesh Identity.
• Multiple signers can be authorized for a single venue

Technical Details

Receipt Requirements

For an off-chain leg to be considered complete:

• The receipt must be signed by a currently authorized signer for the venue
• The signature must be cryptographically valid
• The receipt must correctly reference the instruction and leg IDs
• The receipt cannot be withdrawn once submitted

note

If a venue's authorized signers are changed, previously submitted receipts remain valid as long as they were signed by an authorized signer at the time of submission.

Receipt Generation Process

When generating an off-chain receipt, the following information must be encoded and signed:

1. Required Receipt Data:

   • The unique receipt ID (UID)
   • The instruction ID
   • The leg ID within the instruction
   • The sender's identity (DID)
   • The receiver's identity (DID)
   • The asset ticker symbol/identifier
   • The transfer amount

2. Signature Generation:

   • The data elements are concatenated in a deterministic order
   • Each element is hex-encoded
   • The concatenated hex string forms the payload to be signed
   • An authorized venue signer creates a cryptographic signature of this payload
   • The signature can be generated using supported key types (SR25519, ED25519, ECDSA)

3. Receipt Assembly:

   • The final receipt combines:
     • The receipt UID
     • The leg ID
     • The signer's information
     • The generated signature
     • Optional metadata about the transfer

note

The exact data encoding and signature generation process must follow the chain's requirements to ensure the receipt is valid when submitted. Tools such as the Polymesh SDK provide helper functions to generate valid receipts.

Receipt Process

The off-chain settlement process follows these steps:

1. Instruction Creation: A settlement instruction is created with one or more off-chain legs

2. Off-Chain Transfer: The actual transfer occurs in the external system

3. Receipt Generation: An authorized venue signer creates a receipt as detailed above.

note

Each receipt requires a unique ID (UID) that is tracked via the settlement::ReceiptsUsed storage. This ensures receipts cannot be reused across different legs or instructions.

4. Receipt Submission and Affirmations:

   • Any party can submit the signed receipt using settlement::affirm_with_receipts
   • If the receipt submitter is also a party to other legs they can simultaneously affirm those legs by using settlement::affirm_with_receipts_with_count
   • The receipt's signature and UID are verified:
     • Signature must be from a currently authorized signer for the venue
     • UID must not have been used in any other receipt (tracked via settlement::ReceiptsUsed storage)
   • The receipt cannot be modified once submitted
   • Affirmations for other legs in the instruction can occur independently
   • Parties can provide their affirmations either before or after the receipt is submitted

5. Settlement Completion: The instruction can settle once both conditions are met:

   • All required receipts for off-chain legs are submitted
   • All required affirmations from instruction parties are in place

info

Receipts can be submitted by anyone with a valid signed receipt - not just the venue owner or signers. This allows for flexible integration with external systems while maintaining security through cryptographic signatures. The order of receipt submission and leg affirmations does not matter - parties can affirm their legs before or after receipts are submitted.

info

The combination of venue signers, cryptographic receipts, and on-chain verification creates a secure and flexible system for integrating external transfers with Polymesh's settlement process.