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

# Part 2: TypeScript integration

This part connects the contract to TypeScript. You look at the witnesses, the module that exports the compiled contract, and `LeaderboardAPI`: one class that deploys and calls the contract. The browser DApp in Part 3 and the network tests at the end of this part both use it, each with its own providers.

The browser shares this code, so none of the files in `contract/` or `api/` import a `node:*` module.

## Witnesses[​](#witnesses "Direct link to Witnesses")

[`contract/witnesses.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/contract/witnesses.ts) implements the two witnesses the contract declares. A player's private state is just their secret key:

contract/witnesses.ts

```
export type LeaderboardPrivateState = {

  readonly secretKey: Uint8Array;

};



export const createLeaderboardPrivateState = (secretKey: Uint8Array): LeaderboardPrivateState => ({

  secretKey,

});
```

The custom name changes with every submission, so it is not kept in the private state. The API sets it just before it calls `submitScore`:

contract/witnesses.ts

```
let customName = new Uint8Array(32);



export const setCustomName = (name: string): void => {

  customName = new Uint8Array(32);

  customName.set(new TextEncoder().encode(name).slice(0, 32));

};
```

Each witness receives a `WitnessContext` and returns a tuple of the next private state and the value. Both return the private state unchanged:

contract/witnesses.ts

```
export const witnesses = {

  localSecretKey: ({

    privateState,

  }: WitnessContext<Ledger, LeaderboardPrivateState>): [LeaderboardPrivateState, Uint8Array] => [

    privateState,

    privateState.secretKey,

  ],

  getCustomName: ({

    privateState,

  }: WitnessContext<Ledger, LeaderboardPrivateState>): [LeaderboardPrivateState, Uint8Array] => [

    privateState,

    customName,

  ],

};
```

The property names and types match the `Witnesses` type the compiler generated in `contract/managed/leaderboard/contract/index.d.ts`. `Bytes<32>` maps to `Uint8Array`.

## Contract exports[​](#contract-exports "Direct link to Contract exports")

[`contract/index.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/contract/index.ts) binds the compiled contract to its witnesses:

contract/index.ts

```
export const CompiledLeaderboardContract = CompiledContract.make('leaderboard', Contract).pipe(

  CompiledContract.withWitnesses(witnesses),

  CompiledContract.withCompiledFileAssets('./managed/leaderboard'),

);
```

`CompiledContract` comes from `@midnight-ntwrk/midnight-js-protocol/v9/compact-js`, the Ledger 9 build of the Compact JS runtime that Midnight.js 5 uses. `midnight-js-contracts` takes this object to deploy the contract or to connect to a deployed one.

## Shared types[​](#shared-types "Direct link to Shared types")

[`api/common-types.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/api/common-types.ts) names the private state, the circuits that need proofs, and the provider set:

api/common-types.ts

```
export const leaderboardPrivateStateKey = 'leaderboardPrivateState';

export type PrivateStateId = typeof leaderboardPrivateStateKey;



/** The circuits that need proofs, from the compiled contract's generated types. */

export type LeaderboardCircuitKeys = keyof ImpureCircuits<LeaderboardPrivateState>;



export type LeaderboardProviders = MidnightProviders<LeaderboardCircuitKeys, PrivateStateId, LeaderboardPrivateState>;



export type LeaderboardContract = Contract<LeaderboardPrivateState>;

export type DeployedLeaderboardContract = FoundContract<LeaderboardContract>;
```

`LeaderboardCircuitKeys` is derived from the compiled contract's types, so it follows the contract if you add or rename a circuit. `MidnightProviders` is the set of services Midnight.js needs: private state, ZK config (the keys), proofs, public data (the indexer), the wallet, and submission.

## Display names[​](#display-names "Direct link to Display names")

An anonymous entry's display name is 32 bytes of hash. [`api/utils/index.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/api/utils/index.ts) turns it into something readable:

api/utils/index.ts

