Skip to main content

SmartContract

o1js / Modules / SmartContract

Class: SmartContract

The main zkapp class. To write a zkapp, extend this class as such:

class YourSmartContract extends SmartContract {
// your smart contract code here
}

Table of contents

Constructors

Properties

Accessors

Methods

Constructors

constructor

new SmartContract(address, tokenId?)

Parameters

NameType
addressPublicKey
tokenId?Field

Defined in

lib/zkapp.ts:637

Properties

#_senderState

Private #_senderState: Object

Type declaration

NameType
senderPublicKey
transactionIdnumber

Defined in

lib/zkapp.ts:884


#executionState

Private #executionState: undefined | ExecutionState

Defined in

lib/zkapp.ts:604


address

address: PublicKey

Defined in

lib/zkapp.ts:601


events

events: Object = {}

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

Index signature

[key: string]: FlexibleProvablePure\<any>

Defined in

lib/zkapp.ts:995


tokenId

tokenId: Field

Defined in

lib/zkapp.ts:602


_maxProofsVerified

Static Optional _maxProofsVerified: 0 | 2 | 1

Defined in

lib/zkapp.ts:622


_methodMetadata

Static Optional _methodMetadata: Record\<string, { actions: number ; digest: string ; gates: Gate[] ; hasReturn: boolean ; rows: number }>

Defined in

lib/zkapp.ts:611


_methods

Static Optional _methods: MethodInterface[]

Defined in

lib/zkapp.ts:610


_provers

Static Optional _provers: Prover[]

Defined in

lib/zkapp.ts:621


_verificationKey

Static Optional _verificationKey: Object

Type declaration

NameType
datastring
hashField

Defined in

lib/zkapp.ts:623

Accessors

account

get account(): Account

Current account of the SmartContract.

Returns

Account

Defined in

lib/zkapp.ts:915


balance

get balance(): Object

Balance of this SmartContract.

Returns

Object

NameType
addInPlace(x: string | number | bigint | UInt64 | UInt32 | Int64) => void
subInPlace(x: string | number | bigint | UInt64 | UInt32 | Int64) => void

Defined in

lib/zkapp.ts:989


currentSlot

get currentSlot(): CurrentSlot

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

Defined in

lib/zkapp.ts:929


network

get network(): Network

Current network state of the SmartContract.

Returns

Network

Defined in

lib/zkapp.ts:921


self

get self(): AccountUpdate

Returns the current AccountUpdate associated to this SmartContract.

Returns

AccountUpdate

Defined in

lib/zkapp.ts:841


sender

get sender(): PublicKey

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.

Returns

PublicKey

Defined in

lib/zkapp.ts:894


token

get token(): Object

Token of the SmartContract.

Returns

Object

NameType
idField
parentTokenIdField
tokenOwnerPublicKey
burn(__namedParameters: { address: PublicKey | AccountUpdate | SmartContract ; amount: number | bigint | UInt64 }) => AccountUpdate
mint(__namedParameters: { address: PublicKey | AccountUpdate | SmartContract ; amount: number | bigint | UInt64 }) => AccountUpdate
send(__namedParameters: { amount: number | bigint | UInt64 ; from: PublicKey | AccountUpdate | SmartContract ; to: PublicKey | AccountUpdate | SmartContract }) => AccountUpdate

Defined in

lib/zkapp.ts:935


tokenSymbol

get tokenSymbol(): Object

Returns

Object

NameType
set(tokenSymbol: string) => void

Deprecated

use this.account.tokenSymbol

Defined in

lib/zkapp.ts:983

Methods

approve

approve(updateOrCallback, layout?): AccountUpdate

Approve an account update or callback. This will include the account update in the zkApp's public input, which means it allows you to read and use its content in a proof, make assertions about it, and modify it.

If this is called with a callback as the first parameter, it will first extract the account update produced by that callback. The extracted account update is returned.

