API Documentation - Wallet Provider Go SDK

package walletprovidergosdk // import "github.com/silence-laboratories/wallet-provider-go-sdk"



Package walletprovidergosdk provides a client SDK for interacting with the

Silence Laboratories Wallet Provider Network.



Version: Use GetVersion() to retrieve the current SDK version.



This SDK simplifies the process of integrating distributed key generation (DKG)

and signing capabilities into your Go applications. It handles the complex

networking and cryptographic protocols required to communicate with the Wallet

Provider nodes.



# Overview



The SDK is designed to be easy to use while providing robust security

and performance. The main entry point is the NetworkClient, which manages

connections and executes protocols.



# Features



  - Distributed Key Generation (DKG): Securely generate keys distributed across

    multiple parties.

  - Distributed Signing: Sign transactions or messages without ever

    reconstructing the full private key.

  - Quorum Change: Handle changes dynamically the set of participants by adding

    or removing nodes.



# Getting Started



To use the SDK, first create a NetworkClientConfig with your API key and the

list of network nodes. Then, instantiate a NetworkClient using NewNetworkClient.



    // 1. Setup client

    config := &walletprovidergosdk.NetworkClientConfig{

        APIKey: "your-api-key",

        NetworkNodes: []networkclient.NetworkNode{

            {

                Endpoint: url.URL{

                    Scheme: "wss",

                    Host:   "node1.example.com",

                },

                Attestation: types.NoneAttest,

            },

            {

                Endpoint: url.URL{

                    Scheme: "wss",

                    Host:   "node2.example.com",

                },

                Attestation: types.NoneAttest,

            },

        },

    }



    client, err := walletprovidergosdk.NewNetworkClient(config)



    // 2. Prepare Keygen Options

    opts := []wp_requests.KeygenOpts{

        {

            T:       2,

            N:       2,

            SignAlg: types.ED25519,

        },

    }



    // 3. Create Request Config

    reqCfg := &walletprovidergosdk.RequestConfig{

        // Set necessary config fields

    }



    // 4. Execute Keygen

    result, err := client.Keygen(reqCfg, opts)



# Configuration



  - NetworkClientConfig: Configuration for the network client, including API key

    and network nodes.

  - RequestConfig: Configuration for individual requests, including timeouts and

    protocol versions.

  - github.com/silence-laboratories/wallet-provider-go-sdk/networkclient/wp_requests.KeygenOpts:

    Parameters for distributed key generation, including threshold, number of

    shares, metadata, and signature algorithm.



For more detailed examples, see the examples directory or the example tests in

this package.



VARIABLES



var (

    // Version is set by build flags or defaults to git information

    Version = "development"

    // BuildTime is set by build flags

    BuildTime = "unknown"

)

    Version information for the SDK





FUNCTIONS



func GetBuildTime() string

    GetBuildTime returns the build time of the SDK



func GetVersion() string

    GetVersion returns the current version of the SDK. It first checks if a

    version was set at build time, otherwise it attempts to get version from git

    tags or build info.





TYPES



type ApiVersion string



const (

    // v1 API requires challenge-response exchange.

    ApiV1 ApiVersion = "v1"

    // v2 API works without challenge-response exchange.

    ApiV2 ApiVersion = "v2"

)

func (av ApiVersion) String() string



type ChallengeResponseExchanger interface {

    Next() (string, error) // Returns (message, error)

    Send(msg string) error

    RequestUserSignatures(finalChallenge string) (string, error) // Returns user signatures

}

    ChallengeResponseExchanger is required for ApiV1. It abstracts a

    bidirectional message transport used to exchange challenges from the

    network with the user during challenge-response flows. Implementations

    are responsible for sending challenges to the user and collecting their

    signatures over the challenge.



type NetworkClient struct {

    // Has unexported fields.

}

    NetworkClient is responsible for connecting to the network nodes and

    exchanging messages with them. It exposes methods to run network functions

    such as keygen, signgen, etc.



