# State Structure

Core state is maintained using 2 data structures in the [`Commitments`](https://github.com/Railgun-Privacy/contract/blob/2afd011854daf35aad155a91d6bf2397e39ca90d/contracts/logic/Commitments.sol) contract:

1. An accumulator, in this case an incremental Merkle Tree.
2. A nullifier boolean mapping.

These values can be accessed through the [`merkleRoot`](https://github.com/Railgun-Privacy/contract/blob/2afd011854daf35aad155a91d6bf2397e39ca90d/contracts/logic/Commitments.sol#L39), [`rootHistory`](https://github.com/Railgun-Privacy/contract/blob/2afd011854daf35aad155a91d6bf2397e39ca90d/contracts/logic/Commitments.sol#L58), and [`nullifiers`](https://github.com/Railgun-Privacy/contract/blob/2afd011854daf35aad155a91d6bf2397e39ca90d/contracts/logic/Commitments.sol#L27) variables respectively.

New state objects (UTXOs) are appended to the Merkle Tree and emitted in contract events. Consumed state is invalidated by adding adding the nullifier to the mapping ensuring that old state can't be used twice without compromising privacy.

The contract maintains a mapping of the current and historical Merkle Tree roots so that proofs can be created against the Merkle Tree.

The RAILGUN contract verifies a a set of transaction circuits (JoinSplit with varying input and output UTXO counts) which are the only circuits allowed to write state changes.

External contracts have two primary means of adding functionality on top of the private state:

1. Using the Merkle Tree + nullifier set to generate read-only proofs.
2. Using the RAILGUN JoinSplit circuit with the adapt fields to add additional verification to state transitions.

These 2 ways of interacting with the core RAILGUN contracts can be combined to enable a number of use cases. Some examples are contained in the next section.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.railgun.org/developer-guide/engine-1/state-structure.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.