\@method myApprovingMethod(callback: Callback) {
let approvedUpdate = this.approve(callback);
}

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. The second parameter layout allows you to also make assertions about the approved update's own children, by specifying a certain expected layout of children. See Layout.

Parameters

NameType
updateOrCallbackAccountUpdate | Callback\<any>
layout?AccountUpdatesLayout

Returns

AccountUpdate

The account update that was approved (needed when passing in a Callback)

Defined in

lib/zkapp.ts:961


deploy

deploy(«destructured»?): void

Deploys a SmartContract.

let tx = await Mina.transaction(sender, () => {
AccountUpdate.fundNewAccount(sender);
zkapp.deploy();
});
tx.sign([senderKey, zkAppKey]);

Parameters

NameType
«destructured»Object
› verificationKey?Object
› verificationKey.datastring
› verificationKey.hashstring | Field
› zkappKey?PrivateKey

Returns

void

Defined in

lib/zkapp.ts:725


emitEvent

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

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

Type parameters

NameType
Kextends string | number

Parameters

NameType
typeK
eventany

Returns

void

Defined in

lib/zkapp.ts:1001


fetchEvents

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

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

Parameters

NameTypeDescription
start?UInt32The start height of the events to fetch.
end?UInt32The 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.

Async

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);

Defined in

lib/zkapp.ts:1047


init

init(): void

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

Defined in

lib/zkapp.ts:796


newSelf

newSelf(methodName?): AccountUpdate

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

Parameters

NameType
methodName?string

Returns

AccountUpdate

Defined in

lib/zkapp.ts:876


requireSignature

requireSignature(): void

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

Defined in

lib/zkapp.ts:817


send

send(args): AccountUpdate

Parameters

NameType
argsObject
args.amountnumber | bigint | UInt64
args.toPublicKey | AccountUpdate | SmartContract

Returns

AccountUpdate

Defined in

lib/zkapp.ts:973


setPermissions

setPermissions(permissions): void

Parameters

NameType
permissionsPermissions

Returns

void

Deprecated

use this.account.permissions.set()

Defined in

lib/zkapp.ts:1227


setValue

setValue\<T>(maybeValue, value): void

Type parameters

Name
T

Parameters

NameType
maybeValueSetOrKeep\<T>
valueT

Returns

void

Deprecated

use this.account.<field>.set()

Defined in

lib/zkapp.ts:1220


sign

sign(zkappKey?): void

Parameters

NameType
zkappKey?PrivateKey

Returns

void

Deprecated

this.sign() is deprecated in favor of this.requireSignature()

Defined in

lib/zkapp.ts:823


skipAuthorization

skipAuthorization(): void

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

Defined in

lib/zkapp.ts:834


Proof

Static Proof(): typeof __class

Returns a Proof type that belongs to this SmartContract.

Returns

typeof __class

Defined in

lib/zkapp.ts:628


analyzeMethods

Static analyzeMethods(): Record\<string, { actions: number ; digest: string ; gates: Gate[] ; hasReturn: boolean ; rows: number }>

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.

Returns

Record\<string, { actions: number ; digest: string ; gates: Gate[] ; hasReturn: boolean ; 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
  • hasReturn a boolean indicating whether the method returns a value
  • actions the number of actions the method dispatches
  • gates the constraint system, represented as an array of gates

Defined in

lib/zkapp.ts:1167


compile

Static compile(«destructured»?): Promise\<{ provers: Prover[] ; verificationKey: { data: string ; hash: Field } ; verify: (statement: Statement\<FieldConst>, proof: unknown) => Promise\<boolean> }>

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

NameType
«destructured»Object
› cacheundefined | Cache
› forceRecompileundefined | boolean

Returns

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

Defined in

lib/zkapp.ts:664


digest

Static digest(): string

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

string

the digest, as a hex string

Defined in

lib/zkapp.ts:705


runOutsideCircuit

Static runOutsideCircuit(run): void

Parameters

NameType
run() => void

Returns

void

Defined in

lib/zkapp.ts:1141