> For the complete documentation index, see [llms.txt](https://docs.midnight.network/llms.txt)

# ZK Loan tests

The [contract](https://docs.midnight.network/tutorials/zk-loan/smart-contract.md) and the [attestation API](https://docs.midnight.network/tutorials/zk-loan/attestation-api.md) only prove their worth together, on a real chain, with real proofs. This part walks through `src/test/zk-loan.test.ts`. It deploys the contract to a local devnet, registers the attestation API's key, takes out loans for two borrowers, and tries the attacks the contract defends against: tampered credit data, a non-admin acting as admin, a blacklisted borrower, and an admin who has handed over the role.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

* The [ZK Loan contract](https://docs.midnight.network/tutorials/zk-loan/smart-contract.md) and [Attestation API](https://docs.midnight.network/tutorials/zk-loan/attestation-api.md) parts of this tutorial.
* Docker, running, for the local devnet.

## Run the suite[​](#run-the-suite "Direct link to Run the suite")

From `examples/zk-loan`, start the local network, wait until the test wallet has DUST to pay fees with, and run the tests:

```
npm run env:up

npm run wait:dust

npm run test:local
```

`npm run env:up` starts a Midnight node, an indexer, and a proof server from `compose.yml`. Leave them running while you work through this page. You don't start the attestation API yourself: the suite starts its own copy in-process. Every successful call generates a real proof, so expect the suite to take several minutes.

When it finishes, all 20 tests pass: the 10 on-chain tests, including the ones that expect a rejection, and the attestation API's 10 unit tests:

```
 ✓ src/test/attestation-api/server.test.ts (4 tests)

 ✓ src/test/attestation-api/signing.test.ts (6 tests)

 ✓ src/test/zk-loan.test.ts (10 tests)

     ✓ deploys the contract with the deployer as admin

     ✓ lets the admin register the attestation API's public key

     ✓ approves a Tier 1 loan within the limit

     ✓ proposes a capped amount when the request exceeds the tier, and the borrower accepts

     ✓ records a Tier 2 loan for a second borrower under a separate identity

     ✓ blocks a blacklisted borrower until the admin removes them

     ✓ migrates all loans to the identity derived from a new PIN

     ✓ rotates the admin role to a new admin public key



 Test Files  3 passed (3)

      Tests  20 passed (20)
```

Vitest lists only tests that take longer than 300 ms, so the two tests that expect nothing but a rejection, a non-admin registering a provider and tampered credit data, pass without a line of their own. Run it and the timings tell you something: each successful call takes many seconds, most of it generating a proof, so the tests with two successful calls take about twice as long. Exact times vary from machine to machine. A rejected call fails in well under a second. A failing `assert` stops the circuit on the caller's own machine, so no proof is generated and nothing is submitted.

Tear the network down when you're done:

```
npm run env:down
```

## The test harness[​](#the-test-harness "Direct link to The test harness")

Everything above the line `// Everything above is generated boilerplate. Your tests begin here.` in the test file is the test harness. Most of it is the same in every example in midnight-examples:

* **`src/config.ts`** holds the endpoints for each network. `MIDNIGHT_NETWORK` picks one: `npm run test:local` sets it to `local`, and `npm run test:preview` and `npm run test:preprod` run the same suite against the public test networks.
* **`resolveWallet(network)`**, in `src/wallet.ts`, returns the wallet secret. On `local` it is the devnet's pre-funded wallet, so there is nothing to set up. On a remote network it comes from a repo-root `.env.<network>` file.
* **`src/wallet.ts`** builds, starts, and syncs the wallet. **`src/providers.ts`** bundles the MidnightJS providers a party needs: public data from the indexer, private state, ZK artifacts and proving, and the wallet itself. MidnightJS 5 takes the wallet through `createLedger9WalletProvider` and `createLedger9MidnightProvider`, and the bundle carries a `config` with the network ID and the transaction time-to-live.

### One wallet, two identities[​](#one-wallet-two-identities "Direct link to One wallet, two identities")

Unlike Battleship, this suite has one wallet. It only pays fees. The two parties, Alice and Bob, are two private states, each with its own 32-byte secret:

src/test/zk-loan.test.ts

```
// Both parties share ONE wallet (it only pays fees). Their contract identities

// live in separate private states, each holding its own 32-byte userSecretKey —

// which is the point: in this contract identity comes from the witness secret,

// not from the wallet that submits the transaction.

const ALICE_STATE_ID = 'AliceZkLoanState'; // deployer => admin, and a borrower

const BOB_STATE_ID = 'BobZkLoanState'; // a second borrower, not admin



const PROVIDER_ID = 1n; // the id the attestation API is started with

const ALICE_PIN = 1234n;

const ALICE_NEW_PIN = 5678n;

const BOB_PIN = 4321n;
```

That is the contract's identity model at work. A party is whoever's secret the witness presents, not whichever wallet submits the transaction.

### The attestation provider[​](#the-attestation-provider "Direct link to The attestation provider")

`beforeAll` builds and syncs the wallet and the providers, then starts the real attestation API from `attestation-api/server.ts` on a free port, with a fresh key, as `npm run attestation:start` does without `PROVIDER_SECRET_KEY`:

src/test/zk-loan.test.ts

```
    // Fresh ephemeral provider key per run, like `npm run attestation:start`

    // without PROVIDER_SECRET_KEY.

    attestationServer = createServer(generateKeyPair().sk, Number(PROVIDER_ID));

    await new Promise<void>((resolve) => attestationServer.listen(0, '127.0.0.1', resolve));

    const addr = attestationServer.address();

    attestationUrl = `http://127.0.0.1:${typeof addr === 'string' ? addr : addr.port}`;

    logger.info(`Attestation API at ${attestationUrl}`);
```

The two secrets are random per run:

src/test/zk-loan.test.ts

```
  const aliceSecret = new Uint8Array(randomBytes(32));

  const bobSecret = new Uint8Array(randomBytes(32));



  // Off-chain mirror of `deriveUserPublicKey` — the same pure circuit, so the

  // bytes match what the contract computes in-circuit.

  const userPk = (secret: Uint8Array, pin: bigint): Uint8Array =>

    pureCircuits.deriveUserPublicKey(secret, pin);
```

`userPk` calls the contract's own pure circuit, so the test derives exactly the key the contract derives in-circuit, and can look loans up by it.

### Helpers[​](#helpers "Direct link to Helpers")

`attestedState` is the borrower's half of the [attestation flow](https://docs.midnight.network/tutorials/zk-loan/attestation-api.md#the-attestation-flow). It hashes the borrower's derived key, asks the API to sign the profile against that hash, and builds the private state the witnesses present:

src/test/zk-loan.test.ts

```
  async function attestedState(

    secret: Uint8Array,

    pin: bigint,

    creditScore: number,

    monthlyIncome: number,

    monthsAsCustomer: number,

  ): Promise<ZkLoanPrivateState> {

    const userPubKeyHash = transientHash(bytes32, userPk(secret, pin));

    const res = await fetch(`${attestationUrl}/attest`, {

      method: 'POST',

      headers: { 'Content-Type': 'application/json' },

      body: JSON.stringify({

        creditScore,

        monthlyIncome,

        monthsAsCustomer,

        userPubKeyHash: userPubKeyHash.toString(),

      }),

    });

    expect(res.status).toBe(200);

    const { signature } = (await res.json()) as AttestationResponse;

    return {

      creditScore: BigInt(creditScore),

      monthlyIncome: BigInt(monthlyIncome),

      monthsAsCustomer: BigInt(monthsAsCustomer),

      // JSON carries bigints as decimal strings.

      attestationSignature: {

        announcement: { x: BigInt(signature.announcement.x), y: BigInt(signature.announcement.y) },

        response: BigInt(signature.response),

      },

      attestationProviderId: PROVIDER_ID,

      userSecretKey: secret,

    };

  }
```

Only the hash leaves the test. The API never sees the secret or the PIN.

Two more helpers keep each step short. `setPrivateState` stores a party's private state for the deployed contract, and `call` wraps `submitCallTx`, the MidnightJS function that calls a circuit on a deployed contract:

src/test/zk-loan.test.ts

```
  async function setPrivateState(id: string, state: ZkLoanPrivateState): Promise<void> {

    await providers.privateStateProvider.forContract(contractAddress).set(id, state);

  }



  // Thin wrapper over submitCallTx so each step reads as the circuit call it is.

  async function call<K extends ZkLoanCircuitId>(

    privateStateId: string,

    circuitId: K,

    ...args: CircuitArgs<K>

  ) {

    return submitCallTx(providers, {

      compiledContract: CompiledZkLoanContract,

      contractAddress,

      privateStateId,

      circuitId,

      args,

    } as any);

  }
```

A helper also reads the contract's public ledger, and the tests use it after every call. `ledgerState`, from `src/providers.ts`, decodes the era-tagged state that MidnightJS 5 returns (`read.contractState`, ledger 9 here) into the data the compiled `ledger()` decodes:

src/test/zk-loan.test.ts

```
  async function queryLedger() {

    const state = await providers.publicDataProvider.queryContractState(contractAddress);

    expect(state).not.toBeNull();

    return ledger(ledgerState(state));

  }
```

## Setting up the contract[​](#setting-up-the-contract "Direct link to Setting up the contract")

### Alice deploys[​](#alice-deploys "Direct link to Alice deploys")

Alice deploys with a private state that holds only her secret. That is all the constructor needs:

src/test/zk-loan.test.ts

```
  it('deploys the contract with the deployer as admin', async () => {

    const deployed: DeployedContract<Contract> = await deployContract(providers, {

      compiledContract: CompiledZkLoanContract,

      privateStateId: ALICE_STATE_ID,

      initialPrivateState: createZkLoanPrivateState(aliceSecret),

    });



    contractAddress = deployed.deployTxData.public.contractAddress;

    logger.info(`Contract deployed at: ${contractAddress}`);

    expect(contractAddress).toBeDefined();

    expect(contractAddress.length).toBeGreaterThan(0);



    const state = await queryLedger();

    // Only the derived admin PUBLIC key is on-chain — never the secret.

    expect(state.contractAdmin).toEqual(pureCircuits.deriveAdminPublicKey(aliceSecret));

    expect(state.loans.isEmpty()).toBe(true);

    expect(state.providers.isEmpty()).toBe(true);

  });
```

`deployContract` takes the providers, the compiled contract from `contract/index.ts`, and the private state ID and initial private state. It stores the private state under `ALICE_STATE_ID`.

The checks show the constructor's effect: `contractAdmin` holds the hash of Alice's secret, computed off-chain here with the same pure circuit, and the secret itself is nowhere on the ledger.

### Registering the provider[​](#registering-the-provider "Direct link to Registering the provider")

Alice reads the API's key from `/provider-info` and registers it:

src/test/zk-loan.test.ts

```
  it("lets the admin register the attestation API's public key", async () => {

    const res = await fetch(`${attestationUrl}/provider-info`);

    expect(res.status).toBe(200);

    const info = (await res.json()) as ProviderInfoResponse;

    expect(BigInt(info.providerId)).toEqual(PROVIDER_ID);

    const providerPk = { x: BigInt(info.publicKey.x), y: BigInt(info.publicKey.y) };



    await call(ALICE_STATE_ID, 'registerProvider', PROVIDER_ID, providerPk);



    const state = await queryLedger();

    expect(state.providers.member(PROVIDER_ID)).toBe(true);

    const pk = state.providers.lookup(PROVIDER_ID);

    expect(pk.x).toEqual(providerPk.x);

    expect(pk.y).toEqual(providerPk.y);

  });
```

### A non-admin tries to register a provider[​](#a-non-admin-tries-to-register-a-provider "Direct link to A non-admin tries to register a provider")

Bob gets a private state with his own secret, and tries to register a provider of his own. The call is wrapped in `expect(...).rejects.toThrow()`, which passes only if the call fails:

src/test/zk-loan.test.ts

```
  it('rejects provider registration by a non-admin', async () => {

    await setPrivateState(BOB_STATE_ID, createZkLoanPrivateState(bobSecret));

    // Fails while building the proof: Bob's secret does not hash to contractAdmin.

    await expect(

      call(BOB_STATE_ID, 'registerProvider', 2n, generateKeyPair().pk),

    ).rejects.toThrow();

    expect((await queryLedger()).providers.member(2n)).toBe(false);

  });
```

Bob's secret doesn't hash to `contractAdmin`, so the guard fails while the proof is built, on Bob's own machine. Nothing is submitted, and the ledger has no provider 2.

Asserting on the ledger after a rejected call matters. It shows that the attack had no effect, not merely that it threw.

## Borrowing[​](#borrowing "Direct link to Borrowing")

### A Tier 1 loan[​](#a-tier-1-loan "Direct link to A Tier 1 loan")

Alice gets her profile signed (a score of 720, an income of 2,500, and 24 months as a customer) and asks for 5,000:

src/test/zk-loan.test.ts

```
  it('approves a Tier 1 loan within the limit', async () => {

    // Tier 1: score >= 700, income >= 2000, tenure >= 24 => up to 10,000.

    await setPrivateState(ALICE_STATE_ID, await attestedState(aliceSecret, ALICE_PIN, 720, 2500, 24));

    await call(ALICE_STATE_ID, 'requestLoan', 5000n, ALICE_PIN);



    const state = await queryLedger();

    const aliceKey = userPk(aliceSecret, ALICE_PIN);

    expect(state.loans.member(aliceKey)).toBe(true);

    const loan = state.loans.lookup(aliceKey).lookup(1n);

    expect(loan.status).toEqual(LoanStatus.Approved);

    expect(loan.authorizedAmount).toEqual(5000n);

  });
```

The profile meets Tier 1, which allows up to 10,000, so the loan is `Approved` for the full 5,000. It is loan 1 under Alice's derived key. The ledger holds the status and the amount, and nothing about the profile.

### A capped proposal[​](#a-capped-proposal "Direct link to A capped proposal")

Alice asks for 15,000, more than Tier 1 allows:

src/test/zk-loan.test.ts

```
  it('proposes a capped amount when the request exceeds the tier, and the borrower accepts', async () => {

    await call(ALICE_STATE_ID, 'requestLoan', 15000n, ALICE_PIN);



    const aliceKey = userPk(aliceSecret, ALICE_PIN);

    let loan = (await queryLedger()).loans.lookup(aliceKey).lookup(2n);

    expect(loan.status).toEqual(LoanStatus.Proposed);

    expect(loan.authorizedAmount).toEqual(10000n);



    await call(ALICE_STATE_ID, 'respondToLoan', 2n, ALICE_PIN, true);



    loan = (await queryLedger()).loans.lookup(aliceKey).lookup(2n);

    expect(loan.status).toEqual(LoanStatus.Approved);

    expect(loan.authorizedAmount).toEqual(10000n);

  });
```

The contract records loan 2 as `Proposed` at the tier's maximum, 10,000. Alice accepts with `respondToLoan`, and the loan becomes `Approved`. Her private state still holds the same signed profile, so this call needs no new attestation.

### Tampered credit data[​](#tampered-credit-data "Direct link to Tampered credit data")

Bob gets a profile signed honestly, a score of 650, then inflates the score to 800 in his private state before he applies:

src/test/zk-loan.test.ts

```
  it('rejects a request whose credit data was tampered with after signing', async () => {

    const signed = await attestedState(bobSecret, BOB_PIN, 650, 1600, 10);

    // Bob inflates his score; the provider's signature no longer matches.

    await setPrivateState(BOB_STATE_ID, { ...signed, creditScore: 800n });

    await expect(call(BOB_STATE_ID, 'requestLoan', 5000n, BOB_PIN)).rejects.toThrow();

    expect((await queryLedger()).loans.member(userPk(bobSecret, BOB_PIN))).toBe(false);

  });
```

With a score of 800, Bob would qualify for more. But the signature covers the score the provider signed, 650. Inside `requestLoan`, `evaluateApplicant` rebuilds the message from the witness's profile, and `schnorrVerify` fails on it. No proof, no transaction, and no loans under Bob's key.

### A Tier 2 loan, declined[​](#a-tier-2-loan-declined "Direct link to A Tier 2 loan, declined")

Bob applies again with his honest, signed profile, for 9,000:

src/test/zk-loan.test.ts

```
  it('records a Tier 2 loan for a second borrower under a separate identity', async () => {

    // Tier 2: score >= 600, income >= 1500 => up to 7,000.

    await setPrivateState(BOB_STATE_ID, await attestedState(bobSecret, BOB_PIN, 650, 1600, 10));

    await call(BOB_STATE_ID, 'requestLoan', 9000n, BOB_PIN);



    const state = await queryLedger();

    const loan = state.loans.lookup(userPk(bobSecret, BOB_PIN)).lookup(1n);

    expect(loan.status).toEqual(LoanStatus.Proposed);

    expect(loan.authorizedAmount).toEqual(7000n);

    // Bob declines the lower offer.

    await call(BOB_STATE_ID, 'respondToLoan', 1n, BOB_PIN, false);

    const declined = (await queryLedger()).loans.lookup(userPk(bobSecret, BOB_PIN)).lookup(1n);

    expect(declined.status).toEqual(LoanStatus.NotAccepted);

    expect(declined.authorizedAmount).toEqual(0n);

  });
```

A score of 650 and an income of 1,600 meet Tier 2, which allows up to 7,000. So the loan is `Proposed` at 7,000. Bob declines, and the loan becomes `NotAccepted` with an amount of 0.

Bob's loan is loan 1 under *his* key, in the same contract as Alice's two. Each borrower's loans live under their own derived key.

## Admin actions[​](#admin-actions "Direct link to Admin actions")

### The blacklist[​](#the-blacklist "Direct link to The blacklist")

Alice blacklists Bob by his derived key, and Bob's next request is rejected. Then she lifts the ban:

src/test/zk-loan.test.ts

```
  it('blocks a blacklisted borrower until the admin removes them', async () => {

    const bobKey = userPk(bobSecret, BOB_PIN);

    await call(ALICE_STATE_ID, 'blacklistUser', bobKey);

    expect((await queryLedger()).blacklist.member(bobKey)).toBe(true);



    await expect(call(BOB_STATE_ID, 'requestLoan', 1000n, BOB_PIN)).rejects.toThrow();



    await call(ALICE_STATE_ID, 'removeBlacklistUser', bobKey);

    expect((await queryLedger()).blacklist.member(bobKey)).toBe(false);

  });
```

The admin can blacklist Bob because his key is on the ledger: it is the key of his loans.

### Changing a PIN[​](#changing-a-pin "Direct link to Changing a PIN")

Alice moves to a new PIN:

src/test/zk-loan.test.ts

```
  it('migrates all loans to the identity derived from a new PIN', async () => {

    const oldKey = userPk(aliceSecret, ALICE_PIN);

    const newKey = userPk(aliceSecret, ALICE_NEW_PIN);



    // Alice has 2 loans, below the batch size of 5, so one call finishes.

    await call(ALICE_STATE_ID, 'changePin', ALICE_PIN, ALICE_NEW_PIN);



    const state = await queryLedger();

    expect(state.loans.member(oldKey)).toBe(false);

    expect(state.onGoingPinMigration.member(oldKey)).toBe(false);

    const migrated = state.loans.lookup(newKey);

    expect(migrated.size()).toEqual(2n);

    expect(migrated.lookup(1n).authorizedAmount).toEqual(5000n);

    expect(migrated.lookup(2n).authorizedAmount).toEqual(10000n);

  });
```

Alice has two loans, fewer than the batch size of five, so one `changePin` call moves both and clears the migration cursor. Her old key is gone from `loans`, and her loans are now under the new key. The `changePin` transaction names both keys, though, so anyone watching the chain can link them.

### Handing over the admin role[​](#handing-over-the-admin-role "Direct link to Handing over the admin role")

Alice hands the admin role to Bob. Bob derives his admin key off-chain with the pure circuit, and only that public key reaches the contract:

src/test/zk-loan.test.ts

```
  it('rotates the admin role to a new admin public key', async () => {

    const bobAdminPk = pureCircuits.deriveAdminPublicKey(bobSecret);

    await call(ALICE_STATE_ID, 'rotateAdmin', bobAdminPk);

    expect((await queryLedger()).contractAdmin).toEqual(bobAdminPk);



    // The old admin is now locked out; the new one can act.

    await expect(call(ALICE_STATE_ID, 'removeProvider', PROVIDER_ID)).rejects.toThrow();

    await call(BOB_STATE_ID, 'removeProvider', PROVIDER_ID);

    expect((await queryLedger()).providers.member(PROVIDER_ID)).toBe(false);

  });
```

Alice is locked out at once: her secret no longer hashes to `contractAdmin`, so her `removeProvider` call is rejected. Bob's succeeds.

## Test yourself[​](#test-yourself "Direct link to Test yourself")

The suite checks some of the contract's defenses, not all of them. Add a test for each of these, using the patterns above:

* Bob reuses Alice's signed profile: copy her `attestationSignature` into his private state and request a loan. Which check stops him?
* Alice responds to a loan that isn't `Proposed`, such as her loan 1.
* A borrower with a score of 550 applies. What does the ledger record?
* Alice calls `requestLoan` with an amount of 0.
* After Bob is blacklisted, he tries `changePin` to escape to a new identity.

For each rejection, assert on the ledger afterwards too, to show the call changed nothing.

The full test file is [`src/test/zk-loan.test.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/zk-loan/src/test/zk-loan.test.ts). The contract's 65 simulator tests, in [`src/test/zk-loan.sim.test.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/zk-loan/src/test/zk-loan.sim.test.ts), cover many more cases, and run in seconds with `npm run test:sim`.

## Conclusion[​](#conclusion "Direct link to Conclusion")

This tutorial covered private computation over data you can't trust by itself:

* **Attestations verified in the circuit.** A trusted provider signs the private data, and a Compact module verifies the Schnorr signature inside the proof, so tampered data can't pass.
* **One hash on both sides.** The off-chain signer calls the contract's own pure circuit for the challenge, so the signer and the circuit can't disagree.
* **Constrained witnesses.** The witness-assisted reduction is checked over the integers, so a prover can't pick a convenient answer.
* **Witness-derived identity.** Admin and borrower identities are domain-separated hashes of a private secret, never `ownPublicKey()`.
* **Fixed-size batching** to work over a variable number of records, with a cursor on the ledger.
* **Only the outcome on chain:** the status and amount of each loan, under a derived key rather than a wallet address. The provider that signed the attestation can still match that key to the borrower.

The full example is [`examples/zk-loan`](https://github.com/midnightntwrk/midnight-examples/tree/main/examples/zk-loan) in midnight-examples.

## Next[​](#next "Direct link to Next")

The last step in the learning path is the [Leaderboard](https://docs.midnight.network/tutorials/leaderboard.md) tutorial: a full-stack DApp with a browser UI, Lace wallet integration, and a deployment to Vercel.
