Multisignature for transfers

By default only a user key signs transactions on Stellar blockchain.

Default flow with a single signer

As an option, in order to mitigate the risk of secret forgery a transaction can also be signed by multiple participants.

This flow combines signatures from 2 sides (counterparty and DCM):

Relations between private keys and secrets

Key principles

1. counterparty decides from the very beginning, either they use multisignature or a default approach with single signature is implemented

   • counterparty generates 2 key pairs and provides public parts to DCM before start

2. 3 signatures are required to post a transaction (counterparty, DCM & Customer)

3. customer’s seed is encrypted on DCM side

4. a secret (stored by the Counterparty) is required to decrypt the customer’s seed

5. the Counterparty uses its own seed to sign a transaction

Confirm payment with multisignature

At steps 4, 5, and 9 all three signatures are added to a transaction envelope.

Confirm a payment

POST /sign

Request example

No authentication is used

{
"address":[
    "GALY4D4HZ6XMC2YI5FOWXZ3JKMEOYPWZPADPXBC7ZA232SSEEUCGAR5X"    
    ],
"transaction_xdr":"AAAAAgAAAAAOc/Ep0SpnfQ9wyROTSWSDI5dnsJpSL15kDAmaTEqyIwAAAMgAExmIAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAQAAAAC9uikHe+PC/4jPg01zIk3O7mOC0oFATGCEC3VG3Sz8BAAAAAFlVUFIAAAAAL26KQd748L/iM+DTXMiTc7uY4LSgUBMYIQLdUbdLPwEAAAAAAABhqAAAAAAAAAACgAAAAxwYXltZW50X2d1aWQAAAABAAAAJGRiNzhjNzVjLTFhNTAtMTFlZS1iZDVmLTNhNmFhNDQzNmZlZQAAAAAAAAAA"
}

The attribute address lists all the expected signers for the transfer.

The envelope from tranasction_xdr for testing purposes can be decoded manually via Stellar.Laboratory.

Decoded example:

v1
  tx
    sourceAccount: [keyTypeEd25519]
      ed25519: GAHHH4JJ2EVGO7IPODERHE2JMSBSHF3HWCNFEL26MQGATGSMJKZCGJYJ
    fee: 200
    seqNum: 5376096463749122
    cond: [precondTime]
      timeBounds
        minTime: 0
        maxTime: 0
    operations: Array[2]
      [0]
        sourceAccount: none
        body: [payment]
          paymentOp
            destination: [keyTypeEd25519]
              ed25519: GC63UKIHPPR4F74IZ6BU24ZCJXHO4Y4C2KAUATDAQQFXKRW5FT6AJKYS
            asset: [assetTypeNative]
              alphaNum4
                assetCode: UAH
                issuer: [publicKeyTypeEd25519]
                  ed25519: GC63UKIHPPR4F74IZ6BU24ZCJXHO4Y4C2KAUATDAQQFXKRW5FT6AJKYS
              amount: 0.00001 (raw: 100)
      [1]
        sourceAccount: none
        body: [manageData]
          manageDataOp
            dataName: payment_guid [hex: ZXh0ZXJuYWxfcGF5bWVudF9ndWlk]
            dataValue: db78c75c-1a50-11ee-bd5f-3a6aa4436fee [hex: ZGI3OGM3NWMtMWE1MC0xMWVlLWJkNWYtM2E2YWE0NDM2ZmVl]
    ext: [undefined]
  signatures: Array[1] Signatures checked!
    [0]
      hint: G______________________________________________MJKZC____
      signature: C26wsxgT6q/Pdelp7wEXYfZJUZxfU24yyK7nomVPRMEZ/bUELq1fzL4A7OEjSPeBzzekG+R+Oc9lteZKA0OuAQ== 

The block "manageDataOp" contains an attribute payment_guid that should be used in the method #counterparty-counterparty_guid-payments-payment_guid to obtain the transfer details.

Response example

{
"address": [
    "GALY4D4HZ6XMC2YI5FOWXZ3JKMEOYPWZPADPXBC7ZA232SSEEUCGAR5X"
    ],
"transaction_xdr": "AAAAAgAAAAAOc/Ep0SpnfQ9wyROTSWSDI5dnsJpSL15kDAmaTEqyIwAAAMgAExmIAAAAAgAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAQAAABB0ZXN0IG1hbmFnZV9kYXRhAAAAAgAAAAAAAAABAAAAAL26KQd748L/iM+DTXMiTc7uY4LSgUBMYIQLdUbdLPwEAAAAAAAAAAAAAABkAAAAAAAAAAoAAAAVZXh0ZXJuYWxfcGF5bWVudF9ndWlkAAAAAAAAAQAAACRkYjc4Yzc1Yy0xYTUwLTExZWUtYmQ1Zi0zYTZhYTQ0MzZmZWUAAAAAAAAAAUxKsiMAAABAC26wsxgT6q/Pdelp7wEXYfZJUZxfU24yyK7nomVPRMEZ/bUELq1fzL4A7OEjSPeBzzekG+R+Oc9lteZKA0OuAQ=="
}

Both attributes are obligatory in response: address indicates the address signed the envelope. At least 1 signature is required in transaction_xdr.

Stellar SDK to work with signatures:

1. Key generation
2. Sign a transaction

Expected errors

1. 400 Bad request: when envelope is malformed

   • transfer is stopped

2. 401 Unauthorized: none of addresses from the request are available for signing

   • transfer is stopped

3. 404 Not found: in case a response from GET /payments returns no results.

   • a retry will be sent later to POST /sign (up to 5 retries)

Create customer with multisignature

In order a customer digital entity has 3 signers, the flow of customer creation is amended with step 9, when a pre-configured set of public keys are attributed to a Stellar address as signers.

In terms of integration with API, creation happens as usual.

Create a customer