package module
Version: v0.1.0 Latest Latest

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

Go to latest
Published: Jun 21, 2022 License: AGPL-3.0 Imports: 13 Imported by: 13



Go Reference Go Report Card Test Lint

Low level API to create and manipulate iden3 Claims.


All code here is experimental and WIP


go test ./...


go-iden3-core is part of the iden3 project copyright 2018 0kims association and published with GPL-3 license, please check the LICENSE file for more details.



Package core contains a low level API to create and manipulate claims.

Claims are created using the constructor function core.NewClaim. It accepts core.SchemaHash and a number of core.Option functions.




View Source
const (
	SlotNameIndexA = SlotName("IndexA")
	SlotNameIndexB = SlotName("IndexB")
	SlotNameValueA = SlotName("ValueA")
	SlotNameValueB = SlotName("ValueB")
View Source
const DIDMethod = "iden3"

DIDMethod DID method-name

View Source
const DIDSchema = "did"

DIDSchema DID Schema


View Source
var (
	// TypeDefault specifies the regular identity
	// - first 2 bytes: `00000000 00000000`
	TypeDefault = [2]byte{0x00, 0x00}

	// TypeReadOnly specifies the readonly identity, this type of identity MUST not be published on chain
	// - first 2 bytes: `00000000 00000001`
	TypeReadOnly = [2]byte{0b00000000, 0b00000001}
View Source
var ErrDataOverflow = errors.New("data does not fits SNARK size")

ErrDataOverflow means that given *big.Int value does not fit in Field Q e.g. greater than Q constant:

Q constant: 21888242871839275222246405745257275088548364400416034343698204186575808495617
View Source
var (

	// ErrDoesNotMatchRegexp is returned when did string parsed
	ErrDoesNotMatchRegexp = errors.New("did does not match regex")
View Source
var ErrIncorrectIDPosition = errors.New("incorrect ID position")

ErrIncorrectIDPosition means that passed position is not one of predefined: IDPositionIndex or IDPositionValue

View Source
var ErrInvalidSubjectPosition = errors.New("invalid subject position")

ErrInvalidSubjectPosition returns when subject position flags sets in invalid value.

View Source
var ErrNoID = errors.New("ID is not set")

ErrNoID returns when ID not found in the Claim.


func CalculateChecksum

func CalculateChecksum(typ [2]byte, genesis [27]byte) [2]byte

CalculateChecksum returns the checksum for a given type and genesis_root, where checksum:

hash( [type | root_genesis ] )

func CheckChecksum

func CheckChecksum(id ID) bool

CheckChecksum returns a bool indicating if the ID.Checksum is consistent with the rest of the ID data

func DecomposeID

func DecomposeID(id ID) ([2]byte, [27]byte, [2]byte, error)

DecomposeID returns type, genesis and checksum from an ID

func ElemBytesToInts added in v0.0.13

func ElemBytesToInts(elements []ElemBytes) []*big.Int

ElemBytesToInts converts slice of ElemBytes to slice of *big.Int

func IdenState

func IdenState(clr, rer, ror *big.Int) (*big.Int, error)

IdenState calculates the Identity State from the Claims Tree Root, Revocation Tree Root and Roots Tree Root.


type Blockchain added in v0.0.13

type Blockchain string

Blockchain id of the network "eth", "polygon", etc.

const (
	ETHEREUM Blockchain = "eth"     // ETHEREUM ethereum network
	POLYGON  Blockchain = "polygon" // POLYGON polygon network

type Claim

type Claim struct {
	// contains filtered or unexported fields

func NewClaim

func NewClaim(schemaHash SchemaHash, options ...Option) (*Claim, error)

NewClaim creates new Claim with specified SchemaHash and any number of options. Using options you can specify any field in claim.

var schemaHash SchemaHash
expDate := time.Date(2021, 1, 10, 20, 30, 0, 0, time.UTC)
claim, err := NewClaim(schemaHash,
if err != nil {
expDateRes, ok := claim.GetExpirationDate()


indexEntry, valueEntry := claim.RawSlots()
indexHash, err := poseidon.Hash(ElemBytesToInts(indexEntry[:]))
if err != nil {
valueHash, err := poseidon.Hash(ElemBytesToInts(valueEntry[:]))
if err != nil {

indexSlot, err := NewElemBytesFromInt(indexHash)
if err != nil {
valueSlot, err := NewElemBytesFromInt(valueHash)
if err != nil {



func (*Claim) Clone

func (c *Claim) Clone() *Claim

Clone returns full deep copy of claim

func (*Claim) GetExpirationDate

func (c *Claim) GetExpirationDate() (time.Time, bool)

GetExpirationDate returns expiration date and flag. Flag is true if expiration date is present, false if null.

func (*Claim) GetFlagUpdatable

func (c *Claim) GetFlagUpdatable() bool

GetFlagUpdatable returns claim's flag `updatable`

func (*Claim) GetID

func (c *Claim) GetID() (ID, error)

GetID returns ID from claim's index of value. Returns error ErrNoID if ID is not set.

func (*Claim) GetIDPosition added in v0.0.17

func (c *Claim) GetIDPosition() (IDPosition, error)

GetIDPosition returns the position at which the ID is stored.

func (*Claim) GetRevocationNonce

func (c *Claim) GetRevocationNonce() uint64

GetRevocationNonce returns revocation nonce

func (*Claim) GetSchemaHash

func (c *Claim) GetSchemaHash() SchemaHash

GetSchemaHash return copy of claim's schema hash.

func (*Claim) GetVersion

func (c *Claim) GetVersion() uint32

GetVersion returns claim's version

func (*Claim) HIndex added in v0.0.14

func (c *Claim) HIndex() (*big.Int, error)

HIndex calculates the hash of the Index of the Claim

func (*Claim) HValue added in v0.0.14

func (c *Claim) HValue() (*big.Int, error)

HValue calculates the hash of the Value of the Claim

func (*Claim) HiHv added in v0.0.14

func (c *Claim) HiHv() (*big.Int, *big.Int, error)

HiHv returns the HIndex and HValue of the Claim

func (Claim) MarshalBinary added in v0.0.14

func (c Claim) MarshalBinary() ([]byte, error)

func (Claim) MarshalJSON added in v0.0.14

func (c Claim) MarshalJSON() ([]byte, error)

func (*Claim) RawSlots added in v0.0.13

func (c *Claim) RawSlots() (index [4]ElemBytes, value [4]ElemBytes)

RawSlots returns raw bytes of claim's index and value

func (*Claim) RawSlotsAsInts added in v0.0.14

func (c *Claim) RawSlotsAsInts() []*big.Int

RawSlotsAsInts returns slots as []*big.Int

func (*Claim) ResetExpirationDate

func (c *Claim) ResetExpirationDate()

ResetExpirationDate removes expiration date from claim

func (*Claim) ResetID

func (c *Claim) ResetID()

ResetID deletes ID from index and from value.

func (*Claim) SetExpirationDate

func (c *Claim) SetExpirationDate(dt time.Time)

SetExpirationDate sets expiration date to dt

func (*Claim) SetFlagUpdatable

func (c *Claim) SetFlagUpdatable(val bool)

SetFlagUpdatable sets claim's flag `updatable`

func (*Claim) SetIndexData

func (c *Claim) SetIndexData(slotA, slotB ElemBytes) error

SetIndexData sets data to index slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func (*Claim) SetIndexDataBytes

func (c *Claim) SetIndexDataBytes(slotA, slotB []byte) error

SetIndexDataBytes sets data to index slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func (*Claim) SetIndexDataInts

func (c *Claim) SetIndexDataInts(slotA, slotB *big.Int) error

SetIndexDataInts sets data to index slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func (*Claim) SetIndexID

func (c *Claim) SetIndexID(id ID)

SetIndexID sets id to index. Removes id from value if any.

func (*Claim) SetRevocationNonce

func (c *Claim) SetRevocationNonce(nonce uint64)

SetRevocationNonce sets claim's revocation nonce

func (*Claim) SetSchemaHash

func (c *Claim) SetSchemaHash(schema SchemaHash)

SetSchemaHash updates claim's schema hash.

func (*Claim) SetValueData

func (c *Claim) SetValueData(slotA, slotB ElemBytes) error

SetValueData sets data to value slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func (*Claim) SetValueDataBytes

func (c *Claim) SetValueDataBytes(slotA, slotB []byte) error

SetValueDataBytes sets data to value slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func (*Claim) SetValueDataInts

func (c *Claim) SetValueDataInts(slotA, slotB *big.Int) error

SetValueDataInts sets data to value slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func (*Claim) SetValueID

func (c *Claim) SetValueID(id ID)

SetValueID sets id to value. Removes id from index if any.

func (*Claim) SetVersion

func (c *Claim) SetVersion(ver uint32)

SetVersion sets claim's version

func (*Claim) UnmarshalBinary added in v0.0.14

func (c *Claim) UnmarshalBinary(data []byte) error

func (*Claim) UnmarshalJSON added in v0.0.14

func (c *Claim) UnmarshalJSON(in []byte) error

type DID added in v0.0.13

type DID struct {
	ID         ID         // ID did specific id
	Blockchain Blockchain // Blockchain network identifier eth / polygon,...
	NetworkID  NetworkID  // NetworkID specific network identifier eth {main, ropsten, rinkeby, kovan}

DID Decentralized Identifiers (DIDs)

func NewDID added in v0.0.13

func NewDID(didStr string, options ...DIDOption) (*DID, error)

func ParseDID added in v0.0.13

func ParseDID(didStr string) (*DID, error)

ParseDID method parse string and extract DID if string is valid Iden3 identifier

func (*DID) String added in v0.0.13

func (did *DID) String() string

String did as a string

type DIDOption added in v0.0.13

type DIDOption func(*DID) error

func WithNetwork added in v0.0.13

func WithNetwork(blockchain Blockchain, network NetworkID) DIDOption

WithNetwork sets Blockchain and NetworkID (eth:main)

type ElemBytes added in v0.0.13

type ElemBytes [32]byte

ElemBytes length is 32 bytes. But not all 32-byte values are valid. The value should be not greater than Q constant 21888242871839275222246405745257275088548364400416034343698204186575808495617

func NewElemBytesFromInt added in v0.0.13

func NewElemBytesFromInt(i *big.Int) (ElemBytes, error)

NewElemBytesFromInt creates new ElemBytes from *big.Int. Returns error ErrDataOverflow if value is too large to fill the Field Q.

func (ElemBytes) Hex added in v0.0.13

func (el ElemBytes) Hex() string

Hex returns HEX representation of ElemBytes

func (*ElemBytes) SetInt added in v0.0.13

func (el *ElemBytes) SetInt(value *big.Int) error

SetInt sets element's data to serialized value of *big.Int in little-endian. And checks that the value is valid (fits in Field Q). Returns ErrDataOverflow if the value is too large

func (ElemBytes) ToInt added in v0.0.13

func (el ElemBytes) ToInt() *big.Int

ToInt returns *big.Int representation of ElemBytes.

type ErrSlotOverflow

type ErrSlotOverflow struct {
	Field SlotName

ErrSlotOverflow means some ElemBytes overflows Q Field. And wraps the name of overflowed slot.

func (ErrSlotOverflow) Error

func (e ErrSlotOverflow) Error() string

type ID

type ID [idLength]byte

ID is a byte array with [ type | root_genesis | checksum ] [2 bytes | 27 bytes | 2 bytes ] where the root_genesis are the first 28 bytes from the hash root_genesis

func IDFromBytes

func IDFromBytes(b []byte) (ID, error)

IDFromBytes returns the ID from a given byte array

func IDFromInt added in v0.0.15

func IDFromInt(i *big.Int) (ID, error)

IDFromInt returns the ID from a given big.Int

func IDFromString

func IDFromString(s string) (ID, error)

IDFromString returns the ID from a given string

func IdGenesisFromIdenState

func IdGenesisFromIdenState(typ [2]byte,
	state *big.Int) (*ID, error)

IdGenesisFromIdenState calculates the genesis ID from an Identity State.

func NewID

func NewID(typ [2]byte, genesis [27]byte) ID

NewID creates a new ID from a type and genesis

func (*ID) BigInt

func (id *ID) BigInt() *big.Int

func (*ID) Bytes

func (id *ID) Bytes() []byte

Bytes returns the bytes from the ID

func (*ID) Equal

func (id *ID) Equal(id2 *ID) bool

func (*ID) Equals

func (id *ID) Equals(id2 *ID) bool

func (ID) MarshalText

func (id ID) MarshalText() ([]byte, error)

func (*ID) String

func (id *ID) String() string

String returns a base58 from the ID

func (*ID) UnmarshalText

func (id *ID) UnmarshalText(b []byte) error

type IDPosition

type IDPosition uint8
const (
	// IDPositionNone means ID value not located in claim.
	IDPositionNone IDPosition = iota
	// IDPositionIndex means ID value is in index slots.
	// IDPositionValue means ID value is in value slots.

type NetworkID added in v0.0.13

type NetworkID string
const (
	MAIN    NetworkID = "main"    // main net
	TEST    NetworkID = "test"    // test net
	ROPSTEN NetworkID = "ropsten" // ropsten net
	RINKEBY NetworkID = "rinkeby" // rinkeby net
	KOVAN   NetworkID = "kovan"   // kovan net

type Option

type Option func(*Claim) error

Option provides the ability to set different Claim's fields on construction

func WithExpirationDate

func WithExpirationDate(dt time.Time) Option

WithExpirationDate sets claim's expiration date to `dt`.

func WithFlagUpdatable

func WithFlagUpdatable(val bool) Option

WithFlagUpdatable sets claim's flag `updatable`

func WithID

func WithID(id ID, pos IDPosition) Option

WithID sets ID to claim's index or value depending on `pos`.

func WithIndexData

func WithIndexData(slotA, slotB ElemBytes) Option

WithIndexData sets data to index slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func WithIndexDataBytes

func WithIndexDataBytes(slotA, slotB []byte) Option

WithIndexDataBytes sets data to index slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func WithIndexDataInts

func WithIndexDataInts(slotA, slotB *big.Int) Option

WithIndexDataInts sets data to index slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func WithIndexID

func WithIndexID(id ID) Option

WithIndexID sets ID to claim's index

func WithRevocationNonce

func WithRevocationNonce(nonce uint64) Option

WithRevocationNonce sets claim's revocation nonce.

func WithValueData

func WithValueData(slotA, slotB ElemBytes) Option

WithValueData sets data to value slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func WithValueDataBytes

func WithValueDataBytes(slotA, slotB []byte) Option

WithValueDataBytes sets data to value slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func WithValueDataInts

func WithValueDataInts(slotA, slotB *big.Int) Option

WithValueDataInts sets data to value slots A & B. Returns ErrSlotOverflow if slotA or slotB value are too big.

func WithValueID

func WithValueID(id ID) Option

WithValueID sets ID to claim's value

func WithVersion

func WithVersion(ver uint32) Option

WithVersion sets claim's version

type SchemaHash

type SchemaHash [schemaHashLn]byte

SchemaHash is a 16-bytes hash of file's content, that describes claim structure.

func NewSchemaHashFromHex added in v0.0.14

func NewSchemaHashFromHex(s string) (SchemaHash, error)

NewSchemaHashFromHex creates new SchemaHash from hex string

func NewSchemaHashFromInt added in v0.0.16

func NewSchemaHashFromInt(i *big.Int) SchemaHash

NewSchemaHashFromInt creates new SchemaHash from big.Int

func (SchemaHash) BigInt added in v0.0.16

func (sc SchemaHash) BigInt() *big.Int

BigInt returns a bigInt presentation of SchemaHash

func (SchemaHash) MarshalText

func (sc SchemaHash) MarshalText() ([]byte, error)

MarshalText returns HEX representation of SchemaHash.

Returning error is always nil.

type SlotName

type SlotName string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL