StellarStandards
← All standards
SEP-0019Source ↗

Bootstrapping Multisig Transaction Submission

5 min · 1,035 words

#Simple Summary

Provides a standard way for multisig accounts to designate where transactions should be submitted for coordination of additional signatures.

#Abstract

An account may designate which multisig server to use in a data entry that points to a server with a stellar.toml file. This file contains a MULTISIG_ENDPOINT field which is an API where multisig transactions should be submitted. Wallets should implement this SEP so they can support multisig accounts without requiring them to run a multisig service themselves.

#Motivation

Currently there are only a few public tools that allow for multisig accounts, and they all do it by implementing their own signature coordinator services to do so. Wallets or other services that do not implement their own backends have no real way to deal with multisig accounts, so most of them just don't at all. By allowing an account to specify where they want their multisig transactions submitted to, it enables those wallets to interop with existing multisig services without relying on vendor-specific SDKs and APIs.

Additionally, there may be use cases where users do not want their multisig transactions broadcasted to a public coordinator, but would still like to use existing wallets to submit them to a private coordinator.

#Specification

#Account Data

A multisig account adds a data entry with the key config.multisig.coordinator and the value of a hostname used to resolve the stellar.toml file of the multisig service.

Example: Key: config.multisig.coordinator Value: stellarguard.me

#Multisig Server stellar.toml

Multisig coordinators advertise the existence of their service through the stellar.toml file. The top-level parameter MULTISIG_ENDPOINT should contain a fully-qualified URL of a multisig coordination service where transactions should be submitted.

Example of stellar.toml:

MULTISIG_ENDPOINT="https://stellarguard.me/api/transactions"

#Multisig Server API Endpoints

Multisig Services must expose two REST API endpoints.

#Submit Transaction Endpoint

This is the endpoint defined in the stellar.toml under the MULTISIG_ENDPOINT key.

Request

#Request

POST MULTISIG_ENDPOINT

ContentType: application/json.

Request Body Parameters:

NameTypeDescription
uristringA SEP-0007 style tx URI for the transaction to sign.

Example:

POST https://stellarguard.me/api/transactions 

{
  "uri": "web+stellar:tx?xdr=AAAAAHFd0%2BHQV5u%2FY%2FfM3%2BVelUr1IWwSFL8CUDIAUudUdD4MAAAAZAADyI8AAAADAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAAcV3T4dBXm79j98zf5V6VSvUhbBIUvwJQMgBS51R0PgwAAAAAAAAAAACYloAAAAAAAAAAAVR0PgwAAABAEw8ODG0iixkbAHg1aJATAnZS2531PhGauuSvFDad2WxHKzIenUNbc7K5mGiSpe5jvqe19OQCbNFuBjqN11jfBw%3D%3D"
}
Response

On success, the endpoint should return a 200 HTTP status code and a JSON-encoded object.

Response fields:

NameTypeDescription
idstringRequired. An identifier for the multisig request that is generated by the multisig service.
statusHrefstringRequired. A fully qualified url where an agent can poll for updates on the status of the multisig request. This is specified in the Status Endpoint section.
extrasobjectOptional. An object that contains additional application specific response data which could be used to provide an enhanced user experience. For instance, showing a link to authorize a transaction.

Example:

{
  "id": "c585ceee-b1b9-4009-aa37-b8544346a036",
  "statusHref": "https://stellarguard.me/api/transactions/c585ceee-b1b9-4009-aa37-b8544346a036",
  "extras": {
    "isStellarGuard": true,
    "url": "https://stellarguard.me/transactions/c585ceee-b1b9-4009-aa37-b8544346a036"
  }
}

#Status Endpoint

This will be used to query for the status of a multisig transaction.

Request

GET MULTISIG_ENDPOINT>/:id

Request Path Parameters:

NameTypeDescription
idstringRequired. The id used to look up the status, which was returned in the submit transaction response.

Example:

