Skip to main content

DKLS Go Library - API Reference

Quick Reference

This document provides a concise API reference for the DKLS Go library.

Package: go-wrapper/go-dkls/sessions

Types

Handle

type Handle int32

Opaque reference to Rust objects (sessions, keyshares).

Distributed Key Generation (Keygen)

DklsKeygenSetupMsgNew

func DklsKeygenSetupMsgNew(threshold int, keyID []byte, ids []byte) ([]byte, error)

Creates a setup message for distributed key generation.

Parameters:

  • threshold: Minimum parties needed for signing (t in t-of-n)
  • keyID: Unique key identifier (nil for random)
  • ids: Null-separated party IDs (e.g., []byte("p1\x00p2\x00p3"))

Returns: Setup message bytes

Example:

setupMsg, err := session.DklsKeygenSetupMsgNew(2, nil, []byte("p1\x00p2\x00p3"))

DklsKeygenSessionFromSetup

func DklsKeygenSessionFromSetup(setup []byte, id []byte) (Handle, error)

Creates a keygen session from setup message.

Parameters:

  • setup: Setup message from DklsKeygenSetupMsgNew
  • id: This party's identifier

Returns: Session handle

Example:

sessionHnd, err := session.DklsKeygenSessionFromSetup(setupMsg, []byte("p1"))

DklsKeyRefreshSessionFromSetup

func DklsKeyRefreshSessionFromSetup(setup []byte, id []byte, oldKeyshare Handle) (Handle, error)

Creates a key refresh session to update shares while preserving the public key.

Parameters:

  • setup: Setup message with same key ID as old keyshare
  • id: This party's identifier
  • oldKeyshare: Existing keyshare handle to refresh

Returns: Refresh session handle

DklsKeyMigrateSessionFromSetup

func DklsKeyMigrateSessionFromSetup(
    setup []byte,
    id []byte,
    publicKey []byte,
    rootChainCode []byte,
    secretCoefficient []byte,
) (Handle, error)

Creates a session to migrate keys from other threshold schemes (e.g., GG20).

Parameters:

  • setup: Keygen setup message
  • id: This party's identifier
  • publicKey: Expected 33-byte compressed public key
  • rootChainCode: 32-byte BIP32 chain code
  • secretCoefficient: 32-byte secret share coefficient

Returns: Migration session handle

DklsKeygenSessionOutputMessage

func DklsKeygenSessionOutputMessage(session Handle) ([]byte, error)

Gets the next message to send from a keygen session.

Returns: Message bytes (nil if no messages available)

DklsKeygenSessionMessageReceiver

func DklsKeygenSessionMessageReceiver(session Handle, message []byte, index int) (string, error)

Gets the recipient ID for a message at the given index.

Parameters:

  • session: Session handle
  • message: Message from OutputMessage
  • index: Receiver index (0 to n-1)

Returns: Receiver ID (empty string if no more receivers)

DklsKeygenSessionInputMessage

func DklsKeygenSessionInputMessage(session Handle, message []byte) (bool, error)

Processes an incoming message.

Returns: true if session is finished, false otherwise

DklsKeygenSessionFinish

func DklsKeygenSessionFinish(session Handle) (Handle, error)

Finalizes keygen and returns the keyshare.

Returns: Keyshare handle

DklsKeygenSessionFree

func DklsKeygenSessionFree(session Handle) error

Frees a keygen session handle.

Threshold Signing

DklsSignSetupMsgNew

func DklsSignSetupMsgNew(
    keyID []byte,
    chainPath []byte,
    messageHash []byte,
    ids []byte,
) ([]byte, error)

Creates a setup message for signing.

Parameters:

  • keyID: Key identifier from keyshare
  • chainPath: BIP32 derivation path (nil for root)
  • messageHash: 32-byte message hash
  • ids: Null-separated signer IDs

Returns: Setup message bytes

Examples:

// Full sign
setupMsg, err := session.DklsSignSetupMsgNew(keyID, nil, msgHash, []byte("p1\x00p2"))

// // Presign (no message)
// setupMsg, err := session.DklsSignSetupMsgNew(keyID, nil, nil, []byte("p1\x00p2"))

// // HD sign
// setupMsg, err := session.DklsSignSetupMsgNew(keyID, []byte("m/44/60/0/0/0"), msgHash, ids)

DklsFinishSetupMsgNew

func DklsFinishSetupMsgNew(sessionID []byte, messageHash []byte, ids []byte) ([]byte, error)

Creates a setup message for finishing a presignature.

