Curves

Every named curve constructor in core/curves, the complete Point and Scalar method sets, pairing curves, and a map of the low-level native field arithmetic underneath.

core/curves is the catalog. It exposes one constructor per supported group, all of which hand back a *curves.Curve (or a *curves.PairingCurve for the pairing-friendly ones). Everything on this page was read out of go doc github.com/sonr-io/crypto/core/curves.

Reach for this page when you need to know which curve a package will accept, what a serialized point looks like on the wire, or which method on Point/Scalar does the thing you want. You do not need this page if you are just passing a curve through — curves.K256() and go.

Named curves

Two extra string constants exist for “the pairing construction, group unspecified”: BLS12831Name = "BLS12831" and BLS12377Name = "BLS12377".

Lookup by name

curve := curves.GetCurveByName(curves.K256Name)
if curve == nil {
	return fmt.Errorf("unsupported curve")
}

GetCurveByName accepts every constant above. BLS12831Name and BLS12377Name both resolve to the G1 curve. Anything else returns nil.

Pairing curves

BBS+ and the accumulator need a pairing, so they take a *curves.PairingCurve — a different type from *curves.Curve. Passing curves.BLS12381G1() where a *PairingCurve is wanted will not compile.

type PairingCurve struct {
	Scalar  PairingScalar
	PointG1 PairingPoint
	PointG2 PairingPoint
	GT      Scalar
	Name    string
}

PairingPoint and PairingScalar are extensions of the ordinary interfaces, so every Point/Scalar method is still available:

type PairingPoint interface {
	Point
	OtherGroup() PairingPoint          // G1 <-> G2
	Pairing(rhs PairingPoint) Scalar   // e(self, rhs) as a GT element
	MultiPairing(...PairingPoint) Scalar
}

type PairingScalar interface {
	Scalar
	SetPoint(p Point) PairingScalar
}

Note that Pairing returns a Scalar, not a distinct GT type — the target group element is modelled as a ScalarBls12381Gt. It supports the Scalar arithmetic surface (Mul, Add, Invert, Bytes) but it is a group element in the target group GT, not a field element mod the group order. Do not feed it back into ScalarBaseMult.

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/sonr-io/crypto/core/curves"
)

func main() {
	pc := curves.BLS12381(curves.BLS12381G1().NewIdentityPoint())

	s := pc.NewScalar().Random(rand.Reader)
	g1 := pc.ScalarG1BaseMult(s) // s·G1
	g2 := pc.NewG2GeneratorPoint()

	gt := g1.Pairing(g2) // e(s·G1, G2)
	fmt.Println(pc.Name, len(gt.Bytes()))
	fmt.Println(g1.OtherGroup().CurveName()) // BLS12381G2
}

The Point interface

Twenty methods, no error returns except on the two deserializers and Set.

Serialization

Concrete point types also implement MarshalBinary/UnmarshalBinary, MarshalText/UnmarshalText, and MarshalJSON/UnmarshalJSON — that is how the higher layers (BBS+ proofs, accumulator witnesses, DKG round messages) persist points. The interface itself does not declare them, so if you need marshalling through the interface you type-assert to encoding.BinaryMarshaler.

SumOfProducts — multi-scalar multiplication

This is the MSM entry point, and the reason Bulletproofs and the accumulator are tractable. Call it on the curve’s point prototype; the receiver’s own value is ignored.

// Computes sum(scalars[i] · points[i]) using a 4-bit windowed bucket
// (Pippenger-style) multi-exponentiation, not n independent scalar mults.
result := curve.Point.SumOfProducts(points, scalars)
if result == nil {
	return errors.New("length mismatch or foreign point/scalar type")
}

The Scalar interface

The doc comment describes it as “an element of the scalar field F_q of the elliptic curve construction” — that is, arithmetic is mod the group order, not the field characteristic.

Three behaviours that catch people:

• Cmp returns -2 if the two scalars belong to different fields. It is the library’s only cross-curve mismatch signal. -1/0/1 are the usual ordering.
• New(value int) takes a signed int and reduces it, so New(-1) is q - 1. Since q is odd for these curves, New(-1).IsEven() is true — the parity predicates describe the reduced representative, not the integer you passed.
• SetBytes demands the exact width, while SetBytesWide wants double the width and reduces. Use SetBytesWide when converting hash output into a scalar without modulo bias; use Hash if you just want “bytes to scalar” done correctly.

