Proposal: optional Zikuani permission layer for anti-Sybil / proof-of-humanity escrows

[JoelVR17]

Proposal: optional Zikuani permission layer for anti-Sybil / proof-of-humanity escrows

Summary

We'd like to propose an optional, additive identity-permission layer for Trustless Work escrows using Zikuani, a privacy-preserving zero-knowledge (ZK) identity system built natively on Soroban.

The goal: let an escrow optionally restrict participation to addresses that have proven they are a real, unique human from an eligible (non-restricted) jurisdiction — without anyone (including Trustless Work) ever seeing or storing personal data.

This is opt-in and additive: escrows that don't enable it are completely unaffected, and in the v1 design no changes to Trustless Work's core contracts are required.

This follows the same pattern as the existing reclaim-protocol-integration spike (ZK proofs in escrows / privacy enhancements): we propose to add the integration as a parallel zikuani-integration/ folder in this repo, contributed via PR (spike/zikuani-integration) and tested on Stellar Testnet.

Why this is useful for Trustless Work

Many escrow flows need more than "this wallet has funds" — they need to know a real, unique person is behind the address:

• Grants / crowdfunding escrows where recipients or backers must be real, unique humans (anti-bot, anti-farming, one-person-one-slot).
• Gated marketplaces / service escrows restricted to verified or eligible participants.
• Jurisdiction gating (excluding restricted countries) without ever collecting identity documents.

It gives Trustless Work an anti-Sybil / proof-of-humanity option for escrows, with no personal-data liability — there is no honeypot to breach because no personal data is ever collected.

How Zikuani works (in brief)

• A user generates a ZK proof on their own device from a government-issued credential (biometric passport / ISO 18013-5 mDL). Only the proof and a one-way nullifier leave the device — no personal data is transmitted or stored anywhere.
• A Soroban verifier contract checks the proof on-chain (Groth16 over BN254 + Poseidon, via Protocol 25 host functions).
• A Proof Registry contract records only: a claim type (e.g. verified-human, age≥18, eligible-jurisdiction), a validity window, and the nullifier (which enables one-human-one-account Sybil resistance). No personally identifiable information is ever stored on-chain.

Proposed integration approaches

Pattern A — application-layer gate (v1, no contract changes)

The integrating platform checks the Zikuani Proof Registry for a valid claim on an address before that address is assigned to an escrow role (e.g. receiver / service provider / approver) or admitted to the escrow. This consumes Trustless Work's existing public interface and requires no changes to Trustless Work contracts. The check is enforced at role-assignment / admission time.

Pattern B — on-chain permission gate (exploration)

A small PermissionGate Soroban contract sits in the authorization path and performs a cross-contract call into the Zikuani registry, authorizing the action only if the counterparty address holds a valid, unexpired claim. This moves enforcement on-chain (contract-enforced rather than app-enforced), which is preferable for higher-value escrows. This depends on the open question below.

Open questions for the Trustless Work team

1. (Pattern B) Can an escrow role (e.g. approver / releaser) be assigned to a contract address (C...) today — so a contract can co-authorize an action via cross-contract logic — or is that something planned for V2?
2. Which roles are the most natural gating points in your typical escrow flows (receiver / service provider, approver, other)?
3. Are there any constraints in the current API / SDK we should be aware of when reading role assignment or release steps?

Where this will live

The integration code will be added as a new zikuani-integration/ folder in this repo (Trustless-Work/trustlesswork-spikes), mirroring the existing reclaim-protocol-integration ZK spike. Contribution will follow the repo's standard flow: a PR from branch spike/zikuani-integration, tested on Stellar Testnet, with the reference adapter, the end-to-end demo, and a README documenting setup and the reproducible flow.

Proposed scope

• Create the zikuani-integration/ spike folder with a README and reproducible setup
• Confirm gating points and the Pattern A flow against the current Trustless Work API / SDK
• Implement a registry-check adapter (Pattern A) and a reference integration
• End-to-end demo on testnet: verified human → admitted to escrow → release, publicly reproducible
• Explore Pattern B (PermissionGate contract), pending the answer to open question poc: Escrow Data Viewer Using Stellar RPC #1
• Documentation + reproducible example

What we'd need from Trustless Work

• Pattern A: nothing beyond the existing public interface — plus your feedback on the open questions above.
• Pattern B: confirmation on contract-address roles / V2 direction.

Status & context

Proposed by the Zikuani / Sakundi team, in collaboration with the Trustless Work team [optionally name the co-founder here if they're comfortable being named]. This integration is part of our Stellar Community Fund work, and we'd be happy to jump on a quick call to align on the approach. Verbal green light to proceed has been given.

cc @JoelVR17 · @techrebelgit (product) — for visibility and to confirm the open questions above.

References

• Existing precedent in this repo: reclaim-protocol-integration
• Zikuani: https://github.com/kuronosec/zikuani-stellar-boilerplate
• Live demo: https://demo.sakundi.io/

[AnoukRImola]

Hi @JoelVR17 / Trustless Work team — quick follow-up on this.

We're including this integration in our Stellar Community Fund #44 submission as a named, in-progress integration with Trustless Work, and we'd like to point reviewers to this issue as the public reference.

[grantfox-oss]

🦊 GrantFox — @AnoukRImola has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #249)
2. Your PR will be reviewed by the Trustless-Work maintainers

Good luck! Track your progress on GrantFox.

[techrebelgit]

From the questions:
(Pattern B) Can an escrow role (e.g. approver / releaser) be assigned to a contract address (C...) today — so a contract can co-authorize an action via cross-contract logic — or is that something planned for V2?
Technically you CAN assign a role to a C-address, we have nolimit to that, the problem lies in the fact that the C-Address will not be signing the function, so that our escrows cannot verify the signing address. For example, lets say you assign a C-Address to an approver role. When you want to sign the approve function, The C-address will not be the one signing the transaction, it will be a re-layer. So the validation that the approve function signer address == the approver roel asigned address fails
So that's the issue we have with C-address right now.

[techrebelgit]

Which roles are the most natural gating points in your typical escrow flows (receiver / service provider, approver, other)?
All are required. You CAN release funds only approving and releasing, without providing any status update, but you will still need to assign an address for this role.