Parameters:

  • sessionID: Session ID from presign
  • messageHash: 32-byte message hash
  • ids: Null-separated signer IDs

Returns: Finish setup message bytes

DklsSignSessionFromSetup

func DklsSignSessionFromSetup(setup []byte, id []byte, shareOrPresign Handle) (Handle, error)

Creates a signing session.

Parameters:

  • setup: Setup message from DklsSignSetupMsgNew or DklsFinishSetupMsgNew
  • id: This party's identifier
  • shareOrPresign: Keyshare handle (for sign/presign) or presign handle (for finish)

Returns: Sign session handle

Note: Function automatically detects whether to create a full sign, presign, or finish session based on setup message and handle type.

DklsSignSessionOutputMessage

func DklsSignSessionOutputMessage(session Handle) ([]byte, error)

Gets the next message to send from a sign session.

Returns: Message bytes (empty if no messages available)

DklsSignSessionMessageReceiver

func DklsSignSessionMessageReceiver(session Handle, message []byte, index int) ([]byte, error)

Gets the recipient ID for a message at the given index.

Returns: Receiver ID bytes (empty if no more receivers)

DklsSignSessionInputMessage

func DklsSignSessionInputMessage(session Handle, message []byte) (bool, error)

Processes an incoming message.

Returns: true if session is finished, false otherwise

DklsSignSessionFinish

func DklsSignSessionFinish(session Handle) ([]byte, error)

Finalizes signing session.

Returns:

  • For full/finish sessions: 65-byte signature [R || S || RecoveryID]
  • For presign sessions: Serialized presignature bytes

Format:

  • Bytes 0-31: R component
  • Bytes 32-63: S component
  • Byte 64: Recovery ID (0-3)

DklsSignSessionFree

func DklsSignSessionFree(session Handle) error

Frees a sign session handle.

Keyshare Operations

DklsKeyshareFromBytes

func DklsKeyshareFromBytes(buf []byte) (Handle, error)

Deserializes a keyshare from bytes.

DklsKeyshareToBytes

func DklsKeyshareToBytes(share Handle) ([]byte, error)

Serializes a keyshare to bytes.

DklsKeysharePublicKey

func DklsKeysharePublicKey(share Handle) ([]byte, error)

Gets the compressed public key (33 bytes) from a keyshare.

DklsKeyshareKeyID

func DklsKeyshareKeyID(share Handle) ([]byte, error)

Gets the unique key identifier from a keyshare.

DklsKeyshareChainCode

func DklsKeyshareChainCode(share Handle) ([]byte, error)

Gets the BIP32 chain code (32 bytes) from a keyshare.

DklsKeyshareDeriveChildPublicKey

func DklsKeyshareDeriveChildPublicKey(share Handle, derivationPathStr []byte) ([]byte, error)

Derives a child public key using BIP32 derivation.

Parameters:

  • share: Parent keyshare handle
  • derivationPathStr: Derivation path (e.g., []byte("m/44/60/0/0/0"))

Returns: 33-byte compressed child public key

DklsKeyshareToRefreshBytes

func DklsKeyshareToRefreshBytes(share Handle) ([]byte, error)

Serializes keyshare in refresh format (for key refresh protocol).

DklsRefreshShareFromBytes

func DklsRefreshShareFromBytes(buf []byte) (Handle, error)

Deserializes a refresh share from bytes.

DklsRefreshShareToBytes

func DklsRefreshShareToBytes(share Handle) ([]byte, error)

Serializes a refresh share to bytes.

DklsKeyshareFree

func DklsKeyshareFree(share Handle) error

Frees a keyshare handle.

Setup Message Utilities

DklsDecodeKeyID

func DklsDecodeKeyID(setup []byte) ([]byte, error)

Extracts key ID from a setup message.

DklsDecodeMessage

func DklsDecodeMessage(setup []byte) ([]byte, error)

Extracts message hash from a sign setup message.

DklsDecodePartyName

func DklsDecodePartyName(setup []byte, index int) ([]byte, error)

Extracts party name at given index from setup message.

Error Codes

See go-wrapper/go-dkls/errors/lib_err.go for complete error definitions.

Common Errors:

  • LIB_OK (0): Success
  • LIB_NULL_PTR: Null pointer passed
  • LIB_INVALID_HANDLE: Invalid handle
  • LIB_SETUP_MESSAGE_VALIDATION: Invalid setup message
  • LIB_KEYGEN_ERROR: Key generation failed
  • LIB_SIGNGEN_ERROR: Signature generation failed