```
export const decodeDisplayName = (bytes: Uint8Array, entryId: number, score: number): string => {

  const decoded = new TextDecoder().decode(bytes).replace(/\0/g, '').trim();

  if (decoded.length > 0 && decoded.split('').every((c) => c.charCodeAt(0) >= 32 && c.charCodeAt(0) < 127)) {

    return decoded;

  }

  const h = (bytes[0] << 24 | bytes[1] << 16 | bytes[2] << 8 | bytes[3]) >>> 0;

  const seed = (h ^ (entryId * 2654435761) ^ (score * 1597334677)) >>> 0;

  return `${ADJECTIVES[seed % ADJECTIVES.length]} ${NOUNS[(seed >>> 16) % NOUNS.length]}`;

};
```

Printable ASCII, as stored for a custom name, is shown as it is. Anything else becomes a generated name, picked deterministically from the bytes, the entry id, and the score.

## Decode the public state[​](#decode-the-public-state "Direct link to Decode the public state")

[`api/index.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/api/index.ts) starts with two functions that turn indexer data into leaderboard rows. Midnight.js 5 returns a contract's state tagged with the ledger version that wrote it. `decodeLedger` accepts Ledger 9 state, deserializes it, and decodes it with the compiled contract's `ledger()`:

api/index.ts

```
export const decodeLedger = (read: ContractStateRead): Ledger => {

  if (read.contractState.era !== 'v9') throw new Error('expected a Ledger 9 contract state');

  return ledger(read.contractState.deserialize({ v9: ContractState }).data);

};
```

`deriveState` turns the decoded ledger into display rows, highest score first:

api/index.ts

```
export const deriveState = (ledgerState: Ledger): LeaderboardDerivedState => {

  const entries: LeaderboardEntry[] = [];

  for (const [key, entry] of ledgerState.scores) {

    entries.push({

      id: Number(key),

      score: Number(entry.score),

      displayName: utils.decodeDisplayName(entry.displayName, Number(key), Number(entry.score)),

      ownerHash: utils.toHex(entry.ownerHash),

    });

  }

  entries.sort((a, b) => b.score - a.score);

  return { entryCount: Number(ledgerState.nextId), entries };

};
```

## LeaderboardAPI[​](#leaderboardapi "Direct link to LeaderboardAPI")

`LeaderboardAPI` wraps a deployed contract. Its constructor subscribes to the contract's state through the public data provider, so `state$` emits fresh rows whenever the leaderboard changes:

api/index.ts

```
export class LeaderboardAPI {

  private constructor(

    public readonly deployedContract: DeployedLeaderboardContract,

    providers: LeaderboardProviders,

    private readonly logger?: Logger,

  ) {

    this.deployedContractAddress = deployedContract.deployTxData.public.contractAddress;

    this.state$ = providers.publicDataProvider

      .contractStateObservable(this.deployedContractAddress, { type: 'latest' })

      .pipe(map(({ value }) => deriveState(decodeLedger(value))));

  }



  readonly deployedContractAddress: ContractAddress;

  readonly state$: Observable<LeaderboardDerivedState>;
```

The two circuit calls are thin wrappers over `callTx`, which builds the transaction, runs the witnesses, proves it, and hands it to the wallet to balance and submit:

api/index.ts

```
  /** Submits a score. With a custom name, the getCustomName witness supplies it. */

  async submitScore(score: number, customName?: string): Promise<void> {

    if (customName) setCustomName(customName);

    this.logger?.info({ score, customName: !!customName }, 'Submitting score');

    await this.deployedContract.callTx.submitScore(BigInt(score), !!customName);

  }
```

api/index.ts

```
  /** Proves ownership of an entry. The proof reveals nothing about the caller's key. */

  async verifyOwnership(entryId: number): Promise<void> {

    this.logger?.info({ entryId }, 'Proving ownership');

    await this.deployedContract.callTx.verifyOwnership(BigInt(entryId));

  }
```

`deploy` creates a new leaderboard, and `join` connects to an existing one by address. Both store the player's private state under `leaderboardPrivateStateKey`:

api/index.ts

```
  /** Deploys a new leaderboard contract. */

  static async deploy(providers: LeaderboardProviders, secretKey: Uint8Array, logger?: Logger): Promise<LeaderboardAPI> {

    const deployedContract = await deployContract(providers, {

      compiledContract: CompiledLeaderboardContract,

      privateStateId: leaderboardPrivateStateKey,

      initialPrivateState: createLeaderboardPrivateState(secretKey),

    });

    logger?.info({ address: deployedContract.deployTxData.public.contractAddress }, 'Deployed leaderboard');

    return new LeaderboardAPI(deployedContract, providers, logger);

  }
```

api/index.ts

```
  /** Joins an existing leaderboard contract. */

  static async join(

    providers: LeaderboardProviders,

    contractAddress: ContractAddress,

    secretKey: Uint8Array,

    logger?: Logger,

  ): Promise<LeaderboardAPI> {

    const deployedContract = await findDeployedContract(providers, {

      contractAddress,

      compiledContract: CompiledLeaderboardContract,

      privateStateId: leaderboardPrivateStateKey,

      initialPrivateState: createLeaderboardPrivateState(secretKey),

    });

    logger?.info({ address: contractAddress }, 'Joined leaderboard');

    return new LeaderboardAPI(deployedContract, providers, logger);

  }
```

## Run it against a live network[​](#run-it-against-a-live-network "Direct link to Run it against a live network")

The network tests in [`src/test/leaderboard.test.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/src/test/leaderboard.test.ts) drive `LeaderboardAPI` from Node with two real wallets. `buildProviders` in [`src/providers.ts`](https://github.com/midnightntwrk/midnight-examples/blob/main/examples/leaderboard/src/providers.ts) gives each wallet its own provider set: keys from disk, a local proof server, the network's indexer, and the wallet wrapped for Ledger 9.

src/providers.ts

```
export function buildProviders(wallet: MidnightWalletProvider, config: NetworkConfig): LeaderboardProviders {

  const zkConfigProvider = new NodeZkConfigProvider<LeaderboardCircuitKeys>(zkConfigPath);

  return {

    privateStateProvider: levelPrivateStateProvider({

      privateStateStoreName: `leaderboard-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,

      // this password has requirements (capital/special chars >= 3)

      privateStoragePasswordProvider: () => 'Leaderboard-Test-Password',

      accountId: wallet.getCoinPublicKey(),

    }),

    publicDataProvider: indexerPublicDataProvider(

      config.indexer,

      config.indexerWS,

    ),

    zkConfigProvider,

    proofProvider: httpClientProofProvider(

      config.proofServer,

      zkConfigProvider,

    ),

    // Midnight.js 5 providers are tagged with the ledger eras they serve. The

    // wallet is ledger 9 only; these lift it into the tagged interfaces.

    walletProvider: createLedger9WalletProvider(wallet),

    midnightProvider: createLedger9MidnightProvider((tx) => wallet.submitTx(tx)),

    config: { networkId: config.networkId, ttlSeconds: TX_TTL_SECONDS },

  };

}
```

The suite deploys a leaderboard as Alice, submits under a name, joins as Bob, and submits anonymously. Then it checks that `state$` ranks the entries:

src/test/leaderboard.test.ts

```
  it('state$ lists the entries, highest score first', async () => {

    const state = await firstValueFrom(bob.state$);

    expect(state.entryCount).toBe(2);

    expect(state.entries.map((e) => [e.id, e.score])).toEqual([

      [2, 900],

      [1, 420],

    ]);

    expect(state.entries[1].displayName).toBe('alice');

  });
```

and that only the right key can prove ownership:

src/test/leaderboard.test.ts

```
  it('Alice proves she owns entry 1', async () => {

    await expect(alice.verifyOwnership(1)).resolves.toBeUndefined();

  });
```

src/test/leaderboard.test.ts

```
  it("Bob cannot prove he owns Alice's entry, or an entry that does not exist", async () => {

    await expect(bob.verifyOwnership(1)).rejects.toThrow(/not the owner/);

    await expect(bob.verifyOwnership(99)).rejects.toThrow(/entry not found/);

  });
```

The local devnet doesn't run Ledger 9 yet, so run the suite against Preview. Start a proof server, then from the repo root create the shared test wallets and fund the addresses it prints at the [Preview faucet](https://midnight-tmnight-preview.nethermind.dev/):

```
npm run proof:up

(cd ../.. && npm run wallets:new)

npm run test:preview
```

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

In [Part 3](https://docs.midnight.network/tutorials/leaderboard/browser-dapp.md) you put the same API behind a React frontend, with the Lace wallet supplying the providers.
