Skip to content

Latest commit

 

History

History
203 lines (142 loc) · 11 KB

sep-0019.md

File metadata and controls

203 lines (142 loc) · 11 KB
Raw

Preamble

SEP: 0019
Title: Bootstrapping Multisig Transaction Submission
Author: Paul Selden <[email protected]>, Nikhil Saraf <[email protected]>
Track: Standard
Status: Draft
Created: 2018-12-07
Discussion: [https://groups.google.com/forum/#!msg/stellar-dev/-erucceOKbs/ewjFSQcNBwAJ](SEP: Bootstrapping Multisig Coordination)

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:

Name Type Description
uri string A 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:

Name Type Description
id string Required. An identifier for the multisig request that is generated by the multisig service.
statusHref string Required. 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.
extras object Optional. 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:

Name Type Description
id string Required. 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:

Name Type Description
id string Required. An identifier for the multisig request that is generated by the multisig service.
status string Required. 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
uri string Required. The original SEP-0007 URI that was submitted to the service.
signers string[] Required. An array of public keys that have signed the transaction.
xdr string Required. 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/