Skip to main content
Version: 2.4.0

TokenContract

Defined in: lib/mina/v1/token/token-contract.ts:24

Base token contract which

  • implements the Approvable API, with the approveBase() method left to be defined by subclasses
  • implements the Transferable API as a wrapper around the Approvable API

Extends​

Constructors​

new TokenContract()​

new TokenContract(address: PublicKey, tokenId?: Field): TokenContract

Defined in: lib/mina/v1/zkapp.ts:552

Parameters​

address​

PublicKey

tokenId?​

Field

Returns​

TokenContract

Inherited from​

SmartContract.constructor

Properties​

address​

address: PublicKey;

Defined in: lib/mina/v1/zkapp.ts:517

Inherited from​

SmartContract.address

events​

events: {} = {};

Defined in: lib/mina/v1/zkapp.ts:925

A list of event types that can be emitted using this.emitEvent()`.

Index Signature​

[key: string]: FlexibleProvablePure<any>

Inherited from​

SmartContract.events

sender​

sender: {
  self: SmartContract;
  getAndRequireSignature: PublicKey;
  getUnconstrained: PublicKey;
};

Defined in: lib/mina/v1/zkapp.ts:817

self​

self: SmartContract;

getAndRequireSignature()​

Return a public key that is forced to sign this transaction.

Note: This doesn't prove that the return value is the transaction sender, but it proves that whoever created the transaction controls the private key associated with the returned public key.

Returns​

PublicKey

getUnconstrained()​

The public key of the current transaction's sender account.

Throws an error if not inside a transaction, or the sender wasn't passed in.

Warning: The fact that this public key equals the current sender is not part of the proof. A malicious prover could use any other public key without affecting the validity of the proof.

Consider using this.sender.getAndRequireSignature() if you need to prove that the sender controls this account.

Returns​

PublicKey

Inherited from​

SmartContract.sender

tokenId​

tokenId: Field;

Defined in: lib/mina/v1/zkapp.ts:518

Inherited from​

SmartContract.tokenId

_methodMetadata?​

static optional _methodMetadata: Record<string, {
  actions: number;
  digest: string;
  gates: Gate[];
  proofs: ProofClass[];
  rows: number;
}>;

Defined in: lib/mina/v1/zkapp.ts:527

Inherited from​

SmartContract._methodMetadata

_methods?​

static optional _methods: MethodInterface[];

Defined in: lib/mina/v1/zkapp.ts:526

Inherited from​

SmartContract._methods

_provers?​

static optional _provers: Prover[];

Defined in: lib/mina/v1/zkapp.ts:537

Inherited from​

SmartContract._provers

_verificationKey?​

static optional _verificationKey: {
  data: string;
  hash: Field;
};

Defined in: lib/mina/v1/zkapp.ts:538

data​

data: string;

hash​

hash: Field;

Inherited from​

SmartContract._verificationKey

MAX_ACCOUNT_UPDATES​

static MAX_ACCOUNT_UPDATES: number = 9;

Defined in: lib/mina/v1/token/token-contract.ts:29

The maximum number of account updates using the token in a single transaction that this contract supports.

Accessors​

account​

Get Signature​

get account(): Account

Defined in: lib/mina/v1/zkapp.ts:869

Current account of the SmartContract.

Returns​

Account

Inherited from​

SmartContract.account

balance​

Get Signature​

get balance(): {
  addInPlace: void;
  subInPlace: void;
}

Defined in: lib/mina/v1/zkapp.ts:919

Balance of this SmartContract.

Returns​
{
  addInPlace: void;
  subInPlace: void;
}
addInPlace()​
Parameters​
x​

string | number | bigint | UInt64 | UInt32 | Int64

Returns​

void

subInPlace()​
Parameters​
x​

string | number | bigint | UInt64 | UInt32 | Int64

Returns​

void

Inherited from​

SmartContract.balance

currentSlot​

Get Signature​

get currentSlot(): CurrentSlot

Defined in: lib/mina/v1/zkapp.ts:883

Current global slot on the network. This is the slot at which this transaction is included in a block. Since we cannot know this value at the time of transaction construction, this only has the assertBetween() method but no get() (impossible to implement) or assertEquals() (confusing, because the developer can't know the exact slot at which this will be included either)

Returns​

CurrentSlot

Inherited from​

SmartContract.currentSlot

internal​

Get Signature​

get internal(): {
  burn: AccountUpdate;
  mint: AccountUpdate;
  send: AccountUpdate;
}

Defined in: lib/mina/v1/token/token-contract.ts:77

Helper methods to use from within a token contract.

Returns​
{
  burn: AccountUpdate;
  mint: AccountUpdate;
  send: AccountUpdate;
}
burn()​

Burn token balance on address. Returns the burn account update.

Parameters​
__namedParameters​
address​

| PublicKey | AccountUpdate | SmartContract

amount​

number | bigint | UInt64

Returns​

AccountUpdate

mint()​

Mints token balance to address. Returns the mint account update.

Parameters​
__namedParameters​
address​

| PublicKey | AccountUpdate | SmartContract

amount​

number | bigint | UInt64

Returns​

AccountUpdate

send()​

Move token balance from from to to. Returns the to account update.

Parameters​
__namedParameters​
amount​

number | bigint | UInt64

from​

| PublicKey | AccountUpdate | SmartContract

to​

| PublicKey | AccountUpdate | SmartContract

Returns​

AccountUpdate

network​

Get Signature​

get network(): Network

Defined in: lib/mina/v1/zkapp.ts:875

Current network state of the SmartContract.

Returns​

Network

Inherited from​

SmartContract.network

self​

Get Signature​

get self(): AccountUpdate

Defined in: lib/mina/v1/zkapp.ts:775

Returns the current AccountUpdate associated to this SmartContract.

Returns​

AccountUpdate

Inherited from​

SmartContract.self

Methods​

approve()​

approve(update: 
  | AccountUpdate
  | AccountUpdateTree
  | AccountUpdateForest): void

Defined in: lib/mina/v1/zkapp.ts:908

Approve an account update or tree / forest of updates. Doing this means you include the account update in the zkApp's public input, which allows you to read and use its content in a proof, make assertions about it, and modify it.

`@method` myApprovingMethod(update: AccountUpdate) {
  this.approve(update);

  // read balance on the account (for example)
  let balance = update.account.balance.getAndRequireEquals();
}

Under the hood, "approving" just means that the account update is made a child of the zkApp in the tree of account updates that forms the transaction. Similarly, if you pass in an AccountUpdateTree, the entire tree will become a subtree of the zkApp's account update.

Passing in a forest is a bit different, because it means you set the entire children of the zkApp's account update at once. approve() will fail if the zkApp's account update already has children, to prevent you from accidentally excluding important information from the public input.

Parameters​

update​

AccountUpdate | AccountUpdateTree | AccountUpdateForest

Returns​

void

Inherited from​

SmartContract.approve

approveAccountUpdate()​

approveAccountUpdate(accountUpdate: 
  | AccountUpdate
| AccountUpdateTree): Promise<void>

Defined in: lib/mina/v1/token/token-contract.ts:137

Approve a single account update (with arbitrarily many children).

Parameters​

accountUpdate​

AccountUpdate | AccountUpdateTree

Returns​

Promise<void>

approveAccountUpdates()​

approveAccountUpdates(accountUpdates: (
  | AccountUpdate
| AccountUpdateTree)[]): Promise<void>

Defined in: lib/mina/v1/token/token-contract.ts:145

Approve a list of account updates (with arbitrarily many children).

Parameters​

accountUpdates​

( | AccountUpdate | AccountUpdateTree)[]

Returns​

Promise<void>

approveBase()​

abstract approveBase(forest: AccountUpdateForest): Promise<void>

Defined in: lib/mina/v1/token/token-contract.ts:84

Parameters​

forest​

AccountUpdateForest

Returns​

Promise<void>

checkZeroBalanceChange()​

checkZeroBalanceChange(updates: AccountUpdateForest): void

Defined in: lib/mina/v1/token/token-contract.ts:121

Use forEachUpdate() to prove that the total balance change of child account updates is zero.

This is provided out of the box as it is both a good example, and probably the most common implementation, of approveBase().

Parameters​

updates​

AccountUpdateForest

Returns​

void

deploy()​

deploy(args?: DeployArgs): Promise<void>

Defined in: lib/mina/v1/token/token-contract.ts:52

Deploys a TokenContract.

In addition to base smart contract deployment, this adds two steps:

  • set the access permission to proofOrSignature(), to prevent against unauthorized token operations
    • not doing this would imply that anyone can bypass token contract authorization and simply mint themselves tokens
  • require the zkapp account to be new, using the isNew precondition. this guarantees that the access permission is set from the very start of the existence of this account. creating the zkapp account before deployment would otherwise be a security vulnerability that is too easy to introduce.

Note that because of the isNew precondition, the zkapp account must not be created prior to calling deploy().

If the contract needs to be re-deployed, you can switch off this behaviour by overriding the isNew precondition:

async deploy() {
  await super.deploy();
  // DON'T DO THIS ON THE INITIAL DEPLOYMENT!
  this.account.isNew.requireNothing();
}

Parameters​

args?​

DeployArgs

Returns​

Promise<void>

Overrides​

SmartContract.deploy

deriveTokenId()​

deriveTokenId(): Field

Defined in: lib/mina/v1/token/token-contract.ts:70

Returns the tokenId of the token managed by this contract.

Returns​

Field

emitEvent()​

emitEvent<K>(type: K, event: any): void

Defined in: lib/mina/v1/zkapp.ts:972

Emits an event. Events will be emitted as a part of the transaction and can be collected by archive nodes.

Type Parameters​

• K extends string | number

Parameters​

type​

K

event​

any

Returns​

void

Inherited from​

SmartContract.emitEvent

emitEventIf()​

emitEventIf<K>(
   condition: Bool, 
   type: K, 
   event: any): void

Defined in: lib/mina/v1/zkapp.ts:933

Conditionally emits an event.

Events will be emitted as a part of the transaction and can be collected by archive nodes.

Type Parameters​

• K extends string | number

Parameters​

condition​

Bool

type​

K

event​

any

Returns​

void

Inherited from​

SmartContract.emitEventIf

fetchEvents()​

fetchEvents(start?: UInt32, end?: UInt32): Promise<{
  blockHash: string;
  blockHeight: UInt32;
  chainStatus: string;
  event: {
     data: ProvablePure<any>;
     transactionInfo: {
        transactionHash: string;
        transactionMemo: string;
        transactionStatus: string;
       };
    };
  globalSlot: UInt32;
  parentBlockHash: string;
  type: string;
}[]>

Defined in: lib/mina/v1/zkapp.ts:988

Asynchronously fetches events emitted by this SmartContract and returns an array of events with their corresponding types.

Parameters​

start?​

UInt32 = ...

The start height of the events to fetch.

end?​

UInt32

The end height of the events to fetch. If not provided, fetches events up to the latest height.

Returns​

Promise<{ blockHash: string; blockHeight: UInt32; chainStatus: string; event: { data: ProvablePure<any>; transactionInfo: { transactionHash: string; transactionMemo: string; transactionStatus: string; }; }; globalSlot: UInt32; parentBlockHash: string; type: string; }[]>

A promise that resolves to an array of objects, each containing the event type and event data for the specified range.

Throws​

If there is an error fetching events from the Mina network.

Example​

const startHeight = UInt32.from(1000);
const endHeight = UInt32.from(2000);
const events = await myZkapp.fetchEvents(startHeight, endHeight);
console.log(events);

Inherited from​

SmartContract.fetchEvents

forEachUpdate()​

forEachUpdate(updates: AccountUpdateForest, callback: (update: AccountUpdate, usesToken: Bool) => void): void

Defined in: lib/mina/v1/token/token-contract.ts:91

Iterate through the account updates in updates and apply callback to each.

This method is provable and is suitable as a base for implementing approveUpdates().

Parameters​

updates​

AccountUpdateForest

callback​

(update: AccountUpdate, usesToken: Bool) => void

Returns​

void

init()​

init(): void

Defined in: lib/mina/v1/zkapp.ts:723

SmartContract.init() will be called only when a SmartContract will be first deployed, not for redeployment. This method can be overridden as follows

class MyContract extends SmartContract {
 init() {
   super.init();
   this.account.permissions.set(...);
   this.x.set(Field(1));
 }
}

Returns​

void

Inherited from​

SmartContract.init

newSelf()​

newSelf(methodName?: string): AccountUpdate

Defined in: lib/mina/v1/zkapp.ts:807

Same as SmartContract.self but explicitly creates a new AccountUpdate.

Parameters​

methodName?​

string

Returns​

AccountUpdate

Inherited from​

SmartContract.newSelf

requireSignature()​

requireSignature(): void

Defined in: lib/mina/v1/zkapp.ts:756

Use this command if the account update created by this SmartContract should be signed by the account owner, instead of authorized with a proof.

Note that the smart contract's Permissions determine which updates have to be (can be) authorized by a signature.

If you only want to avoid creating proofs for quicker testing, we advise you to use LocalBlockchain({ proofsEnabled: false }) instead of requireSignature(). Setting proofsEnabled to false allows you to test your transactions with the same authorization flow as in production, with the only difference being that quick mock proofs are filled in instead of real proofs.

Returns​

void

Inherited from​

SmartContract.requireSignature

send()​

send(args: {
  amount: number | bigint | UInt64;
  to:   | PublicKey
     | AccountUpdate
     | SmartContract;
 }): AccountUpdate

Defined in: lib/mina/v1/zkapp.ts:912

Parameters​

args​
amount​

number | bigint | UInt64

to​

| PublicKey | AccountUpdate | SmartContract

Returns​

AccountUpdate

Inherited from​

SmartContract.send

skipAuthorization()​

skipAuthorization(): void

Defined in: lib/mina/v1/zkapp.ts:768

Use this command if the account update created by this SmartContract should have no authorization on it, instead of being authorized with a proof.

WARNING: This is a method that should rarely be useful. If you want to disable proofs for quicker testing, take a look at LocalBlockchain({ proofsEnabled: false }), which causes mock proofs to be created and doesn't require changing the authorization flow.

Returns​

void

Inherited from​

SmartContract.skipAuthorization

transfer()​

transfer(
   from: PublicKey | AccountUpdate, 
   to: PublicKey | AccountUpdate, 
amount: number | bigint | UInt64): Promise<void>

Defined in: lib/mina/v1/token/token-contract.ts:155

Transfer amount of tokens from from to to.

Parameters​

from​

PublicKey | AccountUpdate

to​

PublicKey | AccountUpdate

amount​

number | bigint | UInt64

Returns​

Promise<void>

analyzeMethods()​

static analyzeMethods(__namedParameters: {
  printSummary: boolean;
 }): Promise<Record<string, {
  actions: number;
  digest: string;
  gates: Gate[];
  proofs: ProofClass[];
  rows: number;
}>>

Defined in: lib/mina/v1/zkapp.ts:1108

This function is run internally before compiling a smart contract, to collect metadata about what each of your smart contract methods does.

For external usage, this function can be handy because calling it involves running all methods in the same "mode" as compile() does, so it serves as a quick-to-run check for whether your contract can be compiled without errors, which can greatly speed up iterating.

analyzeMethods() will also return the number of rows of each of your method circuits (i.e., the number of constraints in the underlying proof system), which is a good indicator for circuit size and the time it will take to create proofs. To inspect the created circuit in detail, you can look at the returned gates.

Note: If this function was already called before, it will short-circuit and just return the metadata collected the first time.

Parameters​

__namedParameters​
printSummary​

boolean = false

Returns​

Promise<Record<string, { actions: number; digest: string; gates: Gate[]; proofs: ProofClass[]; rows: number; }>>

an object, keyed by method name, each entry containing:

  • rows the size of the constraint system created by this method
  • digest a digest of the method circuit
  • actions the number of actions the method dispatches
  • gates the constraint system, represented as an array of gates

Inherited from​

SmartContract.analyzeMethods

compile()​

static compile(__namedParameters: {
  cache: Cache;
  forceRecompile: boolean;
 }): Promise<{
  provers: Prover[];
  verificationKey: {
     data: string;
     hash: Field;
    };
  verify: (statement: Statement<FieldConst>, proof: unknown) => Promise<boolean>;
}>

Defined in: lib/mina/v1/zkapp.ts:580

Compile your smart contract.

This generates both the prover functions, needed to create proofs for running @methods, and the verification key, needed to deploy your zkApp.

Although provers and verification key are returned by this method, they are also cached internally and used when needed, so you don't actually have to use the return value of this function.

Under the hood, "compiling" means calling into the lower-level Pickles and Kimchi libraries to create multiple prover & verifier indices (one for each smart contract method as part of a "step circuit" and one for the "wrap circuit" which recursively wraps it so that proofs end up in the original finite field). These are fairly expensive operations, so expect compiling to take at least 20 seconds, up to several minutes if your circuit is large or your hardware is not optimal for these operations.

Parameters​

__namedParameters​
cache​

Cache = Cache.FileSystemDefault

forceRecompile​

boolean = false

Returns​

Promise<{ provers: Prover[]; verificationKey: { data: string; hash: Field; }; verify: (statement: Statement<FieldConst>, proof: unknown) => Promise<boolean>; }>

Inherited from​

SmartContract.compile

digest()​

static digest(): Promise<string>

Defined in: lib/mina/v1/zkapp.ts:621

Computes a hash of your smart contract, which will reliably change whenever one of your method circuits changes. This digest is quick to compute. it is designed to help with deciding whether a contract should be re-compiled or a cached verification key can be used.

Returns​

Promise<string>

the digest, as a hex string

Inherited from​

SmartContract.digest

getMaxProofsVerified()​

static getMaxProofsVerified(): Promise<0 | 1 | 2>

Defined in: lib/mina/v1/zkapp.ts:632

The maximum number of proofs that are verified by any of the zkApp methods. This is an internal parameter needed by the proof system.

Returns​

Promise<0 | 1 | 2>

Inherited from​

SmartContract.getMaxProofsVerified

Proof()​

static Proof(): typeof __class

Defined in: lib/mina/v1/zkapp.ts:543

Returns a Proof type that belongs to this SmartContract.

Returns​

typeof __class

Inherited from​

SmartContract.Proof

runOutsideCircuit()​

static runOutsideCircuit(run: () => void): void

Defined in: lib/mina/v1/zkapp.ts:1084

Parameters​

run​

() => void

Returns​

void

Inherited from​

SmartContract.runOutsideCircuit

setVerificationKeyUnsafe()​

static setVerificationKeyUnsafe(verificationKey: {
  data: string;
  hash: string | Field;
 }): void

Defined in: lib/mina/v1/zkapp.ts:640

Manually set the verificaiton key.

Parameters​

verificationKey​
data​

string

hash​

string | Field

Returns​

void

Inherited from​

SmartContract.setVerificationKeyUnsafe