func NewNetworkClient(config *NetworkClientConfig) (*NetworkClient, error)

    NewNetworkClient creates a new NetworkClient instance.



    - `config`: configuration options for the network client.



func (nc *NetworkClient) Keygen(

    cfg *RequestConfig,

    keygenOpts []wp_requests.KeygenOpts,

) ([]wp_responses.KeyshareIdentifier, error)

    Keygen executes distributed key generation based on the provided options.



    - `cfg`: configuration options of API routes: version, request_id...

    - `keygenOpts`: options for keygen operation.



    Returns:



    - `[]wp_responses.KeyshareIdentifier`: the result of keygen operation



func (nc *NetworkClient) QuorumChange(

    cfg *RequestConfig,

    quorumChangeRequest *wp_requests.QuorumChangeRequest,

) (*wp_responses.KeyshareIdentifier, error)

    QuorumChange executes quorum change protocol based on the provided options.



    - `cfg`: configuration options of API routes: version, request_id...

    - `quorumChangeRequest`: options for quorum change operation.



    Returns:



    - `*wp_responses.KeyshareIdentifier`: the result of quorum change operation



func (nc *NetworkClient) Signgen(

    cfg *RequestConfig,

    signOpts *wp_requests.SignOpts,

) ([]wp_responses.SigngenResponse, error)

    Signgen executes signing based on the provided options.



    - `cfg`: configuration options of API routes: version, request_id...

    - `signOpts`: options for sign operation.



    Returns:



    - `[]wp_responses.SigngenResponse`: the result of signgen operation



type NetworkClientConfig struct {

    // APIKey is the API key used for authentication with the network nodes.

    APIKey string

    // NetworkNodes is the list of network nodes to connect to.

    NetworkNodes []networkclient.NetworkNode

    // SetupSK is the setup signing key used for authentication with the network nodes.

    SetupSK *setup_sk.WpSigningKey

}

    NetworkClientConfig holds the required configuration for the NetworkClient

    construction.



type NetworkClientWithChalResp struct {

    // Has unexported fields.

}

    NetworkClientWithChalResp is responsible for connecting to the network nodes

    and exchanging messages with them using the challenge-response protocol

    ApiV1. It exposes methods to run network functions such as keygen, signgen,

    adding ephemeral keys, and revoking ephemeral keys.



func NewNetworkClientWithChalResp(config *NetworkClientConfig) (*NetworkClientWithChalResp, error)

    NewNetworkClientWithChalResp creates a new NetworkClientWithChalResp

    instance.



    - `config`: configuration options for the network client.



func (nc *NetworkClientWithChalResp) AddEphKey(

    cfg *RequestConfig,

    addEphKeyReq *wp_requests.AddEphKeyRequest,

    chalRespExchanger ChallengeResponseExchanger,

) ([]wp_responses.AddEphKeyResponse, error)

    AddEphKey handles adding an ephemeral key using the ApiV1



    - `cfg`: configuration options of API routes: version, request_id...

    - `addEphKeyReq`: request payload for adding an ephemeral key.

    - `chalRespExchanger`: transport to exchange messages with the user for

    collecting signatures.



    Returns:



    - `[]wp_responses.AddEphKeyResponse`: the result of the add ephemeral key

    operation returned by the network.



func (nc *NetworkClientWithChalResp) Keygen(

    cfg *RequestConfig,

    keygenOpts []wp_requests.KeygenOpts,

    chalRespExchanger ChallengeResponseExchanger,

) ([]wp_responses.KeyshareIdentifier, error)

    Keygen executes distributed key generation based on the provided options

    using ApiV1.



    - `cfg`: configuration options of API routes: version, request_id...

    - `keygenOpts`: options for keygen operation. - `chalRespExchanger`:

    transport to exchange messages with the user for collecting signatures.



    Returns:



    - `[]wp_responses.KeyshareIdentifier`: the result of keygen operation



