api

package
v0.118.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 29, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package api provides a client for Turnkey's Visualsign API.

The client handles: - API authentication with ECDSA P-256 keys - Request/response marshaling and signing - Attestation document retrieval - Cryptographic operations for API key authentication

Usage

Create a client using NewClient with an API key provider: 

client, err := api.NewClient(hostURI, httpClient, organizationID, keyProvider)
if err != nil {
	log.Fatal(err)
}

Call CreateSignablePayload to request transaction parsing: 

response, err := client.CreateSignablePayload(ctx, &api.CreateSignablePayloadRequest{
	UnsignedPayload: "base64-encoded-payload",
	Chain:           "CHAIN_SOLANA",
})
if err != nil {
	log.Fatal(err)
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ABISignature added in v0.105.0 

type ABISignature struct {
	Value    string        `json:"value"`
	Metadata []SignatureKV `json:"metadata,omitempty"`
}

ABISignature is an optional cryptographic signature over an ABI definition. Value is the hex-encoded signature over the ABI JSON content. Metadata carries algorithm, public key, and any other attestation fields. Use NewABISignature to construct with the standard metadata layout.

func NewABISignature added in v0.105.0 

func NewABISignature(value, algorithm, publicKey string, extra ...SignatureKV) *ABISignature

NewABISignature constructs an ABISignature with the standard metadata fields. value is the hex-encoded signature over the ABI JSON string. algorithm is the signing algorithm, e.g. "secp256k1" or "ed25519". publicKey is the hex-encoded public key of the signer. extra adds any additional metadata entries (e.g. "issuer", "timestamp").

type ABIValue added in v0.105.0 

type ABIValue struct {
	Value     string        `json:"value"`
	Signature *ABISignature `json:"signature,omitempty"`
	// AbiType classifies the ABI (implementation vs proxy). nil means the field is
	// omitted (proto None); the parser treats an absent type as implementation.
	AbiType *AbiType `json:"abiType,omitempty"`
	// ImplementationAddress is, for proxies, the 0x-prefixed address whose ABI
	// decodes the calldata. nil means the field is omitted (proto None).
	ImplementationAddress *string `json:"implementationAddress,omitempty"`
}

ABIValue holds a JSON-encoded ABI definition and optional metadata.

type AbiType added in v0.118.0 

type AbiType string

AbiType mirrors parser.proto AbiType. It is sent on the JSON wire as the proto enum name (e.g. "ABI_TYPE_PROXY"), matching the parser's serde representation. The metadata digest hashes the underlying proto enum number, not this string; see borsh.go. 

const (
	// AbiTypeUnspecified is the proto default. The parser treats it as implementation.
	AbiTypeUnspecified AbiType = "ABI_TYPE_UNSPECIFIED"
	// AbiTypeImplementation marks an ABI that decodes calldata directly.
	AbiTypeImplementation AbiType = "ABI_TYPE_IMPLEMENTATION"
	// AbiTypeProxy marks a proxy contract whose calldata is decoded with the ABI
	// at ImplementationAddress.
	AbiTypeProxy AbiType = "ABI_TYPE_PROXY"
)

type AttestationQueryRequest 

type AttestationQueryRequest struct {
	OrganizationID string `json:"organizationId"`
	EnclaveType    string `json:"enclaveType"`
	PublicKey      string `json:"publicKey"`
}

AttestationQueryRequest represents the request to get attestation document

type AttestationQueryResponse 

type AttestationQueryResponse struct {
	AttestationDocument string `json:"attestationDocument"`
}

AttestationQueryResponse represents the response from the attestation query

type AttestationType 

type AttestationType string

AttestationType represents different types of attestations 

const (
	BootAttestationKey AttestationType = "boot_attestation"
	AppAttestationKey  AttestationType = "app_attestation"
)

type Client 

type Client struct {
	HostURI              string
	HTTPClient           HTTPClient
	APIKey               *TurnkeyAPIKey
	APIKeyProvider       KeyProvider
	VisualSignAPIVersion string
	// UseDevPath, when true, routes requests to "/visualsign-dev/api/<version>/parse"
	// instead of the canonical "/visualsign/api/<version>/parse". Use during
	// production-readiness testing of the parser deployed under the dev path.
	UseDevPath bool
}

Client implements the Turnkey API client

func NewClient 

func NewClient(hostURI string, httpClient HTTPClient, organizationID string, provider KeyProvider) (*Client, error)

NewClient creates a new Turnkey API client with key provider

func (*Client) CreateSignablePayload 

func (c *Client) CreateSignablePayload(ctx context.Context, req *CreateSignablePayloadRequest) (*SignablePayloadResponse, error)

CreateSignablePayload calls Turnkey's visualsign API to create a signable payload

func (*Client) GetBootAttestation 

func (c *Client) GetBootAttestation(ctx context.Context, publicKey, enclaveType string) (string, error)

GetBootAttestation retrieves boot attestation for a specific public key and enclave type

type CreateSignablePayloadRequest 

type CreateSignablePayloadRequest struct {
	UnsignedPayload string
	Chain           string
	ChainMetadata   *RequestChainMetadata // optional — nil means no ABIs sent
}

CreateSignablePayloadRequest represents the request to create signable payload

type ECDSASignature 

type ECDSASignature struct {
	R, S *big.Int
}

ECDSASignature represents an ECDSA signature for ASN.1 encoding

type EthereumChainMetadata added in v0.105.0 

type EthereumChainMetadata struct {
	NetworkID   *string             `json:"networkId,omitempty"`
	ABIMappings map[string]ABIValue `json:"abiMappings,omitempty"`
}

EthereumChainMetadata carries optional ABI mappings for Ethereum parse requests. ABIMappings maps 0x-prefixed contract address to its ABI JSON.

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient interface for dependency injection

type KeyProvider 

type KeyProvider interface {
	GetAPIKey(ctx context.Context) (*TurnkeyAPIKey, error)
}

KeyProvider interface for providing API keys

type RequestChainMetadata added in v0.105.0 

type RequestChainMetadata struct {
	Ethereum *EthereumChainMetadata `json:"ethereum,omitempty"`
}

RequestChainMetadata is the chain_metadata field in the Turnkey parse request.

func (*RequestChainMetadata) BorshBytes added in v0.116.0 

func (r *RequestChainMetadata) BorshBytes() ([]byte, error)

BorshBytes returns borsh::to_vec(&chain_metadata) — the canonical bytes the visualsign-parser hashes for metadata_digest. hex.EncodeToString of SHA256 over these bytes equals MetadataDigestHex(). These bytes let a verifier recompute the digest off-chain. Returns the Borsh encoding of ChainMetadata{metadata: None} ([]byte{0x00}) when r is nil or r.Ethereum is nil.

func (*RequestChainMetadata) MetadataDigestHex added in v0.105.0 

func (r *RequestChainMetadata) MetadataDigestHex() (string, error)

MetadataDigestHex returns the hex-encoded SHA-256 of the Borsh encoding of r, matching the metadata_digest the visualsign-parser computes for the same input.

type SignablePayloadResponse 

type SignablePayloadResponse struct {
	SignablePayload                  string                     `json:"signablePayload"`
	ParsedPayload                    string                     `json:"parsedPayload,omitempty"`      // v2
	InputPayloadDigest               string                     `json:"inputPayloadDigest,omitempty"` // v2
	MetadataDigest                   string                     `json:"metadataDigest,omitempty"`     // v2
	TurnkeySerializedSignablePayload string                     `json:"turnkeySerializedSignablePayload"`
	ManifestVersion                  manifest.ManifestVersion   `json:"manifestVersion"`
	Attestations                     map[AttestationType]string `json:"attestations"`
	QosManifestB64                   string                     `json:"qosManifestB64,omitempty"`
	QosManifestEnvelopeB64           string                     `json:"qosManifestEnvelopeB64,omitempty"`
	EphemeralPublicKeyHex            string                     `json:"ephemeralPublicKeyHex,omitempty"`
	EnclaveApp                       string                     `json:"enclaveApp,omitempty"`
	DeploymentLabel                  string                     `json:"deploymentLabel,omitempty"`
}

SignablePayloadResponse represents the response from CreateSignablePayload

type SignatureKV added in v0.105.0 

type SignatureKV struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

SignatureKV is a key-value metadata entry attached to an ABISignature. Standard keys: "algorithm" ("secp256k1" or "ed25519"), "public_key" (hex), "issuer" (address), "timestamp" (unix epoch string).

type TurnkeyAPIKey 

type TurnkeyAPIKey struct {
	PublicKey      string
	PrivateKey     *ecdsa.PrivateKey
	OrganizationID string
}

TurnkeyAPIKey represents the API key configuration

type TurnkeyBootProof 

type TurnkeyBootProof struct {
	AwsAttestationDocB64   string `json:"awsAttestationDocB64"`
	QosManifestB64         string `json:"qosManifestB64"`
	QosManifestEnvelopeB64 string `json:"qosManifestEnvelopeB64"`
	EphemeralPublicKeyHex  string `json:"ephemeralPublicKeyHex"`
	EnclaveApp             string `json:"enclaveApp"`
	DeploymentLabel        string `json:"deploymentLabel"`
}

TurnkeyBootProof represents the boot proof object in the response. Fields match the Turnkey visualsign API bootProof response object. See: https://docs.turnkey.com/concepts/enclave-secure-channels

type TurnkeySignature 

type TurnkeySignature struct {
	Message   string `json:"message"`
	PublicKey string `json:"publicKey"`
	Scheme    string `json:"scheme"`
	Signature string `json:"signature"`
}

TurnkeySignature represents the signature object in the response

type TurnkeyStamp 

type TurnkeyStamp struct {
	PublicKey string `json:"publicKey"`
	Signature string `json:"signature"`
	Scheme    string `json:"scheme"`
}

TurnkeyStamp represents the stamp structure for API key authentication

type TurnkeyVisualSignRequest 

type TurnkeyVisualSignRequest struct {
	Request struct {
		UnsignedPayload string                `json:"unsigned_payload"`
		Chain           string                `json:"chain"`
		ChainMetadata   *RequestChainMetadata `json:"chain_metadata,omitempty"`
	} `json:"request"`
	OrganizationID string `json:"organization_id"`
}

TurnkeyVisualSignRequest represents the request to Turnkey's visualsign API

type TurnkeyVisualSignResponse 

type TurnkeyVisualSignResponse struct {
	BootProof *TurnkeyBootProof `json:"bootProof,omitempty"`
	Response  struct {
		ParsedTransaction struct {
			Payload struct {
				SignablePayload    string `json:"signablePayload"`
				ParsedPayload      string `json:"parsedPayload,omitempty"`      // v2
				InputPayloadDigest string `json:"inputPayloadDigest,omitempty"` // v2
				MetadataDigest     string `json:"metadataDigest,omitempty"`     // v2
			} `json:"payload"`
			Signature *TurnkeySignature `json:"signature,omitempty"`
		} `json:"parsedTransaction"`
	} `json:"response"`
	Error string `json:"error,omitempty"`
}

TurnkeyVisualSignResponse represents the response from Turnkey's visualsign API

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.