aleo_utils

README

Aleo utility wrapper for Golang

This is a helper library for Golang, it provides selected functions (see below) from the Aleo library with correct encoding.

This library is using WebAssembly under the hood, which is compiled to wasm32-wasi. It is using the library based on https://github.com/AleoHQ/snarkVM console crate. The WebAssembly program is embed into the binary using go:embed.

Building WASM module before using

1. Install Cargo and Rust 1.76.0
2. Build WASM library by running ./build.sh
3. (optional) optimize wasm by running this command (requires wasm-snip, wasm-opt): ./optimize_wasm.sh

Usage

Available functions:

Function	Arguments	Return type	Description
NewPrivateKey		(key []byte, address string, err error)	Generates a new Aleo private key, returns it with it's public address. The caller should zero the returned slice after use using ZeroizePrivateKey
FormatMessage	message []byte - buffer to format for Leo targetChunks int - number of desired chunks in the resulting struct, where every chunk is a struct of 32 u128s. Allowed: 1-32.	(formattedMessage []byte, err error)	Formats a byte buffer as a nested struct with the specified number of 512-byte chunks. The result is returned as bytes of the string representation of the struct.
RecoverMessage	formattedMessage []byte	(message []byte, err error)	Recovers original byte buffer from a formatted message created with FormatMessage
HashMessageToString	message []byte	(hash string, err error)	Hashes a message using Poseidon8 Leo function, and returns a string representation of a resulting u128, meaning it can be used as a literal in a Leo program, e.g. "12345u128"
HashMessage	message []byte	(hash []byte, err error)	Hashes a message using Poseidon8 Leo function, and returns a byte representation of a resulting u128, meaning it has to be converted to Leo u128 type before it can be used as a literal. Use this function if you want to sign a message that is too big and verify it in a contract. If you don't plan to verify it in contract, HashMessageToString will work as well
Sign	key []byte - private key for signing, e.g. from NewPrivateKey message []byte - a message to sign, must be string or byte representation of Leo u128 value	(signature string, err error)	Signs data using private key, returns the signature as a string representation of Leo signature value. The private key bytes are wiped from WASM memory immediately after signing

Create a wrapper using NewWrapper. It will return a wrapper manager, runtime close function, and optionally an error. Then use wrapper manager to create a new session.

import (
  aleo "github.com/venture23-aleo/aleo-utils-go"
  "context"
)

func main() {
  wrapper, closeFn, err := aleo.NewWrapper(context.Background())
  if err != nil {
    panic(err)
  }

  session, err := wrapper.NewSession()
  if err != nil {
    panic(err)
  }

  // session provides access to the functionality
  key, addr, _ := session.NewPrivateKey()
  defer ZeroizePrivateKey(key) // best-effort zeroization

  // calling closeFn will destroy WASM runtime,
  // all wrapper functions will panic if called after the runtime was closed
  defer closeFn()
}

After the wrapper session is instantiated, you can use the wrapper functions.

For more examples check out: github.com/venture23-aleo/aleo-utils-go/blob/main/example_test.go

Using in SGX

Since this package uses WASM, an SGX enclave needs to have the executable heap enabled in the config. Heap size may also need to be increased.

Documentation

Overview

Package aleo_utils implements Aleo-compatible Schnorr signing.

Example

package main

import (
	"log"

	aleo "github.com/venture23-aleo/aleo-utils-go"
)

func main() {
	// create Aleo wrapper
	wrapper, closeFn, err := aleo.NewWrapper()
	if err != nil {
		log.Fatalln(err)
	}
	defer closeFn()

	// create a new session
	s, err := wrapper.NewSession()
	if err != nil {
		log.Fatalln(err)
	}

	// generate a new Aleo private key
	privKey, address, err := s.NewPrivateKey()
	if err != nil {
		log.Fatalln(err)
	}

	// create a formatted message. the message fits in 1 512-byte block, so that's how many we request.
	// the formatted message is an equivalent of Leo type Data with 1 DataChunk
	// struct DataChunk {
	//   f0: u128,
	//   ...
	//   f31: u128
	// }
	// struct Data {
	// 	c0: DataChunk
	// }
	formattedMessage, err := s.FormatMessage([]byte("btc/usd = 1.0"), 1)
	if err != nil {
		log.Fatalln(err)
	}

	// formatted message can be signed as is or hashed first
	hashedMessage, err := s.HashMessage(formattedMessage)
	if err != nil {
		log.Fatalln(err)
	}

	// sign a message
	signature, err := s.Sign(privKey, hashedMessage)
	if err != nil {
		log.Fatalln(err)
	}

	log.Println("Formatted message:", formattedMessage)
	log.Println("Signature:", signature)
	log.Println("Address:", address)
	log.Println("Poseidon8 hash:", hashedMessage)
	log.Println("Private key:", string(privKey))

}

Index

• Constants
• Variables
• type Session
• type Wrapper
  • func NewWrapper() (wrapper Wrapper, closeFn func(), err error)

Examples

• Package

Constants

const (
	PRIVATE_KEY_SIZE          = 59
	ADDRESS_SIZE              = 63
	SIGNATURE_SIZE            = 216
	MESSAGE_FORMAT_BLOCK_SIZE = 16 * 32
	MAX_FORMAT_MESSAGE_CHUNKS = 32
)

Variables

var ErrNoModule = errors.New("session module is closed")

var ErrNoRuntime = errors.New("no runtime, create new wrapper")

Types

type Session

type Session interface {
	// NewPrivateKey returns a newly generated private key as a byte slice and the
	// corresponding address. The caller is responsible for zeroizing the returned
	// slice when it is no longer needed (see ZeroizePrivateKey).
	NewPrivateKey() (key []byte, address string, err error)
	FormatMessage(message []byte, targetChunks int) (formattedMessage []byte, err error)
	RecoverMessage(formattedMessage []byte) (message []byte, err error)
	HashMessageToString(message []byte) (hash string, err error)
	HashMessage(message []byte) (hash []byte, err error)
	// Sign creates an Aleo-compatible Schnorr signature. The private key is not
	// copied as a string and is wiped from WASM memory immediately after use.
	Sign(key []byte, message []byte) (signature string, err error)

	Close()
}

Provides access to wrapper functionality. A session is not goroutine safe so you need to create a new one for every goroutine

type Wrapper

type Wrapper interface {
	NewSession() (Session, error)
	Close()
}

Wrapper is an interface for Aleo Wrapper session manager. Create an instance of a Wrapper using NewWrapper, then create a new Session to use the signing functionality.

func NewWrapper

func NewWrapper() (wrapper Wrapper, closeFn func(), err error)

NewWrapper creates Leo contract compatible Schnorr wrapper manager. The second argument is a cleanup function, which destroys wrapper runtime. aleoWrapper cannot be used after the cleanup function is called, and must be recreated using this function.