Full lesson

zk-lokomotive-core

The only true metadata leak-free, platform-less end-to-end decentralized data transfer protocol

What it does

From the project README:

zk-lokomotive is an advanced, zero-knowledge proof-based file transfer system designed to operate seamlessly across multiple blockchain networks, including EVM-compatible chains, Solana, and Sui. By leveraging state-of-the-art zero-knowledge cryptography, Arweave for decentralized storage, and Wormhole for cross-chain interoperability, zk-lokomotive provides an unparalleled solution for secure, private, and efficient file transfers in a trustless environment.

Original

zklambda/zk-lokomotive-core

SuperStack fork

Blockchains/zk-lokomotive-core @ 3da6216

Stars

31

Last push (original)

2024-12-24

Languages

JavaScript, Makefile, TypeScript, Move, SCSS, Rust

Detected stack

AnchorNext.jsweb3.js

Categories

Infrastructure & Tooling

Licence

MIT

Homepage

https://zk-lokomotive.xyz/

Architecture

977 source files. By extension: .js ×898, .ts ×32, .tsx ×20, .sol ×10, .rs ×10, .move ×7.

On-chain programs: anchor-cli/programs/lokomotive, zkl-messenger/chains/solana/programs/solana

❌ Does not build as-is, checked 2026-11-02 Tested on 2026-11-02: full log results.json

Build it yourself: step-by-step guide

Every command below was run on 2026-11-02 by tests/run_fork.py against the pinned commit, and the results come from that run. The full output is in the committed log.

1. Prerequisites (versions we tested with)

• Rust: rustc 1.99.1 (58cf8f9c3 2026-10-13)
• Solana CLI (Agave): solana-cli 1.18.17 (src:c027cfc3; feat:4215500110, client:Agave)
• Anchor (via avm): 0.32.1
• Node.js: v24.22.1
• npm: 11.21.1
• pnpm: 10.34.6
• Go: go version go1.27.3 linux/amd64

cargo install --git https://github.com/coral-xyz/anchor avm --locked
avm install 0.32.1 && avm use 0.32.1
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

2. Clone at the tested commit

git clone https://github.com/Blockchains/zk-lokomotive-core.git && cd zk-lokomotive-core
git checkout 3da6216e112b150fb657c2dbc968b9b8c369aea4

3. Configure

The repo reads these environment variables. Copy the example file and fill in your own values. Never commit real keys.

• zkl-ccir-main /.env.example: MONGODB_URI, PORT

4. Install dependencies

prebuild ERR! build     at Object..js (node:internal/modules/cjs/loader:2060:10)
prebuild ERR! build     at Module.load (node:internal/modules/cjs/loader:1651:32)
prebuild ERR! build     at Module._load (node:internal/modules/cjs/loader:1443:12)
prebuild ERR! build     at wrapModuleLoad (node:internal/modules/cjs/loader:261:19)
prebuild ERR! build     at Module.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:154:5)
prebuild ERR! build     at node:internal/main/run_main_module:33:47

5. Build

      = note: to use the edition 2021 resolver, specify `workspace.resolver = "2"` in the workspace root's manifest
      = note: for more details see https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions
        Updating crates.io index
    error: no matching package named `ipfs-http-client` found
    location searched: crates.io index
    required by package `lokomotive v0.1.0 (/tmp/scbuild/zk-lokomotive-core/anchor-cli/programs/lokomotive)`

496 -                 let proc_macro::LineColumn { line, column } = s.end();
496 +                 let LineColumn { line, column } = s.end();
    |
For more information about this error, try `rustc --explain E0422`.
error: could not compile `proc-macro2` (lib) due to 2 previous errors
warning: build failed, waiting for other jobs to finish...

Error: Unable to deserialize config: TOML parse error at line 36, column 1
   |
36 | [[test.genesis]]
   | ^^^^^^^^^^^^^^^^
missing field `program`

Import trace for requested module:
./pages/index.js
./pages/share/[guid].js
Module not found: Can't resolve 'server' in '/tmp/scbuild/zk-lokomotive-core/pages/share'
> Build failed because of webpack errors
error Command failed with exit code 1.

  200 |         ) : (
> 201 |           <TwitterProfile tweets={profileTweets} wallet={wallet} />
      |            ^
  202 |         )}
  203 |       </div>
  204 |     </div>

  library: 'digital envelope routines',
  reason: 'unsupported',
  code: 'ERR_OSSL_EVP_UNSUPPORTED'
}
Node.js v24.22.1
error Command failed with exit code 1.