func (nc *NetworkClientWithChalResp) RevokeEphKey(

    cfg *RequestConfig,

    revokeEphKeyReq *wp_requests.RevokeEphKeyRequest,

    chalRespExchanger ChallengeResponseExchanger,

) (string, error)

    RevokeEphKey handles revoking an ephemeral key using the ApiV1



    - `cfg`: configuration options of API routes: version, request_id...

    - `revokeEphKeyReq`: request payload for revoking an ephemeral key.

    - `chalRespExchanger`: transport to exchange messages with the user for

    collecting signatures.



    Returns:



    - `string`: the result of the revoke ephemeral key operation returned by the

    network ("success" or error messages).



func (nc *NetworkClientWithChalResp) Signgen(

    cfg *RequestConfig,

    signOpts *wp_requests.SignOpts,

    chalRespExchanger ChallengeResponseExchanger,

) ([]wp_responses.SigngenResponse, error)

    Signgen executes signing based on the provided options using the ApiV1



    - `cfg`: configuration options of API routes: version, request_id...

    - `signOpts`: options for sign operation. - `chalRespExchanger`: transport

    to exchange messages with the user for collecting signatures.



    Returns:



    - `[]wp_responses.SigngenResponse`: the result of signgen operation



type NetworkConn struct {

    // Has unexported fields.

}

    NetworkConn encapsulates a WebSocket connection to the Initiator node along

    with the API key used for authentication. It provides primitives to send

    requests and receive responses from/to the Initiator node.



type NodeEndpoint struct {

    Endpoint url.URL

    // Has unexported fields.

}



type RRLoadBalancer struct {

    // Has unexported fields.

}



type RequestConfig struct {

    // Version is the API version (current supported: "v1", "v2").

    Version ApiVersion

    // RequestID is a unique identifier for the request.

    RequestID string

}

    RequestConfig holds the configuration for a request to the wallet provider

    API.



func NewRequestConfig(version ApiVersion, requestID string) *RequestConfig



type SignRequestBuilder struct {

    // Has unexported fields.

}

    SignRequestBuilder constructs the canonicalized JSON request payload for

    DSG. The value returned by Build() should be assigned to SignOpts.Message.



func NewSignRequestBuilder() *SignRequestBuilder

    NewSignRequestBuilder creates a new SignRequestBuilder.



func (b *SignRequestBuilder) Build() (string, error)

    Build builds and returns the Map as canonicalized JSON.

    Returns the canonicalized JSON of Map.



func (b *SignRequestBuilder) SetRequest(transactionID string, message string, requestType SignRequestType) *SignRequestBuilder

    SetRequest sets the transaction ID, message, and request type for the sign

    request. Ensures that each transaction ID is only set once.



    - transactionID: The transaction ID.



    - message: The message to be signed.



    - requestType: The type of the sign request. See SignRequestType.



    Returns the builder instance to allow chaining.



type SignRequestType string

    SignRequestType represents the type of signing transaction. For eddsa it is

    REQUIRED to encode the message in hex.



const (

    SignRequestTypeAccountAbstractionTx SignRequestType = "accountAbstractionTx"

    SignRequestTypeEIP712               SignRequestType = "EIP712"

    SignRequestTypeEIP191               SignRequestType = "EIP191"

    SignRequestTypeRawBytes             SignRequestType = "rawBytes"

    SignRequestTypeEDDSA                SignRequestType = "eddsa"

)

func (srt SignRequestType) String() string



type Slug string

    Slug represents the last segment of the API route.



const (

    SlugKeygen       Slug = "keygen"

    SlugSigngen      Slug = "signgen"

    SlugAddEphKey    Slug = "addEphemeralKey"

    SlugRevokeEphKey Slug = "revokeEphemeralKey"

    SlugQuorumChange Slug = "quorumChange"

)

func (s Slug) String() string

    String implements the fmt.Stringer interface for Slug.



type Transaction struct {

    SigningMessage string          `json:"signingMessage"`

    RequestType    SignRequestType `json:"requestType"`

}

    Transaction represents a single signing transaction descriptor.