Struct

Struct<A, T, V, J, Pure>(type: A): (value: T) => T & {
  _isStruct: true;
  } & Pure extends true ? ProvablePure<T, V> : Provable<T, V> & {
  empty: () => T;
  fromJSON: (x: J) => T;
  fromValue: (value: From<A>) => T;
  toInput: (x: T) => {
     fields: Field[];
     packed: [Field, number][];
  };
  toJSON: (x: T) => J;
}

Struct lets you declare composite types for use in o1js circuits.

These composite types can be passed in as arguments to smart contract methods, used for on-chain state variables or as event / action types.

Here's an example of creating a "Voter" struct, which holds a public key and a collection of votes on 3 different proposals:

let Vote = { hasVoted: Bool, inFavor: Bool };

class Voter extends Struct({
  publicKey: PublicKey,
  votes: [Vote, Vote, Vote]
}) {}

// use Voter as SmartContract input:
class VoterContract extends SmartContract {
  \@method register(voter: Voter) {
    // ...
  }
}

In this example, there are no instance methods on the class. This makes Voter type-compatible with an anonymous object of the form { publicKey: PublicKey, votes: Vote[] }. This mean you don't have to create instances by using new Voter(...), you can operate with plain objects:

voterContract.register({ publicKey, votes });

On the other hand, you can also add your own methods:

class Voter extends Struct({
  publicKey: PublicKey,
  votes: [Vote, Vote, Vote]
}) {
  vote(index: number, inFavor: Bool) {
    let vote = this.votes[i];
    vote.hasVoted = Bool(true);
    vote.inFavor = inFavor;
  }
}

In this case, you'll need the constructor to create instances of Voter. It always takes as input the plain object:

let emptyVote = { hasVoted: Bool(false), inFavor: Bool(false) };
let voter = new Voter({ publicKey, votes: Array(3).fill(emptyVote) });
voter.vote(1, Bool(true));

In addition to creating types composed of Field elements, you can also include auxiliary data which does not become part of the proof. This, for example, allows you to re-use the same type outside o1js methods, where you might want to store additional metadata.

To declare non-proof values of type string, number, etc, you can use the built-in objects String, Number, etc. Here's how we could add the voter's name (a string) as auxiliary data:

class Voter extends Struct({
  publicKey: PublicKey,
  votes: [Vote, Vote, Vote],
  fullName: String
}) {}

Again, it's important to note that this doesn't enable you to prove anything about the fullName string. From the circuit point of view, it simply doesn't exist!

Type parameters

• A

• T extends unknown = InferProvable\<A>

• V extends unknown = InferValue\<A>

• J extends unknown = InferJson\<A>

• Pure extends boolean = IsPure\<A>

Parameters

• type: A

Object specifying the layout of the Struct

Returns

(value: T) => T & { _isStruct: true; } & Pure extends true ? ProvablePure\<T, V> : Provable\<T, V> & { empty: () => T; fromJSON: (x: J) => T; fromValue: (value: From\<A>) => T; toInput: (x: T) => { fields: Field[]; packed: [Field, number][]; }; toJSON: (x: T) => J; }

Class which you can extend

Source

lib/provable/types/struct.ts:139