GET https://stellarguard.me/api/transactions/c585ceee-b1b9-4009-aa37-b8544346a036
Response

On success, the endpoint should return a 200 OK HTTP status code and a JSON-encoded object.

Response fields:

NameTypeDescription
idstringRequired. An identifier for the multisig request that is generated by the multisig service.
statusstringRequired. An string indicating the status of the multisig request which can have one of the following values:- pending - The request requires more signatures- success - The transaction has been fully signed- failed - There was an error with the transaction and it could not be submitted successfully
uristringRequired. The original SEP-0007 URI that was submitted to the service.
signersstring[]Required. An array of public keys that have signed the transaction.
xdrstringRequired. The current state of the transaction XDR, including any additional signatures.

Example:

{
  "id": "c585ceee-b1b9-4009-aa37-b8544346a036",
  "status": "pending",
  "uri": "web+stellar:tx?xdr=AAAAAHFd0%2BHQV5u%2FY%2FfM3%2BVelUr1IWwSFL8CUDIAUudUdD4MAAAAZAADyI8AAAADAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAAcV3T4dBXm79j98zf5V6VSvUhbBIUvwJQMgBS51R0PgwAAAAAAAAAAACYloAAAAAAAAAAAVR0PgwAAABAEw8ODG0iixkbAHg1aJATAnZS2531PhGauuSvFDad2WxHKzIenUNbc7K5mGiSpe5jvqe19OQCbNFuBjqN11jfBw%3D%3D",
  "signers": ["GBYV3U7B2BLZXP3D67GN7ZK6SVFPKILMCIKL6ASQGIAFFZ2UOQ7AZB5V"],
  "xdr": "AAAAAHFd0+HQV5u/Y/fM3+VelUr1IWwSFL8CUDIAUudUdD4MAAAAZAADyI8AAAADAAAAAAAAAAAAAAABAAAAAAAAAAEAAAAAcV3T4dBXm79j98zf5V6VSvUhbBIUvwJQMgBS51R0PgwAAAAAAAAAAACYloAAAAAAAAAAAVR0PgwAAABAEw8ODG0iixkbAHg1aJATAnZS2531PhGauuSvFDad2WxHKzIenUNbc7K5mGiSpe5jvqe19OQCbNFuBjqN11jfBw=="
}

#CORS headers

In order to comply with browser cross-origin access policies, the service should provide wildcard CORS response HTTP header. The following HTTP header must be set for the API endpoints:

Access-Control-Allow-Origin: *

#Multisig Transaction Flow

  1. Look up the data entry with the key config.multisig.coordinator on the transaction source account. If the entry does not exist on the account, do not continue with this flow.
  2. Resolve the stellar.toml associated with the account's config.multisig.coordinator entry and return the MULTISIG_ENDPOINT field.
  3. Convert the transaction to a SEP-0007 style URI, setting any additional parameters such as callback.
  4. Before submitting the transaction, it should contain at least one valid signature.
  5. POST to the MULTISIG_ENDPOINT endpoint with the SEP-0007 tx URI in the body as the parameter uri.
  6. The service responds with a 200 HTTP status code and a JSON object specified in the Submit Transaction Endpoint Response section.

#Rationale

When implementing StellarGuard for the Stellar Account Viewer, it was rightly pointed out it should avoid vendor-specific implementation. This SEP provides an alternative approach that can be used by tools that want to support multisig accounts without implementing a multisig server for each product.

One design choice was whether to skip the stellar.toml step and add the fully qualified multisig server endpoint to the account's data field. The stellar.toml approach affords greater flexibilty for the server to change its implementations. It is much easier to update the stellar.toml than to update the data entry of every account that uses it.

#Implementations

The server implementation is currently live on https://test.stellarguard.me and https://stellarguard.me.

A library that implements this protocol has been published here: https://github.com/stellarguard/multisig-utils

A demo using that library that submits to the StellarGuard multisig endpoint: https://stellarguard.github.io/multisig-utils/demo/