6. Test

    at main (file:///tmp/scbuild/zk-lokomotive-core/zkl-evm-tokenbridge/treasury.js:211:19)
    at file:///tmp/scbuild/zk-lokomotive-core/zkl-evm-tokenbridge/treasury.js:341:1
    at ModuleJob.run (node:internal/modules/esm/module_job:561:25)
    at async node:internal/modules/esm/loader:647:26
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)
Node.js v24.22.1

  testMatch: /tmp/scbuild/zk-lokomotive-core/zkl-old-arweave/src/**/__tests__/**/*.{js,jsx,ts,tsx}, /tmp/scbuild/zk-lokomotive-core/zkl-old-arweave/src/**/*.{spec,test}.{js,jsx,ts,tsx} - 0 matches
  testPathIgnorePatterns: /node_modules/ - 15 matches
  testRegex:  - 0 matches
Pattern:  - 0 matches
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command failed with exit code 1.

7. Deploy to a local validator

solana-test-validator --reset   # separate terminal
solana config set -ul && solana airdrop 100
anchor deploy --provider.cluster localnet

Deploy to devnet (free)

solana config set --url devnet
solana airdrop 2   # or https://faucet.solana.com
anchor deploy --provider.cluster devnet   # native: solana program deploy target/deploy/<name>.so
# point the frontend RPC env var at https://api.devnet.solana.com

How it works

Every instruction handler in the program, with the accounts struct it validates. Each link points to the line at the pinned commit.

Extend it

1. Add an integration test that runs the main flow end to end and asserts every account state change.
2. Add a negative test: call each instruction with the wrong signer or account and check that it fails.
3. Add an event (emit!) to each state-changing instruction and subscribe to it from the client.
4. Replace any unchecked AccountInfo with typed accounts plus has_one/seeds constraints.
5. Make the frontend read the cluster from an env var, deploy it to GitHub Pages and point it at your devnet program.
6. Wire the build into CI by copying this site's verify-forks workflow.

Key code, explained

Excerpts chosen automatically where the code uses the most Solana concepts, pinned to the fork's commit.

use anchor_lang::prelude::*;use crate::constant::*;use crate::account::*;use std::str::FromStr;use anchor_lang::solana_program::sysvar::{rent, clock};use crate::wormhole::*;use hex::decode; #[derive(Accounts)]pub struct Initialize<'info> {    #[account(        init,        seeds=[b"config".as_ref()],        payer=owner,        bump,        space=8+32+32+1024    )]    pub config: Account<'info, Config>,    #[account(mut)]    pub owner: Signer<'info>,    pub system_program: Program<'info, System>} #[derive(Accounts)]

        h.write(serialized_vaa.as_slice()).unwrap();        let vaa_hash: [u8; 32] = h.finalize().into();         let (vaa_key, _) = Pubkey::find_program_address(&[            b"PostedVAA",            &vaa_hash        ], &Pubkey::from_str(CORE_BRIDGE_ADDRESS).unwrap());         if ctx.accounts.core_bridge_vaa.key() != vaa_key {            return err!(MessengerError::VAAKeyMismatch);        }         msg!("Checking emitter chain and address");        // Already checked that the SignedVaa is owned by core bridge in account constraint logic        //Check that the emitter chain and address match up with the vaa        if vaa.emitter_chain != ctx.accounts.emitter_acc.chain_id ||           vaa.emitter_address != &decode(&ctx.accounts.emitter_acc.emitter_addr.as_str()).unwrap()[..] {            return err!(MessengerError::VAAEmitterMismatch)        }         ctx.accounts.config.current_msg = String::from_utf8(vaa.payload).unwrap();        Ok(())    }}

How to run, build and test

These commands come from the repo's own manifests (package.json scripts, Anchor.toml, Cargo, go.mod, Makefile). Check the README for prerequisites and environment variables.

What you could build from it

• Fork the SuperStack copy and extend it within the Infrastructure & Tooling gaps listed on the idea page.
• Learn the pattern first: Building and sending transactions from a client
• Learn the pattern first: Anchor account constraints

Used in lessons

• Program Derived Addresses (PDAs)
• Anchor account constraints