// Uniform scalar from arbitrary input, no bias, no length constraints:
s := curve.Scalar.Hash([]byte("some transcript bytes"))

// Exact-width canonical decoding, e.g. reading a stored private key:
s, err := curve.Scalar.SetBytes(keyBytes) // len(keyBytes) must be exactly 32 for K256

The crypto/elliptic bridge

Some code (Go’s crypto/ecdsa, X.509 marshalling, the legacy EcPoint API) needs an elliptic.Curve. Several shims exist, and they are not interchangeable:

All of them satisfy elliptic.Curve. Curve.ToEllipticCurve() is the generic entry point:

ec, err := curves.K256().ToEllipticCurve() // -> *Koblitz256, nil
ec, err = curves.ED25519().ToEllipticCurve() // -> nil, "can't convert ed25519"

secp256k1.BitCurve additionally offers Marshal(x, y) []byte / Unmarshal(data) (x, y) and exposes its parameters as public fields (P, N, B, Gx, Gy, BitSize).

core/curves/native — the layer below

native is the constant-time-oriented field and point arithmetic that the modern Point/Scalar implementations sit on. It is a building block, and almost nothing outside core/curves should import it.

Fields are represented as four 64-bit limbs in the Montgomery domain:

const (
	FieldBytes     = 32 // canonical byte width
	FieldLimbs     = 4  // uint64 limbs
	WideFieldBytes = 64 // width for bias-free reduction
	MaxDstLen      = 255
)

type Field struct {
	Value      [FieldLimbs]uint64
	Params     *FieldParams   // R, R2, R3, Modulus, BiModulus
	Arithmetic FieldArithmetic // per-curve limb routines
}

Field provides Add, Sub, Mul, Square, Double, Neg, Exp, Invert, Sqrt, CMove, Equal, Cmp, plus SetBytes/SetBytesWide/SetBigInt/SetLimbs/SetRaw and their Bytes/BigInt/Raw inverses. EllipticPoint provides Weierstrass point arithmetic in Jacobian coordinates (Add, Double, Generator, Hash, Equal, BigInt, GetX, GetY).

Which fields and groups are actually implemented:

Hash-to-curve hashers

EllipticPointHasher bundles a hash function with its expansion mode. It is what Point.Hash uses internally, and the only reason to construct one yourself is if you are calling native.ExpandMsgXmd / native.ExpandMsgXof or EllipticPoint.Hash directly.

ExpandMsgXmd and ExpandMsgXof implement §5.4.1 and §5.4.2 of the CFRG hash-to-curve draft (the source links to draft-irtf-cfrg-hash-to-curve-13). Domain separation tags longer than MaxDstLen are hashed down using the OversizeDstSalt prefix H2C-OVERSIZE-DST-.

Legacy curve types

For completeness, since they show up in go doc next to everything above. These belong to the older API described on the foundations overview and are used by sharing/v1, dkg/gennaro, and ted25519 keygen.

• EcPoint{Curve elliptic.Curve; X, Y *big.Int} with NewScalarBaseMult, PointFromBytesUncompressed, Add, Neg, ScalarMult, Bytes, Equals, IsOnCurve, IsIdentity, IsBasePoint, IsValid, and binary/JSON marshalling (plus EcPointJSON as the wire shape).
• Field/Element — generic big.Int modular arithmetic over an explicit modulus, with ElementJSON for serialization.
• EcScalar — a strategy interface (Add, Sub, Neg, Mul, Div, Hash, Random, IsValid, Bytes) implemented by NewK256Scalar(), NewP256Scalar(), NewEd25519Scalar(), NewBls12381Scalar(), and NewPallasScalar().
• EcdsaSignature, EcdsaVerify, and VerifyEcdsa(pk *EcPoint, hash []byte, sig *EcdsaSignature) bool — the verification hook used by threshold ECDSA. See ECDSA.
• Ed25519Order() *big.Int — the Ed25519 group order as a big.Int.