# AIR Kit Developer Dashboard
Source: https://docs.moca.network/airkit/airkit-dashboard

AIR Kit dashboard - manage account and credentials all in one place

The <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> is a self-service platform for partners of the Moca Network.

It provides the tools for both developers of AIR Account and AIR Credential and has the following key sections:

* Account
* Issuer
* Verifiers

It is designed to manage the entire lifecycle of AIR Kits, from account creation to issuance to verification.

The dashboard is accessed via a connected EVM wallet, which serves as the primary account identifier, and allows users to access your app's settings.

## Account

The account section contains your partner configuration.

### 1. General Settings

This is where you can get a generated set of IDs that is used for your implementation. Below is an example of what your generated settings might look like, which you can easily copy from the dashboard.

```json theme={null}
{
  "partnerId": "1234-5678-9012",
  "issuerDid": "did:moca:0xabcdef1234567890abcdef1234567890abcdef",
  "verifierDid": "did:moca:0x9876543210fedcba9876543210fedcba987654",
  "name": "My Awesome dApp",
  "logoUrl": "https://your-cdn.com/logo.png",
  "websiteUrl": "https://your-dapp.com",
  "jwksUrl": "https://your-auth-provider.com/.well-known/jwks.json"
}
```

| Field            | Description                                                                                                                                                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Partner ID**   | Your AIR Kit partner ID, used to identify you across the AIR Kit ecosystem.                                                                                                                                                                    |
| **Issuer DID**   | Your Issuer DID, used to let users and verifiers know who is the issuer of the credentials.                                                                                                                                                    |
| **Verifier DID** | Your Verifier DID, used to let users and issuers know who requested usage of the credentials.                                                                                                                                                  |
| **Name**         | Your App's name, which may be shown to users during various operations such as wallet transactions, credential issuance, or credential verification.                                                                                           |
| **Logo URL**     | Your App's logo, which may be shown to users during various operations such as wallet transactions, credential issuance, or credential verification.                                                                                           |
| **Website URL**  | Your App's website, which may be shown to users if they want to learn more about your application.                                                                                                                                             |
| **JWKS URL**     | Required for Credential Services, or if you utilize the [bring your own auth](/airkit/usage/user-authentication#custom-auth-bring-your-own-auth) feature. See [Authentication (Partner JWT)](/airkit/usage/partner-authentication) for details |

### 2. Allowed Domains

As a security setting, we require partners to set the app domains that are allowed to load AIR Kit. Wildcards are supported (e.g. \*.myapp.example.com)

You can add up to 3 domains or subdomains as you need. But do note that some domains may be blocked for security purposes and if you require these domains to be supported please reach out to our team to further discuss your requirements.

<Info>
  `localhost` is whitelisted for following ports: `3000`, `5173` and `8200`. We do not support adding `localhost` to the allowed domains list.
  In addition, our production environment requires all domains to use HTTPS.
</Info>

## Issuer

The Issuer section is designed for any entity that needs to create and distribute verifiable credentials. Its functionalities are organized into three main areas: Schemas, Credentials, and a monitoring Dashboard.

### 1. Schema Builder

This is the starting point for creating any new credential. A Schema acts as a blueprint, defining the structure, data type, and rules for a specific type of credential.

* **Create Schemas**: Issuers can build custom schemas by defining a title, version, and description.
* **Define Attributes**: Within each schema, issuers add specific data fields (attributes). For each attribute, they define a name, data type (e.g., string, number, boolean), a descriptive title, and can mark it as required.
* **Publish and Store**: Once defined, schemas are published and stored on either a centralized server (OSS) or decentralized storage (dStorage) on Moca Chain to be used for issuing credentials.

Here is an example of a simple schema for a "DAO Membership" credential:

```json theme={null}
{
  "title": "DAO Membership",
  "version": "1.0",
  "description": "Verifies that the holder is a member of a specific DAO.",
  "attributes": [
    {
      "name": "daoName",
      "type": "string",
      "title": "DAO Name",
      "required": true
    },
    {
      "name": "memberSince",
      "type": "date",
      "title": "Member Since",
      "required": true
    },
    {
      "name": "votingPower",
      "type": "number",
      "title": "Voting Power",
      "required": false
    }
  ]
}
```

### 2. Issuance Program

Once a schema is in place, issuers can create and configure the actual credentials that will be distributed to users.

* **Select a Schema**: The process begins by selecting the appropriate schema, which loads its predefined attributes.
* **Set Issuance Rules**: Issuers can configure key parameters for the credential, such as:
  * **Accessible Until**: An optional date range during which the credential is valid.
  * **Maximum Issuance**: An optional cap on the total number of credentials that can be claimed.
  * **Expiration Duration**: The lifespan of the credential after it has been issued to a user (e.g., 90 days, 1 year, permanent).
* **Issue Credential**: After confirming the details, the credential is issued and becomes available for users to claim.

### 3. Issuer Dashboard Monitoring

This section provides a high-level overview and detailed logs of all issuance activity.

* **Key Metrics**: View statistics like the Total Issued Number (the total number of credentials claimed by users) and the Total Credential Number (the number of different credential types created).
* **Claim Records**: See a detailed list of every credential that has been claimed by a user, including the Holder ID, Credential ID, and the Claimed Time. Issuers can also revoke a claimed credential directly from this interface.

## Verifier

The Verifier section is for any application or service that needs to confirm the validity of a user's AIR Credential. It is centered around creating Verification Programs and monitoring their usage.

### 1. Verification Program Management

A Verification Program is a set of rules created by a verifier to check a user's credential for specific attributes.

* **Create Programs**: Verifiers build programs by defining a name and selecting the credential schema they intend to verify.
* **Define Verification Logic**: The core of the program is its logic. Verifiers add specific Operators (e.g., "equals," "greater than," "is a member of") and Attribute Values to create precise verification conditions. For example, a program could verify if a "Country" attribute equals "USA" or if an "Age" attribute is greater than "18".
* **Data Recovery Options**: Programs can be configured to allow verifiers to request access to the underlying data from the user, subject to their explicit consent.

Here is an example of verification logic to check if a user is a member of "Moca DAO":

```json theme={null}
{
  "programName": "Moca DAO Member Check",
  "credentialSchema": "DAO Membership",
  "logic": [
    {
      "attribute": "daoName",
      "operator": "equals",
      "value": "Moca DAO"
    }
  ],
  "dataRecovery": false
}
```

### 2. Verifier Dashboard Monitoring

This dashboard provides a comprehensive record of all verification activities.

* **Key Metrics**: View the Total Verified Number of credentials and other relevant statistics.
* **Verification Records**: Access a detailed log of all verification attempts, including the Holder ID, the Program Name used, the Verified Time, and the Current Status (e.g., Passed, Verification Failed).

### 3. Settings and Fee Wallet

Both Issuers and Verifiers have access to a settings panel to manage their operations. For Verifiers, this includes a Fee Wallet system. Because issuance and verifications can incur on-chain gas fees, the dashboard provides a dedicated wallet that verifiers can pre-fund with \$MOCA. The system automatically deducts fees from this balance for verification transactions, and the dashboard provides a detailed history of all deposits and charges.


# Development Environments
Source: https://docs.moca.network/airkit/environments

Starting with **AirKit 1.8.0-beta**, the Sandbox environment defaults to **Moca Chain Testnet**.

<Warning>
  **Breaking Change: Sandbox Now Defaults to Testnet**

  Starting with **AirKit 1.8.0-beta**, the Sandbox environment defaults to **Moca Chain Testnet**.
</Warning>

<Tip>
  Make sure you're selecting the correct chain when using different build environment. Otherwise, your app may hit unexpected errors
</Tip>

| Environment       | Moca Chain | Purpose                   | Developer Dashboard                                                                            |
| ----------------- | ---------- | ------------------------- | ---------------------------------------------------------------------------------------------- |
| Sandbox (Testnet) | Testnet    | For development & testing | [https://developers.sandbox.air3.com/dashboard](https://developers.sandbox.air3.com/dashboard) |

> Once Mainnet is available, Production credentials will be validated against Mainnet and hence previously issued credentials on Testnet will need to be re-issued. Issuance Schemas and Programs *may* be migrated. Your Issuer and Verifier DID may also change.

## Sandbox Environment Changes

Starting with **AirKit 1.8.0-beta**, the Sandbox environment defaults to **Moca Chain Testnet** instead of Devnet. Both Testnet and Devnet remain available for development, with Testnet being the recommended choice to align with Production.

### What's Changed

| Before (\< 1.8.0)                                                                     | After (1.8.0-beta+)                                                                                   |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Sandbox → Devnet (Chain ID: 5151)                                                     | Sandbox → Testnet (Chain ID: 222888)                                                                  |
| Dashboard: [https://developers.sandbox.air3.com](https://developers.sandbox.air3.com) | Dashboard: [https://developers.sandbox.air3.com/testnet](https://developers.sandbox.air3.com/testnet) |

### Impact

* Credentials issued on Devnet are **not** available on Testnet
* Smart Account addresses remain the same across networks
* You will need to re-issue test credentials on Testnet

<Tip>
  We recommend migrating to Testnet as soon as possible to align with production.
</Tip>

### Initializing AirService with the correct Environment

<Tabs>
  <Tab title="Web">
    ```js theme={null}
    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({
      partnerId: YOUR_PARTNER_ID
    });
    await airService.init({
      buildEnv: BUILD_ENV.SANDBOX, // BUILD_ENV.PRODUCTION
      enableLogging: true
    });
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    Future<void> initialize({
      YOUR_PARTNER_ID,
      navigatorKey,
      Environment.sandbox, // Environment.production
      true,
    })
    ```
  </Tab>
</Tabs>

## Chains

| Chain   | Chain ID | RPC                                                                    | Explorer                                                                 |
| ------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Testnet | 222888   | [https://testnet-rpc.mocachain.org](https://testnet-rpc.mocachain.org) | [https://testnet-scan.mocachain.org](https://testnet-scan.mocachain.org) |
| Mainnet | 2288     | `coming soon`                                                          | `coming soon`                                                            |


# Flutter Android setup
Source: https://docs.moca.network/airkit/flutter/android-setup

Configure Android for AIR Kit Flutter: Digital Asset Links, manifest, network security, and build settings.

## Prerequisites

* Android Gradle Plugin and Kotlin versions supported by your Flutter template
* **`minSdk` 26** and **`compileSdk` 34** (required for AIR Kit)

## Asset statements (Digital Asset Links)

Create or edit `android/app/src/main/res/values/strings.xml`:

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="asset_statements" translatable="false">
        [
        {"include": "https://account.air3.com/.well-known/assetlinks.json"},
        {"include": "https://account.sandbox.air3.com/.well-known/assetlinks.json"}
        ]
    </string>
</resources>
```

Reference the resource from `AndroidManifest.xml` inside `<application>`:

```xml theme={null}
<meta-data
    android:name="asset_statements"
    android:resource="@string/asset_statements" />
```

## App signing and allowlisting

Provide your app’s **SHA-256 signing certificate fingerprint** and **package name** to Moca for allowlisting (debug and release may differ). Use `keytool`:

```bash theme={null}
keytool -list -v -keystore <path-to-keystore> -alias <alias>
```

## `minSdk` and `compileSdk`

In your app-level Gradle file (Kotlin DSL or Groovy), set at least:

```kotlin theme={null}
android {
    compileSdk = 34
    defaultConfig {
        minSdk = 26
    }
}
```

## Network security config

Optional: add `android/app/src/main/res/xml/network_security_config.xml` for TLS and (if needed) local dev domains:

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="false">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>
```

Point `<application>` to it:

```xml theme={null}
android:networkSecurityConfig="@xml/network_security_config"
```

## Permissions

Typical requirements:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

## ProGuard / R8

If you minify release builds, add keep rules for AIR Kit, WebView, and crypto dependencies. **Verify package names** against your resolved dependencies after `flutter pub get`:

```proguard theme={null}
-keepattributes Signature,*Annotation*,EnclosingMethod,InnerClasses
# Adjust package patterns to match your app’s dependencies
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**
```

## Verify the build

```bash theme={null}
flutter clean
flutter pub get
flutter build apk
```

## Troubleshooting

| Issue                   | What to check                                                        |
| ----------------------- | -------------------------------------------------------------------- |
| Passkey / domain errors | Asset statements JSON, signing cert vs allowlist, `meta-data` wiring |
| WebView blank / SSL     | `networkSecurityConfig`, INTERNET permission                         |
| Gradle conflicts        | `flutter clean`, `./gradlew clean` under `android/`                  |

More help: [Flutter troubleshooting](/airkit/flutter/troubleshooting) and [SDK issues](/airkit/troubleshooting/sdk-issues).

## Next steps

* [iOS setup](/airkit/flutter/ios-setup)
* [Google Sign-In](/airkit/flutter/google-signin) (optional)
* [SDK initialization](/airkit/usage/initialization)

## Reference

* [Digital Asset Links](https://developers.google.com/digital-asset-links/v1/getting-started)
* [Flutter Android deploy](https://docs.flutter.dev/deployment/android)


# Flutter Google Sign-In
Source: https://docs.moca.network/airkit/flutter/google-signin



AIR Kit can expose **Google** as a login method when your partner configuration enables it. Configure native Google Sign-In on each platform so the SDK can complete the OAuth flow.

## Prerequisites

* [Flutter installation](/airkit/flutter/installation) and platform setup ([Android](/airkit/flutter/android-setup), [iOS](/airkit/flutter/ios-setup))
* Google Cloud / Firebase project with OAuth client IDs for your Android package name and iOS bundle ID
* Google OAuth settings aligned with the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/general)

## How it connects to AIR Kit

Partner configuration supplies the Google OAuth client behavior expected by AIR Kit. Ensure the **same OAuth clients** you configure in Firebase are the ones you share with Moca for manual dashboard setup (see [Dashboard](#dashboard)).

## iOS

1. In [Firebase Console](https://console.firebase.google.com/), add an iOS app with your bundle ID.
2. Download `GoogleService-Info.plist` and add it to `ios/Runner/` in Xcode (copy if needed).
3. In `Info.plist`, add `CFBundleURLTypes` using the **`REVERSED_CLIENT_ID`** from `GoogleService-Info.plist` as the URL scheme (see Google’s Flutter / iOS Sign-In docs).

## Android

1. In Firebase, add an Android app with your **application ID** (package name).
2. Download `google-services.json` to `android/app/`.
3. In the **project** `android/build.gradle`, include the Google services classpath if required by your template.
4. In the **app** `android/app/build.gradle`, apply the Google Services plugin per [FlutterFire / Google Sign-In setup](https://pub.dev/packages/google_sign_in).

## Dashboard

Partners must provide the **Google OAuth client IDs** for iOS and Android (from Firebase / Google Cloud). The Developer Dashboard does **not** yet let partners enter these values themselves. Moca sets them **manually** for your partner, the same way as other allowlisted values (for example Android signing certificate fingerprints and iOS app identifiers — see [Android setup](/airkit/flutter/android-setup) and [iOS setup](/airkit/flutter/ios-setup)).

Enable Google as a login method in partner configuration once your client IDs are on file. If you need IDs added or updated, use your Moca / partner channel.

## Troubleshooting

| Symptom                 | Checks                                                                      |
| ----------------------- | --------------------------------------------------------------------------- |
| `redirect_uri_mismatch` | iOS URL scheme matches `REVERSED_CLIENT_ID`; OAuth client matches bundle ID |
| Google button missing   | Partner config; correct `partnerId` and environment                         |
| Android build errors    | `google-services.json` path; package name; Play Services on device          |

## Security

* Do not commit `GoogleService-Info.plist` or `google-services.json` to public repos if they contain secrets; use CI secrets or private config distribution.

## Next steps

* [User login & sessions](/airkit/usage/user-authentication)
* [Partner authentication](/airkit/usage/partner-authentication)
* [User management](/airkit/usage/user-management)

## Reference

* [Google Sign-In for Flutter](https://pub.dev/packages/google_sign_in)
* [Google Sign-In iOS](https://developers.google.com/identity/sign-in/ios/start)
* [Google Sign-In Android](https://developers.google.com/identity/sign-in/android/start)


# Flutter installation
Source: https://docs.moca.network/airkit/flutter/installation

Install the AIR Kit Flutter package with OnePub and configure minimum platform versions.

## Prerequisites

* Flutter SDK and Dart toolchain on your PATH
* OnePub access (credentials provided by Moca)
* Android: `compileSdk` 34+, `minSdk` 26+ (see [Android setup](/airkit/flutter/android-setup))
* iOS: platform 14.0+ in `Podfile` (see [iOS setup](/airkit/flutter/ios-setup))

## OnePub CLI

```bash theme={null}
dart pub global activate onepub
onepub login
```

<Warning>
  If `onepub` is not found, add Pub’s global bin directory to your PATH, for example: `export PATH=$PATH:$HOME/.pub-cache/bin`
</Warning>

## Add the dependency

**Option A — `pubspec.yaml`**

```yaml theme={null}
dependencies:
  airkit:
    hosted: https://onepub.dev/api/sxhddavuhn/
    version: ^1.6.0-beta.1
```

Use the version your team recommends; check [Release notes](/airkit/release-notes) for current Flutter SDK versions.

**Option B — CLI**

```bash theme={null}
onepub pub add airkit
```

Then run:

```bash theme={null}
flutter pub get
```

## Import

```dart theme={null}
import 'package:airkit/airkit.dart';
```

## Next steps

1. [Android setup](/airkit/flutter/android-setup) — asset statements, manifest, network security
2. [iOS setup](/airkit/flutter/ios-setup) — associated domains, `Podfile`
3. [Initialization](/airkit/usage/initialization) — `AirService` and `navigatorKey`
4. [Google Sign-In](/airkit/flutter/google-signin) if you use Google login


# Flutter iOS setup
Source: https://docs.moca.network/airkit/flutter/ios-setup

Configure iOS for AIR Kit Flutter: Associated Domains, Podfile, and passkey-related settings.

## Prerequisites

* Xcode and CocoaPods
* **iOS deployment target 14.0+** in `Podfile` (required for AIR Kit)

## Associated Domains

1. Open `ios/Runner.xcworkspace` in Xcode.
2. Select the **Runner** target → **Signing & Capabilities**.
3. Add **Associated Domains**.
4. Add the domains you use:

```
webcredentials:account.air3.com
webcredentials:account.sandbox.air3.com
```

Optional for non-production testing:

```
webcredentials:account.staging.air3.com
webcredentials:account.uat.air3.com
```

<Note>
  Include only environments you actually use. Production and sandbox are the usual minimum.
</Note>

## App ID allowlisting

Provide Moca with your **Apple Team ID** and **bundle identifier** in the form `TEAMID.com.example.app`.

## Podfile

Set the platform version:

```ruby theme={null}
platform :ios, '14.0'
```

Then:

```bash theme={null}
cd ios
pod install
```

## Info.plist (optional)

If you need ATS exceptions for specific domains, configure them narrowly in `Info.plist`. Prefer default secure TLS where possible.

Optional usage strings if you add camera / photo features:

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Required for features that use the camera.</string>
```

## Testing

* Passkeys and full WebAuthn behavior require a **physical device** in many cases.
* Build with `flutter build ios` and run from Xcode or `flutter run`.

## Troubleshooting

| Issue                        | What to check                                                                     |
| ---------------------------- | --------------------------------------------------------------------------------- |
| Domain verification failures | Capability enabled, correct team, provisioning profile, domains spelled correctly |
| `pod install` errors         | `rm -rf Pods Podfile.lock`, `pod repo update`, `pod install`                      |
| WebView / network            | Associated Domains, device network, ATS settings                                  |

See also [Flutter troubleshooting](/airkit/flutter/troubleshooting).

## Next steps

* [Google Sign-In](/airkit/flutter/google-signin) (optional)
* [SDK initialization](/airkit/usage/initialization)
* [User login & sessions](/airkit/usage/user-authentication)

## Reference

* [Associated Domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains)
* [Flutter iOS deploy](https://docs.flutter.dev/deployment/ios)


# Flutter SDK overview
Source: https://docs.moca.network/airkit/flutter/overview

Integrate AIR Kit in Flutter apps for account services, wallet features, and native mobile flows.

## What to read first

1. [Flutter installation](/airkit/flutter/installation) — OnePub setup and `pubspec.yaml`
2. [Android setup](/airkit/flutter/android-setup) and [iOS setup](/airkit/flutter/ios-setup) — passkeys, asset links, associated domains
3. [SDK initialization](/airkit/usage/initialization) (Flutter tab) and [Reference](/airkit/usage/reference) (Flutter tab) for `AirService` APIs

## Capability summary

See the [platform support matrix](/airkit/platform-matrix) for supported platforms, browsers, and package installs.

Credential **issuance** and **verification** in the client SDK are available on Flutter. Start with [Issue credentials](/airkit/quickstart/issue-credentials), [Verify credentials](/airkit/quickstart/verify-credentials), [Issuing credentials](/airkit/usage/credential/issuing-credentials), and [Verify](/airkit/usage/credential/verify). Server-side [Issue on Behalf](/airkit/usage/credential/issue-on-behalf-api) works from any backend.

## Authentication on Flutter

On Flutter, sign-in uses `login` with a **Partner JWT** (`authToken`) after `initialize()`. See [User login & sessions](/airkit/usage/user-authentication) (Flutter tab) and [Partner authentication](/airkit/usage/partner-authentication).

## Environment and dashboard

Use the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard) for partner ID, programs, and configuration. Environment values match [Environments](/airkit/environments) (`Environment.sandbox`, `production`, etc.).

## Related guides

* [Google Sign-In](/airkit/flutter/google-signin) — Firebase / platform OAuth setup
* [Wallet operations](/airkit/flutter/wallet-operations) — balances, transactions, signing
* [Provider functions](/airkit/flutter/provider-functions) — JSON-RPC via `AirService`
* [UI components](/airkit/flutter/ui-components) — login, swap, on-ramp, MFA
* [Troubleshooting](/airkit/flutter/troubleshooting) — common Flutter issues


# Flutter provider functions
Source: https://docs.moca.network/airkit/flutter/provider-functions

Call Ethereum JSON-RPC methods through AirService on Flutter.

On Flutter, `AirService.sendEthereumRpcRequest` exposes an **EIP-1193-style** surface for common RPC methods. Use it directly or wrap it for libraries like **web3dart**.

<Note>
  **wagmi** is for web React apps. For wagmi, see [Wagmi integration](/recipes/wagmi-integration) and the Web SDK [provider](/airkit/usage/account/provider-functions) docs.
</Note>

## Request and response shapes

See [Reference](/airkit/usage/reference) (Flutter tab) for `EthereumRpcRequest` and `EthereumRpcSuccessResponse`.

## Examples

### `eth_accounts` and `eth_chainId`

```dart theme={null}
final accountsRes = await airService.sendEthereumRpcRequest(
  EthereumRpcRequest(method: 'eth_accounts', params: []),
);
final chainRes = await airService.sendEthereumRpcRequest(
  EthereumRpcRequest(method: 'eth_chainId', params: []),
);
```

### `eth_getBalance`

```dart theme={null}
final address = await airService.getAbstractAccountAddress();
if (address != null) {
  final res = await airService.sendEthereumRpcRequest(
    EthereumRpcRequest(
      method: 'eth_getBalance',
      params: [address, 'latest'],
    ),
  );
}
```

### Switch or add chain

```dart theme={null}
await airService.sendEthereumRpcRequest(
  EthereumRpcRequest(
    method: 'wallet_switchEthereumChain',
    params: [
      {'chainId': '0x1'},
    ],
  ),
);
```

## web3dart

You can implement a thin adapter that forwards `JsonRpc` calls to `sendEthereumRpcRequest`. Keep the adapter in your app repo and test against your SDK version.

## Next steps

* [Wallet operations](/airkit/flutter/wallet-operations)
* [Supported chains](/airkit/usage/account/supported-chains)


# Flutter troubleshooting
Source: https://docs.moca.network/airkit/flutter/troubleshooting

Common fixes for AIR Kit Flutter integration: install, platform config, login, and WebView issues.

## Installation and OnePub

| Issue                      | What to try                                                                                           |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `onepub` command not found | Add `$HOME/.pub-cache/bin` to PATH                                                                    |
| Package resolve failures   | `onepub login`, verify hosted URL and version in [Flutter installation](/airkit/flutter/installation) |

## Android

| Issue                            | What to try                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Passkey / asset links            | [Android setup](/airkit/flutter/android-setup): `strings.xml`, manifest `meta-data`, signing cert allowlisting |
| `minSdk` / manifest merge errors | Set `minSdk` 26+, `compileSdk` 34+                                                                             |

## iOS

| Issue              | What to try                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| Associated Domains | [iOS setup](/airkit/flutter/ios-setup): capability, exact domain entries, physical device |
| CocoaPods          | `cd ios && rm -rf Pods Podfile.lock && pod install`                                       |

## Runtime

| Issue                        | What to try                                                          |
| ---------------------------- | -------------------------------------------------------------------- |
| Login UI does not appear     | `navigatorKey` passed to `MaterialApp` and `initialize()`            |
| `Service is not initialized` | Await `initialize()` before other calls                              |
| WebView blank                | Platform network config, ATS (iOS), Associated Domains / asset links |

## Credentials on Flutter

Credential **issuance** and **verification** are available on Flutter. Use the [Issue credentials](/airkit/quickstart/issue-credentials) and [Verify credentials](/airkit/quickstart/verify-credentials) quickstarts, plus [Issuing credentials](/airkit/usage/credential/issuing-credentials) and [Verify](/airkit/usage/credential/verify).

If calls fail or payloads are rejected, see [Credential issues](/airkit/troubleshooting/credential-issues). For Google OAuth client IDs and dashboard-side setup, see [Google Sign-In — Dashboard](/airkit/flutter/google-signin#dashboard).

## More help

* [SDK issues](/airkit/troubleshooting/sdk-issues) — includes Flutter-specific notes
* [Common errors](/airkit/troubleshooting/common-errors)
* Support via your Moca / partner channel


# Flutter UI components
Source: https://docs.moca.network/airkit/flutter/ui-components

Built-in AIR Kit UI on Flutter: login, swap, on-ramp, and MFA.

AIR Kit exposes **native Flutter UI** for login and several **hosted UI flows** through `AirService`. APIs below match the [Reference](/airkit/usage/reference) Flutter tab.

## Prerequisites

* [Initialization](/airkit/usage/initialization) with a valid `GlobalKey<NavigatorState>` on `MaterialApp`
* For **Swap**, **On-ramp**, and **MFA** below: an authenticated session after `login`
* Optional: `preloadWallet()` before opening wallet UIs for smoother first open

## Login

`login` presents **native Flutter UI** for the configured login methods. After `initialize()`, call `login` with your **Partner JWT** (`authToken`) as described in [User login & sessions](/airkit/usage/user-authentication) (Flutter tab).

## Swap UI

```dart theme={null}
await airService.showSwapUi();
```

## On-ramp UI

```dart theme={null}
await airService.showOnRampUi(
  displayCurrencyCode: 'USD',
  targetCurrencyCode: 'ETH', // optional
);
```

## MFA setup

```dart theme={null}
await airService.setupOrUpdateMfa();
```

Check status via `getUserInfo()` → `user.isMFASetup` (see Reference models).

## Theming, locale, and currency

Web SDK uses `sessionConfig` / `updateSessionConfig` on `init`. For Flutter, confirm behavior in your SDK version and [Release notes](/airkit/release-notes). Dashboard and partner configuration also affect login and widget appearance — see [Theming](/airkit/usage/config-theming) and [Language & currency](/airkit/usage/config-language) for product-level options.

## Web-first built-in UI

Some Account Services UIs documented under [Built-in UI](/airkit/usage/account/builtin-ui) are Web-first; Flutter parity varies by release. Confirm APIs and behavior in the [Reference](/airkit/usage/reference) Flutter tab and [Release notes](/airkit/release-notes).

## Next steps

* [Wallet operations](/airkit/flutter/wallet-operations)
* [User login & sessions](/airkit/usage/user-authentication)


# Flutter wallet operations
Source: https://docs.moca.network/airkit/flutter/wallet-operations



After [initialization](/airkit/usage/initialization) and login, use `AirService` for embedded wallet operations. Method names match the [Reference](/airkit/usage/reference) Flutter tab.

## Prerequisites

* `await airService.initialize(...)` completed
* User authenticated (see [User login & sessions](/airkit/usage/user-authentication))
* Optional: `await airService.preloadWallet()` before first wallet UI or heavy RPC use

## Accounts and address

```dart theme={null}
final accounts = await airService.getAccounts();
final address = await airService.getAbstractAccountAddress();
```

## Balances

```dart theme={null}
final address = await airService.getAbstractAccountAddress();
if (address != null) {
  final balanceWei = await airService.getBalance(address);
  // Format for display (example: 18 decimals)
}
```

## Sign messages

```dart theme={null}
final signature = await airService.signMessage('Hello from AIR Kit');
```

## Contract reads (`call`)

```dart theme={null}
final result = await airService.call(
  '0xContractAddress',
  'balanceOf',
  [/* parameters */],
  erc20AbiJsonString,
);
```

## Transactions (`sendTransaction`)

Use `web3dart` `Transaction` / `Transaction.callContract` types as in your SDK version:

```dart theme={null}
import 'package:web3dart/web3dart.dart';

// Example shape — adjust gas, chain, and contract types to your app
final txHash = await airService.sendTransaction(transaction);
```

## Smart account deployment

```dart theme={null}
final deployed = await airService.isSmartAccountDeployed();
if (!deployed) {
  final txHash = await airService.deploySmartAccount();
}
```

## Built-in wallet UI

* Swap: `await airService.showSwapUi();`
* On-ramp: `await airService.showOnRampUi(displayCurrencyCode: 'USD');`

See [UI components](/airkit/flutter/ui-components).

## Error handling

Catch `AirKitException` and inspect `type` (`client`, `sdk`, `server`, `unknown`) for logging and user messaging.

## Next steps

* [Provider functions](/airkit/flutter/provider-functions) — raw JSON-RPC
* [Account Services](/airkit/usage/account/smart-account) — product concepts (web-centric sections may still apply conceptually)
* [Paymaster](/airkit/usage/account/paymaster) — gas sponsorship where supported


# AIR for Advertising & Audiences
Source: https://docs.moca.network/airkit/guides/air-for-advertising

Build verified, consent-based audience segments without third-party cookies. Let advertisers buy access to cryptographically proven user attributes — no raw data leaves user accounts.

Post-cookie advertising is broken in one specific way: every replacement (contextual, cohort, data clean rooms) still requires someone to hold raw user data and vouch for it. AIR Kit takes a different approach — **users hold their own verified attribute credentials**, and publishers verify them at ad-serve time via ZK proof. The advertiser gets a signal they can trust. No data broker in the middle. No raw data leaves the user's account.

## What You Can Build

* **Verified audience segments** — Issue demographic and interest credentials on profile completion or KYC; advertisers target against cryptographic proof, not self-reported fields
* **Consent-portable targeting** — User consents once; that consent credential is verifiable by any publisher in the ecosystem without a consent management platform re-prompt
* **Age-verified ad targeting** — Gate alcohol, gambling, and adult ad categories behind a ZK age proof — no DOB ever transmitted to the ad server
* **Cross-publisher identity** — A user's verified attributes follow them across publisher sites without third-party cookies or device fingerprinting
* **Bot and fraud resistance** — Issue a "verified human" credential after KYC or passkey authentication; DSPs and SSPs can filter on-credential instead of on-signal
* **Brand safety compliance** — Verify user age and location at serve time without storing the data, satisfying COPPA, GDPR Article 8, and regional ad regulations

## Architecture

```mermaid theme={null}
graph TD
    A["User completes profile / KYC\non your platform"] --> B[Your Backend]
    B -->|Issue on Behalf API| C[AIR Kit / Moca Chain]
    C --> D["Audience Credentials\nin User's AIR Account"]

    D --> E{Ad serve request}
    E -->|Publisher verifies| F["ZK proof: age ✓ location ✓\ninterest segment ✓"]
    F --> G[DSP receives verified segment signal]
    G --> H[Targeted ad served]

    D --> I{Cross-publisher visit}
    I -->|Any partner publisher| J["Same credentials verified\nno cookie / fingerprint needed"]
```

## Recommended Schemas

### Verified Audience Segment

```json theme={null}
{
  "title": "Audience Segment",
  "description": "Publisher-verified user audience attributes — no raw PII included",
  "properties": {
    "publisherId": {
      "type": "string",
      "description": "Issuing publisher identifier"
    },
    "ageRange": {
      "type": "string",
      "enum": ["18-24", "25-34", "35-44", "45-54", "55+"],
      "description": "Verified age bracket — never the actual age or DOB"
    },
    "isOver18": {
      "type": "boolean"
    },
    "isOver21": {
      "type": "boolean"
    },
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 — verified registration country"
    },
    "interestSegments": {
      "type": "array",
      "items": { "type": "string" },
      "description": "IAB content categories — e.g. ['IAB19', 'IAB9'] — derived from behaviour, not declared"
    },
    "verifiedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["publisherId", "isOver18", "countryCode", "verifiedAt"]
}
```

### Consent Credential

```json theme={null}
{
  "title": "Ad Consent",
  "description": "Verifiable record of user consent for personalised advertising",
  "properties": {
    "publisherId": { "type": "string" },
    "consentedTo": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["personalised_ads", "cross_site_tracking", "interest_inference"]
      }
    },
    "consentVersion": {
      "type": "string",
      "description": "CMP policy version the user consented to"
    },
    "consentedAt": {
      "type": "string",
      "format": "date-time"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Consent expiry — re-issue when user re-confirms"
    }
  },
  "required": ["publisherId", "consentedTo", "consentVersion", "consentedAt"]
}
```

<Warning>
  Never include name, email address, IP address, device ID, or precise location in `credentialSubject`. Use only **derived, aggregated attributes** — `ageRange`, `countryCode`, `interestSegments`. The ZK proof lets the ad server confirm `isOver18 === true` without ever receiving the subscriber's date of birth.
</Warning>

## Implementation

### Step 1 — Issue audience credentials on profile completion

```javascript theme={null}
// profile-complete-handler.js
const { getPartnerJwt } = require('./lib/jwt');

const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

async function issueAudienceCredential({ userEmail, profile }) {
  const token = await getPartnerJwt(userEmail);

  const res = await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-partner-auth': token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.AUDIENCE_CREDENTIAL_ID,
      credentialSubject: {
        publisherId: process.env.PUBLISHER_ID,
        ageRange: getAgeRange(profile.birthYear),    // "25-34" — NOT the DOB
        isOver18: profile.age >= 18,
        isOver21: profile.age >= 21,
        countryCode: profile.countryCode,
        interestSegments: profile.iabSegments,       // e.g. ['IAB19', 'IAB9-30']
        verifiedAt: new Date().toISOString(),
      },
      onDuplicate: 'revoke', // refresh when profile or interests update
    }),
  });

  if (!res.ok) throw new Error(`Audience credential issuance failed: ${res.status}`);
  return res.json();
}

function getAgeRange(birthYear) {
  const age = new Date().getFullYear() - birthYear;
  if (age < 25) return '18-24';
  if (age < 35) return '25-34';
  if (age < 45) return '35-44';
  if (age < 55) return '45-54';
  return '55+';
}

// Fire on profile completion and on interest segment updates
userEvents.on('profile:completed', ({ userEmail, profile }) =>
  issueAudienceCredential({ userEmail, profile })
);
userEvents.on('interests:updated', ({ userEmail, profile }) =>
  issueAudienceCredential({ userEmail, profile })
);
```

### Step 2 — Issue consent credential when user accepts CMP

```javascript theme={null}
// consent-handler.js
async function issueConsentCredential({ userEmail, consentRecord }) {
  const token = await getPartnerJwt(userEmail);

  const expiresAt = new Date();
  expiresAt.setFullYear(expiresAt.getFullYear() + 1); // 1-year consent window

  await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.CONSENT_CREDENTIAL_ID,
      credentialSubject: {
        publisherId: process.env.PUBLISHER_ID,
        consentedTo: consentRecord.purposes,       // ["personalised_ads", ...]
        consentVersion: consentRecord.policyVersion,
        consentedAt: new Date().toISOString(),
        expiresAt: expiresAt.toISOString(),
      },
      onDuplicate: 'revoke', // replace on re-consent or withdrawal
    }),
  });
}

// Wire into your CMP callback
cmp.on('consent:granted', ({ userEmail, purposes, policyVersion }) =>
  issueConsentCredential({
    userEmail,
    consentRecord: { purposes, policyVersion },
  })
);

// Revoke consent credential on withdrawal
cmp.on('consent:withdrawn', async ({ userEmail }) => {
  // Issue credential with empty consentedTo to effectively invalidate
  // Or call the revoke endpoint directly — see Issue on Behalf API reference
});
```

### Step 3 — Verify audience attributes at ad-serve time

```javascript theme={null}
// ad-server-verify.js (publisher ad server / prebid adapter)
import { AirService } from '@mocanetwork/airkit';

import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.PUBLISHER_PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.PRODUCTION });

async function getVerifiedAudienceSignal() {
  // Check age compliance for restricted category
  const ageResult = await airService.verifyCredential({
    programId: process.env.AGE_18_VERIFY_PROGRAM_ID,
    // Program rule: isOver18 === true
    // Verifier receives only: COMPLIANT / NON_COMPLIANT
  });

  // Check consent for personalised ads
  const consentResult = await airService.verifyCredential({
    programId: process.env.CONSENT_VERIFY_PROGRAM_ID,
    // Program rule: "personalised_ads" in consentedTo AND expiresAt > now
  });

  return {
    ageVerified: ageResult.status === 'COMPLIANT',
    consentVerified: consentResult.status === 'COMPLIANT',
    // Pass these as verified signals to your DSP bid request
    // No raw age, no raw consent record — just provable booleans
  };
}

// Enrich bid request with verified signals
async function buildBidRequest(adSlot, user) {
  const signals = await getVerifiedAudienceSignal();

  return {
    ...adSlot,
    user: {
      ...user,
      ext: {
        airkit: {
          ageVerified: signals.ageVerified,
          consentVerified: signals.consentVerified,
          // DSP can bid higher on verified signals vs. unverified
        },
      },
    },
  };
}
```

### Step 4 — Cross-publisher audience verification (partner publisher)

Partner publishers integrate AIR Kit as a verifier. One SDK call replaces the cookie sync / data clean room round-trip.

```javascript theme={null}
// partner-publisher.js
import { AirService } from '@mocanetwork/airkit';

// The PARTNER publisher uses their own Partner ID
const airService = new AirService({ partnerId: 'PARTNER_PUBLISHER_PARTNER_ID' });
await airService.init({ buildEnv: BUILD_ENV.PRODUCTION });

async function verifyAudienceForPartner() {
  const result = await airService.verifyCredential({
    programId: process.env.CROSS_PUB_AUDIENCE_VERIFY_PROGRAM_ID,
    // Program checks: isOver18 === true AND countryCode in allowed list
    // The partner publisher never receives the user's raw profile data
    // They get: COMPLIANT / NON_COMPLIANT — that's it
  });
  return result.status === 'COMPLIANT';
}
```

## Key Patterns

| Pattern                     |  `onDuplicate` | When to Use                               |
| --------------------------- | :------------: | ----------------------------------------- |
| Initial audience credential |   `"ignore"`   | Issue once on first profile completion    |
| Interest segment refresh    |   `"revoke"`   | Monthly or on significant interest drift  |
| Consent granted             |   `"revoke"`   | Always replace with latest consent record |
| Consent withdrawn           | Revoke via API | Immediately invalidate consent credential |
| KYC-backed audience         |   `"revoke"`   | Re-issue when KYC result updates          |

## Privacy Guarantee

No raw user data — no DOB, no email, no IP, no browsing history — is transmitted during ad verification. The ZK proof flow means the verifier (DSP, SSP, partner publisher) receives only boolean results.

| What the Verifier Sees      | What Stays Private            |
| --------------------------- | ----------------------------- |
| `COMPLIANT / NON_COMPLIANT` | Date of birth, exact age      |
| `ageRange` (`25-34`)        | Full name, email address      |
| `isOver18: true`            | IP address, device ID         |
| `countryCode` (`AU`)        | Precise location              |
| IAB segment IDs             | Browsing history, clickstream |
| Consent expiry date         | Declared interests            |

## Regulatory Alignment

* **GDPR Article 8** — Age verification without storing DOB satisfies child protection obligations
* **CCPA / CPRA** — Consent credential provides an auditable, user-owned record of opt-in; revocation is instant and on-chain
* **COPPA** — ZK age gate (isOver18 === false blocks serve) without collecting minor data
* **TCF 2.2** — Consent credentials can encode TCF purpose IDs; verifiers check compliance without a centralised CMP dependency

## Examples

The repo uses a venue check-in and merch store; the same event-triggered pattern applies to ad engagement (publisher issues, ad server verifies). Adapt via schema and branding — see the README's "Adapting to Your Vertical" section.

<CardGroup>
  <Card title="Fan Attendance — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/fan-attendance/issuer">
    Venue check-in app: issues attendance credential when the fan scans in at the event.
  </Card>

  <Card title="Fan Attendance — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/fan-attendance/verifier">
    Merch store app: verifies attendance and unlocks rewards (e.g. discount, exclusive offer).
  </Card>
</CardGroup>

## Next Steps

<Columns>
  <Card title="Issue on Behalf — Concepts" icon="book" href="/airkit/usage/credential/issue-on-behalf">
    Server-side issuance without user presence.
  </Card>

  <Card title="Issue on Behalf — API" icon="code" href="/airkit/usage/credential/issue-on-behalf-api">
    Full endpoint reference with error codes.
  </Card>

  <Card title="AIR for Fintech & Payments" icon="credit-card" href="/airkit/guides/air-for-fintech">
    KYC portability and age verification patterns.
  </Card>

  <Card title="Schema Use Cases" icon="list" href="/airkit/usage/credential/schema-use-cases">
    More credential schema examples.
  </Card>
</Columns>


# AIR for Fintech & Payments
Source: https://docs.moca.network/airkit/guides/air-for-fintech

Issue KYC credentials, income proofs, and compliance attestations without storing PII. Enable privacy-preserving financial verification with AIR Kit.

Traditional KYC and compliance verification requires every platform to collect, store, and protect sensitive personal data — creating liability, compliance risk, and repeated friction for users. AIR Kit lets you **issue a KYC credential once**, and any partner platform can verify it via zero-knowledge proof without ever accessing raw PII.

## What You Can Build

* **KYC credentials** — Issue a verified identity attestation the moment a user passes KYC; partner platforms accept it without re-running the check
* **Income / accreditation proofs** — Issue an "Accredited Investor" credential backed by income verification, provable via ZK proof
* **Compliance gating** — Gate DeFi pools, financial products, or high-value transactions behind credential checks
* **Age verification** — Prove a user is 18+ or 21+ without revealing their birthdate to the verifier
* **Cross-border compliance** — One credential, accepted at every partner service in the ecosystem

## Architecture

```mermaid theme={null}
graph TD
    A["User completes KYC\nwith your KYC provider"] --> B["KYC Provider webhook / callback"]
    B --> C[Your Backend]
    C -->|Issue on Behalf API| D[AIR Kit / Moca Chain]
    D --> E[KYC Credential in User's AIR Account]

    E --> F{User accesses financial product}
    F -->|Your platform| G["Verify KYC credential\nNo PII stored or transferred"]
    F -->|Partner DeFi protocol| H["ZK proof: user is KYC'd"]
    F -->|Cross-border service| I[Compliance check passed]
```

## Recommended Schema

### KYC Attestation

```json theme={null}
{
  "title": "KYC Attestation",
  "description": "Identity verification attestation — no raw PII included",
  "properties": {
    "kycLevel": {
      "type": "string",
      "enum": ["basic", "enhanced", "institutional"],
      "description": "Level of KYC verification completed"
    },
    "kycProvider": {
      "type": "string",
      "description": "Name of the KYC provider (e.g. 'Jumio', 'Onfido')"
    },
    "verifiedAt": {
      "type": "string",
      "format": "date-time"
    },
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code"
    },
    "isOver18": {
      "type": "boolean"
    },
    "isOver21": {
      "type": "boolean"
    }
  },
  "required": ["kycLevel", "kycProvider", "verifiedAt", "isOver18"]
}
```

<Warning>
  Never include raw PII — full name, passport number, date of birth, address — in `credentialSubject`. Store only **attestations and derived facts**. ZK proofs let verifiers confirm `isOver18 === true` without seeing any underlying data.
</Warning>

## Implementation

### Step 1 — Issue KYC credential from your KYC webhook

```javascript theme={null}
// kyc-webhook.js  — called when your KYC provider sends a completion event
const { getPartnerJwt } = require('./lib/jwt');

async function issueKycCredential({ userEmail, kycResult }) {
  if (kycResult.status !== 'APPROVED') return; // only issue on success

  const token = await getPartnerJwt(userEmail);

  const res = await fetch('https://api.sandbox.mocachain.org/v1/credentials/issue-on-behalf', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-partner-auth': token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.KYC_CREDENTIAL_ID,
      credentialSubject: {
        kycLevel: kycResult.level,             // "basic" | "enhanced" | "institutional"
        kycProvider: 'YourKYCProvider',
        verifiedAt: new Date().toISOString(),
        countryCode: kycResult.countryCode,    // e.g. "US", "GB"
        isOver18: kycResult.age >= 18,
        isOver21: kycResult.age >= 21,
      },
      onDuplicate: 'revoke', // re-issue if KYC level upgrades
    }),
  });

  if (!res.ok) throw new Error(`KYC credential issuance failed: ${res.status}`);
  return res.json();
}

// Express webhook endpoint
app.post('/webhooks/kyc', async (req, res) => {
  const { userEmail, kycResult } = req.body;
  await issueKycCredential({ userEmail, kycResult });
  res.json({ ok: true });
});
```

### Step 2 — Gate financial products with credential verification

```javascript theme={null}
// fintech-gate.js  (frontend)
import { AirService } from '@mocanetwork/airkit';

import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

async function requireKyc() {
  const result = await airService.verifyCredential({
    programId: process.env.KYC_VERIFY_PROGRAM_ID,
    // Verifier program rule: kycLevel is "enhanced" or "institutional"
  });

  if (result.status !== 'COMPLIANT') {
    throw new Error('KYC_REQUIRED');
  }
  return result;
}

// Gate a high-value transaction
try {
  await requireKyc();
  proceedWithTransaction();
} catch (err) {
  if (err.message === 'KYC_REQUIRED') showKycOnboarding();
}
```

### Step 3 — Age verification gate (no birthdate exposed)

```javascript theme={null}
// age-gate.js  (frontend)
async function requireAgeVerification() {
  const result = await airService.verifyCredential({
    programId: process.env.AGE_18_VERIFY_PROGRAM_ID,
    // Program checks: isOver18 === true  — verifier never sees the actual age/DOB
  });
  return result.status === 'COMPLIANT';
}
```

## Privacy Guarantee

The ZK proof flow means the verifier receives **only a boolean result**. No raw KYC data, no PII, no liability for the verifier to store sensitive documents.

| What the Verifier Sees           | What Stays Private              |
| -------------------------------- | ------------------------------- |
| `COMPLIANT / NON_COMPLIANT`      | Full name, passport / ID number |
| Credential expiry date           | Date of birth                   |
| KYC level (`basic` / `enhanced`) | Residential address             |
| Issuer DID                       | Income figures, net worth       |
| `isOver18: true`                 | Actual age                      |

## Examples

<CardGroup>
  <Card title="KYC Passport — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/issuer">
    KYC provider app: issues credentials once; user carries the proof to other platforms.
  </Card>

  <Card title="KYC Passport — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/verifier">
    Lending platform app: verifies the credential and accepts the proof without re-running KYC.
  </Card>

  <Card title="ZK Age Verification — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/issuer">
    Identity provider app: issues age credential; user proves 18+ without revealing date of birth.
  </Card>

  <Card title="ZK Age Verification — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/verifier">
    iGaming platform app: verifies age-gate (e.g. 18+) via ZK proof; no PII received.
  </Card>
</CardGroup>

## Next Steps

<Columns>
  <Card title="Issue on Behalf — Concepts" icon="book" href="/airkit/usage/credential/issue-on-behalf">
    Server-side issuance without user presence.
  </Card>

  <Card title="Architecture & Data Flow" icon="diagram-project" href="/airkit/guides/overview">
    ZK proof flow end-to-end.
  </Card>

  <Card title="Partner Authentication" icon="key" href="/airkit/usage/partner-authentication">
    JWT signing setup for your backend.
  </Card>

  <Card title="Verifying Credentials" icon="shield-check" href="/airkit/usage/credential/verify">
    SDK verification reference.
  </Card>
</Columns>


# AIR for Gaming & NFTs
Source: https://docs.moca.network/airkit/guides/air-for-gaming

Port player identities, achievements, and badges across games and chains. Issue cross-game credentials that follow players wherever they play.

In gaming, players rebuild their reputation from zero every time they switch titles. AIR Kit lets you **make achievements, badges, and identities portable** — a player's rank in your game becomes a credential they carry to partner games, tournaments, communities, and airdrops.

## What You Can Build

* **Achievement badges** — Issue on-chain proof that a player reached Diamond rank, completed a raid, or earned a title
* **Cross-game identity** — Let players carry their AIR Account identity and credentials into any game in the Moca ecosystem
* **Anti-cheat / bot gating** — Verify a player holds a "verified human" or KYC credential before allowing tournament entry
* **Airdrop gating** — Reward only players who hold specific credentials (e.g. "played > 100 hrs", "held NFT for 90 days")
* **Guild / DAO membership** — Issue guild membership credentials that gate Discord roles, in-game benefits, and governance votes

## Architecture

```mermaid theme={null}
graph TD
    A["In-game event\ne.g. rank achieved, raid completed"] --> B[Game Server]
    B -->|Issue on Behalf API| C[AIR Kit / Moca Chain]
    C --> D[Achievement Credential in Player's AIR Account]

    D --> E{Player uses credential}
    E --> F[Display badge in game profile]
    E --> G[Enter partner game tournament]
    E --> H[Claim ecosystem airdrop]
    E --> I[Access guild Discord role]
```

## Recommended Schema

```json theme={null}
{
  "title": "Game Achievement",
  "description": "On-chain proof of a player achievement or rank",
  "properties": {
    "gameId": {
      "type": "string",
      "description": "Unique identifier of the game"
    },
    "achievementId": {
      "type": "string",
      "description": "Unique identifier of the achievement"
    },
    "achievementName": {
      "type": "string",
      "description": "Display name — e.g. 'Diamond Rank Season 3'"
    },
    "tier": {
      "type": "string",
      "enum": ["Bronze", "Silver", "Gold", "Platinum", "Diamond"],
      "description": "Achievement tier"
    },
    "earnedAt": {
      "type": "string",
      "format": "date-time"
    },
    "season": {
      "type": "string",
      "description": "Game season, e.g. 'Season 3'"
    }
  },
  "required": ["gameId", "achievementId", "achievementName", "earnedAt"]
}
```

## Implementation

### Step 1 — Issue an achievement credential on rank-up

```javascript theme={null}
// game-server.js
const { getPartnerJwt } = require('./lib/jwt');

async function issueAchievement({ playerEmail, achievement }) {
  const token = await getPartnerJwt(playerEmail);

  const res = await fetch('https://api.sandbox.mocachain.org/v1/credentials/issue-on-behalf', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-partner-auth': token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.ACHIEVEMENT_CREDENTIAL_ID,
      credentialSubject: {
        gameId: process.env.GAME_ID,
        achievementId: achievement.id,
        achievementName: achievement.name,
        tier: achievement.tier,
        earnedAt: new Date().toISOString(),
        season: 'Season 3',
      },
      onDuplicate: 'ignore', // achievements are one-time — don't re-issue
    }),
  });

  if (!res.ok) throw new Error(`Achievement issuance failed: ${res.status}`);
  return res.json();
}

// Wire into your game's rank-up event system
gameEvents.on('player:rank_up', async ({ playerEmail, newRank }) => {
  await issueAchievement({
    playerEmail,
    achievement: {
      id: `rank-${newRank.toLowerCase()}`,
      name: `${newRank} Rank`,
      tier: newRank,
    },
  });
  console.log(`Achievement issued to ${playerEmail}: ${newRank}`);
});
```

### Step 2 — Gate tournament entry with credential check

```javascript theme={null}
// tournament-gate.js  (frontend or server)
import { AirService } from '@mocanetwork/airkit';

import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

async function canJoinTournament() {
  const result = await airService.verifyCredential({
    programId: process.env.TOURNAMENT_VERIFY_PROGRAM_ID,
    // Verifier program rule: tier === "Diamond" AND gameId === process.env.GAME_ID
  });
  return result.status === 'COMPLIANT';
}

const eligible = await canJoinTournament();
if (!eligible) {
  showMessage('Reach Diamond rank to enter this tournament.');
}
```

### Step 3 — Cross-game SSO with AIR Account

Partner games authenticate using the same AIR Account — no new signup required.

```javascript theme={null}
// partner-game.js  (any game integrating AIR Kit)
import { AirService } from '@mocanetwork/airkit';

const airService = new AirService({ partnerId: 'PARTNER_GAME_PARTNER_ID' });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

await airService.login(); // player logs in with existing AIR Account
const user = await airService.getUserInfo();
// user.email is the same across all games — portable, unified identity
```

### Step 4 — Bot-resistant airdrop gating

Only distribute tokens to players who provably hold a real game achievement — filtered on-chain.

```javascript theme={null}
// airdrop.js  (server-side)
async function getEligiblePlayers(allPlayers) {
  const eligible = [];
  for (const { email } of allPlayers) {
    const token = await getPartnerJwt(email);
    // Use your verifier program to check credential status per player
    // In production, batch this with your own DB query first to reduce API calls
    const res = await fetch(
      `https://api.sandbox.mocachain.org/v1/credentials/status?...`,
      { headers: { 'x-partner-auth': token } }
    );
    const { vcStatus } = await res.json();
    if (vcStatus === 'ONCHAIN') eligible.push(email);
  }
  return eligible;
}
```

## Examples

<CardGroup>
  <Card title="ZK Age Verification — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/issuer">
    Identity provider app: issues age credential; user proves 18+ without revealing date of birth.
  </Card>

  <Card title="ZK Age Verification — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/zk-age-verification/verifier">
    iGaming or age-gated app: verifies age via ZK proof and grants access; no PII received.
  </Card>
</CardGroup>

## Next Steps

<Columns>
  <Card title="Issue on Behalf API" icon="code" href="/airkit/usage/credential/issue-on-behalf-api">
    Full endpoint reference and error codes.
  </Card>

  <Card title="Issuing Credentials (SDK)" icon="badge-check" href="/airkit/usage/credential/issuing-credentials">
    User-initiated issuance for in-game claim flows.
  </Card>

  <Card title="Schema Use Cases" icon="list" href="/airkit/usage/credential/schema-use-cases">
    More schema examples including event pass.
  </Card>

  <Card title="AIR for Ticketing & Events" icon="ticket" href="/airkit/guides/air-for-ticketing">
    Attendance credentials for live events.
  </Card>
</Columns>


# AIR for Loyalty & Rewards
Source: https://docs.moca.network/airkit/guides/air-for-loyalty

Build portable, verifiable loyalty programs using AIR Kit credential services. Issue tier badges, points milestones, and membership credentials that travel with users across platforms.

Loyalty programs today are siloed — a user's Gold status with one brand is invisible to another. AIR Kit lets you issue **verifiable loyalty credentials** that users carry in their AIR Account and present anywhere in the ecosystem, across brands, apps, and chains.

## What You Can Build

* **Tier credentials** — Issue a "Gold Member" or "VIP" badge that upgrades or revokes automatically as status changes
* **Milestone badges** — Issue a credential when a user reaches 1,000 points, 10 purchases, or any event-driven threshold
* **Cross-platform loyalty** — Allow partner apps to accept your loyalty credentials as proof of status, no API integration required
* **Zero-friction issuance** — Trigger credential issuance from your loyalty engine backend; the user doesn't need to open a wallet or take any action

## Architecture

```mermaid theme={null}
graph TD
    A["User Action\ne.g. purchase, referral, check-in"] --> B[Your Loyalty Engine]
    B -->|Milestone reached| C[Issue on Behalf API]
    C --> D[AIR Kit / Moca Chain]
    D --> E[Loyalty Credential in User's AIR Account]

    E --> F{User presents credential}
    F -->|At your app| G[Tier unlock / reward]
    F -->|At partner app| H[Cross-brand benefit]
    F -->|At any verifier| I[Gated access / discount]
```

## Recommended Schema

Create this schema in the [AIR Kit Dashboard](https://developers.sandbox.air3.com/dashboard) under **Issuer → Schema Builder**.

```json theme={null}
{
  "title": "Loyalty Tier",
  "description": "Brand loyalty membership tier credential",
  "properties": {
    "tier": {
      "type": "string",
      "enum": ["Bronze", "Silver", "Gold", "Platinum"],
      "description": "Current loyalty tier"
    },
    "totalPoints": {
      "type": "number",
      "description": "Lifetime points accumulated"
    },
    "memberSince": {
      "type": "string",
      "format": "date",
      "description": "Date of first loyalty enrollment"
    },
    "brandId": {
      "type": "string",
      "description": "Issuing brand identifier"
    }
  },
  "required": ["tier", "totalPoints", "brandId"]
}
```

## Implementation

### Step 1 — Issue a loyalty credential on milestone

Use **Issue on Behalf** to issue silently when a backend event fires. The user's session is not required.

```javascript theme={null}
// loyalty-engine.js
const { getPartnerJwt } = require('./lib/jwt'); // see Partner Authentication

const BASE_URL = 'https://api.sandbox.mocachain.org/v1'; // swap for prod URL on launch

async function issueLoyaltyCredential({ userEmail, tier, totalPoints, memberSince }) {
  const token = await getPartnerJwt(userEmail); // JWT must include scope: "issue on-behalf"

  const res = await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-partner-auth': token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,          // Dashboard → Accounts → General
      credentialId: process.env.LOYALTY_CRED_ID,  // Dashboard → Issuer → Programs
      credentialSubject: { tier, totalPoints, memberSince, brandId: process.env.BRAND_ID },
      onDuplicate: 'revoke',  // upgrade tier by revoking old credential, issuing new one
    }),
  });

  if (!res.ok) throw new Error(`Issuance failed: ${res.status}`);
  const { coreClaimHash } = await res.json();
  return coreClaimHash;
}

// Hook into your existing loyalty event pipeline
loyaltyEngine.on('tier:upgrade', async ({ userEmail, newTier, totalPoints }) => {
  const hash = await issueLoyaltyCredential({
    userEmail,
    tier: newTier,
    totalPoints,
    memberSince: new Date().toISOString().split('T')[0],
  });
  console.log(`Loyalty credential issued: ${hash}`);
});
```

### Step 2 — Verify loyalty tier at point of benefit

On your frontend, verify the user holds the required tier before granting access or rewards.

```javascript theme={null}
// loyalty-gate.js  (frontend)
import { AirService } from '@mocanetwork/airkit';

import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX }); // or BUILD_ENV.PRODUCTION

async function checkLoyaltyTier() {
  const result = await airService.verifyCredential({
    programId: process.env.LOYALTY_VERIFY_PROGRAM_ID, // Dashboard → Verifier → Programs
  });
  // Your verifier program rule: tier === "Gold" (or higher)
  return result.status === 'COMPLIANT';
}

const hasGoldStatus = await checkLoyaltyTier();
if (hasGoldStatus) {
  unlockPremiumContent();
} else {
  showUpgradePrompt();
}
```

## Key Patterns

| Pattern                   |       `onDuplicate` value       | When to Use                                    |
| ------------------------- | :-----------------------------: | ---------------------------------------------- |
| Tier upgrade              |            `"revoke"`           | Always revoke old credential and issue new one |
| One-time milestone badge  |            `"ignore"`           | Don't re-issue if credential already held      |
| Time-boxed VIP            | Set `expirationDate` in subject | Seasonal or campaign-based access              |
| Retroactive bulk issuance |  Loop `issueLoyaltyCredential`  | Migrating existing loyalty members             |

## Status Polling (optional)

Issuance is asynchronous. Poll until `ONCHAIN` before showing a confirmation to the user.

```javascript theme={null}
async function waitForOnchain(userEmail, coreClaimHash, maxAttempts = 10) {
  const token = await getPartnerJwt(userEmail);
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(
      `${BASE_URL}/credentials/status?coreClaimHash=${encodeURIComponent(coreClaimHash)}`,
      { headers: { 'x-partner-auth': token } }
    );
    const { vcStatus } = await res.json();
    if (vcStatus === 'ONCHAIN') return true;
    await new Promise(r => setTimeout(r, 2000)); // wait 2 s between polls
  }
  return false;
}
```

## Examples

<CardGroup>
  <Card title="VIP Status Portability — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/issuer">
    Airline loyalty app: issues tier credential; user carries status to partner brands.
  </Card>

  <Card title="VIP Status Portability — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/verifier">
    Hotel chain app: verifies tier and grants equivalent perks (e.g. room upgrade, lounge).
  </Card>
</CardGroup>

## Next Steps

<Columns>
  <Card title="Issue on Behalf — Concepts" icon="book" href="/airkit/usage/credential/issue-on-behalf">
    Understand when and why to use server-side issuance.
  </Card>

  <Card title="Issue on Behalf — API" icon="code" href="/airkit/usage/credential/issue-on-behalf-api">
    Full endpoint reference with error codes.
  </Card>

  <Card title="Schema Use Cases" icon="list" href="/airkit/usage/credential/schema-use-cases">
    More schema examples including membership and event pass.
  </Card>

  <Card title="Verifying Credentials" icon="shield-check" href="/airkit/usage/credential/verify">
    SDK verification flow reference.
  </Card>
</Columns>


# AIR for Telco & Subscriptions
Source: https://docs.moca.network/airkit/guides/air-for-telco

Issue subscriber credentials at activation, reuse KYC across carrier partners, and build loyalty tiers that reduce churn — without storing subscriber PII.

Carriers run identity verification for every new subscriber, but that verified status stays locked inside each operator's silo. A prepaid user who passes KYC at one carrier starts from zero at a roaming partner. AIR Kit lets you **issue a subscriber credential at activation** — so your KYC investment travels with the user across carriers, MVNOs, and partner services.

## What You Can Build

* **Subscriber credentials** — Issue a verified subscriber attestation the moment a user activates; roaming and partner carriers accept it without re-running identity checks
* **Plan tier credentials** — Issue a "Premium" or "Business" tier badge that unlocks partner benefits automatically, with no bilateral API required
* **Device ownership proofs** — Issue a verified device credential (IMEI-bound) for device insurance, warranty, and repair partner integrations
* **Churn intervention** — Trigger a "Loyalty Reward" credential when a subscriber hits a retention milestone; partner services can verify and honour the benefit
* **Roaming partner verification** — Let partner carriers verify a subscriber's KYC status via ZK proof; no PII crosses operator boundaries
* **Age-gated service access** — Gate adult content, gambling, or age-restricted add-ons behind an age credential without storing birthdates

## Architecture

```mermaid theme={null}
graph TD
    A["User activates SIM / subscription"] --> B[Your Activation Backend]
    B -->|KYC pass + activation event| C[Issue on Behalf API]
    C --> D[Subscriber Credential in User's AIR Account]

    D --> E{User accesses partner service}
    E -->|Roaming carrier| F["Verify subscriber KYC\nNo PII transferred"]
    E -->|MVNO partner| G["Tier unlock\nno API integration required"]
    E -->|Device insurer| H["Device ownership proof"]
    E -->|Your retention offer| I["Loyalty reward gated by tenure credential"]
```

## Recommended Schemas

### Subscriber Credential

```json theme={null}
{
  "title": "Subscriber Credential",
  "description": "Verified mobile subscriber attestation — no raw PII included",
  "properties": {
    "carrierId": {
      "type": "string",
      "description": "Issuing carrier identifier"
    },
    "planType": {
      "type": "string",
      "enum": ["prepaid", "postpaid", "business", "iot"],
      "description": "Subscription plan category"
    },
    "kycLevel": {
      "type": "string",
      "enum": ["basic", "enhanced", "full"],
      "description": "Level of identity verification completed at activation"
    },
    "activatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "isOver18": {
      "type": "boolean"
    },
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 — subscriber's registration country"
    }
  },
  "required": ["carrierId", "planType", "kycLevel", "activatedAt", "isOver18"]
}
```

### Subscriber Loyalty Tier

```json theme={null}
{
  "title": "Subscriber Loyalty Tier",
  "description": "Carrier loyalty tier based on tenure and spend",
  "properties": {
    "carrierId": { "type": "string" },
    "tier": {
      "type": "string",
      "enum": ["Standard", "Silver", "Gold", "Platinum"],
      "description": "Current loyalty tier"
    },
    "tenureMonths": {
      "type": "number",
      "description": "Months as active subscriber"
    },
    "memberSince": {
      "type": "string",
      "format": "date"
    }
  },
  "required": ["carrierId", "tier", "tenureMonths"]
}
```

<Warning>
  Never include MSISDN (phone number), IMSI, full name, or address in `credentialSubject`. Store only **attestations and derived facts** — `isOver18`, `kycLevel`, `planType`. ZK proofs let partner services confirm subscriber attributes without receiving any underlying data.
</Warning>

## Implementation

### Step 1 — Issue subscriber credential at activation

Your activation system already fires an event when a subscriber passes KYC and activates. Add one Issue on Behalf call to that event handler.

```javascript theme={null}
// activation-handler.js
const { getPartnerJwt } = require('./lib/jwt');

const BASE_URL = 'https://api.sandbox.mocachain.org/v1';

async function issueSubscriberCredential({ userEmail, activation }) {
  if (activation.kycStatus !== 'APPROVED') return;

  const token = await getPartnerJwt(userEmail);

  const res = await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-partner-auth': token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.SUBSCRIBER_CREDENTIAL_ID,
      credentialSubject: {
        carrierId: process.env.CARRIER_ID,
        planType: activation.planType,          // "prepaid" | "postpaid" | "business"
        kycLevel: activation.kycLevel,          // "basic" | "enhanced" | "full"
        activatedAt: new Date().toISOString(),
        isOver18: activation.age >= 18,
        countryCode: activation.countryCode,    // e.g. "AU", "SG"
      },
      onDuplicate: 'revoke', // re-issue if subscriber upgrades plan / re-verifies
    }),
  });

  if (!res.ok) throw new Error(`Subscriber credential issuance failed: ${res.status}`);
  return res.json();
}

// Hook into your existing activation pipeline
activationPipeline.on('subscriber:activated', async ({ userEmail, activationData }) => {
  await issueSubscriberCredential({ userEmail, activation: activationData });
});
```

### Step 2 — Issue loyalty tier on tenure milestone

```javascript theme={null}
// churn-prevention.js — runs nightly or on billing cycle
async function issueLoyaltyTierIfEligible({ userEmail, tenureMonths }) {
  const tier =
    tenureMonths >= 36 ? 'Platinum' :
    tenureMonths >= 24 ? 'Gold' :
    tenureMonths >= 12 ? 'Silver' : 'Standard';

  const token = await getPartnerJwt(userEmail);

  await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-partner-auth': token },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.LOYALTY_TIER_CREDENTIAL_ID,
      credentialSubject: {
        carrierId: process.env.CARRIER_ID,
        tier,
        tenureMonths,
        memberSince: getMemberSinceDate(userEmail),
      },
      onDuplicate: 'revoke', // always replace with updated tier
    }),
  });
}

// Run on each billing cycle to keep tiers current
billingCycle.on('invoice:settled', async ({ userEmail, tenureMonths }) => {
  await issueLoyaltyTierIfEligible({ userEmail, tenureMonths });
});
```

### Step 3 — Verify subscriber KYC at a roaming partner

The roaming partner integrates AIR Kit as a verifier. They call one SDK method — they never receive subscriber PII, only a COMPLIANT/NON\_COMPLIANT result plus the KYC level.

```javascript theme={null}
// roaming-partner.js (frontend — partner carrier's app)
import { AirService } from '@mocanetwork/airkit';

import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.ROAMING_PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.PRODUCTION });

async function verifyRoamingSubscriber() {
  const result = await airService.verifyCredential({
    programId: process.env.ROAMING_VERIFY_PROGRAM_ID,
    // Verifier program rule: kycLevel === "enhanced" OR "full"
    // The verifier sees only: COMPLIANT / NON_COMPLIANT
    // No MSISDN, no name, no raw subscriber data
  });

  if (result.status !== 'COMPLIANT') {
    throw new Error('SUBSCRIBER_KYC_REQUIRED');
  }
  return result;
}
```

### Step 4 — Gate age-restricted services

```javascript theme={null}
// age-restricted-service.js (frontend)
async function requireAgeVerification() {
  const result = await airService.verifyCredential({
    programId: process.env.AGE_18_VERIFY_PROGRAM_ID,
    // Program checks: isOver18 === true — subscriber's birthdate never exposed
  });
  return result.status === 'COMPLIANT';
}

const allowed = await requireAgeVerification();
if (!allowed) showAgeVerificationPrompt();
```

## Key Patterns

| Pattern               | `onDuplicate` | When to Use                                                       |
| --------------------- | :-----------: | ----------------------------------------------------------------- |
| Initial activation    |   `"ignore"`  | Issue once at first activation; don't re-issue if user reinstalls |
| Plan upgrade / re-KYC |   `"revoke"`  | Always reissue with updated `kycLevel` or `planType`              |
| Loyalty tier update   |   `"revoke"`  | Monthly billing cycle refresh                                     |
| Device credential     |   `"ignore"`  | One credential per device — immutable proof of ownership          |

## Privacy Guarantee

The roaming partner or MVNO receives **only a boolean result** from the ZK proof. No MSISDN, no IMSI, no subscriber identity document data crosses operator boundaries.

| What the Verifier Sees                     | What Stays Private       |
| ------------------------------------------ | ------------------------ |
| `COMPLIANT / NON_COMPLIANT`                | MSISDN / phone number    |
| `kycLevel` (`basic` / `enhanced` / `full`) | IMSI / SIM data          |
| `isOver18: true`                           | Full name, date of birth |
| `planType`                                 | Address, national ID     |
| Credential expiry                          | Billing history          |

## Examples

The repo uses fintech and loyalty app names (KYC provider, lending platform, airline, hotel). The same code adapts to telco (carrier, roaming partner) via schema and branding — see each example's `schema.json` and the README's "Adapting to Your Vertical" section.

<CardGroup>
  <Card title="KYC Passport — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/issuer">
    KYC provider app: issues credentials once; user carries the proof to other platforms.
  </Card>

  <Card title="KYC Passport — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/kyc-passport/verifier">
    Lending platform app: verifies the credential and accepts the proof without re-running KYC.
  </Card>

  <Card title="VIP Status Portability — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/issuer">
    Airline loyalty app: issues tier credential; user carries status to partner brands.
  </Card>

  <Card title="VIP Status Portability — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/verifier">
    Hotel chain app: verifies tier and grants equivalent perks (e.g. room upgrade, lounge).
  </Card>
</CardGroup>

## Next Steps

<Columns>
  <Card title="Issue on Behalf — Concepts" icon="book" href="/airkit/usage/credential/issue-on-behalf">
    Server-side issuance without user presence.
  </Card>

  <Card title="Issue on Behalf — API" icon="code" href="/airkit/usage/credential/issue-on-behalf-api">
    Full endpoint reference with error codes.
  </Card>

  <Card title="AIR for Fintech & Payments" icon="credit-card" href="/airkit/guides/air-for-fintech">
    KYC portability patterns used in financial services.
  </Card>

  <Card title="Architecture & Data Flow" icon="diagram-project" href="/airkit/guides/overview">
    ZK proof flow end-to-end.
  </Card>
</Columns>


# AIR for Ticketing & Events
Source: https://docs.moca.network/airkit/guides/air-for-ticketing

Issue tamper-proof attendance credentials at venue check-in. Let fans carry verified event history as portable proofs for loyalty rewards, presales, and exclusive access.

Traditional event tickets are one-time-use and forgotten after the show. AIR Kit lets you transform every venue scan into a **permanent, portable attendance credential** — proof the fan was there, reusable for loyalty rewards, presale access, partner discounts, and cross-brand partnerships.

## What You Can Build

* **Attendance credentials** — Issue a verifiable "I attended X event" badge at check-in
* **Fan loyalty tiers** — Auto-upgrade fans after 5 attended events to "Loyal Fan" credential
* **Exclusive access gating** — Gate VIP lounges, artist meet-and-greets, and presales to verified attendees
* **Cross-brand fan credentials** — Share attendance proof with partner brands (merchandise, hotels, streaming)
* **Anti-scalping** — Gate secondary ticket access behind an attendance credential from a prior event

## Architecture

```mermaid theme={null}
graph TD
    A[Fan arrives at venue] --> B["Venue scanner / check-in system"]
    B -->|"Scan detects fan's AIR Account email"| C[Issue on Behalf API]
    C --> D["Attendance Credential\nin Fan's AIR Account"]

    D --> E{Fan uses credential later}
    E --> F[Claim loyalty reward]
    E --> G[Access VIP presale]
    E --> H[Redeem partner discount]
    E --> I[Prove attendance history]
```

## Recommended Schema

```json theme={null}
{
  "title": "Event Attendance",
  "description": "Verifiable proof of physical attendance at a live event",
  "properties": {
    "eventId": {
      "type": "string",
      "description": "Unique event identifier"
    },
    "eventName": {
      "type": "string",
      "description": "Display name — e.g. 'Coachella 2025 Day 1'"
    },
    "venue": {
      "type": "string",
      "description": "Venue name and city"
    },
    "attendedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of check-in scan"
    },
    "ticketTier": {
      "type": "string",
      "enum": ["General", "VIP", "Backstage", "Artist"],
      "description": "Ticket category"
    },
    "organizerId": {
      "type": "string",
      "description": "Issuing organizer / promoter identifier"
    }
  },
  "required": ["eventId", "eventName", "attendedAt", "organizerId"]
}
```

## Implementation

### Step 1 — Issue attendance credential at check-in

Your venue scanner calls your backend on each valid scan. The backend issues via Issue on Behalf — the fan does nothing, no wallet open, no UX friction at the door.

```javascript theme={null}
// venue-checkin.js
const { getPartnerJwt } = require('./lib/jwt');

async function issueAttendanceCredential({ fanEmail, eventDetails }) {
  const token = await getPartnerJwt(fanEmail);

  const res = await fetch('https://api.sandbox.mocachain.org/v1/credentials/issue-on-behalf', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-partner-auth': token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.ATTENDANCE_CREDENTIAL_ID,
      credentialSubject: {
        eventId: eventDetails.id,
        eventName: eventDetails.name,
        venue: eventDetails.venue,
        attendedAt: new Date().toISOString(),
        ticketTier: eventDetails.ticketTier,   // "General" | "VIP" | "Backstage"
        organizerId: process.env.ORGANIZER_ID,
      },
      onDuplicate: 'ignore', // one credential per event per fan
    }),
  });

  if (!res.ok) throw new Error(`Attendance issuance failed: ${res.status}`);
  const { coreClaimHash } = await res.json();
  return coreClaimHash;
}

// Called by your ticketing system on each valid scan
app.post('/api/checkin', async (req, res) => {
  const { fanEmail, eventId } = req.body;
  const event = await getEventDetails(eventId);
  const hash = await issueAttendanceCredential({ fanEmail, eventDetails: event });
  res.json({ success: true, coreClaimHash: hash });
});
```

### Step 2 — Gate VIP presale to verified attendees

```javascript theme={null}
// presale-gate.js  (frontend)
import { AirService } from '@mocanetwork/airkit';

import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({ partnerId: process.env.PARTNER_ID });
await airService.init({ buildEnv: BUILD_ENV.SANDBOX });

async function canAccessPresale() {
  const result = await airService.verifyCredential({
    programId: process.env.PRESALE_VERIFY_PROGRAM_ID,
    // Verifier program rule: organizerId === process.env.ORGANIZER_ID
    // (attended at least 1 prior event by this organizer)
  });
  return result.status === 'COMPLIANT';
}

const isVerifiedFan = await canAccessPresale();
if (isVerifiedFan) {
  showPresaleRegistration();
} else {
  showMessage('Presale access requires verified attendance at a prior event.');
}
```

### Step 3 — Auto-upgrade fans to loyalty tiers after N events

```javascript theme={null}
// loyalty-tier-check.js — called after each attendance credential issuance
async function checkAndIssueLoyaltyTier(fanEmail) {
  const attendedCount = await getAttendanceCount(fanEmail); // your DB

  if (attendedCount === 5)  await issueLoyaltyTier({ fanEmail, tier: 'Loyal Fan' });
  if (attendedCount === 20) await issueLoyaltyTier({ fanEmail, tier: 'Super Fan' });
}

// issueLoyaltyTier uses the same Issue on Behalf pattern — see AIR for Loyalty guide
```

## Zero-Friction Fan UX

The key advantage for events: **fans never interact with the credential system at the door**. They scan their ticket as normal, the credential lands in their AIR Account in the background, and they use it the next time they want a reward or presale.

<Steps>
  <Step title="Fan scans ticket at the door">
    No app to open, no wallet prompt. Exactly the same experience as today.
  </Step>

  <Step title="Your backend issues the attendance credential">
    Issue on Behalf fires silently. The fan's AIR Account receives the credential on-chain.
  </Step>

  <Step title="Fan opens the app the next day">
    Sees a notification: "You earned a Verified Attendee credential for Coachella 2025."
  </Step>

  <Step title="Fan uses the credential">
    One tap to register for the presale, claim a merchandise discount, or prove their fan tier to a partner brand.
  </Step>
</Steps>

## Examples

<CardGroup>
  <Card title="Fan Attendance — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/fan-attendance/issuer">
    Venue check-in app: issues attendance credential when the fan scans in at the event.
  </Card>

  <Card title="Fan Attendance — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/fan-attendance/verifier">
    Merch store app: verifies attendance and unlocks rewards (e.g. discount, exclusive offer).
  </Card>

  <Card title="VIP Status Portability — Issuer" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/issuer">
    Airline loyalty app: issues tier credential; user carries status to partner brands.
  </Card>

  <Card title="VIP Status Portability — Verifier" icon="github" href="https://github.com/MocaNetwork/air-examples/tree/main/vip-status-portability/verifier">
    Hotel chain app: verifies tier and grants equivalent perks (e.g. room upgrade, lounge).
  </Card>
</CardGroup>

## Next Steps

<Columns>
  <Card title="AIR for Loyalty & Rewards" icon="gift" href="/airkit/guides/air-for-loyalty">
    Build tier-based loyalty on top of attendance credentials.
  </Card>

  <Card title="Issue on Behalf — API" icon="code" href="/airkit/usage/credential/issue-on-behalf-api">
    Full endpoint reference and error handling.
  </Card>

  <Card title="Issue on Behalf — Concepts" icon="book" href="/airkit/usage/credential/issue-on-behalf">
    When to use server-side vs. user-initiated issuance.
  </Card>

  <Card title="Architecture & Data Flow" icon="diagram-project" href="/airkit/guides/overview">
    End-to-end system overview.
  </Card>
</Columns>


# Architecture & Data Flow
Source: https://docs.moca.network/airkit/guides/overview

End-to-end technical architecture of AIR Kit — SDK services, Moca Chain, credential lifecycle, and how data moves through the system.

AIR Kit is a modular SDK that sits between your application and Moca Chain. It exposes two independent service surfaces — **Account Services** and **Credential Services** — that can be used together or independently.

## System Overview

```mermaid theme={null}
graph TD
    subgraph YourApp["Your Application"]
      A[Frontend / Mobile App]
      B[Backend Server]
    end

    subgraph SDK["AIR Kit SDK"]
      C[Account Services]
      D[Credential Services]
    end

    subgraph Chain["Moca Chain"]
      E[Identity Oracle]
      F[EVM Layer]
      G[Decentralized Storage - MCSP]
    end

    A -->|Web SDK / Flutter SDK| C
    A -->|Web SDK / Flutter SDK| D
    B -->|Partner JWT + REST API| D
    C -->|Wallet & session management| F
    D -->|Issue / Verify credentials| E
    E -->|Anchors credential hash| F
    F -->|Payload stored| G
```

## Account Services Flow

Account Services handles user authentication, smart account creation, and wallet operations.

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant App as Your App
    participant SDK as AIR Kit SDK
    participant Chain as Moca Chain

    U->>App: Click "Login"
    App->>SDK: airService.login()
    SDK->>U: Show login UI (email / social / wallet)
    U->>SDK: Authenticate
    SDK->>Chain: Create / fetch smart account
    Chain-->>SDK: Account address + session
    SDK-->>App: User session + wallet provider
    App-->>U: Logged in ✓
```

## Credential Issuance Flow (User-Initiated)

The standard issuance path — the user is present and triggers the credential claim.

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant App as Your App (Issuer)
    participant SDK as AIR Kit SDK
    participant Chain as Moca Chain

    U->>App: Triggers credential claim
    App->>SDK: airService.issueCredential(credentialId, subject)
    SDK->>U: Prompt user to sign consent
    U->>SDK: Signs with AIR Account
    SDK->>Chain: Submit issuance transaction
    Chain->>Chain: Identity Oracle verifies & anchors hash
    Chain-->>SDK: coreClaimHash
    SDK-->>App: Issuance confirmed
    App-->>U: Credential delivered to AIR Account
```

## Credential Verification Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User (Holder)
    participant App as Your App (Verifier)
    participant SDK as AIR Kit SDK
    participant Chain as Moca Chain

    U->>App: Requests access / action
    App->>SDK: airService.verifyCredential(programId)
    SDK->>U: Prompt user to select credential
    U->>SDK: Presents credential (ZK proof generated client-side)
    SDK->>Chain: Submit ZK proof for verification
    Chain->>Chain: Oracle validates proof on-chain
    Chain-->>SDK: COMPLIANT / NON_COMPLIANT
    SDK-->>App: Verification result
    App-->>U: Access granted or denied
```

## Issue on Behalf Flow (Server-Side, No User Session)

Use this path when a **backend event** should trigger issuance without the user being present.

```mermaid theme={null}
sequenceDiagram
    participant Event as Backend Event
    participant Server as Your Server
    participant API as AIR Kit API
    participant Chain as Moca Chain

    Event->>Server: KYC passed / purchase confirmed / check-in scanned
    Server->>Server: Sign Partner JWT (scope:"issue on-behalf", email: user)
    Server->>API: POST /v1/credentials/issue-on-behalf
    API->>Chain: Queue credential for on-chain processing
    Chain-->>API: coreClaimHash
    API-->>Server: { coreClaimHash }
    Server->>API: GET /v1/credentials/status?coreClaimHash=...
    API-->>Server: { vcStatus: "ONCHAIN" }
    Note over Chain: User receives credential in AIR Account silently
```

## Multi-Vendor Stack Integration

AIR Kit is **additive** — it does not replace your existing infrastructure. The diagram below shows how it slots into a typical enterprise stack alongside loyalty platforms, KYC providers, ticketing systems, and payment processors.

```mermaid theme={null}
graph LR
    subgraph Existing["Your Existing Stack"]
      L[Loyalty Platform]
      K[KYC Provider]
      T[Ticketing System]
      P[Payment Processor]
    end

    subgraph AIR["AIR Kit Integration Layer"]
      IB[Issue on Behalf API]
      SDK2[Web / Flutter SDK]
    end

    subgraph MocaChain["Moca Chain"]
      ORC[Identity Oracle]
      STORE[Decentralized Storage]
    end

    L -->|Milestone event| IB
    K -->|Verification pass| IB
    T -->|Scan / check-in| IB
    P -->|Transaction event| IB
    IB --> ORC
    ORC --> STORE
    SDK2 -->|Verify credential| ORC
```

## Service Independence

Account Services and Credential Services are decoupled — integrate one, both, or mix server-side and client-side patterns.

| Feature                            | Account Services | Credential Services |       Requires Both      |
| ---------------------------------- | :--------------: | :-----------------: | :----------------------: |
| User login / SSO                   |         ✓        |          —          |             —            |
| Smart account / wallet             |         ✓        |          —          |             —            |
| Gas sponsorship (Paymaster)        |         ✓        |          —          |             —            |
| Wagmi connector                    |         ✓        |          —          |             —            |
| Issue credentials (user-initiated) |         —        |          ✓          | ✓ user must be logged in |
| Issue on Behalf (server-side)      |         —        |          ✓          |             —            |
| Verify credentials                 |         —        |          ✓          |             —            |

## Next Steps

<Columns>
  <Card title="Quick Setup" icon="bolt" href="/airkit/usage/getting-started">
    Install and initialize the SDK in minutes.
  </Card>

  <Card title="Integration Guides" icon="puzzle-piece" href="/airkit/guides/air-for-loyalty">
    Vertical-specific guides with code examples for Loyalty, Fintech, Gaming, and Ticketing.
  </Card>

  <Card title="Quickstart: Issue Credentials" icon="badge-check" href="/airkit/quickstart/issue-credentials">
    Step-by-step credential issuance walkthrough.
  </Card>

  <Card title="Issue on Behalf" icon="server" href="/airkit/usage/credential/issue-on-behalf">
    Server-side issuance without user presence.
  </Card>
</Columns>


# AIR Kit Documentation
Source: https://docs.moca.network/airkit/how-to-use

AIR Kit developer documentation for accounts, credentials, and full-stack integration.

# How to Read This Documentation

This documentation is designed to guide developers through using **AIR Kit** efficiently. It is organized to serve multiple personas and use cases.

## 1. Start with Your Persona

Identify which persona matches your use case to choose the appropriate Quickstart:

| Persona                    | Suggested Start                                                                                                                                     |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account Integrators**    | [Quickstart 1: Account Integration & User Onboarding](/airkit/quickstart)                                                                           |
| **Credential Integrators** | [Quickstart 2: Issue Credentials](/airkit/quickstart/issue-credentials) & [Quickstart 3: Verify Credentials](/airkit/quickstart/verify-credentials) |

<Tip>
  Each Quickstart contains step-by-step instructions and example code to get started quickly.
</Tip>

## 2. Core Concepts

Before building, familiarize yourself with the following concepts:

* **AIR Service Overview** – [What AIR Kit is and how it works](/airkit/)
* **Installation & Setup** – [Creating your partner account and initializing the SDK](/airkit/usage/getting-started)
* **Configuration Options** – [Customize AIR Kit behavior for your app](/airkit/usage/config-theming)
* **Authentication & Sessions** – [Partner JWT, login flows, and session management](/airkit/usage/partner-authentication)
* **Verifiable Credentials** – [Issuance, verification, storage, and ecosystem interoperability](/learn/airkit/credentials)
* **Security & Privacy Principles** – Best practices for data handling and privacy

<Tip>
  Each concept links to detailed guides and examples for implementation.
</Tip>

## 3. Using AIR Kit

The functional documentation is organized by capabilities:

1. **General Usage**
   * Initialize SDK, configure authentication, and user management

2. **General Configuration**
   * Theming, languages, and login options

3. **Account Service**
   * Wallet functions and provider
   * Integrations with Wagmi Connector and other functions

4. **Credential Service**
   * Issue and verify credentials

## 4. Advanced Topics (Coming Soon)

Optional sections for experienced developers:

* **API Reference** – All classes, methods, and SDK options
* **Plug & Play modules** – Coming soon
* **Migration & Compatibility** – Guidelines for upgrading or integrating with existing systems

<Tip>
  Advanced topics are not required for standard usage.
</Tip>

## 5. Support & Maintenance

Use this section for:

* Troubleshooting issues
* Reviewing release notes
* Providing feedback or contributing to AIR Kit

## What's next?

Each Quickstart provides:

* Step-by-step instructions you can copy and run
* Code examples in TypeScript for direct use
* Deep links to reference docs for SDK methods and configuration options

👉 Start with the Quickstart that matches your role, then refer back to others as your app grows.


# What is AIR Kit?
Source: https://docs.moca.network/airkit/index

AIR Kit is the SDK for integrating portable credentials, smart accounts, and privacy-preserving identity into your application.

# AIR Kit Overview

AIR Kit is the comprehensive developer toolkit for integrating secure, decentralized identity features into your applications. It simplifies complex concepts like **Web3 login**, **user onboarding**, and **zero-knowledge proofs**, making them accessible for all developers and users.

AIR Kit provides two powerful services:

1. **AIR Account Services**
   * Manage user login and Single Sign-On (SSO)
   * Wallet management and services

2. **AIR Credential Services**
   * Issue, verify, and consume **zero-knowledge credentials**
   * Portable credentials that users can carry anywhere

### Platform support

AIR Kit integrates easily with your **Web App** or **Mobile App**.

By embedding our **Web SDK (Javascript)** on the frontend of your web application, or integrating our **Flutter SDK** on your Mobile app, you can easily access our Account Services and Credential Services.

<Tip>
  Note: Credential Services coming soon to Flutter SDK
</Tip>

## What is AIR?

AIR stands for **Account Identity Reputation**, representing a foundational shift in how users interact with the internet. AIR is designed to create a **user-centric digital experience**, where individuals truly own their **assets, identity, and data**.

Key principles of AIR:

* **User Ownership:** Users control their digital assets, identity, and personal data.
* **Common Language of the Internet:** Identity and user data become a shared standard for seamless interaction between applications.
* **True Network Effects:** Applications leveraging the user-as-root model can provide more valuable experiences.
* **Shared Economics:** Incentivizes collaboration among apps to benefit the user.

<img alt="Moca Network Overview" />

*Moca Network = AIR Kit + Moca Chain*

## Who Is This For?

AIR Kit is suitable for any platform where **trust, privacy, and user context** matter:

* Founders building consumer apps who want to skip traditional KYC
* DAOs needing pseudonymous membership tools
* Game developers porting player identities and badges across worlds
* Fintech teams verifying income, age, or credentials **without storing PII**
* AI agents requiring verifiable access and behavioral reputation

## The Big Idea: Identity as a Primitive

By making identity **modular, portable, and verifiable**, AIR Kit enables new types of applications:

* Reward **real participation** with airdrops
* Launch apps **without starting from zero users**
* Grow communities **without re-KYCing everyone**

> With AIR Kit, identity becomes a core building block rather than an afterthought. Plug in the SDK, remix credentials, and design new experiences.

## Key Features & Benefits

* **Single Sign-on**: Users sign on with the same account across the Moca Network ecosystem
* **Embedded Account:** Wallet capabilities without the web3 learning curve
* **Decentralized & Secure:** Users maintain control of their identity and credentials
* **Zero-Knowledge Proofs:** Privacy-preserving verification for sensitive data
* **Cross-Application Portability:** Credentials and identity travel across platforms
* **Ecosystem Growth:** Shared identity enables cooperation and network effects

## Getting Started

### Quickstart Guide

* **Account Integrators:** Start with **Login & User Onboarding**
* **Credential Integrators:** Start with **Issuance & Verification**
* **Full Stack Builders:** Follow **Combined Flow Guide**

Each Quickstart provides **step-by-step instructions and code examples** to get up and running fast.

### Flutter apps

If you build with **Flutter**, start with the [Flutter SDK overview](/airkit/flutter/overview) (installation, Android/iOS setup, wallet, and troubleshooting).

## Next Steps

1. Explore **Core Concepts**: Authentication, sessions, and credentials
2. Install **AIR Kit**: Account and Credential services
3. Implement **Combined Flows**: Login + Issue + Verify for end-to-end integration
4. Check **Advanced Topics**: API references, compatibility, and plug & play modules
5. Refer to **Support & Maintenance**: Troubleshooting, release notes, and feedback


# Integrate Using AI
Source: https://docs.moca.network/airkit/integrating-using-ai

Connect Moca Network documentation to AI tools to accelerate AIR Kit development with real-time access to documentation, API references, and code examples.

Connect the Moca Network documentation MCP server to your IDE or AI assistant for real-time access to AIR Kit documentation, API references, and code examples. When you connect the MCP server, AI assistants can search the documentation directly to help you build faster and more accurately.

## Connect your AI tools

Connect the Moca Network documentation MCP server to your preferred AI tool:

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.moca.network/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.moca.network/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.moca.network/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.moca.network/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

<Tip>
  You can also use the contextual menu on any page of the documentation to copy the MCP server URL or install it directly into Cursor or VS Code.
</Tip>

## Setup with other agents

The Moca skill works with any tool that supports the [Agent Skills](https://agentskills.io/home) standard, including Cursor, VS Code Copilot, Gemini CLI, OpenAI Codex, and more.

Run:

```bash theme={null}
npx skills add https://docs.moca.network
```

The CLI detects your installed agents and places the skill in the correct directory for each one.

## What the skill provides

| Feature                | Description                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Quick references       | SDK install (`@mocanetwork/airkit`), platform matrix, provider and wallet APIs, and REST credential endpoints                                    |
| Decision guidance      | Account-only vs credential flows, embedded AIR login vs bring-your-own auth, and client vs server signing with Partner JWT                       |
| Workflows              | Step-by-step sequences for onboarding, issuance, verification, Issue on Behalf, and advanced flows like paymaster or session keys where relevant |
| Common gotchas         | Initialization and iframe setup, JWKS and JWT errors, polling issuance until credentials are on-chain, and schema or verification pitfalls       |
| Verification checklist | Partner ID, environment (sandbox vs production), chain allowlists, auth headers, and error handling before you ship                              |

## Static docs files

If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

<Warning>
  Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
</Warning>

## Which file should I use?

* **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
* **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

## Setup with Cursor

<Steps>
  <Step title="Open docs settings">
    Go to **Settings** → **Features** → **Docs**.
  </Step>

  <Step title="Add the overview file">
    Click **Add new doc** and paste: `https://docs.moca.network/llms.txt`
  </Step>

  <Step title="Optionally add the full snapshot">
    If your agent needs deeper static reference coverage, add: `https://docs.moca.network/llms-full.txt`
  </Step>

  <Step title="Reference in chat">
    Use **@docs** → **Moca** in your AI chat to reference the documentation.
  </Step>
</Steps>

## Setup with Claude Desktop

<Steps>
  <Step title="Download the overview file">
    Download the curated overview from: [https://docs.moca.network/llms.txt](https://docs.moca.network/llms.txt)
  </Step>

  <Step title="Optionally download the full snapshot">
    Download the full documentation snapshot from: [https://docs.moca.network/llms-full.txt](https://docs.moca.network/llms-full.txt)
  </Step>

  <Step title="Add to your project">
    Save one or both files in your project directory or another known location on your system.
  </Step>

  <Step title="Reference in chat">
    Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
  </Step>
</Steps>


# SDK Platform Support Matrix
Source: https://docs.moca.network/airkit/platform-matrix

Supported platforms, frameworks, browsers, and module formats across AIR Kit SDKs.

## SDK Packages

| SDK           | Package               | Install                                                                  |
| ------------- | --------------------- | ------------------------------------------------------------------------ |
| Web (JS / TS) | `@mocanetwork/airkit` | `npm install @mocanetwork/airkit`                                        |
| Flutter       | `airkit` (Dart)       | OnePub hosted — see [Flutter installation](/airkit/flutter/installation) |

For the latest version numbers see [Release Notes](/airkit/release-notes).

## Platform Support

| Platform         |         Web SDK        | Flutter SDK |
| ---------------- | :--------------------: | :---------: |
| Web (Browser)    |            ✓           |      —      |
| iOS (native)     |            —           |      ✓      |
| Android (native) |            —           |      ✓      |
| React Native     | Partial — WebView only |      —      |
| Electron         |            ✓           |      —      |

## Browser Support (Web SDK)

| Browser           | Minimum Version | Notes                           |
| ----------------- | :-------------: | ------------------------------- |
| Chrome / Chromium |       126+      | Full support (passkey required) |
| Firefox           |       97+       | Full support (passkey required) |
| Safari            |       16+       | Full support (passkey required) |
| Edge              |       126+      | Full support (Chromium-based)   |
| Opera             |       112+      | Full support (Chromium-based)   |
| Samsung Internet  |       14+       | Full support                    |
| IE 11             |        ✗        | Not supported                   |

## Framework Compatibility (Web SDK)

| Framework                 | Status | Notes                                                      |
| ------------------------- | :----: | ---------------------------------------------------------- |
| React 17+                 |    ✓   | Full support                                               |
| React 16                  |    ✓   | Full support                                               |
| Next.js 13+ (App Router)  |    ✓   | Add `'use client'` directive to the initializing component |
| Next.js 12 (Pages Router) |    ✓   | Full support                                               |
| Vue 3                     |    ✓   | Full support                                               |
| Vue 2                     |    ✓   | Full support                                               |
| Nuxt 3                    |    ✓   | Full support                                               |
| SvelteKit                 |    ✓   | Full support                                               |
| Angular 14+               |    ✓   | Full support                                               |
| Vanilla JS                |    ✓   | UMD / ESM builds available                                 |

## Module Formats (Web SDK)

| Format   | Import                                                  | Best For                         |
| -------- | ------------------------------------------------------- | -------------------------------- |
| ESM      | `import { AirService } from '@mocanetwork/airkit'`      | Vite, Webpack 5, modern bundlers |
| CommonJS | `const { AirService } = require('@mocanetwork/airkit')` | Node.js, older bundlers          |
| UMD      | `<script>` CDN tag                                      | No-bundler / script-tag setups   |

## Issue on Behalf — Server Language Support

The Issue on Behalf API is HTTP + JWT — any backend language works. Common JWT libraries:

| Language | Library                           |
| -------- | --------------------------------- |
| Node.js  | `jsonwebtoken`                    |
| Java     | `com.auth0:java-jwt`              |
| C#       | `System.IdentityModel.Tokens.Jwt` |
| Go       | `github.com/golang-jwt/jwt/v5`    |
| Python   | `PyJWT`                           |
| Ruby     | `ruby-jwt`                        |
| PHP      | `firebase/php-jwt`                |

See full signing examples for Node.js, Java, C#, and Go in [Partner Authentication](/airkit/usage/partner-authentication).


# Quickstart 1: Account Integration & User Onboarding
Source: https://docs.moca.network/airkit/quickstart/index

Learn how to set up user onboarding, authentication, and session management with AIR Account SDK

# Quickstart: Login & User Onboarding

Account integration and user onboarding is the foundation of any application.\
If you're here, your primary focus is **seamless onboarding, authentication, and session management**.

With the AIR Kit, you can:

* Enable SSO login for your users
* Provide wallet services similar to a decentralized identity provider
* Establish secure user sessions
* Manage the lifecycle of sessions within your app

This guide will walk you through:

* Setting up AIR Kit
* Implementing login flows
* Utilizing embedded wallet features

<Tip>
  If your app doesn’t require credential issuance or verification yet, this Quickstart alone is enough to get you up and running.
</Tip>

## Step 1: Install the SDK

```bash theme={null}
npm install @mocanetwork/airkit
```

## Step 2: Get Your Partner ID

1. Go to the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a> and login with your EOA wallet.
2. Connect your wallet.
   <img alt="Wallet connect" />
3. Navigate to the Account Section on the navigation bar on the left. Then go to the General page. Copy the **Partner ID** from the partner account information and settings.
   <img alt="Quickstart - get partner ID" />
4. If you’re looking to customise the theme, login flow, or localization, please see the [relevant sections](/airkit/usage/config-theming) for more details.

## Step 3: Import, Initialize & Login

**File:** `./useAirKit.ts`

```ts theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const service = new AirService({
  partnerId: YOUR_PARTNER_ID // Replace with your actual Partner ID
});

// Trigger the login flow
await service.init({
  buildEnv: BUILD_ENV.SANDBOX
});
const loggedInResult = await service.login();
```

☑️ This will:

* Initialize the `AirService` within the [Sandbox Environment](/airkit/environments)
* Present the SSO Login screen of AIR Kit for users to log in
* Handle authentication and session setup
* Enable Account Services (such as wallet functions), and Credential Services (such as credential verification) for your app after the user is logged in

## What You Get After Login

Once login is complete, you’ll have access to:

* User UUID
* Session token
* User metadata

## Next Steps

Once you've set up account and sessions, you can optionally move on to [Issue Credentials](/airkit/quickstart/issue-credentials) and [Verify Credentials](/airkit/quickstart/verify-credentials) if your app needs credential-based access control.

Otherwise, you may explore our documentation on how to utilize AIR Kit's [Account Services](/airkit/usage/account/smart-account)


# Quickstart 2: Credential Issuance
Source: https://docs.moca.network/airkit/quickstart/issue-credentials

Learn how to issue credentials using AIR Kit with zero-knowledge proofs.

If you are looking to **issue credentials (programs) on chain** this guide will help you achieve that.

This Quickstart will walk you through:

* Setting up the **AIR Kit**
* Defining and issuing credentials to users
* Managing credential issuance flows

<Info>
  **Backend API Alternative**

  This guide covers client-side credential issuance using the AIR Kit SDK. For server-side credential issuance without user interaction, see [Issue Credentials on Behalf](/airkit/usage/credential/issue-on-behalf).
</Info>

## What You'll Build

By the end of this Quickstart, you will have:

* A **credential schema** defined for your app (e.g., membership, role, event pass)
* Code that **issues credentials to users** after login
* Application logic that handles credential issuance results

## Before Starting, Ensure You Have

* Completed or understood the [Login & Sessions Quickstart](/airkit/quickstart/) (recommended but not mandatory)
* Node.js v18+ installed

## Step 1: Install the AIR Kit

```bash theme={null}
npm install @mocanetwork/airkit
```

## Step 2: Get Your Partner ID

1. Go to the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a> and login with your EOA wallet
2. Connect your wallet
   <img alt="Wallet connect" />
3. Navigate to the **Accounts section** on the navigation bar on the left. Then go to the **General section**. Copy the **Partner ID** and **Issuer DID** from the partner account information and settings
   <img alt="Get Partner ID connect" />

## Step 3: Setup JWT Authentication

To issue credentials, you need to set up JWT authentication. This involves configuring your JWKS (JSON Web Key Set) URL and generating authentication tokens.

<Info>
  **JWT Setup Required**

  For detailed instructions on setting up JWT authentication, including JWKS configuration and token generation, please refer to the [Partner Authentication guide](/airkit/usage/partner-authentication).
</Info>

**Quick Setup:**

1. Navigate to the [**Accounts Section**](https://developers.sandbox.air3.com/dashboard/general) and configure your **JWKS URL**
2. Generate JWT tokens using your private key for authentication

## Step 4: Create Schema for Credential Issuance

Before issuing credentials, you need to create a schema that defines the structure of your credentials. A schema is a blueprint that specifies what data fields will be included in your credentials.

<Info>
  **Schema Creation Guide**

  For detailed instructions on creating schemas, including best practices, examples, and schema management, please refer to the [Schema Creation Guide](/airkit/usage/credential/schema-creation).
</Info>

**Quick Setup:**

1. Go to the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a>.
2. Navigate to the **Schemas** section under **Issuer**
   <img alt="Create Schema" />
3. Create a schema of your choice:
   * Input title/schema type/description and click continue
   * Click "+" and add at least one Attribute property
   * Click Publish to make it available

<div>
  <video alt="Create schema">
    <source type="video/mp4" />
  </video>
</div>

4. Create credentials (now **Programs**) to be issued. Navigate to the **Programs Section** and create the program with the schema you just created

<div>
  <video alt="Create schema">
    <source type="video/mp4" />
  </video>
</div>

## Issuing Credentials

You can issue credentials (programs) using **both the SDK and the demo application**. Let's look at both methods.

### Issuing Credentials Using the [Example App](https://developers.sandbox.air3.com/example/issue)

1. Generate a JWT token on the interface
   <img alt="Generate-JWT" />

2. Get the configuration details from the Developer Dashboard:
   * Issuer DID and Partner ID from the **General page** under the Account section
     <img alt="Get-issuer DID" />
   * Issuance program ID from the **Credentials section**
     <img alt="Get program issuance id" />

3. Go to the **Demo app** and enter the **Issuer ID**, **Issuance program ID**, and the relevant **field names and values**
   <img alt="issue_cred" />

4. Click **"Start Credential Issuance"**
   <img alt="start cred issuance" />

5. The AIR Credential widget will open and guide the user through the issuance process
   <img alt="start cred issuance" />

6. You'll receive a **success notification** when the process completes and can verify the credentials issued under the **records section** in the **Issuer Tab**

<img alt="start cred issuance" />

***

### Issuing Credentials Using the AIR Kit

The AIR Kit provides a convenient way to issue and verify digital credentials directly in your web application using the AIR service. The function handles **end-to-end flows**, including UI presentation and cryptographic verification, streamlining integration with your decentralized app (dApp).

#### Install the AIR Kit

```bash theme={null}
# Using npm
npm install @mocanetwork/airkit
```

#### Initialize the AIR Service

Before issuing a credential, you must create the **AirService** instance, initialize the service and login the user.

```ts theme={null}
import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

const airService = new AirService({
  partnerId: YOUR_PARTNER_ID // Replace with your actual Partner ID
});
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  enableLogging: true,
  preloadCredential: true
});

// Without any parameters, this will trigger the default Air login dialog which provides different login methods for the user to choose from.
await airService.login();
```

#### Generate the Authentication JWT

Issuance requires an auth token (JWT) to authenticate your service with AIR.

```ts theme={null}
const jwt = await generateJwt({ partnerId, privateKey });
```

* `generateJwt` is a utility function. Refer to [Authentication (Partner JWT)](/airkit/usage/partner-authentication) on how to generate JWT tokens
* `partnerId` and `privateKey` come from environment variables
* JWT is used for authorization when calling `airService.issueCredential` function

<Tip>NOTE: For production, generate JWTs on the backend to keep private keys secure.</Tip>

#### Configure Issuance Parameters

Set up the essential credential issuance details

```ts theme={null}
const config = {
  issuerDid: "did:example:issuer123",
  credentialId: "c21hc0g0joevn0015479aK"
};
```

* `issuerDid`\*\* – Decentralized Identifier of the issuer
* `credentialId` – Program ID for the credential created on the Developer Dashboard

#### Define the Credential Subject

The credential subject contains the data fields issued to the user, e.g., age, location, or email.

```ts theme={null}
const credentialSubject = {
  age: 20,
  location: "Netherlands",
  isMember: true
};
```

* Fields can be **string, number, boolean, or date**.
* The schema for the credential is defined before creating the Issuance program ID on the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a>.

#### Issue the Credential

Call the AIR service to issue the credential:

```ts theme={null}
const result = await airService.issueCredential({
  authToken: jwt,
  credentialId: config.credentialId,
  credentialSubject: credentialSubject,
  issuerDid: config.issuerDid,
  curve: "secp256r1" // Optional: "secp256r1" (default) or "secp256k1"
});

// If compliance encryption is enabled, you'll receive the public key
if (result.cakPublicKey) {
  // Use cakPublicKey to encrypt compliance data before storing
  console.log("Compliance encryption public key:", result.cakPublicKey);
}
```

* `authToken` – JWT generated in step 2
* `credentialId` – ID of the credential program
* `credentialSubject` – JSON object of the data to populate for the credential
* `issuerDid` – DID of the issuer
* `curve` – Optional. Elliptic curve for compliance encryption key generation (`"secp256r1"` or `"secp256k1"`). Defaults to `secp256r1`.

**Response:**
The function returns an object with an optional `cakPublicKey` (Compliance Encryption User Public Key) when compliance encryption is enabled for your issuance program. See the [Issuing Credentials](/airkit/usage/credential/issuing-credentials#compliance-encryption-public-key) documentation for detailed information about this feature.

> On success, the user receives a **signed credential** that can be stored in their wallet or identity provider.

#### Handle Issuance Status

The component tracks status for better UX:

* **Loading** – Shows a spinner while issuing the credential
* **Success** – Displays a success message when the credential is issued
* **Error** – Shows any errors if issuance fails

```ts theme={null}
setIsLoading(true);
setIsSuccess(true);
setError(null);
```

**Summary of Issuance Process:**

1. Initialize AirService with environment config and partner ID
2. Generate a JWT for authentication
3. Configure issuer DID and issuance program ID on the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a>
4. Add credential subject fields (dynamic data)
5. Call `airService.issueCredential` to issue the credential
6. Handle success or error states

## Example Implementation

For a complete working example, check out the [AIR Credential Example repository](https://github.com/MocaNetwork/air-credential-example) which demonstrates:

* Full credential issuance flow with React components
* Dynamic credential subject field management
* Error handling and status management
* Complete integration with the AIR Kit's Credential Services

## Next Steps

Now that you know how to issue credentials, you can:

* **Verify credentials** - Learn how to verify the credentials you've issued in the [Credential Verification Quickstart](/airkit/quickstart/verify-credentials)


# Quickstart 3: Credential Verification
Source: https://docs.moca.network/airkit/quickstart/verify-credentials

Learn how to verify credentials using AIR Kit with zero-knowledge proofs.

If you are looking to **verify credentials on chain** this guide will help you achieve that.

This Quickstart will walk you through:

* Setting up verification programs
* Verifying user credentials with zero-knowledge proofs
* Handling verification results

## What You'll Build

By the end of this Quickstart, you will have:

* A **verification program** configured for your app
* Code that **verifies credentials** from users
* Application logic that reacts to verification results (e.g., grant/deny access)

## Before Starting, Ensure You Have

* Completed or understood the [Login & Sessions Quickstart](/airkit/quickstart/) (recommended but not mandatory)
* Completed the [Credential Issuance Quickstart](/airkit/quickstart/issue-credentials) (to have credentials to verify)
* Node.js v18+ installed

## Step 1: Install the AIR Kit

```bash theme={null}
npm install @mocanetwork/airkit
```

## Step 2: Get Your Partner ID

1. Go to the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a> and login with your EOA wallet
2. Connect your wallet
   <img alt="Wallet connect" />
3. Navigate to the [**Accounts section**](https://developers.sandbox.air3.com/dashboard/general) on the navigation bar on the left. Then go to the **General section**. Copy the **Partner ID** and **Verifier DID** from the partner account information and settings
   <img alt="Get Partner ID connect" />

## Step 3: Setup JWT Authentication

To verify credentials, you need to set up JWT authentication similar to the issuance process.

<Info>
  **JWT Setup Required**

  For detailed instructions on setting up JWT authentication, including JWKS configuration and token generation, please refer to the [Partner Authentication guide](/airkit/usage/partner-authentication).
</Info>

**Quick Setup:**

1. Navigate to the [**Accounts tab**](https://developers.sandbox.air3.com/dashboard/general) and configure your **JWKS URL**
2. Generate JWT tokens using your private key for authentication

## Step 4: Understanding Credential Verification

A **verifiable credential** is a secure, digital version of a credential record that can be verified using zero-knowledge proofs.

To start verifying a credential, you need to first set up a verification program and question set that validates the proof.

**Example:** Proving age > 18 without sharing full ID. Say you want to enter a bar and prove you are above 18 without showing your ID or sharing your birth date - you can leverage the age credential that was issued. You send the zero-knowledge proof (not your full passport) to the bar. The proof only answers the question: "Is this person over 18?" and nothing more.

## Step 5: Prerequisites

* Go to the [**Faucet**](https://testnet-scan.mocachain.org/faucet), connect your wallet, and get \$MOCA test tokens
  <img alt="Moca Faucet" />
* Go to Developer Dashboard -> Verifier -> Fee wallet and deposit funds
  <img alt="fund fee wallet" />

## Step 6: Setup Verification Program

* Navigate to the [**Verifier tab**](https://developers.sandbox.air3.com/dashboard/verifier/programs) and click **"Create Program"**
  <img alt="Moca verifier program" />
* Select the schema configured for credential issuance (e.g., `kyc_schema`)
* Configure your query with **question set**, operator, and attribute values
  <img alt="Moca verifier program setup" />
* Add necessary details like **Issuer ID** and hit save. Your program will be created
  <img alt="Moca verifier program created" />
* Now that you have the verifier program created, click on Details and Apply the program.
  <img alt="Moca verifier program setup" />
* Once applied the status of the program will change from Draft to Active
  <img alt="Moca verifier program deployed" />

## Step 7: Verifying Credentials Using the Example App

You can verify credentials using the [Example app](https://developers.sandbox.air3.com/example/verify)

* Generate a JWT token on the demo app interface
  <img alt="verifier_jwt" />

* Enter the verifier DID, verifier program ID and a custom redirect URL to issue credential (if required) and click on "Start Credential Verification"
  <img alt="start verification" />

* The widget will guide you through the verification process.
  <img alt="Verification process start" />

* Once completed you will be able to verify the result on the UI as compliant or non compliant. In this case the result of verification will be compliant as the age was 20 and location was netherlands \[we were verifying adult users outside of the USA].
  <img alt="verification_complete" />

* You can verify the credential verification under the records section in the Verifier Tab.
  <img alt="verify_verification" />

## Step 8: Verifying Credentials Using the AIR Kit

After you've set up your verification program, you can verify credentials programmatically using the AIR Kit. This shows how to configure the verification flow, generate JWTs for authentication, and interact with the AIR SDK's verification API.

### Configure Verification Parameters

We need the following key parameters and configs:

```ts theme={null}
const [config, setConfig] = useState({
  verifierDid: env.VERIFIER_DID || "did:example:verifier123",
  programId: env.PROGRAM_ID || "c21hc030kb5iu0030224Qs",
  redirectUrlForIssuer: env.REDIRECT_URL_FOR_ISSUER || "http://localhost:8080/issue"
});
```

* `verifierDid`: The DID (Decentralized Identifier) of the verifier - identifies who is performing the verification.
* `programId`: The credential program being verified against. This must match the program ID on the Developer Dashboard.
* `redirectUrlForIssuer`: Used in cases when the credential doesnt exist and you want to redirect your user to claim a credential / issue one for them.

### Authentication (JWT Handling)

```ts theme={null}
const jwt = await generateJwt({ partnerId, privateKey });

// generateJwt is a utility function. Refer to the link below to look at its implementation
```

* `partnerId` and `privateKey` come from environment variables.
* JWT is used for authorization when calling airService.verifyCredential function.
  you can refer to [Authentication (Partner JWT)](/airkit/usage/partner-authentication) on how to generate JWT tokens
  > Tip: For production, generate JWTs on the backend to keep private keys secure.
* **Private Key**: Needed to sign JWTs, proving the verifier’s identity.
* **Generated JWT**: The signed token that authenticates API calls to AIR Service.

### Verify the Credential

Call `airService.verifyCredential` to verify the credential:

```ts theme={null}
const result = await airService.verifyCredential({
  authToken: jwt,
  programId: config.programId,
  redirectUrl: config.redirectUrlForIssuer
});

// Handle verification result
if (result.status === "Compliant") {
  // Verification successful - result includes zkProofs, transactionHash, and optionally cakPrivateKey
  console.log("Transaction hash:", result.transactionHash);
  console.log("Zero-knowledge proofs:", result.zkProofs);

  if (result.cakPrivateKey) {
    // Use cakPrivateKey to decrypt compliance data if needed
    console.log("Compliance decryption key available");
  }
} else {
  // Non-compliant status - result only contains status
  console.log("Verification status:", result.status);
}

setVerificationResult(result);
```

* Verifier must have a properly initialized `airService` and a logged in user.
* Call `airService.verifyCredential` with: - authToken: the JWT generated above. - programId: ties verification to the specific credential program configured on the Developer Dashboard. - redirectUrl: ensures redirect-based verification flows can complete.
  * Store Results: verificationResult is updated with the outcome (status + payload).
  * When `status` is `"Compliant"` and compliance encryption is enabled, `cakPrivateKey` is available for decrypting compliance data. See the [Verifying Credentials](/airkit/usage/credential/verify) documentation for details.

### Status Handling

Helper functions map the verification status into colors, icons, and descriptions:

```ts theme={null}
getStatusColor("Compliant"); // → green badge
getStatusIcon("Revoked"); // → 🚫
getStatusDescription("Expired"); // → "The credential has expired..."
```

<Tip>You can refer to this [Authentication (Partner JWT)](/airkit/usage/partner-authentication) for the implementation of these functions.</Tip>

## Summary of Verification Process

1. Set up verification program on the Developer Dashboard
2. Configure verifier DID, program ID, and redirect URL
3. Generate JWT for authentication
4. Call `airService.verifyCredential` to verify the credential
5. Handle verification results and display status

## Example Implementation

For a complete working example, check out the [AIR Credential Example repository](https://github.com/MocaNetwork/air-credential-example) which demonstrates:

* Full credential verification flow with React components
* Verification status handling and display
* Error handling and user feedback
* Complete integration with the AIR Kit's Credential Services

## Next Steps

Now that you know how to verify credentials, you can:

* **Issue credentials** - Learn how to use plug and play templates for issuing and verifying credentials in the [Plug and Play Quickstart](/airkit/templates/plug-and-play-issuer)


# Release Notes
Source: https://docs.moca.network/airkit/release-notes

AIR Kit SDK release history, breaking changes, and migration notes.

## **Version 1.8.0 (Unreleased)**

### ✨ **New Features**

* Credential payment support
* Issue credentials on behalf of users
* Compliance encryption keys support for credential issuance and verification
* Display currency configuration (USD, EUR, CNY, KRW, TRY)
* New `air_accounts` RPC method to check account status across all supported chains
* `wallet_sendCalls` RPC method for batch transaction execution
* New `chainNetwork` option to temporarily use Devnet during migration

### ➕ **Improvements**

* Credential issuance and verification UI improvements and bug fixes
* Swap and OnRamp UI improvements and bug fixes
* WalletConnect stability improvements

### **⚠️ Breaking Changes**

* Sandbox environment now defaults to **Moca Chain Testnet** instead of Devnet
* Credentials issued on Devnet will not be available on Testnet
* Devnet support continues to be available alongside Testnet but will be deprecated later

### **📋 Migration Guide**

After upgrading to `1.8.0`, Sandbox will connect to Testnet by default. If your integration is not ready, you can temporarily stay on Devnet:

```js theme={null}
import { AirService, BUILD_ENV, CHAIN_NETWORK } from "@mocanetwork/airkit";

const airService = new AirService({
  partnerId: YOUR_PARTNER_ID
});
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  chainNetwork: CHAIN_NETWORK.DEVNET, // Stay on Devnet if needed
  enableLogging: true
});
```

We recommend migrating to Testnet as soon as possible. Re-issue any test credentials on Testnet.

***

## **Version 1.7.0 (Nov 18, 2025)**

### ✨ **New Features**

* Cross-chain credential verification support
* Transaction payment token support
* Custom RPC URL configuration
* Automatic in-wallet login flow

### ➕ **Improvements**

* Credential UI updates
* Passkey UI updates
* Significant Air Services performance improvements
* Improved Credential error handling
* Swap UI improvements and bug fixes

## **Version 1.6.0 (Sept 16, 2025)**

### ✨ **New Features**

* Initial Air Credential support
* Flutter SDK released (version 1.5.0)
* Swap beta support
* OnRamp beta support
* Account deletion (via air3.com/recovery)
* Additional chains added:
  * Ethereum Testnet & Mainnet
  * Moca Testnet
  * Gnosis Testnet & Mainnet
  * Edu Testnet & Mainnet

### ➕ **Improvements**

* Air theme update
* Improved wallet login and mobile support
* Improved i18n support
* Improved error handling
* Overall Air Services stability

### **⚠️ Notes**

* Air theme uses light theme only now

## **Version 1.5.0 (July 30, 2025)**

### ✨ **New Features**

* Flutter SDK beta released (version `1.5.0-beta.x`)
* Account email update and recovery (via air3.com/recovery)
* Additional chains added:
  * BNB Smart Chain
  * Kaia and Kairos

### ➕ **Improvements**

* Improved iOS Safari PWA support

### **⚠️ Notes**

* `eth_accounts` will only return AA from now on

## **Version 1.4.0 (June 26, 2025)**

### ✨ **New Features**

* Moca Devnet chain added

### ➕ **Improvements**

* New SANDBOX environment for development and testing

## **Version 1.3.0 (June 5, 2025)**

### ➕ **Improvements**

* Captcha required during OTP for enhanced security
* Signing screen shows actual message
* Improved security by moving signing and transaction screens into separate window
* Improved Passkey provider suggestions
* Wagmi connect method now exposes authToken parameter
* Access token contains `sourcePartnerId` in case of cross partner rehydration
* Many small stabilization improvements

### **⚠️ Notes**

* Signing and transaction screens are now shown in a separate browser window instead of iframe modals

## **Version 1.2.0 (May 7, 2025)**

### ✨ **New Features**

* User login token refresh support

### ➕ **Improvements**

* Improved MFA setup and verification flow
* More user-friendly transaction screen
* Bottom sheet instead of modal on mobile screens
* Animations for smoother transitions
* Support of small mobile screens
* Improved session key support
* Improved provider error handling

## **Version 1.1.0 (March 27, 2025)**

### ✨ **New Features**

* Persistent user sessions across AIR Kit dApps
* Protect user accounts with MFA via Passkey
* Login via EoA wallet
* Soneium chain support (Testnet / Mainnet)

### ➕ **Improvements**

* Simplified transaction screens
* Improved modal UI
* Wallet can be preloaded in the background
* Provider can be retrieved and subscribed to before wallet initialization
* Paymaster policies can be defined per chain
* Various minor bug fixes and optimizations

### **⚠️ Notes**

* The AA will only be returned after the user has MFA set up
* MFA setup will automatically trigger on any wallet action

## **Version 1.0.0 (Feb 27, 2025)**

### ✨ **New Features**

* Smart accounts (AA) can be checked for deployment
* Smart accounts (AA) can be deployed without minting an Air Id
* Experimental session key support

### ➕ **Improvements**

* Full wallet services support
* Improved token refresh mechanism
* Login rehydration across partners

### **⚠️ Notes**

* The `getUserInfo()` and `getPartnerUserInfo()` methods have been merged into `getUserInfo()`

## **Version 0.6.0 (Feb 17, 2025)**

### ✨ **New Features**

* Beta version of wallet services

### ➕ **Improvements**

* Small UI updates
* More helpful error messages

### **⚠️ Notes**

* The wallet initialized event also returns the Smart Account (AA) address from now on

## **Version 0.5.0 (Feb 11, 2025)**

The first official release of AIR Kit, rebranded from Realm SDK, focuses on drastic performance and UX improvements and sets the foundation for upcoming features.

### ✨ **New Features**

* Customizable language support, including localized emails
* Toggleable email input field
* Support for custom authentication (Bring Your Own Auth)
* Optional partner user linking flow
* Introduction of a Global User ID to unify multiple Air IDs

### ➕ **Improvements**

* Simplified design tokens for UI customization
* Significantly faster initialization time and login experience
* Keep login session alive by automatic token refresh
* Backward compatibility down to ES2020
* Various minor bug fixes and optimizations

### **⚠️ Notes**

* The MPC Signer address is no longer being returned
* External wallet login (e.g. MetaMask) is not yet supported
* Wallet-related services, including EIP1193 provider support, are unavailable in this version
* Smart Account (AA) addresses created in this version are different from previous versions


# AIR Kit for Your Business
Source: https://docs.moca.network/airkit/solutions/index

What AIR Kit enables for enterprise partners — portable credentials, cross-platform loyalty, and KYC without PII storage. No blockchain knowledge required.

AIR Kit is the integration layer that lets your platform issue verifiable credentials — proofs of identity, membership, loyalty status, or any user attribute — that your customers can carry and reuse across your partner ecosystem.

Your customers stop re-verifying. Your partners stop building bilateral APIs with you. Your compliance team stops holding raw PII they don't need to hold.

## Two Ways to Use These Docs

<CardGroup>
  <Card title="I'm evaluating AIR Kit" icon="briefcase" href="/solutions/loyalty">
    Explore what AIR Kit enables for your vertical. No code, no technical setup required.
  </Card>

  <Card title="I'm ready to integrate" icon="code" href="/airkit/usage/getting-started">
    Jump to the developer Quick Setup and integration guides.
  </Card>
</CardGroup>

## What AIR Kit Does

At its core, AIR Kit enables three things:

**1. Issue credentials from your existing backend**
When a business event happens — a user passes KYC, reaches loyalty Gold, activates a subscription — your backend fires one API call. A verifiable credential lands in that user's AIR Account. No user action required, no wallet to open.

**2. Verify credentials at any point of use**
When that user shows up at your app, a partner's app, or any service in the ecosystem, one SDK call confirms what they hold. Your platform gets a simple COMPLIANT / NON\_COMPLIANT signal. No raw data crosses.

**3. Let credentials travel across platforms**
The credential belongs to the user, not your database. A loyalty Gold earned with you is presentable at a partner hotel, airline, or retailer — without a direct API agreement between you and that partner. The credential is the integration.

## Which Vertical Fits Your Business

<CardGroup>
  <Card title="Loyalty & Rewards" icon="gift" href="/solutions/loyalty">
    Cross-brand tier portability. No bilateral APIs. No unredeemed point silos.
  </Card>

  <Card title="Identity & Compliance" icon="shield-check" href="/solutions/identity">
    KYC once, accepted everywhere. ZK proof of identity without storing PII.
  </Card>

  <Card title="Fintech & Payments" icon="credit-card" href="/solutions/fintech">
    Compliance gating, accredited investor proofs, age verification without DOB storage.
  </Card>

  <Card title="Gaming & Entertainment" icon="gift" href="/solutions/gaming">
    Portable player achievements, cross-game identity, bot-resistant airdrop gating.
  </Card>

  <Card title="Telco & Subscriptions" icon="signal" href="/solutions/telco">
    Subscriber KYC portability for roaming, MVNO, and partner services.
  </Card>

  <Card title="Advertising & Audiences" icon="megaphone" href="/solutions/advertising">
    Verified audience segments without cookies. Age-gated serving without storing DOB.
  </Card>
</CardGroup>

## Common Questions

**Do our users need a crypto wallet?**
No. AIR Account is a smart account — users authenticate with email, social login, or passkey. The blockchain layer is invisible to them.

**How long does integration take?**
Most partners are live in 2–4 weeks for a backend engineer. The core integration is one API call in your existing event handler.

**Does AIR Kit replace our KYC provider?**
No. You keep your existing KYC provider. AIR Kit converts the pass result into a portable credential. Your provider still runs the verification.

**Where does our customer data go?**
Nowhere new. AIR Kit stores only cryptographic attestations — the proof that a fact is true, not the underlying data. See the [Compliance FAQ](/solutions/compliance-faq) for full detail.


# Plug & Play Templates
Source: https://docs.moca.network/airkit/templates/plug-and-play

AIR Kit provides two ready-to-use templates that you can fork, configure, and deploy with minimal development work:

AIR Kit provides two ready-to-use templates that you can fork, configure, and deploy with minimal development work:

* **Issuer Template** - for issuing AIR credentials

* **Verifier Template** - for verifying credentials inside your application

These templates are designed to be plug-and-play, allowing you to integrate AIR in minutes and extend as needed.

## Key Features

* **Zero-to-live in under 30 minutes**
* **Battle-tested UI flows**
* **Minimal configuration requirements**
* **Full extensibility after setup**

The upcoming [**Guides**](/airkit/templates/plug-and-play-issuer) show exactly how to go from forking these templates → deploying → verifying credentials.

## Issuer Template

A flexible credential-issuer template that supports AIR Account, Web2, and Web3 login methods. You can use it as-is or extend it to fit your workflow, data sources, and branding.

### Key Features

* Multi-login support: AIR Account, Web2 OAuth, Web3 wallets
* Customizable credential schema
* Optional external data source integration
* Theming and UI customization
* Ready-to-deploy production template

Try it out [here](https://air-credential-issuer-template.netlify.app/)

### Repository

```
https://github.com/MocaNetwork/air-credential-issuance-template
```

## Verifier Template

The Verifier Template allows you to verify AIR credentials inside your application within minutes. It is designed to be the fastest way to verify credentials on chain, with the ability to customize and embed it into any architecture.

The goal is simple:
Fork → Deploy → Configure → Verify.

After that, you can adapt the template freely to match your UX, branding, and business logic.

### Key Features

* You can instantly plug the verifier into an existing app

* Spin up a working verifier in under 30 minutes

* Fully functional credential verification flow

* Easily adjustable design, layout, and logic

* Ready for both local testing and production deployment

* Works across AIR Account, Web2, and Web3 login systems

Try it out [here](https://air-credential-verifier-template.netlify.app/)

***

# What’s Next: Quickstart Guides

The next section contains **step-by-step Quickstart Guides** for both templates.

You will learn how to:

* fork the templates
* configure them with your Partner ID
* connect your Issuer and Verifier flows
* deploy on Vercel or Netlify
* run credential issuance + verification end-to-end

These Quickstarts are designed so that:

* Developers can **spin up a working verifier in 30 minutes**
* Partners can **issue their first credential on day 1**
* Teams can embed AIR flows into their existing app with minimal friction

👉 Continue to **Quickstart: Issuer Template**
👉 Continue to **Quickstart: Verifier Template**


# Quickstart: Credential Issuance Template
Source: https://docs.moca.network/airkit/templates/plug-and-play-issuer

This guide provides the steps necessary to get the AIR Credential Issuer running, configured, and ready to issue credentials.

This guide provides the steps necessary to get the AIR Credential Issuer running, configured, and ready to issue credentials.

> **🌟 Support the Project**
>
> If you find this template useful, please consider starring the repository on GitHub!
>
> [![Star on GitHub](https://img.shields.io/github/stars/MocaNetwork/air-credential-issuance-template?style=social)](https://github.com/MocaNetwork/air-credential-issuance-template)

## 1. Local Setup & Prerequisites

Before you begin, ensure your local environment is configured and you have the necessary accounts ready.

### 1.1 Prerequisites Checklist

| Item                            | Requirement                                                                                                                                                               | Source                                                                                                 |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------- |
| **Node.js**                     | v18 or later                                                                                                                                                              | Development Environment                                                                                |
| **Package Manager**             | `pnpm` (recommended) or `npm`                                                                                                                                             | Development Environment                                                                                |
| **Partner ID & Issuer DID**     | Obtain Credentials. Understand more on Partner ID [here](/airkit/airkit-dashboard#_1-general-settings)                                                                    | [Sandbox Developer Dashboard](https://developers.sandbox.air3.com/dashboard)                           |
| **Issuance Program ID**         | Create Program & Schema. Refer to [this](/airkit/quickstart/issue-credentials#step-4-create-schema-for-credential-issuance) guide to create Schema and issuance programID | [Sandbox Dashboard (Issuer Section)](https://developers.sandbox.air3.com/dashboard/issuer/credentials) |
| **Reown Project ID** (Optional) | Required for `wallet` authentication                                                                                                                                      | [Reown](https://reown.com)                                                                             |

### 1.2 Local Development

1. **Clone the Repository**

   ```bash theme={null}
   git clone https://github.com/MocaNetwork/air-credential-issuance-template.git
   cd air-credential-issuance-template
   ```

2. **Install Dependencies**

   ```bash theme={null}
   pnpm install
   # or npm install
   ```

3. **Configure Environment Variables**
   Copy the example file and start populating your credentials.

   ```bash theme={null}
   cp .env.example .env.local
   ```

4. **Start the Development Server**

   ```bash theme={null}
   pnpm dev
   # or npm run dev
   ```

   Your issuer app is now running at [http://localhost:3000](http://localhost:3000).

## 2. Partner Configuration

This section details the critical steps for connecting your application to the AIR Kit services.

### 2.1 Set Issuance Details

1. Log into the [Sandbox Developer Dashboard](https://developers.sandbox.air3.com/dashboard).
2. Retrieve your **Partner ID** and **Issuer DID** from **Account -> General Settings**.
3. Create an **Issuance Program** and **Schema** in the **Issuer** section.
4. Update the following variables in your `.env.local`:
   * `NEXT_PUBLIC_PARTNER_ID`
   * `NEXT_PUBLIC_ISSUER_DID`
   * `NEXT_PUBLIC_ISSUE_PROGRAM_ID`

### 2.2 Select Authentication Method

Set the method the application will use to identify the user before issuance:

| Method Option | Set `NEXT_PUBLIC_AUTH_METHOD` | Details                                                                                                      |
| :------------ | :---------------------------- | :----------------------------------------------------------------------------------------------------------- |
| **Wallet**    | `wallet`                      | Uses Web3 Wallet Connect (requires `NEXT_PUBLIC_REOWN_PROJECT_ID`).                                          |
| **AIR Kit**   | `airkit`                      | Uses the native AIR Kit User ID system.                                                                      |
| **Custom**    | *Leave blank/Configure*       | Use your existing internal user sessions (JWTs/Cookies). [See details here](#bringing-your-own-user-session) |

### 2.3 Set up Partner Signing Key

A private key is required to sign the Partner JWT used for user sessions and issuance.

1. **Generate an ES256 Private Key**:

   ```bash theme={null}
   openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt | tr -d '\n'
   ```

2. Copy the generated key (the content between `BEGIN` and `END` lines) and set it securely as a server-side variable.

   ```bash theme={null}
   # .env.local (Server-side)
   PARTNER_PRIVATE_KEY="MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg..."
   ```

   > **⚠️ Security Note**: This key must be kept secret and never committed to source control.

***

## 3. Data Integration & Issuance Logic

You must customize the endpoint that retrieves user data to populate the credential claims.

### 3.1 Retrieve User Data

1. Open the data fetching endpoint file:
   ```
   app/(home)/api/user/user-data/route.ts
   ```
2. Replace the mock logic with real data retrieval, typically a **secure backend-to-backend API call** using the authenticated `userId`.

### 3.2 Map Data to Schema

Ensure the data fetched in the previous step is transformed to exactly match the attribute structure defined in your **Credential Schema**. This data is what will be signed and embedded in the issued credential.

## 4. Deployment & Finalization

The final step is deploying the application and registering its public key endpoint with the AIR Partner Dashboard.

### 4.1 Production Build and Deployment

1. **Build**:
   ```bash theme={null}
   pnpm build
   # or npm run build
   ```
2. Deploy the output to your chosen hosting service (e.g., Vercel, Netlify).

### 4.2 Set JWKS URL (Critical Step)

The **JWKS URL** allows AIR Kit to verify the JWTs signed by your deployed application.

1. Once deployed, your application automatically hosts the public key at:
   ```
   <your-host-url>/jwks.json
   ```
2. Navigate to the **Sandbox Developer Dashboard** (**Account -> General Settings**) and configure this full URL as your **JWKS URL** setting.

### 4.3 Whitelist Your Domain

To ensure communication with AIR Kit services is secure and allowed:

1. Go to the **Sandbox Developer Dashboard** (**Account > Domains**).
2. Add your deployed application URL (e.g., `https://my-issuer-app.com`) to the allowed domains list.

### 4.4 Bringing your own user session

To use your internal User ID and User session within this app, you'll need the user to log into your app before starting the issuance process on this app.

This app reads cookies from air.issuer-template.session, expecting the following format (`{"state":{"accessToken":null},"version":0}`), where the accessToken is a signed JWT verifiable by your public key.

<Note>Under the hood, the template uses a lightweight state management library called [zustand](https://www.npmjs.com/package/zustand).</Note>

Once the session is validated, you would use the contents of the payload (e.g., user Id) to retrieve specific user data info from your application.

## 5. Configuration Reference

### Client-side Environment Variables

| Variable                       | Description                        | Example Value                |
| :----------------------------- | :--------------------------------- | :--------------------------- |
| `NEXT_PUBLIC_PARTNER_ID`       | Your Partner ID.                   | `partner_abc123`             |
| `NEXT_PUBLIC_ISSUER_DID`       | Your Decentralized Identifier.     | `did:air:issuer_xyz`         |
| `NEXT_PUBLIC_ISSUE_PROGRAM_ID` | The ID of your Issuance Program.   | `prog_987`                   |
| `NEXT_PUBLIC_AUTH_METHOD`      | Authentication method for the app. | `wallet` or `airkit`         |
| `NEXT_PUBLIC_REOWN_PROJECT_ID` | Reown ID (if using `wallet` auth). | `proj_reown_def`             |
| `NEXT_PUBLIC_BUILD_ENV`        | Build environment.                 | `sandbox` or `production`    |
| `NEXT_PUBLIC_THEME`            | Application color theme.           | `light`, `dark`, or `system` |

### Server-side Environment Variables

| Variable              | Description                                    |
| :-------------------- | :--------------------------------------------- |
| `PARTNER_PRIVATE_KEY` | **Your private key** (must be kept secret).    |
| `SIGNING_ALGORITHM`   | Algorithm for signing the JWT (e.g., `ES256`). |

***

The **Credential Issuer Template** handles all the user flow and cryptographic signing necessary to issue a Verifiable Credential.
Once configured, the issued credential is ready to be presented to any application using the [Verifier Template](/airkit/templates/plug-and-play-verifier).

Now that you have setup the issuance and verification, you can now customize the theming of the issuance and verification screens. Refer to the [customization section](/airkit/usage/config-theming) for more details


# Quickstart: Credential Verifier Template
Source: https://docs.moca.network/airkit/templates/plug-and-play-verifier

This guide provides the steps necessary to set up, configure, and deploy the AIR Credential Verifier template, allowing your application to instantly 

This guide provides the steps necessary to set up, configure, and deploy the AIR Credential Verifier template, allowing your application to instantly verify credentials using **AIR Kit**.

> **🌟 Support the Project**
>
> If you find this template useful, please consider starring the repository on GitHub!
>
> [![Star on GitHub](https://img.shields.io/github/stars/MocaNetwork/air-credential-issuance-template?style=social)](https://github.com/MocaNetwork/air-credential-verifier-template)

## Local Setup & Prerequisites

Ensure your environment is ready and you have obtained the necessary credentials from the Partner Dashboard.

### 1.1 Prerequisites Checklist

| Item                        | Requirement                                                                                                                   | Source                                                                                                  |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
| **Node.js**                 | v18 or later                                                                                                                  | Development Environment                                                                                 |
| **Package Manager**         | `pnpm` (recommended) or `npm`                                                                                                 | Development Environment                                                                                 |
| **Partner ID**              | Obtain PartnerID. Understand more on Partner ID [here](/airkit/airkit-dashboard#_1-general-settings)                          | [Sandbox Developer Dashboard](https://developers.sandbox.air3.com/dashboard)                            |
| **Verification Program ID** | Create Program. Learn how to create a program [here](/airkit/quickstart/verify-credentials#step-6-setup-verification-program) | [Sandbox Dashboard (Verifier Section)](https://developers.sandbox.air3.com/dashboard/verifier/programs) |

### 1.2 Local Development

1. **Clone the Repository**

   ```bash theme={null}
   git clone https://github.com/MocaNetwork/air-credential-verifier-template.git
   cd air-credential-verifier-template
   ```

2. **Install Dependencies**

   ```bash theme={null}
   pnpm install
   # or npm install
   ```

3. **Configure Environment Variables**
   Copy the example file to start configuring your settings:

   ```bash theme={null}
   cp .env.example .env.local
   ```

4. **Start the Development Server**

   ```bash theme={null}
   pnpm dev
   # or npm run dev
   ```

   Your verifier app is now running at [http://localhost:3000](http://localhost:3000).

## Customizing the Verifier Template

This section covers setting up your verification program and the essential JWT signing key.

### 2.1 Set Verification Details

1. Log into the [Sandbox Developer Dashboard](https://developers.sandbox.air3.com/dashboard).
2. Retrieve your **Partner ID** from **Account -> General Settings**.
3. Under the **Verifier** section, create a **Verification Program** appropriate for the credentials you wish to accept.
4. Update the following variables in your `.env.local`:
   * `NEXT_PUBLIC_PARTNER_ID`
   * `NEXT_PUBLIC_VERIFIER_PROGRAM_ID`

### 2.2 Set up Partner Signing Key

A private key is necessary for JWT signing during the verification process.

1. **Generate an ES256 Private Key**:

   ```bash theme={null}
   openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt | tr -d '\n'
   ```

2. Copy the generated key (the content between `BEGIN` and `END` lines) and set it securely as a server-side variable.

   ```bash theme={null}
   # .env.local (Server-side)
   PARTNER_PRIVATE_KEY="MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg..."
   ```

   > **⚠️ Security Note**: This key must be kept secret and never committed to source control.

## Deployment & Finalization

The verifier template is designed for a simple development, testing, and deployment cycle.

### 3.1 Production Build and Deployment

1. **Build the application**:
   ```bash theme={null}
   pnpm build
   # or npm run build
   ```
2. Deploy the output to your hosting service.

### 3.2 Whitelist Your Domain (Critical Step)

To ensure secure communication between your deployed verifier application and the AIR Kit services:

1. Go to the **Sandbox Developer Dashboard** (**Account > Domains**).
2. Add your deployed application URL (e.g., `https://my-verifier-app.com`) to the
   allowed domains list.

### 3.3 Deploying to Vercel

Click the button below to deploy directly to Vercel:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/MocaNetwork/air-credential-verifier-example\&env=NEXT_PUBLIC_PARTNER_ID,NEXT_PUBLIC_VERIFIER_PROGRAM_ID,NEXT_PUBLIC_ISSUER_URL,NEXT_PUBLIC_SITE_NAME,NEXT_PUBLIC_SITE_DESCRIPTION,NEXT_PUBLIC_BUILD_ENV,NEXT_PUBLIC_THEME,PARTNER_PRIVATE_KEY,SIGNING_ALGORITHM\&envDescription=Configure%20your%20AIR%20Kit%20credentials%20and%20application%20settings\&envLink=https://github.com/MocaNetwork/air-credential-verifier-example/blob/main/README.md)

### 3.4 Customizing the UX

* **UI/Theming**: This project uses **Shadcn UI**. Customize the look by setting the `NEXT_PUBLIC_THEME` and referring to the [Shadcn UI Theming Guide](https://ui.shadcn.com/docs/theming).
* **Redirects**: Control the post-verification experience by setting these optional variables:
  * `NEXT_PUBLIC_RETURN_SITE_NAME`: Display name of your app for users returning after verification.
  * `NEXT_PUBLIC_RETURN_URL`: The URL where users are redirected after successful verification.

## Configuration Reference

### Client-side Environment Variables

| Variable                          | Description                                   | Example Value             |
| :-------------------------------- | :-------------------------------------------- | :------------------------ |
| `NEXT_PUBLIC_PARTNER_ID`          | Your Partner ID.                              | `partner_abc123`          |
| `NEXT_PUBLIC_VERIFIER_PROGRAM_ID` | The ID of your Verification Program.          | `verify_prog_987`         |
| `NEXT_PUBLIC_ISSUER_URL`          | URL where users can go to get the credential. | `https://my-issuer.com`   |
| `NEXT_PUBLIC_SITE_NAME`           | Site/application name for display.            | `Moca Access Portal`      |
| `NEXT_PUBLIC_RETURN_URL`          | Redirect URL after verification.              | `/dashboard`              |
| `NEXT_PUBLIC_BUILD_ENV`           | Build environment.                            | `sandbox` or `production` |

### Server-side Environment Variables

| Variable              | Description                                    |
| :-------------------- | :--------------------------------------------- |
| `PARTNER_PRIVATE_KEY` | **Your private key** (must be kept secret).    |
| `SIGNING_ALGORITHM`   | Algorithm for signing the JWT (e.g., `ES256`). |

### Additional Client-side Variables

| Variable                       | Description            |
| :----------------------------- | :--------------------- |
| `NEXT_PUBLIC_SITE_DESCRIPTION` | Site description text. |


# Common Errors
Source: https://docs.moca.network/airkit/troubleshooting/common-errors

HTTP error codes, JWT errors, and JWKS issues you may encounter when integrating AIR Kit.

## API error codes

These errors apply to the AIR Kit REST API (e.g. [Issue on Behalf](/api-reference/introduction)).

| HTTP status | Likely cause                                | How to fix                                                                                                                                              |
| ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | Missing or invalid request fields           | Verify `issuerDid`, `credentialId`, and `credentialSubject` match your schema. Check that required fields are present and types are correct.            |
| 401         | Invalid or expired Partner JWT              | Verify the JWT is not expired (`exp`), the signature matches your JWKS key, `kid` in the header maps to the correct key, and `typ: "JWT"` is set.       |
| 403         | Feature not enabled or schema not allowed   | Confirm the feature (e.g. Issue on Behalf) is enabled for your partner account in the Developer Dashboard. Check that your `issuerDid` owns the schema. |
| 404         | Unknown issuer DID or program ID            | Double-check `issuerDid` and `credentialId` values against the Developer Dashboard.                                                                     |
| 409         | User consent rejected or duplicate conflict | The user has denied consent for credentials issued on their behalf, or a duplicate credential exists with `onDuplicate: "ignore"`.                      |
| 500         | Server-side failure                         | Retry with exponential backoff. If persistent, check the [Moca Network status page](https://discord.gg/mocaversenft) or contact support.                |

## JWT and JWKS errors

### "Invalid signature" or "JWT verification failed"

* Confirm the `kid` in your JWT header matches a key ID in your JWKS endpoint.
* Verify the algorithm (`RS256` or `ES256`) matches the key type in your JWKS.
* Check that you are signing with the correct private key.

### "Token expired"

* The `exp` claim has passed. Generate a new JWT with a fresh `exp` (recommended: 5 minutes from now).
* Verify your server clock is synchronized (NTP).

### "JWKS endpoint unreachable"

* Your JWKS URL must be publicly accessible over HTTPS.
* Test it with `curl https://your-domain/.well-known/jwks.json` — it should return a valid JSON document.
* Ensure no firewall or IP allowlist blocks AIR Kit's servers.

### "kid not found"

* The `kid` in your JWT header does not match any key in the JWKS response.
* If you recently rotated keys, publish the new key to your JWKS endpoint before using it in JWTs.

### "Missing typ header"

* For Issue on Behalf, the JWT header must include `typ: "JWT"`. Add it to your JWT signing options:

```js theme={null}
jwt.sign(payload, privateKey, {
  algorithm: "RS256",
  header: { kid: "your-key-id", typ: "JWT" },
});
```

## CORS errors

If you see CORS errors when initializing the SDK in a browser:

* AIR Kit uses an iframe for login. Ensure your `Content-Security-Policy` allows `frame-src` from `*.air3.com`.
* If you are proxying requests, ensure the `Origin` header is forwarded correctly.

## Rate limiting

API endpoints may return `429 Too Many Requests` if you exceed rate limits. Back off and retry with exponential delays. Avoid tight polling loops on the status endpoint — start with 1-second intervals and double each attempt.


# Credential Issues
Source: https://docs.moca.network/airkit/troubleshooting/credential-issues

Troubleshooting credential issuance, verification, and schema problems.

## Issuance

### Credential stuck in WAIT\_ONCHAIN

The credential has been submitted but not yet confirmed on-chain. This is normal during periods of chain congestion.

* Poll the [status endpoint](/api-reference/introduction) with exponential backoff (start at 1 second, double each attempt, cap at 30 seconds).
* If the credential remains in `WAIT_ONCHAIN` for more than 5 minutes, check the [Moca Chain block explorer](/mocachain/native-dapps/block-explorer) for chain health.
* Do not re-issue the credential while it is pending — use the status endpoint to wait.

### Issue on Behalf returns 400

* Verify `issuerDid`, `credentialId`, and `credentialSubject` are all present and correctly typed.
* Ensure `credentialSubject` matches the schema definition exactly. Extra fields or wrong types will be rejected.
* Check the response body for a specific error message.

### Issue on Behalf returns 409

This usually means:

* **User consent rejected:** The user has previously declined credentials from your partner account. Contact the user or wait for them to re-consent.
* **Duplicate credential with `onDuplicate: "ignore"`:** A credential already exists for this user + schema combination. If you need to update it, use `onDuplicate: "revoke"`.

### Credential not visible to user after issuance

* Confirm the credential status is `ONCHAIN` via the status endpoint.
* For Issue on Behalf, newly created users see issued credentials when they first log in. They may be prompted to accept or reject credentials.
* Verify the user's email matches the `email` claim in your Partner JWT.

## Verification

### Verification returns "no matching credential"

* The user may not have a credential matching the verification program's schema. Check that:
  * The credential was issued using the correct issuance program.
  * The credential has not been revoked.
  * The verification program's schema matches the issuance program's schema.

### Verification fails with "proof invalid"

* The credential may have been tampered with or the on-chain anchor may not match.
* If the credential was recently issued, ensure it has reached `ONCHAIN` status before attempting verification.
* Check that the credential has not expired (`expirationDate` in the status response).

### User declines verification

* The SDK prompts users for consent before presenting a credential. If the user declines, the verification result will indicate failure.
* Your app should handle this gracefully — show a message explaining why the credential is needed and offer to retry.

## Schema issues

### "Schema not found" error

* Verify the schema exists in the Developer Dashboard (Issuer > Schemas).
* Ensure the `credentialId` (Issuance Program ID) references a published program, not a draft.

### Schema mismatch between issuance and verification

* If a verification program rejects credentials that were successfully issued, the issuance and verification programs may reference different schema versions.
* Check both programs in the Developer Dashboard and ensure they point to the same schema.

## CAK-specific issues

### Encrypted data not decrypting for verifier

* Verify the user has granted consent in the SDK UI.
* Ensure the verification program has `CAK required` enabled.
* Check that the issuer's CAK callback URL is correctly configured and returning 200 responses.

See [Privacy & Compliance](/learn/advanced-topics/privacy-and-compliance) for the full CAK framework.


# SDK Issues
Source: https://docs.moca.network/airkit/troubleshooting/sdk-issues

Common issues with AIR Kit SDK initialization, login, and session management.

## Initialization

### SDK does not initialize

* Verify you are calling `init()` with a valid `partnerId`:

```ts theme={null}
const airService = new AirService();
await airService.init({ partnerId: "your-partner-id" });
```

* Check the browser console for errors. A network failure to load the AIR Kit iframe will surface here.
* Ensure you are using a supported browser (Chrome, Firefox, Safari, Edge — latest versions).

### "Partner ID not found" error

* Confirm the Partner ID in the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard) matches what you pass to `init()`.
* Check that you are using the correct environment. Sandbox and Production have different Partner IDs.

## Login

### Login dialog does not appear

* The SDK opens an iframe for login. If it doesn't appear:
  * Check that `Content-Security-Policy` headers allow `frame-src` from `*.air3.com`.
  * Check for CSS `z-index` conflicts — the iframe may be behind other elements.
  * Disable browser extensions that block iframes or popups.

### Login succeeds but user data is missing

* `login()` returns an `AirLoginResult` containing `token` and account information. If fields are missing, verify your Partner JWT includes the expected claims.
* If using Custom Auth (BYO), ensure `email` is included in the Partner JWT.

### "Session expired" after page refresh

* By default, AIR Kit auto-restores sessions for 30 days. If sessions expire immediately:
  * Check that `skipRehydration` is not set to `true` in your `init()` options.
  * Verify cookies and local storage are not being cleared by your app or browser settings.

### Session rehydration fails silently

* Call `isLoggedIn` after `init()` to check if rehydration succeeded.
* If the session cannot be restored (expired, corrupted), `isLoggedIn` returns `false`. Call `login()` to start a new session.

## Flutter-specific

For a consolidated checklist, see [Flutter troubleshooting](/airkit/flutter/troubleshooting).

### SDK not loading on iOS

* Ensure your `ios/Runner/Info.plist` includes the required URL schemes and capabilities.
* Follow [Flutter iOS setup](/airkit/flutter/ios-setup) and the [Installation guide](/airkit/usage/installation) (Flutter tab).

### SDK not loading on Android

* Verify `minSdk` 26+ and `compileSdk` 34+ in your Gradle config.
* Ensure internet permission is declared in `AndroidManifest.xml`.
* Follow [Flutter Android setup](/airkit/flutter/android-setup).

## wagmi connector

### Connector not appearing in wagmi

* Ensure `@mocanetwork/airkit-connector` is installed and the connector is added to your wagmi config:

```ts theme={null}
import { airConnector } from "@mocanetwork/airkit-connector";

const config = createConfig({
  connectors: [airConnector({ partnerId: "your-partner-id" })],
  // ...
});
```

### `isMocaNetwork` is undefined

* Cast the connector to the correct type:

```ts theme={null}
import type { AirConnectorProperties } from "@mocanetwork/airkit-connector";
const isAir = (connector as Connector & AirConnectorProperties)?.isMocaNetwork;
```

## Still stuck?

* Check the [AIR Kit release notes](/airkit/release-notes) for known issues in your SDK version.
* Join our [Discord](https://discord.gg/mocaversenft) for community support.


# Advanced Functions (Beta)
Source: https://docs.moca.network/airkit/usage/account/advanced-functions

AIR Kit extends the standard EIP-1193 provider with custom RPC methods for advanced functionality.

<Warning>
  Swap functionality, advanced DeFi operations are only supported on `Base` chain only.
</Warning>

### Swap Operations (Beta)

**air\_getSwapQuote**

```tsx theme={null}
const quote = await provider.request({
  method: "air_getSwapQuote",
  params: [
    {
      fromToken: string,
      toToken: string,
      fromAmount: string
    }
  ]
});
// Returns: swap quote data
```

**air\_sendSwapTransaction**

```tsx theme={null}
const txHash = await provider.request({
  method: "air_sendSwapTransaction",
  params: [
    {
      fromToken: string,
      toToken: string,
      fromAmount: string
    }
  ]
});
// Returns: string (transaction hash)
```

**air\_showSwapUI**

```tsx theme={null}
const txHash = await provider.request({
  method: "air_showSwapUI",
  params: []
});
// Returns: string (transaction hash)
```


# Built-in UI (Beta)
Source: https://docs.moca.network/airkit/usage/account/builtin-ui

Opens the AIR Kit swap interface, allowing users to exchange tokens directly within your application.

## Swap Interface

### showSwapUI()

Opens the AIR Kit swap interface, allowing users to exchange tokens directly within your application.

**Method Signature:**

```ts theme={null}
public async showSwapUI(options?: {
  initialFromToken?: string;
  fallbackFromToken?: string;
  initialToToken?: string;
}): Promise<{ txHash: `0x${string}` }>
```

**Returns:**

```ts theme={null}
{
  txHash: string; // The transaction hash of the swap transaction
}
```

**Usage:**

```ts theme={null}
try {
  const result = await airService.showSwapUI();
  console.log("Swap completed! Transaction hash:", result.txHash);
} catch (error) {
  console.error("Swap failed:", error);
}
```

**What happens during swap:**

1. Opens the swap interface
2. User selects token and amount to swap
3. User confirms the swap transaction
4. Returns the transaction hash upon successful completion

**Requirements:**

* User must be logged in

**Important Notes:**

* **Experimental feature**: This method is marked as experimental and may change in future versions
* **Chain support**: Currently only supported on Base network
* **User experience**: Opens a full swap interface with token selection, amount input, and slippage settings.
* **Advanced control**: For more control over the swap flow, use the RPC method `air_getSwapQuote` and `air_sendSwapTransaction` to specify exact token addresses, amounts, and slippage settings

## On-Ramp Interface

### showOnRampUI()

Opens the AIR Kit on-ramp interface, allowing users to purchase cryptocurrency with fiat currency.

**Method Signature:**

```ts theme={null}
public async showOnRampUI(options: {
  displayCurrencyCode: string;
  targetCurrencyCode?: string;
}): Promise<void>
```

**Parameters:**

```ts theme={null}
{
  displayCurrencyCode: string; // Fiat currency code (e.g., "USD", "EUR")
  targetCurrencyCode?: string; // Optional target cryptocurrency (e.g., "ETH", "USDC")
}
```

**Usage:**

```ts theme={null}
try {
  await airService.showOnRampUI({
    displayCurrencyCode: "USD",
    targetCurrencyCode: "USDC"
  });
  console.log("On-ramp interface opened");
} catch (error) {
  console.error("Failed to open on-ramp:", error);
}
```

**What happens during on-ramp:**

1. Opens the on-ramp interface
2. User selects payment method and amount
3. User completes the fiat-to-crypto purchase
4. Cryptocurrency is deposited to their wallet

**Requirements:**

* User must be logged in

**Important Notes:**

* **Experimental feature**: This method is marked as experimental and may change in future versions
* **No return value**: This method doesn't return a transaction hash as the purchase is handled by the on-ramp provider
* **Currency support**: Supported currencies depend on the on-ramp provider configuration


# Sponsoring Gas with Paymaster
Source: https://docs.moca.network/airkit/usage/account/paymaster

With our Paymaster service, we provide granular, API-driven tools to precisely manage your sponsorship strategy and budget.

<Warning>
  To update your gas sponsorship settings, please contact us.
</Warning>

1. **Granular Sponsorship Controls**
   You have fine-grained control over which on-chain activities you sponsor. - **Sponsor Specific Contract Functions:** Whitelist transactions based on the specific function being called (via its `function selector`). - *Example:* A DeFi protocol could sponsor the `deposit` function but not the `withdraw` function. - **Sponsor A Specific Contract:** Whitelist all interactions with a particular smart contract address. - **Support for Atomic Batch Transactions:** The service can process a `UserOperation` containing multiple actions. The entire batch is treated as a single, atomic unit; if any one of the bundled actions fails the policy validation, the entire transaction is rejected, preventing partial execution and unintended gas spending.
2. **ERC-20 Paymaster Support**
   * For user operations that do not qualify for sponsorship, users can opt to pay gas fees using ERC-20 tokens, including MOCA, USDT, USDC, EURe, and others. For a complete list of supported tokens, please contact us.
3. **Powerful Policy & Budget Management**
   You can define comprehensive policies to govern their sponsorship activities and control costs. - **Multi-Chain Policy Configuration:** Define and manage entirely separate sponsorship policies and allowlists for each supported blockchain (e.g., Ethereum, Polygon, Base). - **Set Granular Spending Limits:** Establish robust budgets with different scopes and reset intervals (daily, weekly, monthly): - **Global Limit:** A total budget for the entire policy. - **Per-User Limit:** A spending cap for each individual user. - **Control Transaction Costs:** Set a maximum gas cost (`maxGasCost`) you are willing to sponsor for a single `UserOperation` to protect against volatile or unexpectedly expensive transactions. - **Time-based Policy Activation:** Schedule policies to automatically activate and deactivate at specific `start` and `end` times, ideal for limited-time promotions or campaigns.

## **How It Works: The Sponsorship Flow**

The sponsorship process is a high-speed, automated workflow compliant with the ERC-4337 standard for Account Abstraction. It functions as the core logic for the `pm_sponsorUserOperation` RPC method.

1. **Sponsorship Request:** The flow begins when a user action in a partner application, via our SDK, generates a `UserOperation`. The SDK then calls the `pm_sponsorUserOperation` endpoint to determine sponsorship eligibility.
2. **Webhook to Paymaster:** our bundler provider receives this request and forwards it as a webhook to our Paymaster Service.
3. **Policy Validation:** Our Paymaster Service validates the incoming `UserOperation` against the partner's configured **Sponsorship Policy**. This is a real-time check of all conditions, including spending limits, gas limits, and whether the transaction's target address and function selector are on the partner's **Allowlist**.
4. **Sponsorship Decision:** Based on the validation result, our service responds:
   * **On Success:** The Paymaster cryptographically signs the `UserOperation` and returns the `paymasterAndData` field. This serves as the on-chain proof of sponsorship, allowing the transaction to be bundled and executed.
   * **On Failure:** The service returns an error, rejecting the sponsorship request. Our SDK is designed to handle this failure gracefully, falling back to a standard transaction flow where the user pays the gas fee themselves.


# Wallet Functions
Source: https://docs.moca.network/airkit/usage/account/provider-functions

AIR Kit provides comprehensive wallet functionality that allows you to interact with blockchain networks, manage smart accounts, and perform transactions. The wallet system is built on top of EIP-1193 standards and supports multiple blockchain networks.

## Wallet Preloading

### preloadWallet()

Preloads the wallet service to improve performance by initializing the wallet infrastructure before it's needed.

**Method Signature:**

```tsx theme={null}
public async preloadWallet(): Promise<void>
```

**Usage:**

```tsx theme={null}
try {
  await airService.preloadWallet();
  console.log("Wallet preloaded successfully");
} catch (error) {
  console.error("Failed to preload wallet:", error);
}
```

**Important notes:**

* The wallet can be preloaded even before the user is logged in
* Improves response time for subsequent wallet operations
* Even if preloading hasn't finished, using the provider or any other wallet operation will ensure that the wallet is done initializing before executing the actual call

**Requirements:**

* Service must be initialized

## EIP-1193 Wallet Provider

### getProvider()

Returns an EIP-1193 compatible provider that works seamlessly with popular Web3 libraries such as [web3](https://github.com/web3/web3.js), [ethers](https://github.com/ethers-io/ethers.js), and [Viem](https://viem.sh/).

**Method Signature:**

```tsx theme={null}
getProvider(): EIP1193Provider
```

**Returns:**
An EIP-1193 compatible provider object with the following interface:

```tsx theme={null}
interface EIP1193Provider {
  request(request: AirProviderParameters): Promise<unknown>;
  on<EventName extends keyof EIP1193EventMap>(
    event: EventName,
    listener: EIP1193EventMap[EventName]
  ): void;
  removeListener<EventName extends keyof EIP1193EventMap>(
    event: EventName,
    listener: EIP1193EventMap[EventName]
  ): void;
}
```

**Supported Events:**

```tsx theme={null}
type EIP1193EventMap = {
  accountsChanged(accounts: string[]): void;
  chainChanged(chainId: string): void;
  connect(connectInfo: ProviderConnectInfo): void;
  disconnect(error: ProviderRpcError): void;
  message(message: ProviderMessage): void;
};
```

**Requirements:**

* User must be logged in

## Standard RPC Methods

The provider also supports all standard EIP-1193 methods:

```tsx theme={null}
// Get accounts
const accounts = await provider.request({ method: "eth_accounts" });

// Request accounts
const accounts = await provider.request({ method: "eth_requestAccounts" });

// Get chain ID
const chainId = await provider.request({ method: "eth_chainId" });

// Send transaction
const txHash = await provider.request({
  method: "eth_sendTransaction",
  params: [transactionParams]
});

// Sign message
const signature = await provider.request({
  method: "personal_sign",
  params: [message, address]
});

// Switch chain
await provider.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0x2105" }] // Base mainnet
});

// And more standard RPC calls
```

## Wallet Events

The EIP-1193 provider supports standard wallet events:

```tsx theme={null}
const provider = airService.getProvider();

// Listen for account changes
provider.on("accountsChanged", (accounts) => {
  console.log("Accounts changed:", accounts);
});

// Listen for chain changes
provider.on("chainChanged", (chainId) => {
  console.log("Chain changed to:", chainId);
});

// Listen for connection events
provider.on("connect", (connectInfo) => {
  console.log("Wallet connected:", connectInfo);
});

// Listen for disconnects
provider.on("disconnect", (error) => {
  console.log("Wallet disconnected:", error);
});
```


# Session Key Management (Beta)
Source: https://docs.moca.network/airkit/usage/account/session-keys

AIR Kit extends the standard EIP-1193 provider with custom RPC methods for session key management. Use `air_grantPermissions` to create a scoped session, then `air_executeAction` to send transactions within that scope.

Session keys allow your application to execute transactions on behalf of users without requiring approval for each action. This is useful for gaming, automated strategies, or any flow where per-transaction signing creates friction.

**air\_listSessionKeyScopes**

```tsx theme={null}
const scopes = await provider.request({
  method: "air_listSessionKeyScopes",
  params: [chainId] // optional chain ID
});
// Returns: ActionPolicyInfo[]
```

**air\_grantPermissions**

```tsx theme={null}
const result = await provider.request({
  method: "air_grantPermissions",
  params: [policies] // ActionPolicyInfo[]
});
// Returns: { compressedSessionData: string, sessionOwnerPrivateKey: string, permissionIds: Hex[] }
```

**air\_revokePermission**

```tsx theme={null}
const txHash = await provider.request({
  method: "air_revokePermission",
  params: [permissionId] // Hex
});
// Returns: string (transaction hash)
```

**air\_executeAction**

```tsx theme={null}
const txHash = await provider.request({
  method: 'air_executeAction',
  params: [{
    compressedSessionData: string,
    sessionOwnerPrivateKey: string,
    call: {
      data?: Hex,
      to: Address,
      value?: bigint
    }
  }]
});
// Returns: string (transaction hash)
```


# Smart Accounts
Source: https://docs.moca.network/airkit/usage/account/smart-account



Smart accounts are the primary interface for blockchain interactions in AIR Kit. The smart account is always used when interacting with the AIR Account, while the MPC (Multi-Party Computation) wallet only acts as a signer. AIR Kit provides methods to check deployment status and deploy smart accounts when needed.

**Key Technical Details:**

* Smart accounts are **chain-specific** - deployment status and operations depend on the currently selected chain
* If a smart account is not deployed and your dApp triggers a transaction, AIR Kit will automatically bundle the smart account deployment with the transaction
* Smart account deployments are **sponsored by AIR Kit** via paymaster policy, so users don't need to pay gas fees for deployment

### isSmartAccountDeployed()

Checks whether the user's smart account has been deployed on the currently selected blockchain.

**Method Signature:**

```tsx theme={null}
public async isSmartAccountDeployed(): Promise<boolean>
```

**Returns:**

* `true` if the smart account is deployed on the current chain
* `false` if the smart account is not yet deployed on the current chain

**Requirements:**

* User must be logged in
* User must be on a supported chain

### deploySmartAccount()

Deploys the user's smart account to the currently selected blockchain. This method explicitly deploys the smart account, though deployment will also happen automatically when needed.

**Method Signature:**

```tsx theme={null}
public async deploySmartAccount(): Promise<{ txHash: string }>
```

**Returns:**

```tsx theme={null}
{
  txHash: string; // The transaction hash of the deployment transaction
}
```

**What happens during deployment:**

1. Checks if the smart account is already deployed on the current chain (throws error if already deployed)
2. Creates a deployment transaction that sends to the zero address with no value
3. Submits the transaction to the blockchain using the sponsored paymaster
4. Returns the transaction hash for tracking

**Requirements:**

* User must be logged in
* User must be on a supported chain
* Smart account must not already be deployed on the current chain

**Example:**

```tsx theme={null}
try {
  const { txHash } = await airService.deploySmartAccount();
} catch (error) {
  console.error("Smart account deployment failed:", error);
  // Handle error appropriately
}
```

**Important Notes:**

* **Deployment is sponsored by AIR Kit** - users don't pay gas fees for deployment
* The deployment transaction may take some time to be confirmed on the blockchain
* After deployment, the user will be able to perform blockchain operations on this chain
* **Automatic bundling**: If you don't explicitly deploy and trigger a transaction, deployment will be automatically bundled with the transaction

### Smart Account Deployment Flow

When working with smart accounts, you have two approaches:

**Option 1: Explicit Deployment (Recommended for better UX)**

```tsx theme={null}
const isDeployed = await airService.isSmartAccountDeployed();
if (!isDeployed) {
  const { txHash } = await airService.deploySmartAccount();
  // Wait for deployment confirmation before proceeding
}
```

**Option 2: Let AIR Kit Handle Deployment Automatically**
Simply proceed with your transaction - deployment will be bundled automatically if needed.

**Recommendation:** Use Option 1 for better user experience, as it allows you to show deployment progress and handle any deployment-specific errors separately from your main transaction logic.


# Supported Chains
Source: https://docs.moca.network/airkit/usage/account/supported-chains

AIR Kit supports multiple blockchain networks. The available chains depend on your partner configuration.

# Supported Chains

AIR Kit supports multiple blockchain networks. The available chains depend on your partner configuration.

**Mainnet Chains:**

* **Base** (Chain ID: 8453) - Default mainnet chain
* **BSC** (Chain ID: 56)
* **Gnosis** (Chain ID: 100)
* **Kaia** (Chain ID: 8217)
* **Soneium** (Chain ID: 1868)

**Testnet Chains:**

* **Base Sepolia** (Chain ID: 84532) - Default testnet chain
* **BSC Testnet** (Chain ID: 97)
* **Gnosis Chiado** (Chain ID: 10200)
* **Kairos** (Chain ID: 1001)
* **Soneium Minato** (Chain ID: 1946)
* **Sepolia** (Chain ID: 11155111)

## Chain Configuration

Chains are configured per partner through the partner configuration:

```tsx theme={null}
// Partner configuration example
{
  chainId: "8453", // Default chain (Base mainnet)
  enabledChainIds: ["8453", "56", "100"] // All supported chains of that partner
}
```

## Gas Cost Reference

Gas costs on AIR Kit operations are paid in the native token of the selected chain (or sponsored via Paymaster). The table below shows **approximate gas units** for common operations. Actual \$MOCA costs for Moca Chain credential anchoring are listed separately.

<Note>
  These benchmarks reflect Testnet measurements as of Q1 2025. Mainnet costs may differ. Enable [Gas Sponsorship (Paymaster)](/airkit/usage/account/paymaster) to abstract all gas costs from your end users.
</Note>

### Credential Operations (Moca Chain)

| Operation                                 | Estimated Gas |  Approx. Cost  |
| ----------------------------------------- | :-----------: | :------------: |
| Smart account deployment (first-time)     |   \~200,000   |  \~0.0002 MOCA |
| Credential issuance (on-chain anchor)     |    \~80,000   | \~0.00008 MOCA |
| Credential verification (ZK proof submit) |   \~120,000   | \~0.00012 MOCA |
| Credential revocation                     |    \~50,000   | \~0.00005 MOCA |
| Session key registration                  |    \~60,000   | \~0.00006 MOCA |

### EVM Chain Operations (Base, BSC, Gnosis, etc.)

| Operation                |   Estimated Gas   | Notes                       |
| ------------------------ | :---------------: | --------------------------- |
| Smart account deployment |     \~200,000     | One-time per user per chain |
| UserOperation (ERC-4337) | \~150,000–300,000 | Varies by calldata size     |
| ERC-20 transfer          |      \~65,000     | Standard token transfer     |

## Gas Sponsorship

Use the [Paymaster](/airkit/usage/account/paymaster) to cover all user-facing gas costs from a pre-funded developer wallet. This removes all on-chain funding friction from your end users — they never need to hold or manage gas tokens.


# Wagmi Connector
Source: https://docs.moca.network/airkit/usage/account/wagmi



**Wagmi** is a collection of React Hooks containing everything you need to start working with Ethereum. `@mocanetwork/airkit-connector` is a connector for the popular [wagmi](https://github.com/tmm/wagmi) library to help you integrate and interact with the `AirService`.

This package can be used to initialize a [wagmi client](https://wagmi.sh/) that will seamlessly manage the interaction (wallet connection state and configuration, such as auto-connection, connectors, and ethers providers) of your dApp.

### Initialization

```ts theme={null}
import { http, createConfig, CreateConnectorFn } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { airConnector, AirConnector, AirConnectorProperties } from "@mocanetwork/airkit-connector";

const wagmiConfig = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
  connectors: [
    airConnector({
      partnerId: {{YOUR_PARTNER_ID}},
    }),
  ],
});
```

Inside your (root) React component you can add the wagmi provider to the component tree.

```ts theme={null}
function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      ...
    </WagmiProvider>
  );
}
```

### Usage

Now you can access the connector in any component and interact with the wagmi connector. The `AirService` itself can also be accessed by casting the `Connector` to a union type with `AirConnectorProperties` or directly to `AirConnector`.

```ts theme={null}
const { connect, connectors, error } = useConnect();
const { addresses, connector } = useAccount();

const isAirWalletConnector = (connector as Connector & AirConnectorProperties)
  ?.isMocaNetwork;
const airConnector = useMemo<AirConnector | null>(() => {
  if (isAirWalletConnector) {
    return connector;
  }
  return null;
}, [connector, isAirWalletConnector]);

const service = airConnector.airService;
```


# Language & Currency Configuration
Source: https://docs.moca.network/airkit/usage/config-language

AIR Kit supports multi-language interfaces and currency display configuration. You can configure which languages are available, provide custom translations for your users, and set the display currency for your application.

## Configuration Options

```tsx theme={null}
{
  defaultLanguage?: string; // Default language (e.g., "en", "es", "fr", ...)
  authLocaleUrls?: Record<string, string>; // Auth interface language URLs
  walletLocaleUrls?: Record<string, string>; // Wallet interface language URLs
  recoveryLocaleUrls?: Record<string, string>; // Recovery interface language URLs
  credentialLocaleUrls?: Record<string, string>; // Credential interface language URLs
}
```

## Setting Up Multi-Language Support

**1. Set Default Language:**

```tsx theme={null}
defaultLanguage: "es"; // Spanish as default language
```

**2. Provide Language File URL:**
We will upload your translated language file(s) to our server and provide the URL for configuration:

```tsx theme={null}
{
  defaultLanguage: "es",
  authLocaleUrls: {
    "es": "https://static.air3.com/partner/your-partner-id/i18n-auth-es.json"
  },
  walletLocaleUrls: {
    "es": "https://static.air3.com/partner/your-partner-id/i18n-wallet-es.json"
  }
}
```

### Language File Format

Language files are JSON objects with translated strings:

```json theme={null}
{
  "login": {
    "google": {
      "button": "Continue with Google",
      "error": "Google login failed. Please try again or use another login method."
    },
    "passkey": {
      "button": "Continue with Passkey",
      "authenticating": "Authenticating..."
    }
  },
  "wallet": {
    "connect": "Connect Wallet",
    "transaction": {
      "confirm": "Confirm Transaction",
      "pending": "Transaction Pending"
    }
  },
  ...
}
```

## Currency Configuration

You can configure the display currency for your application by passing a `sessionConfig` object to the `init()` method. Both `locale` and `currency` are optional:

```tsx theme={null}
await airService.init({
  buildEnv: BUILD_ENV.SANDBOX,
  enableLogging: true,
  sessionConfig: {
    locale: "en", // Optional: Language code (e.g., "en", "es", "fr")
    currency: "USD" // Optional: Display currency: "EUR", "USD", "CNY", "KRW", "TRY"
  }
});
```

**Supported Currency Codes:**

* `EUR` - Euro
* `USD` - US Dollar
* `CNY` - Chinese Yuan
* `KRW` - South Korean Won
* `TRY` - Turkish Lira

The currency setting affects how monetary values are displayed throughout the AIR Kit interface, including wallet balances, transaction amounts, and on-ramp/swap interfaces.

### Updating Session Configuration

You can update the locale or currency after initialization using the `updateSessionConfig()` method:

```tsx theme={null}
// Update currency, locale, or both
const updatedConfig = await airService.updateSessionConfig({
  currency: "EUR", // Optional
  locale: "fr" // Optional
});
```

The method returns the complete `AirSessionConfig` object with both `locale` and `currency` values.

## How Language Selection Works

1. **Default Language**: Your `defaultLanguage` setting determines the interface language
2. **Language File**: The system loads the language file from the provided URL
3. **English Fallback**: If a translation key is missing, it falls back to English
4. **No Language Switching**: Currently, the language is set once during initialization and cannot be detected by the browser or changed by the user
5. **Session Configuration**: You can set the locale and currency programmatically via `sessionConfig` when calling `init()`, or update them later using `updateSessionConfig()`. Both `locale` and `currency` are optional within `sessionConfig`


# Login Configuration
Source: https://docs.moca.network/airkit/usage/config-login

The login screen can be customized through the partner config properties that are configured on the backend. These settings control which login methods are available and how the login interface appears to users.

## Login Methods (`loginMethods`)

Control which authentication methods are available on the login screen:

```tsx theme={null}
type LoginMethod =
  | "passwordless" // Email-based passwordless login
  | "google" // Google OAuth login
  | "wallet"; // Wallet connection login
```

**Available Options:**

* **`passwordless`**: Enables email-based passwordless authentication
* **`google`**: Enables Google OAuth login integration
* **`wallet`**: Enables wallet-based authentication

**Example Configuration:**

```tsx theme={null}
// Enable only email login
loginMethods: ["passwordless", "google"];

// Enable all login methods
loginMethods: ["passwordless", "google", "wallet"];
```

**Note:** The order in the array determines the display order in the UI (top to bottom).

### Wallet Login Methods (`walletLoginMethods`)

When `wallet` is included in `loginMethods`, specify which wallet providers are available:

```tsx theme={null}
type LoginWalletId =
  | "bybit" // Bybit Wallet
  | "coinbase" // Coinbase Wallet
  | "crypto.com" // Crypto.com DeFi Wallet
  | "metamask" // MetaMask
  | "okx" // OKX Wallet
  | "phantom" // Phantom Wallet
  | "rabby" // Rabby Wallet
  | "rainbow" // Rainbow Wallet
  | "trust" // Trust Wallet
  | "walletConnect"; // WalletConnect
```

**Example Configuration:**

```tsx theme={null}
// Enable wallet login with specific providers
loginMethods: ["wallet"],
walletLoginMethods: ["metamask", "coinbase", "walletConnect"]

// Default wallet providers if not specified
walletLoginMethods: undefined;
// ["metamask", "phantom", "okx", "coinbase", "rabby", "walletConnect"]
```

<Info>
  The order in the array determines the display order in the UI (left to right, top to bottom). Since AIR accounts are shared across partners, consider including email-based login to avoid forcing users to link wallets to existing accounts.
</Info>

### Style Configuration (`style`)

Customize the visual appearance of the login interface:

```tsx theme={null}
type PartnerConfigStyle = {
  passwordlessButtonVariant?: "inline" | "standalone";
  airLogoTheme?: "default" | "reverse" | "dark_only" | "light_only";
};
```

**Style Options:**

* **`passwordlessButtonVariant`**: Controls how the passwordless login button appears
  * `"inline"`: Button appears inline with other elements
  * `"standalone"`: Button appears as a standalone element below the input
* **`airLogoTheme`**: Controls the AIR logo appearance
  * `"default"`: Standard logo theme
  * `"reverse"`: Reversed color scheme
  * `"dark_only"`: Dark theme only
  * `"light_only"`: Light theme only

**Example Configuration:**

```tsx theme={null}
style: {
  passwordlessButtonVariant: "standalone",
  airLogoTheme: "dark_only",
}
```


# Theming Configurations
Source: https://docs.moca.network/airkit/usage/config-theming

You can customize the visual appearance of AIR Kit interfaces by providing a custom CSS files that overrides the default styling.

### Customizable Elements

| Element Category      | CSS Variables                                                                             | Description                                          |
| --------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Text Colors**       | `--air-text-primary-color` `--air-text-secondary-color` `--air-text-placeholder-color`    | Primary text, secondary text, input placeholders     |
| **Button Colors**     | `--air-button-primary-color` `--air-button-secondary-color` `--air-button-outlined-color` | Primary buttons, secondary buttons, outlined buttons |
| **Background Colors** | `--air-background-color` `--air-surface-color` `--air-container-primary-color`            | Main background, surface areas, containers           |
| **Border Colors**     | `--air-border-color` `--air-border-focus-color`                                           | Default borders, focused input borders               |
| **Status Colors**     | `--air-status-success-color` `--air-status-error-color` `--air-status-pending-color`      | Success, error, pending states                       |
| **Icon Colors**       | `--air-icon-primary-color` `--air-icon-secondary-color` `--air-icon-hover-color`          | Primary icons, secondary icons, hover states         |
| **Logo**              | `--air-logo`                                                                              | Custom logo URL                                      |
| **Font Family**       | `--air-font-family`                                                                       | Custom font family (requires font import)            |

### Example Partner Theme:

Our own Mocaverse theme for mocaverse.xyz

```css theme={null}
:root {
  --mocaverse-air-logo: url(https://static.air3.com/assets/mocaverse.svg);

  --mocaverse-air-text-primary-color: #ffffff;
  --mocaverse-air-text-secondary-color: #b0b0b0;
  --mocaverse-air-text-placeholder-color: #767676;
  --mocaverse-air-text-disabled-color: #ffffff40;
  --mocaverse-air-text-inverse-color: #000000;
  --mocaverse-air-text-on-color: #ffffff;

  --mocaverse-air-button-primary-color: #ff49a0;
  --mocaverse-air-button-primary-hover-color: #000000;
  --mocaverse-air-button-secondary-color: #2450ee;
  --mocaverse-air-button-secondary-hover-color: #ffffff;
  --mocaverse-air-button-disabled-color: #3a3a3a;
  --mocaverse-air-button-outlined-color: #ffffff;
  --mocaverse-air-button-outlined-hover-color: #ffffff14;
  --mocaverse-air-button-outlined-secondary-color: #4e4150;
  --mocaverse-air-button-outlined-secondary-hover-color: #ffffff14;

  --mocaverse-air-border-color: #ffffff40;
  --mocaverse-air-border-focus-color: #ffffff;

  --mocaverse-air-link-color: #3c8cff;
  --mocaverse-air-text-button-color: #ef6aba;

  --mocaverse-air-icon-primary-color: #ffffff;
  --mocaverse-air-icon-secondary-color: #b0b0b0;
  --mocaverse-air-icon-hover-color: #000000;
  --mocaverse-air-icon-disabled-color: #00000040;

  --mocaverse-air-status-success-color: #74ffcd;
  --mocaverse-air-status-error-color: #ff49a0;
  --mocaverse-air-status-pending-color: #f99247;

  --mocaverse-air-surface-color: #110a17;
  --mocaverse-air-surface-dim-color: #343a3b;

  --mocaverse-air-overlay-color: #00000080;

  --mocaverse-air-container-primary-color: #1d1d1d;
  --mocaverse-air-container-secondary-color: #2f2f2f;

  --mocaverse-air-decorative-color: #ef6aba;
  --mocaverse-air-secondary-5-color: #ffffff;

  --mocaverse-air-background-color: linear-gradient(90deg, #202734 0.5%, #3c253c 100.5%);
}
```

### Testing Your Theme

The best way to test your custom theme is to use browser developer tools to manipulate CSS custom properties in real-time:

1. **Open Developer Tools**: Press F12 or right-click → Inspect
2. **Navigate to Elements Tab**: Find the `<html>` element
3. **Access CSS Variables**: In the Styles panel, look for `:root` or `html[theme='your-theme']`
4. **Modify Properties**: Click on any CSS custom property value to edit it
5. **See Changes Instantly**: Changes apply immediately without page refresh

This allows you to:

* Test different color combinations quickly
* Verify contrast ratios
* Ensure your theme works across all screens
* Fine-tune values before finalizing your CSS file

### Best Practices

* **Accessibility**: Ensure sufficient contrast ratios for text and backgrounds. Adjust our AIR logo via config value if necessary
* **Dark/Light Mode**: Consider both light and dark theme variations
* **Font Testing**: Test custom fonts across different devices and browsers
* **Real-time Testing**: Use browser dev tools to iterate quickly on your theme


# CAK Issuer Guide
Source: https://docs.moca.network/airkit/usage/credential/cak-issuer-guide

Enable CAK encryption, integrate the Issuance SDK for key generation, encrypt user data, and implement the callback endpoint.

This guide walks through every step an Issuer needs to support the Compliance Access Key (CAK) framework: enabling CAK in the Dashboard, integrating with the Issuance SDK to obtain the public key, encrypting sensitive user data, and implementing the callback endpoint that receives authorization notifications.

<Info>
  Before starting, make sure you understand the [CAK lifecycle overview](/airkit/usage/credential/cak-overview).
</Info>

***

## Issuer responsibilities summary

| Responsibility                   | Description                                                             |
| -------------------------------- | ----------------------------------------------------------------------- |
| CAK feature configuration        | Enable CAK for pricing schemas and issuance programs in the Dashboard   |
| Callback URL setup               | Configure a global HTTPS callback endpoint                              |
| Data encryption integration      | Use the Issuance SDK to obtain the CAK public key and encrypt user data |
| Callback endpoint implementation | Implement an HTTPS endpoint that handles authorization notifications    |
| Callback business routing        | Route callback requests by `schemaId` to your business logic            |

***

## Step 1: Dashboard configuration

### Enable CAK on a pricing schema

In the Developer Dashboard, navigate to your pricing schema configuration. Enabling CAK here is the top-level switch that determines whether CAK-encrypted credentials can be created under this pricing model.

### Enable CAK on an issuance program

When creating or editing an issuance program, enable the CAK feature. When enabled:

* The Issuance SDK generates a CAK key pair during credential issuance
* The SDK returns the CAK public key to your backend system
* Your system is expected to encrypt the user's raw sensitive data with this key

When disabled, the issuance flow operates identically to standard credential issuance.

### Configure a global callback URL

Set a global HTTPS callback URL that receives notifications whenever a Verifier is authorized to access data from credentials you have issued.

```bash theme={null}
POST /issuer/modify

{
  "callbackUrl": "https://your-domain.com/api/cak/callback"
}
```

This is a single, global endpoint for all your issuance programs. Your implementation must route incoming requests to the correct business logic based on the `schemaId` in the callback payload.

<Warning>
  The callback URL must be highly available. The platform includes retry logic, but prolonged downtime means you miss authorization notifications.
</Warning>

***

## Step 2: Issuance SDK integration

When CAK is enabled for an issuance program, the `issueCredential()` call returns a `cakPublicKey` in its response.

```jsx theme={null}
const result = await airService.issueCredential({
  authToken,          // Partner JWT with scope=issue
  issuerDid,          // Your Issuer DID
  credentialId,       // Issuance program ID
  credentialSubject,  // User's credential claims
  curve: "secp256r1", // Optional: elliptic curve (default: secp256r1)
});

const { cakPublicKey } = result;
```

| Parameter           | Type                         | Required | Description                                                        |
| ------------------- | ---------------------------- | -------- | ------------------------------------------------------------------ |
| `authToken`         | `string`                     | Yes      | Partner JWT with `scope=issue`                                     |
| `issuerDid`         | `string`                     | Yes      | Your Issuer DID                                                    |
| `credentialId`      | `string`                     | Yes      | Issuance program ID                                                |
| `credentialSubject` | `Record<string, unknown>`    | Yes      | Credential claims and attributes                                   |
| `curve`             | `"secp256r1" \| "secp256k1"` | No       | Elliptic curve for key generation. Defaults to `secp256r1` (P-256) |

**Response:**

| Field          | Type     | Description                                                                                                          |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `cakPublicKey` | `string` | CAK public key for encrypting the user's sensitive data. Only returned when CAK is enabled for the issuance program. |

<Note>
  The public key is deterministically derived from the \[User - Issuer - Schema] composite identifier. The same key is returned for the same combination, so you can retrieve it without re-issuing the credential.
</Note>

***

## Step 3: Encrypt and store user data

After receiving the `cakPublicKey`, encrypt the user's raw sensitive data before storing it.

### What to encrypt

Encrypt any raw PII or biometric data associated with the credential:

* Identity document images (ID cards, passports)
* Facial biometric photos
* Full names, dates of birth, document numbers
* Any other data that verifiers may need for compliance review

### Encryption scheme

Use ECIES (Elliptic Curve Integrated Encryption Scheme) with the CAK public key:

| Property | Value                          |
| -------- | ------------------------------ |
| Scheme   | ECIES                          |
| Curve    | SECP256R1 (P-256) by default   |
| Input    | CAK public key + raw user data |
| Output   | Encrypted ciphertext           |

### Storage

Store the encrypted ciphertext in the designated storage system (dStorage on Moca Chain). The encrypted data cannot be read by anyone — including your own systems — without the corresponding CAK private key, which is only generated when a Verifier obtains user consent during verification.

***

## Step 4: Implement the callback endpoint

When a user authorizes a Verifier to access their data, the platform sends an HTTPS POST to your configured callback URL.

### Callback payload

The payload includes fields that identify who authorized whom, for which credential schema:

| Field         | Description                                 |
| ------------- | ------------------------------------------- |
| `userId`      | The user who granted authorization          |
| `verifierDid` | The DID of the Verifier that was authorized |
| `schemaId`    | The credential schema involved              |

<Warning>
  The callback serves as an authorization event notification and audit signal only. It does not contain encrypted data, cryptographic keys, or any information that enables data decryption.
</Warning>

### Implementation requirements

Your callback endpoint must:

1. **Verify the request signature** — Validate that the callback originates from the AIR Credential platform
2. **Route by schemaId** — Direct the callback to the correct business logic based on the credential schema
3. **Return HTTP 2XX** — Acknowledge receipt so the platform marks the callback as delivered
4. **Log the event** — Record the authorization event for your own audit trail

### Callback record lifecycle

The platform manages callback records through these states:

| Status     | Code | Meaning                                                               |
| ---------- | ---- | --------------------------------------------------------------------- |
| `NOT_SEND` | -1   | Initial state — authorization granted but callback not yet dispatched |
| `PENDING`  | 0    | Callback dispatched, awaiting acknowledgment                          |
| Delivered  | —    | Your endpoint returned HTTP 2XX                                       |

The platform retries failed callbacks automatically. Ensure your endpoint is idempotent to handle duplicate deliveries.

***

## Best practices

<AccordionGroup>
  <Accordion title="Encrypt only what verifiers need">
    Only include data that verifiers will legitimately need for their compliance process. Minimize the scope of encrypted data to reduce exposure.
  </Accordion>

  <Accordion title="Use secp256r1 unless you have a specific reason not to">
    The P-256 curve is the default and recommended option. Only switch to secp256k1 if your downstream systems specifically require it.
  </Accordion>

  <Accordion title="Make your callback endpoint highly available">
    The callback URL is your real-time notification channel for all CAK authorization events. Downtime means missed notifications, which can delay your audit and risk monitoring.
  </Accordion>

  <Accordion title="Implement idempotent callback handling">
    The platform retries failed callbacks. Your endpoint should handle duplicate deliveries gracefully — use the combination of userId, verifierDid, and schemaId as a deduplication key.
  </Accordion>
</AccordionGroup>

***

## Related pages

* [CAK Overview](/airkit/usage/credential/cak-overview) — Architecture and lifecycle
* [CAK Verifier Guide](/airkit/usage/credential/cak-verifier-guide) — Verifier-side integration
* [Issuing Credentials](/airkit/usage/credential/issuing-credentials) — Standard issuance SDK reference
* [Compliance & Privacy FAQ](/solutions/compliance-faq) — GDPR, CCPA, and data handling questions


# Compliance Access Key (CAK)
Source: https://docs.moca.network/airkit/usage/credential/cak-overview

Optional consent-gated encryption framework for regulated data access in the AIR Credential lifecycle.

The Compliance Access Key (CAK) is an optional encryption framework that enables regulated data usage without platform-level custody, key escrow, or implicit trust assumptions. When enabled, sensitive user data is encrypted during credential issuance and can only be decrypted by a Verifier who has obtained explicit user consent.

<Info>
  CAK is optional. If your credentials do not contain raw PII or biometric data, or if verifiers only need zero-knowledge proof results, the standard AIR Kit flow is sufficient.
</Info>

***

## When to use CAK

| Scenario                                                              | CAK needed? |
| --------------------------------------------------------------------- | ----------- |
| Credential contains raw PII or biometric data that verifiers may need | Yes         |
| Multiple verifiers require access to underlying identity data         | Yes         |
| Regulatory auditability of data access is required                    | Yes         |
| Credential is used purely for ZK-based attribute proofs               | No          |
| No verifier ever requires access to plaintext data                    | No          |

***

## Three-phase lifecycle

CAK operates across the entire credential lifecycle: configuration, issuance, and verification.

```mermaid theme={null}
sequenceDiagram
    participant Dashboard as Developer Dashboard
    participant Issuer as Issuer Backend
    participant SDK_I as Issuance SDK
    participant User as User (Holder)
    participant dStorage as dStorage
    participant SDK_V as Verification SDK
    participant Verifier as Verifier Backend
    participant Platform as AIR Platform

    Note over Dashboard: Phase 1 — Configuration
    Dashboard->>Issuer: Enable CAK on pricing schema & issuance program
    Dashboard->>Issuer: Configure callback URL
    Dashboard->>Verifier: Create verification program (require CAK)

    Note over SDK_I,Issuer: Phase 2 — Issuance
    SDK_I->>SDK_I: Generate CAK key pair (signed by identity wallet)
    SDK_I->>Issuer: Return CAK public key
    Issuer->>Issuer: Encrypt raw user data with public key
    Issuer->>dStorage: Store encrypted data

    Note over SDK_V,Verifier: Phase 3 — Verification & Authorization
    Verifier->>Platform: POST /verifier/verify/initialize
    SDK_V->>User: Display authorization statement
    User->>SDK_V: Grant consent
    SDK_V->>SDK_V: Generate CAK private key (signed by identity wallet)
    SDK_V->>Verifier: Return CAK private key
    Platform->>Platform: Update callback record (NOT_SEND → PENDING)
    Platform->>Issuer: HTTPS callback notification (userId, verifierDid, schemaId)
    Issuer->>Platform: HTTP 2XX acknowledgment
    Verifier->>Issuer: Request semi-decrypted data
    Issuer->>dStorage: Fetch & partially decrypt with managed key
    Issuer->>Verifier: Return semi-decrypted package (signed, time-limited URL)
    Verifier->>Verifier: Final decryption with CAK private key → plaintext data
```

***

## Phase 1: Dashboard configuration

Before any credentials are issued, administrators configure the CAK rules in the Developer Dashboard.

### Issuer setup

1. **Enable CAK on a Pricing Schema** — This is the top-level switch. Only pricing schemas with CAK enabled can produce CAK-encrypted credentials.
2. **Enable CAK on an Issuance Program** — When enabled, the Issuance SDK will generate a CAK key pair during issuance and return the public key to your system for encryption.
3. **Configure a Global Callback URL** — Set an HTTPS endpoint via `POST /issuer/modify` (pass `callbackUrl`). This endpoint receives authorization notifications whenever a Verifier is granted access to your users' data.

### Verifier setup

1. **Require CAK for a Verification Program** — When enabled, only CAK-encrypted credentials are accepted and the user consent flow is mandatory.
2. **Select Issuers** — If your verification program requires CAK, the system only shows Issuers that have enabled the CAK feature.

<Tip>
  For step-by-step configuration instructions, see the [Issuer guide](/airkit/usage/credential/cak-issuer-guide) and [Verifier guide](/airkit/usage/credential/cak-verifier-guide).
</Tip>

***

## Phase 2: Credential issuance

When CAK is enabled for an issuance program, the `issueCredential()` SDK call includes additional encryption steps.

| Step | Party        | Action                                                                                      |
| ---- | ------------ | ------------------------------------------------------------------------------------------- |
| 1    | Issuance SDK | Generates a temporary CAK key pair locally by signing with the user's identity wallet       |
| 2    | Issuance SDK | Returns the CAK public key to the Issuer's backend via callback                             |
| 3    | Issuer       | Encrypts the user's raw sensitive data (ID photo, name, biometrics) with the CAK public key |
| 4    | Issuer       | Stores the encrypted ciphertext in dStorage                                                 |

The `issueCredential()` response includes a `cakPublicKey` field when CAK is enabled. See [Issuing Credentials](/airkit/usage/credential/issuing-credentials) for the SDK reference.

***

## Phase 3: Verification and authorization

When a user presents a CAK-encrypted credential to a Verifier, the process includes a consent step and a two-stage decryption.

| Step | Party            | Action                                                                        |
| ---- | ---------------- | ----------------------------------------------------------------------------- |
| 1    | Verifier         | Calls `POST /verifier/verify/initialize` to start the verification flow       |
| 2    | Verification SDK | Detects CAK requirement from program configuration                            |
| 3    | Verification SDK | Displays a clear authorization statement to the user                          |
| 4    | User             | Grants or denies consent                                                      |
| 5    | Verification SDK | On consent, generates the CAK private key locally via identity wallet signing |
| 6    | Verification SDK | Returns the private key to the Verifier backend via callback                  |
| 7    | Platform         | Updates callback record status and sends HTTPS notification to Issuer         |
| 8    | Verifier         | Requests semi-decrypted data from the Issuer (zkMe)                           |
| 9    | Issuer (zkMe)    | Partially decrypts with managed key, returns semi-decrypted package           |
| 10   | Verifier         | Performs final decryption with CAK private key to obtain plaintext data       |

The `verifyCredential()` response includes a `cakPrivateKey` field when the result is `"Compliant"` and CAK is enabled. See [Verifying Credentials](/airkit/usage/credential/verify) for the SDK reference.

<Warning>
  The CAK private key must be used in-memory only. Never persist it to disk, database, or logs.
</Warning>

***

## Platform responsibilities

The AIR Credential platform provides the following CAK capabilities:

| Responsibility        | Description                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| **SDKs**              | Issuance and Verification SDKs include CAK key generation, consent UI, and callback handling          |
| **Key derivation**    | Deterministic CAK key pairs derived within SDKs via identity wallet signing (EIP-712 structured data) |
| **Authorization UI**  | Standard, unified user consent interface in the Verification SDK                                      |
| **Callback dispatch** | Reliable HTTPS notifications to the Issuer's callback URL with retry logic                            |
| **Record management** | Authorization records and callback statuses maintained for full process traceability                  |

***

## Cryptographic details

| Property            | Value                                                                  |
| ------------------- | ---------------------------------------------------------------------- |
| Encryption scheme   | ECIES (Elliptic Curve Integrated Encryption Scheme)                    |
| Default curve       | SECP256R1 (P-256)                                                      |
| Alternative curve   | SECP256K1                                                              |
| Key derivation      | Deterministic, based on \[User - Issuer - Schema] composite identifier |
| Key pair generation | Local, via identity wallet signing (EIP-712)                           |

***

## Next steps

<CardGroup>
  <Card title="Issuer integration" icon="file-certificate" href="/airkit/usage/credential/cak-issuer-guide">
    Dashboard configuration, SDK integration, encryption workflow, and callback endpoint implementation.
  </Card>

  <Card title="Verifier integration" icon="magnifying-glass" href="/airkit/usage/credential/cak-verifier-guide">
    Verification setup, user consent flow, decryption workflow, and security best practices.
  </Card>
</CardGroup>


# CAK Verifier Guide
Source: https://docs.moca.network/airkit/usage/credential/cak-verifier-guide

Configure CAK verification programs, handle user consent, receive the private key, and decrypt user data securely.

This guide covers everything a Verifier needs to integrate with the Compliance Access Key (CAK) framework: configuring a verification program that requires CAK, handling the user consent flow, receiving the CAK private key, and performing secure decryption of user data.

<Info>
  Before starting, make sure you understand the [CAK lifecycle overview](/airkit/usage/credential/cak-overview).
</Info>

***

## Verifier responsibilities summary

| Responsibility                | Description                                                                        |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| CAK requirement configuration | Enable CAK requirement for verification programs in the Dashboard                  |
| Verification initialization   | Call the platform's initialization endpoint at the start of each verification flow |
| Private key secure handling   | Receive the CAK private key from the SDK and use it in-memory only                 |
| Data decryption integration   | Decrypt the semi-decrypted data package using the CAK private key                  |
| Data handling compliance      | Handle, store, and destroy decrypted data per applicable regulations               |

***

## Step 1: Dashboard configuration

### Require CAK for a verification program

In the Developer Dashboard, create or edit a verification program and enable the CAK requirement.

When CAK is required:

* Only CAK-encrypted credentials are accepted for verification
* The user consent flow is mandatory — the Verification SDK displays an authorization statement
* Only Issuers that have enabled CAK are available as partners when configuring the program

When CAK is not required:

* Both CAK-encrypted and standard credentials are accepted
* The consent flow is not triggered, even for CAK-encrypted credentials

### Select Issuers

If your verification program requires CAK, the system only shows Issuers that have the CAK feature enabled. Select the Issuers whose credentials you want to verify.

***

## Step 2: Initialize verification

At the start of each verification flow, your backend must call the platform's initialization endpoint. This creates a callback record that tracks the authorization lifecycle.

```bash theme={null}
POST /verifier/verify/initialize

{
  "issuerDid": "did:air:id:..."
}
```

Pass the `issuerDid` of the Issuer whose credential is being verified. The platform creates a callback record with an initial `NOT_SEND` (-1) status.

***

## Step 3: User consent and private key

The Verification SDK handles the consent flow automatically when it detects that the verification program requires CAK.

### What happens

1. The SDK reads the verification program configuration and detects the CAK requirement
2. The SDK displays a clear authorization statement to the user, requesting consent to share their encrypted data with your system
3. The user makes a manual choice: **Agree** or **Deny**

### On user consent

When the user grants consent:

1. The SDK generates the corresponding CAK private key locally by signing with the user's identity wallet
2. The SDK returns the private key to your backend via the verification callback
3. The platform updates the callback record from `NOT_SEND` (-1) to `PENDING` (0) and sends a notification to the Issuer

### On user denial

When the user denies consent:

* The verification process is aborted
* No private key is generated or returned
* The user's encrypted data remains inaccessible
* The user may be unable to complete their business with your service

### SDK integration

Call `verifyCredential()` as usual. When CAK is enabled and the verification is successful, the response includes a `cakPrivateKey` field.

```jsx theme={null}
const result = await airService.verifyCredential({
  authToken,    // Partner JWT with scope=verify
  programId,    // Verification program ID
  redirectUrl,  // Optional: redirect if user lacks the credential
});

if (result.status === "Compliant") {
  const { cakPrivateKey, zkProofs, transactionHash } = result;
  // Use cakPrivateKey to decrypt user data
}
```

**Compliant response fields:**

| Field             | Type                     | Description                                                                                |
| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
| `status`          | `"Compliant"`            | Credential is valid and meets all verification requirements                                |
| `zkProofs`        | `Record<string, string>` | Zero-knowledge proofs generated for the verification                                       |
| `transactionHash` | `string`                 | On-chain transaction hash of the verification                                              |
| `cakPrivateKey`   | `string`                 | CAK private key for decrypting the user's encrypted data. Only present when CAK is enabled |

<Warning>
  The `cakPrivateKey` is only returned when **all** of these conditions are met: (1) the verification status is `"Compliant"`, (2) CAK was enabled for the issuance program, and (3) your verification program requires CAK.
</Warning>

***

## Step 4: Decrypt user data

After receiving the CAK private key, you can decrypt the user's sensitive data through a two-stage process.

### Stage 1: Request semi-decrypted data

Call the Issuer's (zkMe) Semi-Decrypted Data API to request the user's encrypted data. This is not a direct download from dStorage — the Issuer partially decrypts the data using their managed key first.

The Issuer:

1. Validates your request (identity, authorization relationship)
2. Fetches the encrypted data from dStorage
3. Performs initial decryption with their managed key to produce a semi-decrypted data package
4. Returns the package via a signed, time-limited download URL
5. Logs the request in the audit trail

### Stage 2: Final decryption with CAK private key

Use the CAK private key to decrypt the semi-decrypted data package. This produces the user's original raw information:

* Full name, date of birth, document numbers
* Identity document images (ID cards, passports)
* Facial biometric photos
* Other structured identity fields

<Note>
  The two-stage decryption ensures that neither the Issuer alone nor the Verifier alone can access the plaintext data. Both must participate, and both stages require prior user consent.
</Note>

***

## Security best practices

<AccordionGroup>
  <Accordion title="Never persist the CAK private key">
    The CAK private key must be used exclusively in-memory. Never write it to disk, database, logs, or any persistent storage. Discard it immediately after decryption is complete.
  </Accordion>

  <Accordion title="Minimize data retention">
    After using the decrypted data for your compliance process (account opening, eligibility check, etc.), destroy it according to your data retention policy. Only keep what your regulatory obligations specifically require.
  </Accordion>

  <Accordion title="Handle decrypted data per GDPR and applicable laws">
    The decrypted data is raw PII. Treat it with the highest level of data protection. Implement access controls, encryption at rest for any required storage, and data subject rights handling (access, deletion).
  </Accordion>

  <Accordion title="Implement secure transport">
    All communication between your systems and the AIR Credential platform must use HTTPS/TLS. The semi-decrypted data download URL is time-limited and pre-signed — use it immediately.
  </Accordion>

  <Accordion title="Audit all data access">
    Log every instance of decryption, including the user ID, timestamp, purpose, and personnel involved. This audit trail is critical for regulatory compliance.
  </Accordion>
</AccordionGroup>

***

## Verification flow diagram

```mermaid theme={null}
sequenceDiagram
    participant Verifier as Verifier Backend
    participant Platform as AIR Platform
    participant SDK as Verification SDK
    participant User as User (Holder)
    participant Issuer as Issuer (zkMe)
    participant dStorage as dStorage

    Verifier->>Platform: POST /verifier/verify/initialize (issuerDid)
    Platform-->>Verifier: Callback record created (NOT_SEND)

    SDK->>SDK: Detect CAK requirement from program config
    SDK->>User: Display authorization statement
    User->>SDK: Grant consent

    SDK->>SDK: Generate CAK private key (identity wallet signing)
    SDK->>Verifier: Return cakPrivateKey in verification result

    Platform->>Platform: Update callback record (PENDING)
    Platform->>Issuer: HTTPS callback (userId, verifierDid, schemaId)
    Issuer-->>Platform: HTTP 2XX acknowledgment

    Verifier->>Issuer: Request semi-decrypted data
    Issuer->>dStorage: Fetch encrypted data
    Issuer->>Issuer: Partial decryption with managed key
    Issuer-->>Verifier: Semi-decrypted package (time-limited URL)

    Verifier->>Verifier: Final decryption with CAK private key
    Note over Verifier: Plaintext data available for compliance process
```

***

## Related pages

* [CAK Overview](/airkit/usage/credential/cak-overview) — Architecture and lifecycle
* [CAK Issuer Guide](/airkit/usage/credential/cak-issuer-guide) — Issuer-side integration
* [Verifying Credentials](/airkit/usage/credential/verify) — Standard verification SDK reference
* [Compliance & Privacy FAQ](/solutions/compliance-faq) — GDPR, CCPA, and data handling questions


# Credentials Overview
Source: https://docs.moca.network/airkit/usage/credential/credentials-flow

Understand issuer, holder, and verifier roles in the AIR Credential lifecycle.

## What are AIR Credentials?

**AIR Credential** is a universal, decentralized verifiable credential system designed for seamless use across digital applications and networks. Built on Moca Chain’s identity-focused infrastructure, it leverages zero-knowledge proof (ZKP) technology to enable users to prove claims (such as age, qualifications, or affiliations) without exposing their underlying private data. Each issued credential is securely encrypted, controlled by the user, allowing true self-sovereign identity and cross-ecosystem interoperability.

## Who’s Who: Issuer, Holder, Verifier

|                 | **Issuer**                                                                                  | **Holder**                                                                                                        | **Verifier**                                                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Role**        | The entity that creates and vouches for the verifiable credential.                          | The individual or entity that receives and stores the credential in a digital wallet or account.                  | The party that requests and checks for proof of specific claims or attributes.                                                                                        |
| **Key Actions** | Issues and signs credentials                                                                | Stores and presents credentials                                                                                   | Requests and verifies proofs                                                                                                                                          |
| **Details**     | The issuer structures the data, digitally signs it, and sends the credential to the holder. | The holder controls how their credentials are shared, enabling privacy-first, self-sovereign identity management. | Instead of accessing the full credential, the verifier receives cryptographically-secure proof from the holder—often using zero-knowledge proofs for maximal privacy. |
| **Examples**    | Universities, governments, protocols, DAOs, gaming platforms, community managers            | Students, citizens, gamers, employees, community members                                                          | Employers, service providers, event organizers, online platforms, access-controlled communities                                                                       |

## Issuer Process

1. Set up a Partner Account in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a>.
2. Configure General Partner settings.
3. Obtain an Issuer DID.
4. Top up Fee Wallet.
5. Create or search for relevant Credential Schemas.
6. Define Issuance Program(s).
7. Integrate AIR Kit to your app.
8. Issue Credentials for your users.

## Verifier Process

1. Set up a Partner Account in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a>.
2. Configure General Partner settings.
3. Obtain a Verifier DID.
4. Top up Fee Wallet.
5. Search for relevant Credential Schemas and Issuers.
6. Create Verifier Program(s).
7. Integrate AIR Kit to your app.
8. Verify Credentials for your users.


# Issue on Behalf
Source: https://docs.moca.network/airkit/usage/credential/issue-on-behalf

Standard AIR Kit credential issuance requires the **user to be present** — they initiate the flow, authenticate, and receive the credential through an active session.

**Issue on Behalf** flips this. Your **backend server** issues a credential directly to a user's AIR Account without requiring any action from the user at the time of issuance. The user doesn't need to be in a session, open a wallet, or interact with any UI.

This enables **zero-friction, invisible credential issuance** for use cases like:

* Issuing a KYC credential the moment a user passes identity verification
* Issuing an attendance credential when a venue scan detects a fan's check-in
* Issuing a subscriber tier credential at the end of each billing cycle
* Issuing a loyalty credential triggered by a purchase event

The user simply benefits from the credential next time they interact with a verifier.

<Warning>
  **Feature Activation Required**

  Issue on Behalf must be enabled for your partner account before use. Enable it in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> (Accounts → General).
</Warning>

## When to Use It vs. Standard Issuance

| Scenario                                    | Use Standard Issuance | Use Issue on Behalf |
| ------------------------------------------- | --------------------- | ------------------- |
| User initiates credential claim themselves  | Yes                   | No                  |
| Credential is triggered by a backend event  | No                    | Yes                 |
| User is actively logged in at issuance time | Yes                   | Either              |
| User is offline / not in session            | No                    | Yes                 |
| Zero-friction UX is a requirement           | No                    | Yes                 |
| KYC completion triggers credential          | No                    | Yes                 |
| Attendance / purchase / billing events      | No                    | Yes                 |
| User explicitly clicks "Claim Credential"   | Yes                   | No                  |

**Rule of thumb:** If the credential is triggered by something the user *did* (not something the user *initiated in-app*), use Issue on Behalf.

## How It Works

1. A backend event fires — KYC passed, purchase confirmed, check-in scanned.
2. Your server retrieves the target user's email and signs a Partner JWT.
3. Your server calls the Issue on Behalf API endpoint.
4. AIR Kit verifies the JWT and queues the credential for on-chain processing.
5. Issuance is **asynchronous** — your server polls a status endpoint until the credential is confirmed on-chain.
6. The user presents the credential later at any verifier; no action needed at issuance time.

## Prerequisites

Before using Issue on Behalf you need:

1. **Feature activation** — Enable Issue on Behalf for your partner account in the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> (Accounts → General).
2. **Partner ID and Issuer DID** — From the Developer Dashboard (Accounts → General).
3. **Issuance program** — A published credential program in the dashboard (Issuer → Programs).
4. **JWKS endpoint** — A public URL serving your RSA public key for JWT verification. See [Partner Authentication](/airkit/usage/partner-authentication).
5. **User email** — The email address of the AIR Account receiving the credential.

## Auth

Issue on Behalf authenticates via a **Partner JWT** attached to each request. The JWT must include the target user's email as a signed claim. For full setup, key generation, and examples see [Partner Authentication](/airkit/usage/partner-authentication).

## Next Steps

* [Issue on Behalf API & Examples](/airkit/usage/credential/issue-on-behalf-api)
* [Partner Authentication](/airkit/usage/partner-authentication)
* [Issuing Credentials (SDK)](/airkit/usage/credential/issuing-credentials)


# Issue on Behalf API & Examples
Source: https://docs.moca.network/airkit/usage/credential/issue-on-behalf-api

Endpoint reference, polling flow, duplicate handling, and troubleshooting.

Read concepts first: [Issue on Behalf](/airkit/usage/credential/issue-on-behalf)

For JWT/JWKS setup and signing examples, see [Partner Authentication](/airkit/usage/partner-authentication).

## Base URLs

| Environment | Base URL                               |
| ----------- | -------------------------------------- |
| Sandbox     | `https://api.sandbox.mocachain.org/v1` |
| Production  | `https://api.mocachain.org/v1`         |

## 1) Issue credential

Submit credential issuance for a target user.

```
POST /v1/credentials/issue-on-behalf
```

### Request headers

| Header           | Required    | Value                       |
| ---------------- | ----------- | --------------------------- |
| `Content-Type`   | Yes         | `application/json`          |
| `x-partner-auth` | Yes         | Signed Partner JWT          |
| `user-agent`     | Recommended | Identifiable service string |

### Request body

```json theme={null}
{
  "issuerDid": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "credentialId": "c21s70g0i54sn0023172Cv",
  "credentialSubject": {
    "age": 25,
    "location": "United States",
    "isMember": true
  },
  "onDuplicate": "revoke"
}
```

| Field               | Type   | Required | Description                                                                                           |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `issuerDid`         | string | Yes      | Your Issuer DID from Developer Dashboard                                                              |
| `credentialId`      | string | Yes      | Issuance Program ID                                                                                   |
| `credentialSubject` | object | Yes      | Credential data matching your schema                                                                  |
| `onDuplicate`       | string | No       | Duplicate behavior: `"ignore"` returns existing credential, `"revoke"` reissues (default: `"revoke"`) |

### Response

```json theme={null}
{
  "coreClaimHash": "239704895d0c4693d33ee7ab9e37c6eb295f178d80074a32d4ace53b1a779c44",
  "credentialId": "c21s70g0i54sn0023172Cv",
  "userUuid": "7f01c42c-02cf-4325-96ed-ba034700f724"
}
```

| Field           | Description                                        |
| --------------- | -------------------------------------------------- |
| `coreClaimHash` | Unique issuance identifier used for status polling |
| `credentialId`  | Program ID (echoed)                                |
| `userUuid`      | Target user UUID                                   |

<Warning>
  Issuance is asynchronous. Use `coreClaimHash` with the status endpoint to confirm `ONCHAIN`.
</Warning>

## 2) Check issuance status

Poll issuance status by `coreClaimHash`.

```
GET /v1/credentials/status?coreClaimHash={hash}
```

### Request headers

| Header           | Required | Value              |
| ---------------- | -------- | ------------------ |
| `x-partner-auth` | Yes      | Signed Partner JWT |

### Query parameters

| Parameter       | Required | Description                      |
| --------------- | -------- | -------------------------------- |
| `coreClaimHash` | Yes      | Value returned by issue endpoint |

### Response

```json theme={null}
{
  "coreClaimHash": "239704895d0c4693d33ee7ab9e37c6eb295f178d80074a32d4ace53b1a779c44",
  "issuanceDate": "2026-01-19 07:18:45",
  "issuerDid": "did:air:id:test:5P44fsVUhPctDTWH2Nz26pZJFsg6CqyiAELTGeVQDB",
  "vcId": "c28t30c048pe502a3713w0",
  "vcStatus": "ONCHAIN"
}
```

`vcStatus` values:

| Status         | Meaning                          |
| -------------- | -------------------------------- |
| `WAIT_ONCHAIN` | Issuance in progress             |
| `ONCHAIN`      | Credential is available on-chain |

## Examples

### Basic issue + poll (Node.js)

```js theme={null}
require("dotenv").config();
const { getPartnerJwt } = require("./lib/jwt");

const BASE_URL =
  process.env.NODE_ENV === "production"
    ? "https://api.mocachain.org/v1"
    : "https://api.sandbox.mocachain.org/v1";

async function issueOnBehalf(userEmail, credentialSubject) {
  const token = await getPartnerJwt(userEmail);

  const res = await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-partner-auth": token
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.CREDENTIAL_ID,
      credentialSubject,
      onDuplicate: "revoke"
    })
  });

  if (!res.ok) throw new Error(`Issue failed: ${res.status}`);
  return res.json();
}

async function getStatus(userEmail, coreClaimHash) {
  const token = await getPartnerJwt(userEmail);
  const res = await fetch(
    `${BASE_URL}/credentials/status?coreClaimHash=${encodeURIComponent(coreClaimHash)}`,
    { headers: { "x-partner-auth": token } }
  );
  if (!res.ok) throw new Error(`Status failed: ${res.status}`);
  return res.json();
}
```

### Event-driven webhook example

```js theme={null}
app.post("/webhooks/kyc-complete", async (req, res) => {
  const { userEmail, kycLevel } = req.body;

  const issued = await issueOnBehalf(userEmail, {
    kycVerified: true,
    kycLevel,
    verifiedAt: new Date().toISOString()
  });

  res.json({ success: true, coreClaimHash: issued.coreClaimHash });
});
```

### Retry with backoff

```js theme={null}
async function issueOnBehalfWithRetry(userEmail, credentialSubject, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await issueOnBehalf(userEmail, credentialSubject);
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 1000));
    }
  }
}
```

## Error reference

| HTTP status | Likely cause                              | Suggested fix                                           |
| ----------- | ----------------------------------------- | ------------------------------------------------------- |
| 400         | Missing/invalid request fields            | Verify `issuerDid`, `credentialId`, `credentialSubject` |
| 401         | Invalid/expired JWT, JWKS mismatch        | Validate signature, `kid`, `typ: "JWT"`, token expiry   |
| 403         | Feature not enabled or schema not allowed | Enable feature in dashboard, verify schema ownership    |
| 404         | Unknown issuer/program                    | Recheck IDs in dashboard                                |
| 409         | Consent rejected / conflict               | Check user consent and duplicate behavior               |
| 500         | Server-side failure                       | Retry with backoff and inspect logs                     |

## Troubleshooting

* If issue call succeeds but credential is not visible, poll status until `ONCHAIN`.
* If you get authentication errors, verify JWT contains `partnerId`, `scope: "issue"`, `email` and header includes `typ: "JWT"`.
* Ensure JWKS endpoint is public and `kid` maps to the signing key.


# Issuing Credentials
Source: https://docs.moca.network/airkit/usage/credential/issuing-credentials

Issue verifiable credentials from AIR Kit SDK and manage issuance lifecycle.

The issuer is the entity responsible for creating and issuing credentials within the AIR Credential ecosystem. It defines schemas, issues Verifiable Credentials, and manages the lifecycle of credentials.

As an Issuer, you are responsible for issuing **Verifiable Credentials** to users. Follow these steps to integrate and manage the credential issuance process.

<Info>
  **Backend API Alternative**

  For server-side credential issuance without client interaction, see [Issue Credentials on Behalf](/airkit/usage/credential/issue-on-behalf). That API allows you to issue credentials directly from your server.
</Info>

## Issuing Credentials (SDK)

### **Step 1: Set Up an Issuance Program**

1. Use the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> to create an issuance program (Issuer -> Programs).
2. While creating the program, search for the schema for the credentials you intend to issue, and check the attributes to be included (e.g., name, age, nationality, etc.). It is highly recommended to search for an existing schema so that credentials are interoperable across platforms and can be recognized, displayed, or verified by any verifier. If there are no suitable schemas available, please contact us, or you may create your own schema.
3. Publish the program and take note of the program ID.

### **Step 2: Collect User Data**

Securely authenticate and retrieve your user's data within your existing application.

### **Step 3: Generate Auth Token**

Generate a [Partner JWT](/airkit/usage/partner-authentication) securely with your backend server, and include `scope=issue` to limit its scope.

### **Step 4: Issue Credentials**

To encrypt the user's data and create a verified credential on-chain, simply call the issueCredential() function in AIR Kit.

<Tabs>
  <Tab title="Web">
    ```jsx theme={null}
    public async issueCredential({
        authToken,
        issuerDid,
        credentialId,
        credentialSubject,
        curve,
    }: {
        authToken: string;
        issuerDid: string;
        credentialId: string;
        credentialSubject: Record<string, unknown>;
        curve?: "secp256r1" | "secp256k1";
    }): Promise<{ cakPublicKey?: string }>
    ```

    | Parameter           | Type                         | Description                                                                                         |
    | ------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
    | `authToken`         | `string`                     | Your signed Partner JWT, with scope=issue.                                                          |
    | `issuerDid`         | `string`                     | Your Issuer DID.                                                                                    |
    | `credentialId`      | `string`                     | Program ID for the credential being issued.                                                         |
    | `credentialSubject` | `Record<string, unknown>`    | Object containing the credential's claims and attributes for the subject.                           |
    | `curve`             | `"secp256r1" \| "secp256k1"` | Optional. Elliptic curve for compliance encryption key generation. Defaults to `secp256r1` (P-256). |

    **Response:**
    Returns an object with `cakPublicKey` (Compliance Encryption User Public Key) if compliance encryption is enabled for the issuance program. The public key is deterministically derived from \[User – Issuer – Schema] and can be used to encrypt compliance data before issuance. Throws an error if issuance fails.
  </Tab>

  <Tab title="Flutter">
    Not supported yet
  </Tab>
</Tabs>

Under the hood, AIR Kit generates a Verifiable Credential based on the issuance program and schema, pushes the VC on-chain, and stores the encrypted data in decentralized storage. During this process, the raw user data and private keys stay on the client side and are not exposed to Moca's servers.

## Compliance Encryption Public Key

When compliance encryption is enabled for your issuance program (configured in the Developer Dashboard), the `issueCredential` function returns a `cakPublicKey` (Compliance Encryption User Public Key) in the response. This feature allows issuers to:

* **Obtain a user-specific public key** before credential issuance
* **Encrypt additional compliance data** for regulated disclosure or threshold decryption workflows
* **Use a deterministic key** that is tied to the \[User – Issuer – Schema] composite identifier

The public key is derived from the user's Identity Wallet by signing EIP-712 structured data. You can specify the elliptic curve using the optional `curve` parameter:

* `secp256r1` (P-256) - Default, recommended for most use cases
* `secp256k1` - Alternative curve option

The same public key will be returned for the same user, issuer, and schema combination, allowing you to retrieve it without first issuing a credential if needed.

<Card title="Full CAK Issuer Guide" icon="arrow-right" href="/airkit/usage/credential/cak-issuer-guide">
  For complete details on Dashboard configuration, encrypting user data with the CAK public key, and implementing the callback endpoint, see the dedicated CAK Issuer Guide.
</Card>

<Tip>
  * Use the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> to view and manage issued credentials (Issuer -> Records). In cases where credentials need to be invalidated, use the **Revoke** function in the Dashboard.
  * Use the **Chain Explorer** to find the record of the on-chain transaction related to issuance (Credentials -> Issuance)
</Tip>

## Best Practices for Issuers (SDK)

* Only issue credentials after thorough validation of submitted evidence or claims.
* Minimize inclusion of personally identifiable information—issue privacy-preserving credentials whenever possible.
* Adopt open, standardized schemas to maximize compatibility and reduce verification friction across apps.
* Implement robust expiry and revocation processes, and ensure that holders and verifiers are informed of credential status.
* Respect user sovereignty at all stages; credentials should be under full user control and portable across the ecosystem.


# Schema Creation Guide
Source: https://docs.moca.network/airkit/usage/credential/schema-creation

Create and publish credential schemas with the AIR Kit Schema Builder.

Credential schemas are the foundation of your credential issuance system. This guide will help you understand, create, and manage schemas effectively for your AIR Kit applications.

## Creating Schemas with the Schema Builder

The AIR Kit Schema Builder provides an intuitive interface for creating credential schemas without requiring technical knowledge of JSON schema structures.

### Step 1: Access the Schema Builder

1. Go to the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/issuer/schemas)
2. Navigate to the **Schemas** section under **Issuer**
   <img alt="Create Schema" />

### Step 2: Create a New Schema

1. Click **"Create New Schema"**
2. Fill in the basic schema information:
   * **Title**: Choose a descriptive name for your schema
   * **Type**: Select or enter a category for your credential type
   * **Description**: Provide a clear explanation of what this schema represents

### Step 3: Define Attributes

1. Click **"+"** to add attributes
2. For each attribute, specify:
   * **Name**: Field identifier (use camelCase)
   * **Type**: Choose from String, Number, Boolean, or Date
   * **Description**: Explain what this field represents
   * **Required**: Mark if the field is mandatory

### Step 4: Publish Your Schema

1. Review your schema structure
2. Click **"Publish"** to make it available for credential creation
3. Note the schema ID for use in your applications

<div>
  <img alt="Create schema" />
</div>

## Schema Builder Best Practices

### 1. Choose Descriptive Names

* Use clear, descriptive names for your schema title and attributes
* Avoid abbreviations that might be unclear to other developers
* Example: `"memberId"` instead of `"mem_id"`

### 2. Provide Clear Descriptions

* Write detailed descriptions for each attribute
* Explain the purpose and expected format of each field
* Include any validation rules or constraints

### 3. Use Appropriate Data Types

* **String**: For text data, IDs, names, descriptions
* **Number**: For numeric values, ages, quantities, scores
* **Boolean**: For true/false values, flags, status indicators
* **Date**: For timestamps, expiry dates, event dates

### 4. Consider Privacy Requirements

* Only include fields that are necessary for your use case
* Remember that users can selectively disclose fields
* Avoid collecting sensitive data unless absolutely required

### 5. Plan for Future Updates

* Consider how your schema might evolve over time
* Use versioning to manage schema changes
* Design attributes to be extensible


# Schema Management & Versioning
Source: https://docs.moca.network/airkit/usage/credential/schema-management

Manage schema evolution safely with backward-compatible versioning practices.

As your application evolves, you may need to update your credential schemas. Understanding how to manage schema changes is crucial for maintaining compatibility and ensuring smooth operations.

### Schema Versioning Strategy

When you need to modify a schema, consider these approaches:

#### Backward Compatible Changes

These changes don't break existing credentials:

* Adding new optional attributes
* Updating descriptions or metadata
* Adding new schema versions

#### Breaking Changes

These changes require careful planning:

* Removing attributes
* Changing attribute data types
* Making optional attributes required
* Renaming attributes

### Best Practices for Schema Evolution

#### 1. Plan for Growth

**JSON-LD Context v1.0:**

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v1.0.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v1.0#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### 2. Add New Fields Gradually

**JSON-LD Context v1.1:**

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v1.1.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v1.1#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          },
          "phoneNumber": {
            "@id": "vocab:phoneNumber",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### 3. Deprecate Fields Carefully

**JSON-LD Context v2.0:**

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "UserProfileCredential": {
        "@id": "https://your-domain.com/schemas/user-profile-v2.0.json-ld#UserProfileCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/user-profile/v2.0#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "firstName": {
            "@id": "vocab:firstName",
            "@type": "xsd:string"
          },
          "lastName": {
            "@id": "vocab:lastName",
            "@type": "xsd:string"
          },
          "email": {
            "@id": "vocab:email",
            "@type": "xsd:string"
          },
          "phoneNumber": {
            "@id": "vocab:phoneNumber",
            "@type": "xsd:string"
          },
          "fullName": {
            "@id": "vocab:fullName",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

### Managing Schema Updates in Production

#### 1. Gradual Migration Strategy

* Keep old schemas active during transition periods
* Issue new credentials with updated schemas
* Gradually phase out old schema versions
* Monitor credential usage patterns

#### 2. Communication with Users

* Notify users about schema changes
* Provide migration guides for credential holders
* Maintain backward compatibility for verification

#### 3. Testing Schema Changes

* Test new schemas in development environment
* Validate credential issuance with new schemas
* Ensure verification still works with old credentials
* Test selective disclosure with updated schemas

## Schema Registry and Discovery

The AIR Kit provides a schema registry where you can:

* **Browse Available Schemas**: Discover schemas created by other developers
* **Reuse Existing Schemas**: Use well-established schemas for common use cases
* **Contribute Schemas**: Share your schemas with the community

## Next Steps

Now that you understand schema creation and JSON-LD implementation, you can:

* **Issue Credentials** - Use your schemas to issue credentials in the [Credential Issuance Quickstart](/airkit/quickstart/issue-credentials)
* **Verify Credentials** - Learn how to verify credentials in the [Credential Verification Quickstart](/airkit/quickstart/verify-credentials)
* **Explore Schema Registry** - Browse and reuse existing schemas in the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard/issuer/schemas)
* **Advanced Schema Design** - Learn about complex schema patterns and advanced use cases


# Schema Overview
Source: https://docs.moca.network/airkit/usage/credential/schema-overview

Understand credential schema structure, JSON-LD context, and JSON Schema.

A **credential schema** is a blueprint that defines the structure, data types, and validation rules for the credentials you want to issue. Think of it as a template that ensures all credentials of a particular type have consistent fields and data formats.

Schemas serve several critical purposes:

* **Data Consistency**: Ensures all credentials of the same type have identical field structures
* **Validation**: Defines data types and constraints for each field
* **Interoperability**: Allows different systems to understand and process your credentials
* **Privacy**: Enables selective disclosure of specific fields within a credential

## Schema Components

A Schema Type encodes the structure of a particular Verifiable Credential (VC) by defining the type, the fields that must be included inside the VC, and a description for these fields.

Schemas are a crucial component that allows for the interoperable use of VCs across different services. Just by parsing a schema, any program can interpret the content of a Verifiable Credential without having to interact with the Issuer Party.

A schema type is made of **two separate documents**:

### 1. JSON-LD Context

The JSON-LD Context contains a description of the type and its fields, providing semantic meaning to your credential data by linking it to standardized vocabularies and ontologies.

#### Understanding JSON-LD Context

JSON-LD context defines the vocabulary and data types used in your credentials. It maps local field names to globally unique identifiers (URIs) that have well-defined meanings.

Here's an example of a JSON-LD Context for a `MembershipPointsCredential`:

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "MembershipPointsCredential": {
        "@id": "https://your-domain.com/schemas/membership-points.json-ld#MembershipPointsCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/membership-points#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "memberId": {
            "@id": "vocab:memberId",
            "@type": "xsd:string"
          },
          "totalPoints": {
            "@id": "vocab:totalPoints",
            "@type": "xsd:integer"
          },
          "tier": {
            "@id": "vocab:tier",
            "@type": "xsd:string"
          },
          "lastUpdated": {
            "@id": "vocab:lastUpdated",
            "@type": "xsd:dateTime"
          }
        }
      }
    }
  ]
}
```

#### Key JSON-LD Context Elements

* **@version**: Specifies the JSON-LD version (typically 1.1)
* **@protected**: Ensures that terms cannot be overridden
* **@id**: Maps to globally unique identifiers
* **@type**: Specifies the data type using XML Schema types
* **vocab**: Custom vocabulary namespace for your specific fields
* **xsd**: XML Schema Definition namespace for standard data types

### 2. JSON Schema

The JSON Schema contains the validation rules for the Issuer Node, defining the structure and constraints for the credential data.

Here's an example of a JSON Schema for the `MembershipPointsCredential`:

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/membership-points.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/membership-points.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "memberId", "totalPoints", "tier"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "memberId": {
          "title": "Member ID",
          "type": "string",
          "description": "Unique member identifier"
        },
        "totalPoints": {
          "title": "Total Points",
          "type": "integer",
          "description": "Total accumulated membership points",
          "minimum": 0
        },
        "tier": {
          "title": "Membership Tier",
          "type": "string",
          "description": "Current membership tier based on points",
          "enum": ["bronze", "silver", "gold", "platinum"]
        },
        "lastUpdated": {
          "title": "Last Updated",
          "type": "string",
          "format": "date-time",
          "description": "When points were last updated"
        }
      }
    }
  }
}
```

#### Key JSON Schema Elements

* **\$metadata**: Contains URIs linking to both the JSON-LD context and JSON schema
* **required**: Lists all mandatory fields for the credential
* **properties**: Defines the structure and validation rules for each field
* **credentialSubject**: Contains the actual credential data fields
* **format**: Specifies validation formats (uri, date-time, etc.)

#### Benefits of This Two-Document Approach

1. **Separation of Concerns**: JSON-LD handles semantics, JSON Schema handles validation
2. **Interoperability**: Different systems can understand credentials using standard vocabularies
3. **Validation**: Issuer nodes can validate credential structure before issuance
4. **Flexibility**: Allows for complex validation rules while maintaining semantic clarity


# Schema Use Cases
Source: https://docs.moca.network/airkit/usage/credential/schema-use-cases

Reference examples for common credential schema patterns and vertical use cases.

Here are some popular schema types you might create:

### Membership Points Schema

A comprehensive example showing how to create a schema for tracking membership points and tiers.

#### JSON-LD Context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "MembershipPointsCredential": {
        "@id": "https://your-domain.com/schemas/membership-points.json-ld#MembershipPointsCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/membership-points#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "memberId": {
            "@id": "vocab:memberId",
            "@type": "xsd:string"
          },
          "totalPoints": {
            "@id": "vocab:totalPoints",
            "@type": "xsd:integer"
          },
          "tier": {
            "@id": "vocab:tier",
            "@type": "xsd:string"
          },
          "lastUpdated": {
            "@id": "vocab:lastUpdated",
            "@type": "xsd:dateTime"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/membership-points.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/membership-points.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "memberId", "totalPoints", "tier"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "memberId": {
          "title": "Member ID",
          "type": "string",
          "description": "Unique member identifier"
        },
        "totalPoints": {
          "title": "Total Points",
          "type": "integer",
          "description": "Total accumulated membership points",
          "minimum": 0
        },
        "tier": {
          "title": "Membership Tier",
          "type": "string",
          "description": "Current membership tier based on points",
          "enum": ["bronze", "silver", "gold", "platinum"]
        },
        "lastUpdated": {
          "title": "Last Updated",
          "type": "string",
          "format": "date-time",
          "description": "When points were last updated"
        }
      }
    }
  }
}
```

### Age Verification Schema

#### JSON-LD Context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "AgeVerificationCredential": {
        "@id": "https://your-domain.com/schemas/age-verification.json-ld#AgeVerificationCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/age-verification#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "age": {
            "@id": "vocab:age",
            "@type": "xsd:integer"
          },
          "dateOfBirth": {
            "@id": "vocab:dateOfBirth",
            "@type": "xsd:date"
          },
          "jurisdiction": {
            "@id": "vocab:jurisdiction",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/age-verification.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/age-verification.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "age", "dateOfBirth", "jurisdiction"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "age": {
          "title": "Age",
          "type": "integer",
          "description": "User's age in years",
          "minimum": 0,
          "maximum": 150
        },
        "dateOfBirth": {
          "title": "Date of Birth",
          "type": "string",
          "format": "date",
          "description": "User's date of birth"
        },
        "jurisdiction": {
          "title": "Jurisdiction",
          "type": "string",
          "description": "Legal jurisdiction for age verification"
        }
      }
    }
  }
}
```

### Event Pass Schema

#### JSON-LD Context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "EventPassCredential": {
        "@id": "https://your-domain.com/schemas/event-pass.json-ld#EventPassCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/event-pass#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "eventName": {
            "@id": "vocab:eventName",
            "@type": "xsd:string"
          },
          "eventDate": {
            "@id": "vocab:eventDate",
            "@type": "xsd:dateTime"
          },
          "ticketType": {
            "@id": "vocab:ticketType",
            "@type": "xsd:string"
          },
          "seatNumber": {
            "@id": "vocab:seatNumber",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/event-pass.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/event-pass.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": ["id", "eventName", "eventDate", "ticketType"],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "eventName": {
          "title": "Event Name",
          "type": "string",
          "description": "Name of the event"
        },
        "eventDate": {
          "title": "Event Date",
          "type": "string",
          "format": "date-time",
          "description": "Date and time of the event"
        },
        "ticketType": {
          "title": "Ticket Type",
          "type": "string",
          "description": "Type of ticket",
          "enum": ["general", "vip", "backstage", "premium"]
        },
        "seatNumber": {
          "title": "Seat Number",
          "type": "string",
          "description": "Seat or section number"
        }
      }
    }
  }
}
```

### Professional Credential Schema

#### JSON-LD Context

```json theme={null}
{
  "@context": [
    {
      "@version": 1.1,
      "@protected": true,
      "id": "@id",
      "type": "@type",
      "ProfessionalCredential": {
        "@id": "https://your-domain.com/schemas/professional-credential.json-ld#ProfessionalCredential",
        "@context": {
          "@version": 1.1,
          "@protected": true,
          "id": "@id",
          "type": "@type",
          "vocab": "https://your-domain.com/vocab/professional-credential#",
          "xsd": "http://www.w3.org/2001/XMLSchema#",
          "certificationName": {
            "@id": "vocab:certificationName",
            "@type": "xsd:string"
          },
          "issuingOrganization": {
            "@id": "vocab:issuingOrganization",
            "@type": "xsd:string"
          },
          "certificationNumber": {
            "@id": "vocab:certificationNumber",
            "@type": "xsd:string"
          },
          "issueDate": {
            "@id": "vocab:issueDate",
            "@type": "xsd:date"
          },
          "expiryDate": {
            "@id": "vocab:expiryDate",
            "@type": "xsd:date"
          },
          "credentialLevel": {
            "@id": "vocab:credentialLevel",
            "@type": "xsd:string"
          }
        }
      }
    }
  ]
}
```

#### JSON Schema

```json theme={null}
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "$metadata": {
    "uris": {
      "jsonLdContext": "https://your-domain.com/schemas/professional-credential.json-ld",
      "jsonSchema": "https://your-domain.com/schemas/professional-credential.json"
    }
  },
  "required": [
    "@context",
    "id",
    "type",
    "issuanceDate",
    "credentialSubject",
    "credentialSchema",
    "credentialStatus",
    "issuer"
  ],
  "properties": {
    "@context": {
      "type": ["string", "array", "object"]
    },
    "id": {
      "type": "string"
    },
    "type": {
      "type": ["string", "array"],
      "items": {
        "type": "string"
      }
    },
    "issuer": {
      "type": ["string", "object"],
      "format": "uri",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "issuanceDate": {
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "type": "string",
      "format": "date-time"
    },
    "credentialSchema": {
      "type": "object",
      "required": ["id", "type"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uri"
        },
        "type": {
          "type": "string"
        }
      }
    },
    "credentialSubject": {
      "type": "object",
      "required": [
        "id",
        "certificationName",
        "issuingOrganization",
        "certificationNumber",
        "issueDate"
      ],
      "properties": {
        "id": {
          "title": "Credential Subject ID",
          "type": "string",
          "format": "uri"
        },
        "certificationName": {
          "title": "Certification Name",
          "type": "string",
          "description": "Name of the certification"
        },
        "issuingOrganization": {
          "title": "Issuing Organization",
          "type": "string",
          "description": "Organization that issued the certification"
        },
        "certificationNumber": {
          "title": "Certification Number",
          "type": "string",
          "description": "Unique certification identifier"
        },
        "issueDate": {
          "title": "Issue Date",
          "type": "string",
          "format": "date",
          "description": "Date the certification was issued"
        },
        "expiryDate": {
          "title": "Expiry Date",
          "type": "string",
          "format": "date",
          "description": "Date the certification expires"
        },
        "credentialLevel": {
          "title": "Credential Level",
          "type": "string",
          "description": "Level of certification",
          "enum": ["associate", "professional", "expert", "master"]
        }
      }
    }
  }
}
```


# Verifying Credentials
Source: https://docs.moca.network/airkit/usage/credential/verify

The **Verifier** is a key entity within the AIR Credential ecosystem, responsible for verifying the authenticity of a user’s credential and determining whether it meets predefined conditions. Leveraging zero-knowledge proofs, the Verifier can validate credentials without accessing or exposing sensitive user data.

As a Verifier, your role is to verify the authenticity of user credentials and ensure they meet the required conditions. Follow these steps to integrate and operate the verification process.

## Verification Flow

The AIR Credential verification process follows these simplified steps:

1. **Verification Request** - Verifier presents a verification requirement to the user (e.g., "Prove you're over 18")
2. **Credential Issuance** (if needed) - If the user lacks the required credential, a trusted Issuer validates their information and issues an encrypted verifiable credential stored in decentralized storage
3. **Zero-Knowledge Proof Generation** - User generates a cryptographic proof from their credential that answers the verifier's query without revealing personal data
4. **On-Chain Verification** - The proof is submitted to Moca Chain's smart contract, which validates it and records the verification result
5. **Access Granted** - Upon successful verification, the user gains access to the requested service or resource

```mermaid theme={null}
sequenceDiagram
    participant Verifier
    participant User
    participant Issuer
    participant Moca Chain
    participant Decentralized Storage

    Verifier->>User: 1. Verification Request ("Prove you're over 18")
    alt Credential not held
        User->>Issuer: 2a. Provides information
        Issuer->>Decentralized Storage: 2b. Issues encrypted credential
        Issuer-->>User: 2c. Credential issued
    end
    Decentralized Storage->>User: 3a. Download encrypted credential
    User->>User: 3a. Decrypt credential data
    User->>User: 3b. Generates zero-knowledge proof
    User->>Moca Chain: 4. Submits proof for verification
    Moca Chain-->>Verifier: 4. Proof validation result
    Verifier->>User: 5. Access granted
```

## Implementation

### **Step 1: Set Up a Verification Program**

1. Use the <a href="https://developers.sandbox.air3.com/dashboard">Developer Dashboard</a> to create a verification program (Verifier -> Program).
2. While creating the program, search for the schema for the credentials you intend to verify, and check the attributes to be included (e.g., name, age, nationality, etc.).
3. Use the **Define Query** module to set up specific verification conditions, such as:
   * Attributes to verify (e.g., age, nationality).
   * Operators (e.g., Equals, Not Equals, Includes, Excludes).
   * Attribute values to match.
4. Specify the Issuer’s DID to ensure the credentials being verified originate from a trusted issuer. (optional)
5. Provide a program name and review all configured details before saving.
6. Publish the program on-chain and take note of the program ID. You will need \$MOCA in your Fee Wallet (Verifier -> Fee Wallet).

### **Step 2: Generate Auth Token**

Generate a [Partner JWT](/airkit/usage/partner-authentication) securely with your backend server, and include `scope=verify` to limit its scope.

### **Step 3: Initiate Verification Request**

To verify a user's Verified Credentials, simply call the verifyCredentials() function in AIR Kit to verify a VC on-chain.

<Tabs>
  <Tab title="Web">
    ```jsx theme={null}
    public async verifyCredential({
        authToken,
        programId,
        redirectUrl,
      }: {
        authToken: string;
        programId: string;
        redirectUrl?: string;
      }): Promise<CredentialVerificationResult>
    ```

    ### Input Parameters

    | Name          | Type   | Required | Description                                                                           |
    | ------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
    | `authToken`   | string | Yes      | Your signed Partner JWT, with scope=verify.                                           |
    | `programId`   | string | Yes      | Identifier for the verification program.                                              |
    | `redirectUrl` | string | No       | Optional URL to redirect the user if the user has not issued the relevant credential. |

    ### Response

    The function returns a `Promise<CredentialVerificationResult>`. The `CredentialVerificationResult` is a discriminated union type with the following structure:

    **For non-compliant statuses** (`"Non-Compliant"`, `"Pending"`, `"Revoking"`, `"Revoked"`, `"Expired"`, `"NotFound"`):

    | Field    | Type   | Description                                |
    | -------- | ------ | ------------------------------------------ |
    | `status` | string | The result of the credential verification. |

    **For compliant status** (`"Compliant"`):

    | Field             | Type                     | Description                                                                                                                                                                                                       |
    | ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `status`          | `"Compliant"`            | Indicates the credential is valid and meets all verification requirements.                                                                                                                                        |
    | `zkProofs`        | `Record<string, string>` | Zero-knowledge proofs generated for the verification, keyed by proof identifier.                                                                                                                                  |
    | `transactionHash` | `string`                 | On-chain transaction hash of the verification.                                                                                                                                                                    |
    | `cakPrivateKey`   | `string`                 | Optional. Compliance encryption private key. Only present when compliance encryption is enabled. Used to decrypt compliance data that was encrypted with the corresponding public key during credential issuance. |
  </Tab>

  <Tab title="Flutter">
    Not supported yet

    Under the hood, AIR Kit retrieves the encrypted credentials from **Decentralized Storage** based on the user's wallet address and program configuration. After the user approves the verification process, a Zero-knowledge Proof (ZKP) is generated on the client side without exposing the raw data to the verifier or Moca's servers. At the same time, the credentials are checked against any revocation statuses or expiration. Once the ZKP is generated, it is submitted on-chain for verification.

    ### Compliance Encryption Private Key

    When a verification result is `"Compliant"` and compliance encryption was enabled during credential issuance, the verification response includes a `cakPrivateKey` (Compliance Encryption User Private Key). This private key corresponds to the public key (`cakPublicKey`) that was returned during credential issuance.

    This feature enables verifiers to:

    * **Decrypt compliance data** that was encrypted by the issuer using the corresponding public key
    * **Access regulated disclosure information** or participate in threshold decryption workflows
    * **Retrieve compliance data** only after successful credential verification

    The private key is only provided when:

    * The verification status is `"Compliant"` (credential is valid and meets requirements)
    * Compliance encryption was enabled for the issuance program
    * The verifier has proper authorization

    <Card title="Full CAK Verifier Guide" icon="arrow-right" href="/airkit/usage/credential/cak-verifier-guide">
      For complete details on handling user consent, receiving the private key, decrypting user data, and security best practices, see the dedicated CAK Verifier Guide.
    </Card>
  </Tab>
</Tabs>

<Tip>
  * Use the **Chain Explorer** to find the record of the on-chain transaction related to verification (Credentials -> Verification)
  * The `cakPrivateKey` is only available for compliant verifications, ensuring compliance data can only be decrypted after successful verification
</Tip>


# Setting Up Your Partner Account
Source: https://docs.moca.network/airkit/usage/getting-started

To get started, you'll need to head to the Developer Dashboard to obtain a Partner ID and fill in some information about your app.

To get started, you’ll need to head to the <a href="https://developers.sandbox.air3.com/testnet">Developer Dashboard</a> to obtain a Partner ID and fill in some information about your app.

Depending on what your app supports, you'll be using the information:

* Partner ID - your unique ID used throughout AIR Kit
* Issuer DID - used for credentials issuance
* Verifier DID - used for credentials verification

To learn more about the Developer Dashboard's settings, head to the [AIR Kit Dashboard page](/airkit/airkit-dashboard).


# SDK Initialization
Source: https://docs.moca.network/airkit/usage/initialization

AIR Kit creates an iframe that loads the login flow and sets up communication streams between the iframe and the DApp's JavaScript context.

<Tabs>
  <Tab title="Web">
    AIR Kit creates an iframe that loads the login flow and sets up communication streams between the iframe and the DApp's JavaScript context.

    ```js theme={null}
    import { AirService, BUILD_ENV } from "@mocanetwork/airkit";

    const airService = new AirService({
      partnerId: YOUR_PARTNER_ID // Replace with your actual Partner ID
    });
    await airService.init({
      buildEnv: BUILD_ENV.SANDBOX,
      enableLogging: true,
      preloadWallet: true, // Optional: Enable if wallet features will be used
      preloadCredential: true, // Optional: Enable if credential features will be used
      sessionConfig: {
        locale: "en", // Optional: Language code (e.g. "en", "es", ...)
        currency: "USD" // Optional: Display currency (e.g. "EUR", "USD", ...)
      }
    });

    // Without any parameters, this will trigger the default Air login dialog which provides different login methods for the user to choose from.
    await airService.login();
    ```

    Once the SDK is installed and `AirService` is successfully initialized, it can be used to authenticate users.
  </Tab>

  <Tab title="Flutter">
    After installation, the next step to use the AirKit SDK is to create an `AirService` instance and call the `initialize` method.

    The `partnerId` you will receive from us and the `redirectUrl` parameter needs to match the schema discussed in the installation section. It is different for Android and iOS.

    ```dart theme={null}
    Future<void> initialize({
        required String partnerId,
        required GlobalKey<NavigatorState> navigatorKey,
        Environment env = Environment.production,
        bool enableLogging = false,
    })
    ```

    The `partnerId` you will receive from us and the `navigatorKey` parameter is needed to overlay dialogs necessary for specific user flows. During development we recommend using `Environment.sandbox` and enabled logging.

    **Guides:** [Flutter overview](/airkit/flutter/overview) · [Flutter installation](/airkit/flutter/installation) · [Android setup](/airkit/flutter/android-setup) · [iOS setup](/airkit/flutter/ios-setup)

    Minimal pattern:

    ```dart theme={null}
    final navigatorKey = GlobalKey<NavigatorState>();
    final airService = AirService();

    await airService.initialize(
      partnerId: 'YOUR_PARTNER_ID',
      navigatorKey: navigatorKey,
      env: Environment.sandbox,
      enableLogging: true,
    );

    // In MaterialApp: navigatorKey: navigatorKey
    ```
  </Tab>
</Tabs>


# SDK Installation
Source: https://docs.moca.network/airkit/usage/installation

npm install @mocanetwork/airkit

<Tabs>
  <Tab title="Web">
    ```bash theme={null}
    npm install @mocanetwork/airkit
    ```

    ### **Bundling**

    This module is distributed in 3 formats

    * `esm` build `dist/airkit.esm.js` is es6 format
    * `commonjs` build `dist/airkit.cjs.js` in es5 format
    * `umd` build `dist/airkit.umd.min.js` In ES5 format without polyfilling corejs minified

    By default, the appropriate format is used for your specified use case. A different format can be used (if you know what you're doing) by referencing the correct file.
  </Tab>

  <Tab title="Flutter">
    ### Installation

    Before you can install the AirKit Flutter package, you need to install the OnePub CLI in order to access our private package repository. We will provide you with the login credentials for OnePub.

    Open your terminal and use following commands:

    ```bash theme={null}
    dart pub global activate onepub
    onepub login

    ```

    <Warning>
      **OnePub PATH Troubleshooting**

      In case the `onepub` command is not recognized, adding following to your PATH should help:\
      `export PATH=$PATH:$HOME/.pub-cache/bin`
    </Warning>

    To install the AirKit Flutter package, you have two options. You can either manually add the package in the `pubspec.yaml` file, or you can use the `onepub pub add` command.

    Add `airkit` as a dependency to your `pubspec.yaml`.

    ```yaml theme={null}
    dependencies:
      airkit:
        hosted: https://onepub.dev/api/sxhddavuhn/
        version: ^1.6.0-beta.1
    ```

    Add `airkit` using `onepub pub add` command.

    ```bash theme={null}
    onepub pub add airkit

    ```

    ### Android Configuration

    ### Generate SHA256 fingerprint

    In order to whitelist your Android app we would need the SHA-256 fingerprint of the certificate you use to sign your Android app. You will have different fingerprints for your debug and release builds.

    You can get this fingerprint by using the `keytool` command:

    ```bash theme={null}
    keytool -list -v -keystore <path-to-your-keystore> -alias <your-key-alias>

    ```

    In addition to above fingerprints, we would also need the package name.

    ### Update compileSdkVersion and minSdk

    For Android build `compileSdkVersion` needs to be at least `34` and `minSdk` needs to be at least `26`. Check your app module gradle file in your project to change it.

    ```json theme={null}
    android {
        namespace "com.example.appname"
        compileSdkVersion 34
        // ..

        defaultConfig {
            minSdk = 26
            // ..
        }
    }

    ```

    ### Configure asset links

    For passkey to work, you need to add the following to your `android/app/src/main/res/values/strings.xml`:

    ```xml theme={null}
    <string name="asset_statements" translatable="false">
    [
      {"include": "https://account.air3.com/.well-known/assetlinks.json"},
      {"include": "https://account.sandbox.air3.com/.well-known/assetlinks.json"}
    ]
    </string>

    ```

    ### iOS Configuration

    ### App ID whitelisting

    In order to whitelist your iOS app we would need one or more valid Apple App IDs that consist of:

    1. Your **Apple Team ID**: This is a unique, 10-character alphanumeric string assigned to your developer account by Apple (e.g., `ABCDE12345`). You can find it in your Apple Developer account under "Membership Details" or by inspecting your provisioning profiles.
    2. Your App's **Bundle Identifier**: This is the unique identifier for your app, typically in reverse domain name format (e.g., `com.example.appname`). This is set in your Xcode project.

    The final format would be `ABCDE12345.com.example.appname`.

    ### Update global iOS platform

    For iOS build global platform needs to be 14.0. Check `Podfile` in your project to change the global platform.

    ```json theme={null}
    platform :ios, '14.0'
    ```

    ### Configure associate domains

    In order to enable passkey, following steps need to be done:

    1. Open your project in Xcode (`ios/Runner.xcworkspace`).
    2. Select the `Runner` target, go to the **Signing & Capabilities** tab.
    3. Add the **Associated Domains** capability.
    4. Add following domains:
       * `webcredentials:account.air3.com`
       * `webcredentials:account.sandbox.air3.com`

    For dedicated Flutter guides (platform checklist, Google Sign-In, troubleshooting), see the **[Flutter](/airkit/flutter/overview)** section in the sidebar.
  </Tab>
</Tabs>


# Migration & Compatibility
Source: https://docs.moca.network/airkit/usage/migration-compatibility

This document covers essential compatibility information for AIR Kit and AIR Kit Connector packages.

## Browser Compatibility

### Minimum Requirements

Due to passkey authentication requirements, AIR Kit requires:

**Minimum Supported Versions:**

* **iOS**: 16+
* **Android**: 10+
* **Safari**: 16+
* **Chromium**: 126+
* **Firefox**: 97+

**Required Features:**

* Passkey support (WebAuthn)
* Iframe support
* PostMessage API
* ES6+ JavaScript support

## Package Compatibility

### AIR Kit (`@mocanetwork/airkit`)

**Distribution Formats:**

* **ESM**: `dist/airkit.esm.js` (ES6 modules)
* **CommonJS**: `dist/airkit.cjs.js` (ES5 format)
* **UMD**: `dist/airkit.umd.min.js` (browser use)

**Requirements:**

* Node.js >=18.x
* npm >=9.x

### AIR Kit Connector (`@mocanetwork/airkit-connector`)

**Peer Dependencies:**

* `@wagmi/core` ^2.x
* `viem` ^2.x

**Requirements:**

* Node.js >=18.x
* npm >=9.x

## Framework Support

**Framework-Agnostic Design:**
Since AIR Kit spawns iFrames to run the wallet and UI, it should work with most JavaScript frameworks. The SDK communicates and provides an EIP-1193 provider interface, making it compatible with:

* React
* Next.js
* Vue
* Angular
* Svelte
* SolidJS
* And other modern JavaScript frameworks


# SDK Authentication (Partner JWT)
Source: https://docs.moca.network/airkit/usage/partner-authentication

To ensure requests are coming from your servers, a JSON Web Token (JWT) signed by your backend is required for various operations with AIR Kit.

You need to generate and use the JWT when:

* Authenticating a User
* Performing credentials-related operations such as issuing or verifying credentials

For **Issue on Behalf** (server-side credential issuance without user presence), the JWT must include `scope: "issue on-behalf"`, `typ: "JWT"`, and the target user's `email` claim. See [Issue on Behalf](/airkit/usage/credential/issue-on-behalf) for concepts and [Issue on Behalf API & Examples](/airkit/usage/credential/issue-on-behalf-api) for endpoint usage.

**JWT Details**

* **Signing algorithms supported:** ES256, RS256
* **Expiry**: 5 min (recommended)
* **Claims**: varies depending on the operation. You would always need to include your `partnerId` as one of the claims
* **Header**: You must include a `kid` (Key ID) header to indicate which key was used to sign the JWT. This is important for AIR Kit to select the correct key from your JWKS endpoint for verification.
* **JWKS URL** - AIR Kit validates your JWT using JWK standards ([https://datatracker.ietf.org/doc/html/rfc7517](https://datatracker.ietf.org/doc/html/rfc7517)). By specifying your JSON Web Key Set (JWKS) endpoint, we could validate your JWT issued by your Authorization Server. - Example: [https://static.air3.com/.well-known/example-jwks.json](https://static.air3.com/.well-known/example-jwks.json)

To learn more about JWT, visit [jwt.io](https://www.jwt.io).

## Issue on Behalf JWT requirements

For [Issue on Behalf (API)](/airkit/usage/credential/issue-on-behalf), use a Partner JWT with these fields:

| Category  | Required fields                                  | Notes                                               |
| --------- | ------------------------------------------------ | --------------------------------------------------- |
| Claims    | `partnerId`, `scope: "issue on-behalf"`, `email` | `email` must be the target user's AIR Account email |
| Header    | `kid`, `typ: "JWT"`                              | `kid` identifies which key in your JWKS is used     |
| Algorithm | `RS256` or `ES256`                               | Keep consistent with your JWKS key type             |
| Expiry    | `exp` (recommended 5 minutes)                    | Short-lived token recommended                       |

JWKS reminders for Issue on Behalf:

* `kid` in JWT header must match a key ID exposed by your JWKS endpoint
* JWKS endpoint must be publicly reachable by AIR Kit

Focused Node.js example (payload + header shape):

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");
const now = Math.floor(Date.now() / 1000);

const payload = {
  partnerId: "your-partner-id",
  scope: "issue on-behalf",
  email: "user@example.com",
  iat: now,
  exp: now + 5 * 60
};

const token = jwt.sign(payload, privateKey, {
  algorithm: "RS256",
  header: {
    kid: "your-partner-id",
    typ: "JWT"
  }
});
```

## Generating Partner JWTs

### Generating an RS256 Key Pair

To generate a private/public key pair, you may use OpenSSL:

```sh theme={null}
# Generate a 2048-bit RSA private key
openssl genpkey -algorithm RSA -out private.key -pkeyopt rsa_keygen_bits:2048

# Extract the public key in PEM format
openssl rsa -pubout -in private.key -out public.key
```

* `private.key`: Use this file as your signing key in backend code.
* `public.key`: Use this to configure your JWKS endpoint for JWT verification.

> **Tip:** Keep your private key secure and never share it publicly.

### Examples

Below are backend code examples for generating a JWT using ES256 or RS256 algorithms, including the `kid` (Key ID) header.

<Tabs>
  <Tab title="Node.js">
    ```js theme={null}
    const jwt = require("jsonwebtoken");
    const fs = require("fs");

    const privateKey = fs.readFileSync("path/to/private.key");
    const payload = {
      partnerId: "your-partner-id",
      // other claims as needed
      exp: Math.floor(Date.now() / 1000) + 5 * 60 // 5 minutes expiry
    };

    const token = jwt.sign(payload, privateKey, {
      algorithm: "RS256",
      header: {
        kid: "your-key-id"
      }
    });
    console.log(token);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import com.auth0.jwt.JWT;
    import com.auth0.jwt.algorithms.Algorithm;
    import java.util.HashMap;
    import java.util.Map;

    Algorithm algorithm = Algorithm.RSA256(null, privateKey); // Use your private key
    Map<String, Object> headerClaims = new HashMap<>();
    headerClaims.put("kid", "your-key-id");

    String token = JWT.create()
                    .withHeader(headerClaims)
                    .withClaim("partnerId", "your-partner-id")
                    .withExpiresAt(new Date(System.currentTimeMillis() + 5 * 60 * 1000))
                    .sign(algorithm);

    System.out.println(token);
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using System;
    using System.IdentityModel.Tokens.Jwt;
    using System.Security.Claims;
    using Microsoft.IdentityModel.Tokens;
    using System.Collections.Generic;

    // Load your private key and create signing credentials
    var securityKey = new RsaSecurityKey(yourPrivateRsa);
    var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.RsaSha256);

    var claims = new[] {
            new Claim("partnerId", "your-partner-id"),
            // other claims
    };

    var header = new JwtHeader(credentials);
    header["kid"] = "your-key-id";

    var token = new JwtSecurityToken(
            header,
            new JwtPayload(
                    claims: claims,
                    expires: DateTime.UtcNow.AddMinutes(5),
                    notBefore: null,
                    issuedAt: null,
                    audience: null,
                    issuer: null
            )
    );

    var jwt = new JwtSecurityTokenHandler().WriteToken(token);
    Console.WriteLine(jwt);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    import (
            "fmt"
            "time"
            "github.com/golang-jwt/jwt/v5"
    )

    func main() {
            privateKey := []byte("your-private-key") // Use PEM for RS256/ES256
            claims := jwt.MapClaims{
                    "partnerId": "your-partner-id",
                    "exp":       time.Now().Add(5 * time.Minute).Unix(),
            }
            token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
            token.Header["kid"] = "your-key-id"
            signedToken, err := token.SignedString(privateKey)
            if err != nil {
                    panic(err)
            }
            fmt.Println(signedToken)
    }
    ```

    > **Note:** Replace `"your-partner-id"`, `"your-key-id"`, and private key paths with your actual values. For ES256, use the appropriate signing method and key type.
  </Tab>
</Tabs>


# Reference
Source: https://docs.moca.network/airkit/usage/reference

For server-side credential issuance without user presence, use the Issue on Behalf API:

## REST API

For server-side credential issuance without user presence, use the Issue on Behalf API:

* **Endpoint:** `POST /v1/credentials/issue-on-behalf`
* **Status check:** `GET /v1/credentials/status?coreClaimHash={hash}`
* **Sandbox:** `https://api.sandbox.mocachain.org/v1`
* **Production:** `https://api.mocachain.org/v1`

Authenticate with a Partner JWT in the `x-partner-auth` header. Full endpoint reference and implementation examples: [Issue on Behalf API & Examples](/airkit/usage/credential/issue-on-behalf-api).

***

<Tabs>
  <Tab title="Web">
    ### AirService

    ```ts theme={null}
    class AirService {
      constructor({ partnerId: string; });
      get buildEnv(): BUILD_ENV_TYPE; // available env: SANDBOX
      get isInitialized(): boolean;
      get isLoggedIn(): boolean;
      get isWalletInitialized(): boolean;
      get provider(): EIP1193Provider;
      init({
        buildEnv: BUILD_ENV_TYPE;
        credentialNetwork?: CredentialNetwork;
        enableLogging: boolean;
        skipRehydration: boolean;
        preloadWallet: boolean;
        preloadCredential: boolean;
        sessionConfig?: Partial<AirSessionConfig>;
      }): Promise<AirLoginResult | null>;
      login(options?: { authToken?: string }): Promise<AirLoginResult>;
      isSmartAccountDeployed(): Promise<boolean>;
      deploySmartAccount(): Promise<{ txHash: string }>;
      getProvider(): EIP1193Provider;
      preloadWallet(): Promise<void>;
      preloadCredential(): Promise<void>;
      setupOrUpdateMfa(): Promise<void>;
      getUserInfo(): Promise<AirUserDetails>;
      goToPartner(partnerUrl: string): Promise<{ urlWithToken: string }>;
      getAccessToken(): Promise<{ token: string }>;
      updateSessionConfig(config: Partial<AirSessionConfig>): Promise<AirSessionConfig>;
      showSwapUI(options?: {
        initialFromToken?: string;
        fallbackFromToken?: string;
        initialToToken?: string;
      }): Promise<{ txHash: `0x${string}` }>;
      showOnRampUI(options: {
        displayCurrencyCode: string;
        targetCurrencyCode?: string;
      }): Promise<void>;
      issueCredential({
        authToken: string;
        issuerDid: string;
        credentialId: string;
        credentialSubject: Record<string, unknown>;
        curve?: "secp256r1" | "secp256k1";
      }): Promise<{ cakPublicKey?: string }>;
      verifyCredential({
        authToken: string;
        programId: string;
        redirectUrl?: string;
      }): Promise<CredentialVerificationResult>;
      logout(): Promise<void>;
      cleanUp(): Promise<void>;
      on(listener: AirEventListener): void;
      off(listener: AirEventListener): void;
      clearEventListeners(): void;
    }
    ```

    ### Types

    ```ts theme={null}
    export type AirIdDetails = {
      id: string;
      name?: string;
      node: string;
      status: "minting" | "minted";
      chainId: number;
      imageUrl?: string;
    };

    export type AirUserDetails = {
      partnerId?: string;
      partnerUserId?: string;
      airId?: AirIdDetails;
      user: {
        id: string;
        abstractAccountAddress?: string;
        email?: string;
        isMFASetup: boolean;
      };
    };

    export type AirInitializationResult = {
      rehydrated: boolean;
    };

    export type AirLoginResult = {
      isLoggedIn: boolean;
      id: string;
      abstractAccountAddress?: string;
      token: string;
      isMFASetup: boolean;
    };

    export type AirWalletInitializedResult = {
      abstractAccountAddress: string | null;
      isMFASetup: boolean;
    };

    export type CredentialVerificationResult =
      | {
          status:
            | "Non-Compliant"
            | "Pending"
            | "Revoking"
            | "Revoked"
            | "Expired"
            | "NotFound";
        }
      | {
          status: "Compliant";
          zkProofs: Record<string, string>;
          transactionHash: string;
          cakPrivateKey?: string;
        };

    export type ClaimAirIdResult = {
      airId: AirIdDetails;
    };

    export type AirEventOnInitialized = {
      event: "initialized";
      result: AirInitializationResult;
    };

    export type AirEventOnLoggedIn = {
      event: "logged_in";
      result: AirLoginResult;
    };

    export type AirEventOnAirIdMintingStarted = {
      event: "air_id_minting_started";
    };

    export type AirEventOnAirIdMintingFailed = {
      event: "air_id_minting_failed";
      errorMessage?: string;
    };

    export type AirEventOnLoggedOut = {
      event: "logged_out";
    };

    export type AirEventOnWalletInitialized = {
      event: "wallet_initialized";
      result: AirWalletInitializedResult;
    };

    export type AirEventData =
      | AirEventOnInitialized
      | AirEventOnLoggedIn
      | AirEventOnWalletInitialized
      | AirEventOnAirIdMintingStarted
      | AirEventOnAirIdMintingFailed
      | AirEventOnLoggedOut;

    export type AirEventListener = (data: AirEventData) => void;

    export type CredentialNetwork = "devnet" | "testnet";

    export type SupportedCurrencyCode = "EUR" | "USD" | "CNY" | "KRW" | "TRY";

    export type AirSessionConfig = {
      locale: string;
      currency: SupportedCurrencyCode;
    };

    export type ClaimAirIdOptions =
      | {
          token?: string;
          background?: false;
        }
      | {
          token: string;
          background: true;
        };
    ```
  </Tab>

  <Tab title="Flutter">
    ### AirService

    ```dart theme={null}
    class AirService {

      Stream<AirEvent> get airEvents;

      void on(AirEventListener listener);
      void off(AirEventListener listener);
      void clearEventListeners();

      bool get isInitialized;

      Future<void> initialize({
        required String partnerId,
        Environment env = Environment.production,
        required GlobalKey<NavigatorState> navigatorKey,
        bool enableLogging = false,
      });

      Future<LoginResult> login({
        required String authToken,
        OnOtpRequest? onOtpRequest,
      });

      Future<LoginResult> rehydrate();

      Future<UserInfo> getUserInfo();

      Future<void> preloadWallet();

      Future<String?> getAbstractAccountAddress();

      Future<List<String>> getAccounts();

      Future<void> setupOrUpdateMfa();

      Future<BigInt> getBalance(String address);

      Future<EthereumRpcSuccessResponse> call(
        String address,
        String function,
        List<dynamic> params,
        String abi,
      );

      Future<String> signMessage(String message);

      Future<String> sendTransaction(Transaction transaction);

      Future<EthereumRpcSuccessResponse> sendEthereumRpcRequest(
        EthereumRpcRequest request
      );

      Future<String> deploySmartAccount();

      Future<bool> isSmartAccountDeployed();

      Future<void> showSwapUi();

      Future<void> showOnRampUi({
        required String displayCurrencyCode,
        String? targetCurrencyCode,
      });

      Future<void> logout();

      void cleanup();
    ```

    ### Models

    ```dart theme={null}

    enum Environment { staging, uat, sandbox, production }
    ​
    class LoginResult {
      final bool isLoggedIn;
      final String? id;
      final String? abstractAccountAddress;
      final String? token;
      final bool? isMFASetup;
    }
    ​
    enum AirIdStatus {
      minting,
      minted,
    }
    ​
    class AirId {
      final String id;
      final String name;
      final String node;
      final AirIdStatus status;
      final int? chainId;
      final String? imageUrl;
    }
    ​
    class UserInfo {
      final AirId? airId;
      final String? partnerUserId;
      final String? partnerId;
      final User? user;
    }
    ​
    class User {
      final String id;
      final String? abstractAccountAddress;
      final String? email;
      final bool isMFASetup;
    }
    ​
    class EthereumRpcRequest {
      final String method;
      final List<dynamic> params;
      final String? requestId;
    }

    class EthereumRpcSuccessResponse {
      final dynamic response;
    }

    class AirEvent { }

    class AirInitializedEvent extends AirEvent {}

    class AirLoggedInEvent extends AirEvent {
      final LoginResult payload;
    }

    class AirLoggedOutEvent extends AirEvent { }

    class AirWalletInitializedEvent extends AirEvent { }

    typedef AirEventListener = void Function(AirEvent event);

    enum ExceptionType {
      client,
      sdk,
      server,
      unknown,
    }

    class AirKitException implements Exception {
      final String message;
      final ExceptionType type;
    }
    ```
  </Tab>
</Tabs>


# User Login & Sessions
Source: https://docs.moca.network/airkit/usage/user-authentication

AIR Kit provides out of the box authentication of users. You may use AIR Kit’s authentication system, or use your existing authentication. By using AIR Kit’s authentication, your users will be able to use one single login across our Ecosystem.

## Using AIR Kit as your authentication provider

By default, we provide the following methods for users:

* Google Login
* Passwordless Email Login
* Wallet Login (EOA wallet support)

<Tabs>
  <Tab title="Web">
    ```tsx theme={null}
    login(options?: { authToken?: string }): Promise<AirLoginResult>
    ```
  </Tab>

  <Tab title="Flutter">
    On Flutter, call `login` with a **Partner JWT** after `initialize()`:

    ```dart theme={null}
    Future<LoginResult> login({
      required String authToken,
      OnOtpRequest? onOtpRequest,
    });
    ```

    See [Reference](/airkit/usage/reference) (Flutter tab) and [Flutter overview](/airkit/flutter/overview). Build the JWT using [Partner authentication](/airkit/usage/partner-authentication).
  </Tab>
</Tabs>

* `authToken` : (highly recommended but optional) pass in your [Partner JWT](/airkit/usage/partner-authentication) via the parameter with your `partnerId` inside the payload.
* This would trigger the AIR Kit login dialog with built-in login methods for the user to choose from.

<Info>
  **Session Configuration**

  To configure locale and currency settings, pass `sessionConfig` to the `init()` method. See [Language & Currency Configuration](/airkit/usage/config-language) for details.
</Info>

## Custom Auth (Bring your own Auth)

Instead of using AIR Kit as your authentication provider, AIR Kit supports users that have been already authenticated by your system to skip logging in again when using AIR Kit.

To achieve this, pass in additional properties in the [Partner JWT](/airkit/usage/partner-authentication) during login() , specifically `email` and `partnerUserId` .

When an email is provided, we will verify via a one-time password sent to the specified email since it is used as an identifier in the AIR ecosystem.

An example JWT looks like following:

```json theme={null}
{
  "partnerId": "YOUR PARTNER ID",
  "partnerUserId": "YOUR USER ID", // optional
  "email": "YOUR USER EMAIL", // optional
  "exp": 1728973684,
  "iat": 1728970084
}
```

# User Sessions

After successful login, an `AirLoginResult` object will be returned, which also contains a property `token` generated by us containing the following information:

```json theme={null}
{
  sub: string,
  abstractAccountAddress: string,
  partnerId: string,
  partnerUserId?: string,
  sourcePartnerId?: string
}
```

This token can be used in the future to query some of our sdk functions.

You may validate our token by using the following JWKS endpoint: [https://static.air3.com/.well-known/jwks.json](https://static.air3.com/.well-known/jwks.json)

## Session management

AIR Kit automatically handles session management out of the box. When users return to your app, they would be automatically logged in provided that they have not logged out in the last 30 days.

<Tabs>
  <Tab title="Web">
    * To require users to log in every time they visit your app, set `skipRehydration` to true when initializing the SDK.
    * Call `isLoggedIn` to check the login state of a user.
    * To log out, call `logout()`
    * To update locale or currency settings after initialization, use `updateSessionConfig()`:

    ```tsx theme={null}
    // Update currency or locale
    await airService.updateSessionConfig({
      currency: "EUR",
      locale: "es"
    });
    ```
  </Tab>

  <Tab title="Flutter">
    * To remain logged in (after an app restart), `rehydrate()` can be called to automatically log in a previously logged in user with an existing valid session. Otherwise login() needs to be called.
  </Tab>
</Tabs>

## EOA Wallet Authentication (optional add-on)

EOA-based authentication is available as an optional customization on top of the default AIR Account login flow.
This allows your users to authenticate using any EOA wallet (e.g., MetaMask, Trust Wallet) while still benefiting from the AIR Account identity stack. The EOA wallet is used only for authentication and identity verification. It does not replace the underlying MPC-based account abstraction or control mechanisms. In effect, the wallet address serves purely as a login identifier, while account control remains securely managed by AIR.

### Why enable EOA auth?

* Seamlessly supports existing “Connect Wallet” flows
* Zero disruption to current users
* Adds AIR Account–powered authentication without requiring UX changes
* Works alongside Web2 and other login methods

If your application already uses EOA wallet login, you can enable AIR Account authentication on top of it—ensuring a unified identity experience while preserving your existing flow.

### How to request EOA authentication

EOA auth is not enabled by default.
To enable it for your project, please contact our support team with the following details:

### EOA auth enablement request template

**Subject:** Request to Enable EOA Authentication for \<Project Name >

**Email Body:**

```
Hi Team,

I would like to request **EOA authentication** to be enabled for our project.

**Project Name:**
**Partner ID: (Can be obtained from the Dev dashboard: https://developers.sandbox.air3.com/dashboard/general):**
**Environment:** (Production / Sandbox / Both)

**Current Login Method:**
(e.g., Connect Wallet, Web2 login, AIR Account)

**Reason for Enabling EOA Auth:**
(e.g., we support existing EOA wallet login and want to integrate AIR Account without disrupting our users)

Please let us know if you require any additional information or configuration details.

Thank you!
```


# User Management
Source: https://docs.moca.network/airkit/usage/user-management

AIR Kit provides user management capabilities that allow you to retrieve user information, manage multi-factor authentication (MFA), and handle smart account operations.

## User Information

### getUserInfo()

Retrieves detailed information about the currently logged-in user.

**Method Signature:**

```ts theme={null}
public async getUserInfo(): Promise<AirUserDetails>
```

**Returns:**

```ts theme={null}
{
  partnerId?: string;
  partnerUserId?: string;
  airId?: AirIdDetails;
  user: {
    id: string;
    abstractAccountAddress?: string;
    email?: string;
    isMFASetup: boolean;
  };
}
```

**Requirements:**

* User must be logged in

**Example:**

```ts theme={null}
try {
  const userInfo = await airService.getUserInfo();
} catch (error) {
  console.error("Failed to get user info:", error);
  // Handle error appropriately
}
```

## Multi-Factor Authentication (MFA)

### setupOrUpdateMfa()

Sets up or updates multi-factor authentication for the user's account. This method guides the user through the MFA setup process using passkeys.

**Method Signature:**

```ts theme={null}
public async setupOrUpdateMfa(): Promise<void>
```

**What happens during MFA setup:**

1. The method ensures the wallet is initialized
2. Opens the MFA setup flow and guides the user through passkey creation/verification
3. Updates the user's MFA status in the system, including `loginResult` to reflect the new MFA status

**Requirements:**

* User must be logged in

**Important Notes:**

* **MFA is generally required**: If your dApp doesn't trigger `setupOrUpdateMfa()` after login and the user hasn't set up MFA, it will be triggered automatically with any wallet related request, requiring the user to complete setup before the request can be processed
* **Currently only passkey is supported** as the MFA method
* **Only MFA setup is currently implemented, not updates**: It's recommended to check if the user has already set up MFA before calling this method to avoid unnecessary prompts
* **Abstract Account Address availability**: The abstract account address will only be returned in user info and token if MFA is set up

### MFA Setup Integration

Since MFA is generally required, you can either:

**Option 1: Proactive Setup (Recommended)**

```ts theme={null}
try {
  const userInfo = await airService.getUserInfo();
  if (!userInfo.user.isMFASetup) {
    await airService.setupOrUpdateMfa();
    // Abstract account address will now be available
  }
} catch (error) {
  // Handle error appropriately
}
```

**Option 2: Let AIR Kit Handle Automatically**
Simply proceed with wallet operations - MFA will be prompted automatically if required.


# When to Use (and Not to Use) AIR Credentials
Source: https://docs.moca.network/airkit/when-to-use-airkit

Decision guide for when AIR Kit credentials are a good fit for your use case.

## For Credentials

### When to Use

* When users demand **proof-based access** without sharing sensitive personal data (KYC, gated content, regulatory compliance).
* In ecosystems where **data portability, privacy, and user autonomy** are priorities (gaming, DeFi, Web3, loyalty, education).
* To **unify fragmented user identities** and streamline onboarding across platforms.

### Not Ideal For

* Use cases that require **central authority** over credential storage (e.g., when data value changes very quickly) or where **open, public data access** is necessary.
* **Extremely rapid, low-latency verification flows** where decentralized checks could introduce unacceptable friction (though Moca Chain is optimized for performance).
* Situations where **complex document uploads or visual/manual checks** (outside ZKP-compatible claims) are essential.


# Browse programs
Source: https://docs.moca.network/api-reference/catalog/browse-programs

GET /catalog/programs
Returns a paginated list of verification programs with their total verification count and the number of distinct credential types they accept. Only programs marked as discoverable are included. Results are sortable by `created_at`, `verification_count`, `credential_count`, or `name` (default `created_at`).



# Browse schemas
Source: https://docs.moca.network/api-reference/catalog/browse-schemas

GET /catalog/schemas
Returns a paginated list of credential schemas with their credential count and number of distinct issuers (providers). Only schemas marked as discoverable and enabled are included. Results are sortable by `created_at`, `credential_count`, `provider_count`, or `title` (default `created_at`).



# Credential detail
Source: https://docs.moca.network/api-reference/catalog/credential-detail

GET /catalog/credentials/{id}
Returns a single credential with its full profile: the schema-defined data points (field name, type, required flag), issuer identity (name, DID, origin), traction metrics (unique holders, total issuances, total verifications), linked verification programs, and availability window (accessible start/end, expiration duration, first/last issuance timestamps).



# Program detail
Source: https://docs.moca.network/api-reference/catalog/program-detail

GET /catalog/programs/{id}
Returns a single verification program with the verifier's identity, pricing model, the full list of accepted credentials (each with holder/issuance counts), and the zero-knowledge verification conditions required for each credential (e.g. `age >= 18`).



# Schema detail
Source: https://docs.moca.network/api-reference/catalog/schema-detail

GET /catalog/schemas/{id}
Returns a single schema together with every discoverable credential built on it. Each credential includes issuer info and traction metrics (holder count, issuance count, and demand count — the number of verification programs that accept it).



# Search catalog
Source: https://docs.moca.network/api-reference/catalog/search-catalog

GET /catalog/search
Performs a MySQL full-text search (natural language mode) across three entity types in parallel — credentials (matched on ID, name, category, and schema), issuers (matched on name and short name), and verification programs (matched on program name). Returns grouped results with relevance scores, paginated independently per group.



# Check issuance status
Source: https://docs.moca.network/api-reference/credentials/check-issuance-status

/api-reference/openapi.json get /credentials/status
Returns the current status of a credential issuance. Poll this endpoint after calling Issue on Behalf until `vcStatus` is `ONCHAIN`.



# Check Issuance Status
Source: https://docs.moca.network/api-reference/credentials/get-credential-status

GET /credentials/status
Returns the current status of a credential issuance. Poll this endpoint after calling Issue on Behalf until `vcStatus` is `ONCHAIN`.



# Issue Credential on Behalf
Source: https://docs.moca.network/api-reference/credentials/issue-credential-on-behalf

POST /credentials/issue-on-behalf
Initiates credential issuance for a user without requiring their active session. If the user does not exist, they are automatically created. Issuance is asynchronous — use the status endpoint to confirm the credential is on-chain.



# API Reference
Source: https://docs.moca.network/api-reference/introduction

Server-to-server REST API for credential issuance, status tracking, catalog browsing, and partner operations on the Moca Network.

The Moca Network REST API enables server-to-server operations that do not require user presence. Use it for backend automation, bulk credential issuance, programmatic status checks, and browsing the credential catalog.

## Base URLs

| Environment | Base URL                               |
| ----------- | -------------------------------------- |
| Sandbox     | `https://api.sandbox.mocachain.org/v1` |
| Production  | `https://api.mocachain.org/v1`         |

## Authentication

**Credential endpoints** require a **Partner JWT** passed in the `x-partner-auth` header. The JWT must be signed with your private key (RS256 or ES256) and include:

| Claim       | Required | Description                                   |
| ----------- | -------- | --------------------------------------------- |
| `partnerId` | Yes      | Your Partner ID from the Developer Dashboard  |
| `email`     | Yes      | Target user's email address                   |
| `scope`     | Yes      | Operation scope (e.g. `"issue on-behalf"`)    |
| `exp`       | Yes      | Expiration timestamp (recommended: 5 minutes) |

The JWT header must include `kid` (Key ID) matching a key in your JWKS endpoint and `typ: "JWT"`.

For full setup instructions, key generation, and code examples see [Partner Authentication](/airkit/usage/partner-authentication).

**Catalog endpoints** are public and require no authentication.

**API Playground:** Requests from the Try it out playground are sent directly from your browser to the API. Your API must allow CORS from your docs origin (e.g. your Mintlify subdomain or custom domain) for the playground to work. If you see 403 from the playground, check that the API allows the request origin and that your Partner JWT is valid.

## Credentials

<CardGroup>
  <Card title="Issue credential on behalf" icon="certificate" href="/api-reference/credentials/issue-credential-on-behalf">
    Submit server-side credential issuance for a user without requiring their active session.
  </Card>

  <Card title="Check issuance status" icon="circle-check" href="/api-reference/credentials/get-credential-status">
    Poll the status of an asynchronous credential issuance until it is confirmed on-chain.
  </Card>
</CardGroup>

## Catalog

<Warning>
  **Sandbox only at this stage.** Catalog endpoints are available exclusively on `https://api.sandbox.mocachain.org/v1` during the pilot. They are under active development and may change without notice — not yet available in production.
</Warning>

<CardGroup>
  <Card title="Browse schemas" icon="table-layout" href="/api-reference/catalog/browse-schemas">
    Paginated list of credential schemas with credential count and number of issuers. Sortable by popularity or title.
  </Card>

  <Card title="Schema detail" icon="table-layout" href="/api-reference/catalog/schema-detail">
    Single schema with every credential built on it, including issuer info and traction metrics.
  </Card>

  <Card title="Credential detail" icon="id-badge" href="/api-reference/catalog/credential-detail">
    Full credential profile: data points, issuer identity, holder/issuance/verification metrics, linked programs, and availability window.
  </Card>

  <Card title="Browse programs" icon="list-check" href="/api-reference/catalog/browse-programs">
    Paginated list of verification programs with verification counts and accepted credential types.
  </Card>

  <Card title="Program detail" icon="list-check" href="/api-reference/catalog/program-detail">
    Verification program with verifier identity, pricing model, accepted credentials, and ZK verification conditions.
  </Card>

  <Card title="Search catalog" icon="magnifying-glass" href="/api-reference/catalog/search-catalog">
    Full-text search across credentials, issuers, and programs with relevance-ranked grouped results.
  </Card>
</CardGroup>

## Code examples

For end-to-end integration examples including issue-and-poll flows, webhook-driven issuance, and retry logic, see [Issue on Behalf API & Examples](/airkit/usage/credential/issue-on-behalf-api).


# Moca Network Developer Docs
Source: https://docs.moca.network/index

Build with AIR Kit — the identity SDK for portable credentials, ZK-verified compliance, and seamless user onboarding across any platform.

<div>
  <img />

  <div>
    <div>
      AIR Kit SDK · Moca Chain · Identity Infrastructure
    </div>

    <h1>
      <span>The Identity Layer<br /></span> for the Open Internet
    </h1>

    <p>
      Issue portable credentials, verify users without storing PII, and plug into
      700M+ addressable users — all with a few lines of code.
    </p>

    <div>
      <a href="/airkit/usage/installation">
        Quick Setup →
      </a>

      <a href="/airkit/guides/overview">
        View Architecture
      </a>
    </div>
  </div>
</div>

<div>
  <div>
    <p>
      Get started
    </p>

    <div>
      <CardGroup>
        <Card title="I'm a Partner or Business" icon="building-memo" href="/solutions/index">
          Explore AIR Kit solutions by vertical — loyalty, fintech, gaming, telco, and more. Understand partner economics and compliance.
        </Card>

        <Card title="I'm a developer" icon="rectangle-terminal" href="/airkit/usage/getting-started">
          Install the SDK, authenticate users, and issue your first credential in under 30 minutes.
        </Card>

        <Card title="I'm building on Moca Chain" icon="link-simple" href="/mocachain/index">
          Connect to the L1, run a node, deploy contracts, and explore EVM-compatible tooling on Moca Chain.
        </Card>

        <Card title="I want to understand Moca Network" icon="lightbulb" href="/learn/index">
          Learn about the vision, architecture, and why portable identity matters for the open internet.
        </Card>
      </CardGroup>
    </div>
  </div>

  <div>
    <p>
      Start with your use case
    </p>

    <CardGroup>
      <Card title="KYC & compliance" icon="shield-check" href="/airkit/guides/air-for-fintech">
        Issue KYC credentials from your existing provider webhook — no PII stored, no re-KYC across platforms.
      </Card>

      <Card title="Loyalty programs" icon="gift" href="/airkit/guides/air-for-loyalty">
        Trigger verifiable loyalty credentials from your backend. Let users carry tier status across brands.
      </Card>

      <Card title="Gaming" icon="gamepad-modern" href="/airkit/guides/air-for-gaming">
        Issue achievement credentials and portable player identities. Cross-game SSO with a single AIR Account.
      </Card>

      <Card title="Live events & ticketing" icon="ticket-perforated" href="/airkit/guides/air-for-ticketing">
        Issue attendance credentials at check-in. Gate VIP presales and loyalty tiers to verified fans.
      </Card>

      <Card title="API Reference" icon="diamonds-4" href="/api-reference/introduction">
        Server-to-server REST API for credential issuance, status tracking, and partner operations.
      </Card>

      <Card title="Architecture overview" icon="diagram-project" href="/airkit/guides/overview">
        Data flow, service independence, and technical reference for decision-makers.
      </Card>
    </CardGroup>
  </div>

  <div>
    <p>
      Why <span>AIR Kit</span>
    </p>

    <div>
      <Columns>
        <Card>
          One credential, any verifier in the ecosystem. No re-KYC, no re-registration.
        </Card>

        <Card>
          Issue credentials silently from your backend — no user action required.
        </Card>

        <Card>
          Paymaster covers all on-chain costs — users never touch gas tokens.
        </Card>
      </Columns>
    </div>
  </div>

  <div>
    <a href="https://developers.sandbox.air3.com/dashboard">
      Dashboard ↗
    </a>

    <a href="https://github.com/MocaNetwork">
      GitHub ↗
    </a>

    <a href="https://discord.gg/mocaversenft">
      Discord ↗
    </a>

    <a href="https://twitter.com/Moca_Network">
      X / Twitter ↗
    </a>
  </div>
</div>


# Privacy & Compliance
Source: https://docs.moca.network/learn/advanced-topics/privacy-and-compliance

How AIR Kit protects sensitive user data through encryption, user consent, and the Compliance Access Key (CAK) framework.

AIR Kit is built around a privacy-first architecture. Credentials use zero-knowledge proofs so verifiers receive only boolean results ("compliant" or "non-compliant") without accessing raw personal data. For regulated industries that require verifiers to access underlying identity data, AIR Kit provides an additional layer: the **Compliance Access Key (CAK)** framework.

***

## Compliance Access Key (CAK)

CAK is an optional, consent-gated data access primitive designed for regulated data usage. It enables strong encryption of sensitive personal data during credential issuance and controlled decryption during verification — all driven by explicit user consent.

### The core problem

In finance, digital identity (KYC), and other regulated industries, organizations handle extremely sensitive information: ID cards, passports, facial biometric images, and other compliance data. The challenge is threefold:

1. **Encrypt** raw sensitive data during credential issuance
2. **Store** it securely so no party can read it at rest
3. **Decrypt** it only when a specific Verifier has obtained explicit consent from the user

### How CAK addresses it

CAK introduces a user-consent-driven encryption and decryption process built on four principles:

<CardGroup>
  <Card title="Data protection at rest" icon="lock">
    Sensitive data is encrypted with a temporary CAK public key during issuance. The ciphertext cannot be read by anyone — including the Issuer, the platform, or any storage provider — until a consented Verifier receives the corresponding private key.
  </Card>

  <Card title="User sovereignty" icon="user-shield">
    The user is the ultimate controller. During verification, the user must explicitly approve or deny each Verifier's access request. Without consent, no party can decrypt the data.
  </Card>

  <Card title="Compliance enablement" icon="scale-balanced">
    Encrypted storage, user-controlled access, and traceable authorization records provide technical primitives that support compliance efforts — including audit trails and clear responsibility boundaries.
  </Card>

  <Card title="Separation of concerns" icon="arrows-split-up-and-left">
    Encryption happens at issuance (performed by the Issuer). Decryption authorization happens at verification (executed by the Verifier with user consent). The two steps are separated in time and space, creating a clear audit trail.
  </Card>
</CardGroup>

***

## CAK in the credential lifecycle

CAK spans three phases of the digital credential lifecycle.

### Phase 1: Business configuration

Before any credentials are issued, administrators configure rules in the Developer Dashboard.

| Party        | Action                      | CAK decision                                                          |
| ------------ | --------------------------- | --------------------------------------------------------------------- |
| **Issuer**   | Configure Pricing Schema    | Decide if credentials under this pricing model support CAK encryption |
| **Issuer**   | Create Issuance Program     | Choose whether to enable CAK for this specific program                |
| **Issuer**   | Configure Callback URL      | Set a global HTTPS endpoint to receive authorization notifications    |
| **Verifier** | Create Verification Program | Decide if this program requires the credential to be CAK-encrypted    |

### Phase 2: Credential issuance

When a user applies for a credential (for example, completing a KYC check), the CAK flow adds encryption steps to the standard issuance process.

<Steps>
  <Step title="Key pair generation">
    The Issuance SDK generates a temporary CAK key pair locally by signing with the user's identity wallet.
  </Step>

  <Step title="Public key handoff">
    The SDK returns the CAK public key to the Issuer's backend system.
  </Step>

  <Step title="Data encryption">
    The Issuer encrypts the user's raw data (ID photo, name, biometric images) with the CAK public key.
  </Step>

  <Step title="Encrypted storage">
    The encrypted data is stored in decentralized storage (dStorage on Moca Chain). No party can read it without the corresponding private key.
  </Step>
</Steps>

### Phase 3: Verification and authorization

When a user presents their credential to a Verifier, the CAK flow ensures consent-driven decryption.

<Steps>
  <Step title="Verification initialization">
    The Verifier's backend starts the verification process via the platform API.
  </Step>

  <Step title="User consent">
    The Verification SDK displays a clear authorization statement. The user explicitly grants or denies the Verifier's access to their encrypted data.
  </Step>

  <Step title="Private key generation">
    Upon user consent, the SDK generates the corresponding CAK private key locally.
  </Step>

  <Step title="Data decryption">
    The Verifier receives the private key and uses it to decrypt the user's data, completing the compliance workflow.
  </Step>
</Steps>

<Note>
  The platform's callback mechanism serves only as an authorization event notification and audit signal. It does not contain encrypted data, cryptographic keys, or any information that would enable direct data access.
</Note>

***

## When to use CAK

<Tabs>
  <Tab title="CAK recommended">
    * Raw identity data (ID images, biometric photos) may be accessed by verifiers
    * Multiple verifiers need access to the same underlying data
    * Regulatory auditability is a requirement
    * Your industry requires proof that user consent was obtained before data access
  </Tab>

  <Tab title="CAK not necessary">
    * The credential does not contain raw PII or biometric data
    * No verifier ever requires access to plaintext data
    * The credential is used purely for zero-knowledge attribute proofs (the default AIR Kit flow)
  </Tab>
</Tabs>

***

## Key decisions by party

### For Issuers

| Decision                            | Options                   | Impact                                                                                                                                        |
| ----------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable CAK for a pricing schema?    | Yes / No                  | Top-level switch — determines whether CAK-enabled credentials can be issued under this pricing model                                          |
| Enable CAK for an issuance program? | Yes / No                  | **Yes:** SDK generates a key pair and returns the public key for encryption. **No:** Standard issuance flow                                   |
| Configure a callback URL?           | Provide URL / Leave blank | **Provide URL:** Real-time notifications about which user authorized which verifier, critical for auditing. **Leave blank:** No notifications |

### For Verifiers

| Decision                                | Options                | Impact                                                                                                                              |
| --------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Require CAK for a verification program? | Yes / No               | **Yes:** Only CAK-encrypted credentials accepted; user consent flow is mandatory. **No:** Both CAK and non-CAK credentials accepted |
| Which Issuers to select?                | CAK-enabled only / All | If CAK is required, only Issuers with CAK enabled are available as partners                                                         |

### For Users (Holders)

| Decision                | Options      | Impact                                                                                                                                                                                |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorize the Verifier? | Agree / Deny | **Agree:** Verifier gains one-time decryption ability. **Deny:** Verification aborted, data stays encrypted, but the user may be unable to complete their business with that Verifier |

***

## Glossary

| Term          | Definition                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------ |
| **CAK**       | Compliance Access Key — an optional, user-consent-driven encryption framework              |
| **Issuer**    | An entity that issues credentials (e.g., a KYC provider)                                   |
| **Verifier**  | An entity that verifies credentials to grant access to a service (e.g., a crypto exchange) |
| **Holder**    | The end-user who owns and controls their credentials and data                              |
| **dStorage**  | Decentralized Storage on Moca Chain, used for storing encrypted data packages              |
| **ECIES**     | Elliptic Curve Integrated Encryption Scheme — a hybrid encryption scheme using ECC         |
| **SECP256R1** | The elliptic curve (P-256) used for CAK key generation                                     |

***

## Next steps

For technical integration details, see the AIR Kit developer documentation:

<CardGroup>
  <Card title="CAK overview" icon="key" href="/airkit/usage/credential/cak-overview">
    Technical architecture and lifecycle
  </Card>

  <Card title="Issuer guide" icon="file-certificate" href="/airkit/usage/credential/cak-issuer-guide">
    Dashboard setup, SDK integration, callback implementation
  </Card>

  <Card title="Verifier guide" icon="magnifying-glass" href="/airkit/usage/credential/cak-verifier-guide">
    Consent flow, decryption, security best practices
  </Card>
</CardGroup>


# Scaling and Performance
Source: https://docs.moca.network/learn/advanced-topics/scaling-and-performance

Scaling and Performance documentation for AIR Kit and Moca Network.

<Warning>**Coming Soon**</Warning>


# zkTLS: Secure Web2 → On-Chain Proofs
Source: https://docs.moca.network/learn/advanced-topics/zktls

How zkTLS bridges Web2 data sources to on-chain verifiable proofs, enabling secure identity onboarding without exposing raw data.

One of the critical challenges in decentralized identity is bridging the gap between **Web2 data sources** (e.g., social accounts, emails, KYC providers) and **Web3 smart contracts** without compromising privacy.

**zkTLS (Zero-Knowledge Transport Layer Security)** solves this problem by enabling verifiable proofs of HTTPS interactions, allowing on-chain applications to trust data from Web2 endpoints without exposing the underlying payload.

## How zkTLS Works

1. **TLS Handshake Capture**
   * When a client communicates with a Web2 service (e.g., an email provider), the TLS handshake and session are cryptographically captured.

2. **Proof Generation**
   * A **zero-knowledge proof** is constructed showing that the interaction took place with the genuine server, over HTTPS, with specific outputs (e.g., "this email is verified").
   * Importantly, the raw data exchanged remains private.

3. **On-Chain Verification**
   * The ZK proof is submitted to a smart contract, which verifies the claim without needing access to the underlying data.

## Key Advantages

* **Privacy-Preserving**\
  Users can prove statements about their Web2 accounts (like GitHub activity, employment, or KYC status) without exposing personal details.

* **Trustless Bridging**\
  Eliminates the need for centralized verification intermediaries between Web2 and Web3.

* **Interoperability**\
  Works across diverse Web2 data sources and can integrate with multiple blockchains.

* **Compliance-Ready**\
  Sensitive data never leaves the user’s control, reducing liability for dApps and partners.

## Example Use Cases

* **Proof of Humanity**: Verifying a user’s email or social profile to prevent bots.
* **KYC/AML**: On-chain DeFi protocols can accept compliance proofs without storing user passports or IDs.
* **Reputation Systems**: Bringing provable GitHub or LinkedIn credentials into decentralized professional networks.


# AIR Kit
Source: https://docs.moca.network/learn/airkit/about-airkit

AIR Kit is the comprehensive developer toolkit for integrating secure, decentralized identity features into your applications. It simplifies complex c

AIR Kit is the comprehensive developer toolkit for integrating secure, decentralized identity features into your applications. It simplifies complex concepts like **Web3 login**, **user onboarding**, and **zero-knowledge proofs**, making them accessible for all developers and users.

AIR Kit provides two powerful services:

1. **AIR Account Services**
   * Manage user login and Single Sign-On (SSO)
   * Wallet management and services

2. **AIR Credential Services**
   * Issue, verify, and consume **zero-knowledge credentials**
   * Portable credentials that users can carry anywhere

## Who Is This For?

AIR Kit is suitable for any platform where **trust, privacy, and user context** matter:

* Founders building consumer apps who want to skip traditional KYC
* DAOs needing pseudonymous membership tools
* Game developers porting player identities and badges across worlds
* Fintech teams verifying income, age, or credentials **without storing PII**
* AI agents requiring verifiable access and behavioral reputation

## The Big Idea: Identity as a Primitive

By making identity **modular, portable, and verifiable**, AIR Kit enables new types of applications:

* Reward **real participation** with airdrops
* Launch apps **without starting from zero users**
* Grow communities **without re-KYCing everyone**

> With AIR Kit, identity becomes a core building block rather than an afterthought. Plug in the SDK, remix credentials, and design new experiences.

To learn more about AIR Kit, head over to the [AIR Kit section](/airkit) of the docs


# Credential Issuance, Verification & ZK Proof Flow
Source: https://docs.moca.network/learn/airkit/credentials

This guide provides a comprehensive overview of the credential lifecycle in AIR Kit, from issuance through verification, with a focus on zero-knowledg

This guide provides a comprehensive overview of the credential lifecycle in AIR Kit, from issuance through verification, with a focus on zero-knowledge proof generation and validation.

## Overview of the Credential Flow

The AIR Kit credential system follows a three-phase lifecycle:

1. **Issuance Phase**: Creating and issuing verifiable credentials
2. **Storage & Management Phase**: Secure storage and lifecycle management
3. **Verification Phase**: Privacy-preserving verification using zero-knowledge proofs

```mermaid theme={null}
graph TD
    A[Identity Provider] --> B[Credential Issuance]
    B --> C[Credential available on Moca Chain]
    C --> D[ZK Proof Generation]
    D --> E[Proof Submission]
    E --> F[Verification]
    F --> G[Verification Compliant / Non Compliant]

    B --> H[Credential Registry]
    H --> F
```

For detailed implementation guides, see the [Credential Services](/airkit/usage/credential/credentials-flow) documentation.


# Features & Developer Benefits
Source: https://docs.moca.network/learn/airkit/features-developer-benefits

AIR Kit features for developers: plug-and-play integration, zero-knowledge privacy, testing tools, and custom credential schemas.

## Core Features

### 1. Plug-and-Play Integration

Pre-built components and templates for rapid deployment:

* **Familiar APIs**: Standard patterns with well-documented interfaces
* **Template Gallery**: Pre-built issuer and verifier templates to start from

### 2. Zero-Knowledge Privacy

Built-in zero-knowledge proof capabilities:

* **Privacy by Design**: No need to handle sensitive user data
* **Compliance Support**: Designed to support GDPR and CCPA compliance requirements
* **Flexible Disclosure**: Users control what information to share

## Developer Experience Features

### Development Tools

```bash theme={null}
# AIR Kit CLI for development
npm install @mocanetwork/airkit
```

<Info>Refer to this [Quickstart](/airkit/quickstart) guide to get started.</Info>

### Testing & Debugging

* **Sandbox Environment**: Safe testing without affecting production (available in the SDK after initializing)
* **Mock Data Generation**: Realistic test data for development
* **Developer Dashboard**: manage account and credentials config in the [AIR Kit Dashboard](https://developers.sandbox.air3.com/dashboard)

## Performance Benefits

### Speed Optimizations

* **Sub-second Verification**: Credential verification in under 100ms
* **Batch Operations**: Process thousands of credentials simultaneously

## Advanced Features

### Custom Credential Schemas

Define your own credential types with custom attributes:

<div>
  <img alt="Create schema" />
</div>

## Getting Started Benefits

### Onboarding Experience

* **5-Minute Setup**: Get started with minimal configuration
* **Interactive Tutorials**: Learn by doing with guided examples
* **Template Gallery**: Choose from pre-built application templates
* **Migration Tools**: Easy migration from existing identity systems

### Support & Community

* **Telegram Dev Support**: Reach out to us on TG when you need help
* **Developer Community**: Active Discord community


# Integration Workflow
Source: https://docs.moca.network/learn/airkit/integration-workflow

This guide provides a step-by-step workflow for integrating AIR Kit into your application. Whether you're building a new application or adding identit

This guide provides a step-by-step workflow for integrating AIR Kit into your application. Whether you're building a new application or adding identity features to an existing one, this workflow will help you get up and running quickly.

## Prerequisites

Before starting the integration, ensure you have:

* **Node.js 18+** or your preferred runtime environment
* **Basic understanding** of your application's authentication flow
* **Development environment** set up for your chosen platform

## Integration Overview

The AIR Kit integration follows a structured approach:

1. **Setup & Configuration** - Install SDKs and configure your environment
2. **Issuer Integration** - Set up credential issuance capabilities
3. **User Wallet Integration** - Enable users to store and manage credentials
4. **Verification Integration** - Implement privacy-preserving verification
5. **Testing & Deployment** - Test your integration and deploy to production

```mermaid theme={null}
graph LR
    A[Setup] --> B[AIR Account integration]
    B --> C[Onboard user using global AIR account]
    C --> D[Issue credential on Moca chain]
    D --> E[Verification]
    E --> F[Testing]
    F --> G[Production]
```

Learn more about how to integrate the SDKs in the [Quickstart](/airkit/quickstart/) section.

Once you've successfully integrated AIR Kit into your application, here are some next steps to consider:

1. **Explore Advanced Features**: Read more about [advanced topics](/learn/advanced-topics/zktls) for more sophisticated use cases
2. **Understand the Flow**: Deep dive into [Credential Issuance, Verification & ZK Proof Flow](/airkit/how-to-use)
3. **Join the Community**: Connect with other developers and get support on [Discord](https://discord.com/invite/mocaversenft)
4. **Support**: [support@moca.network](mailto:support@moca.network)


# Key Modules
Source: https://docs.moca.network/learn/airkit/key-features

AIR Kit is built around core modules for credential management, identity, and developer tools.

AIR Kit is built around several core modules that work together to provide identity and credential management. Each module can be used independently or combined.

## Core Modules Overview

### 1. Credential Management Module

The Credential Management Module handles the complete lifecycle of verifiable credentials:

* **Credential Issuance**: Create and issue verifiable credentials with cryptographic signatures
* **Credential Storage**: Secure storage and retrieval of credentials
* **Credential Verification**: Validate the authenticity and integrity of credentials
* **Credential Revocation**: Manage credential lifecycle including revocation capabilities

### 2. Identity Module

Secure user authentication and identity management:

* **Multi-Factor Authentication**: Support for various authentication methods
* **Biometric Integration**: Secure biometric data handling and verification
* **Identity Linking**: Connect multiple credentials to a single identity
* **Session Management**: Secure session handling and token management

### 3. Developer Tools & SDKs

Development toolkit for integration:

* **TypeScript SDK**: Full-featured SDK for web applications
* **Mobile SDKs**: Flutter SDK

## Performance & Scalability

Each module is optimized for performance:

* **Credential Operations**: High-throughput credential processing at scale
* **ZK Proof Generation**: Optimized proof generation for common circuits
* **Verification Speed**: Fast verification for real-time user flows
* **Storage Throughput**: Scalable storage for high-volume credential workloads

## Security Features

* **End-to-End Encryption**: All data encrypted in transit and at rest
* **Zero-Knowledge Proofs**: Privacy-preserving verification without exposing underlying data
* **On-Chain Anchoring**: Credential hashes anchored to Moca Chain for tamper-evidence


# Build on Moca
Source: https://docs.moca.network/learn/build-on-moca

Moca Network is open for building. Whether you're creating identity solutions, games, financial products, or cross-platform loyalty systems, Moca Chain provides an EVM-compatible foundation with built-in identity and credential infrastructure.

## Get Started

<CardGroup>
  <Card title="AIR Kit Quickstart" icon="rocket" href="/airkit/quickstart">
    Integrate identity and credential services into your app.
  </Card>

  <Card title="Moca Chain" icon="link" href="/mocachain">
    Deploy smart contracts and run nodes on Moca Chain.
  </Card>

  <Card title="Programs & Events" icon="calendar" href="/learn/programs-events">
    Hackathons, grants, and developer support.
  </Card>

  <Card title="Integration Guides" icon="puzzle-piece" href="/airkit/guides/overview">
    Step-by-step guides for loyalty, fintech, gaming, and more.
  </Card>
</CardGroup>


# Core Problems
Source: https://docs.moca.network/learn/core-problems-addressed

Core problems addressed by Moca Network

Digital identity today is broken. It is fragmented, insecure, and often exploited by centralized platforms. Moca Network addresses these core problems to create a foundation for a safer, more user-empowered digital world.

## 1. Fragmented Identities Across Platforms

❌ Every app or service creates its own login and profile, forcing users to manage dozens of credentials.\
✅ With **AIR ID**, users get one persistent, self-sovereign identity that works seamlessly across apps, games, wallets, and services.

## 2. Data Exploitation

❌ Centralized platforms sell and exploit user data without consent, while individuals have little visibility or control.\
✅ Moca flips the model—data stays with the user. With **zero-knowledge proofs** and decentralized storage, users can prove facts about themselves without exposing sensitive data.

## 3. Lack of Trust and Verification

❌ Online interactions often suffer from fake accounts, unverifiable claims, and lack of authenticity.\
✅ By making identity and credentials programmable, Moca enables **trustworthy, verifiable interactions**—from proving age in gaming, to credentials in education, to compliance in finance.

## 4. Siloed Ecosystems and Poor Interoperability

❌ Credentials and profiles don’t travel across platforms, creating friction for users and limiting developer reach.\
✅ With **EVM compatibility** and **cross-chain identity oracles**, Moca makes identity portable across Ethereum, L2s, and beyond—ensuring no ecosystem lock-in.

## 5. Rising Privacy and Compliance Risks

❌ Regulations like GDPR and new global privacy laws demand stricter data protection, but current infrastructures are ill-suited for compliance at scale.\
✅ Moca provides **privacy-first, regulation-aware design**, anchoring only metadata on-chain while giving users control over where their data lives.

## The Impact

By addressing these problems head-on, Moca Network enables:

* **Users** to reclaim ownership of their digital selves
* **Developers** to build identity-first, interoperable apps
* **Partners and investors** to participate in the creation of a scalable, privacy-preserving identity layer for the internet


# Moca Network Frequently Asked Questions
Source: https://docs.moca.network/learn/help/faq

Moca's FAQs

<Accordion title="What makes Moca different from generic L1 chains?">
  Moca Chain is an EVM-compatible L1 purpose-built for decentralized identity. Moca Chain is designed with identity at its core, making credentials portable and verifiable across chains. It puts privacy first with ZKPs and zkTLS, ensures resilient decentralized storage for credentials, and stays developer-friendly through full EVM compatibility. With \~1s block times and instant finality, it delivers the speed and reliability needed for real-world identity use cases. Read more <a href="/mocachain/why-mocachain">here</a>.
</Accordion>

<Accordion title="How are credentials issued and stored?">
  Read more about the credential issuance process <a href="/airkit/usage/credential/credentials-flow#issuer-process">here</a>

  <br />

  Read more about the credential verification process <a href="/airkit/usage/credential/credentials-flow#verifier-process">here</a>
</Accordion>

<Accordion title="Does it cost anything to issue and verify credentials?">
  Both credential issuance and verification can incur on-chain gas fees, hence the <a href="/airkit/airkit-dashboard">developer dashboard</a> provides a dedicated wallet that verifiers can pre-fund with \$MOCA.
</Accordion>

<Accordion title="How do I get \$MOCA?">
  As Moca Chain is currently in Testnet, you will only be able to get \$MOCA in our Testnet faucet. See <a href="/mocachain/using-moca-chain/how-to-get-moca">How to get \$MOCA</a> for details.
</Accordion>


# What is Moca Network?
Source: https://docs.moca.network/learn/index

Moca Network is a chain-agnostic decentralized identity network with privacy-preserving infrastructure for identity verifications and data interoperability.

Moca Network is a chain-agnostic decentralized identity network with privacy-preserving infrastructure for identity verifications and interoperability of users and data across industries and ecosystems. Seeded by Animoca Brands, Moca Network connects over 570 portfolio companies and a diverse range of enterprise partners. Moca Network uses [\$MOCA](/learn/moca-coin) as its utility and governance token.

* Users can present proofs about themselves — such as age, qualifications, and memberships — without revealing sensitive raw data.
* Developers can build interoperable apps where identity is a first-class citizen.

## What Comprises the Moca Network?

**Moca Network** = [**Moca Chain**](/mocachain/) + [**AIR Kit**](/airkit/)

Identity should not be fragmented, siloed, or extracted — it should be owned, portable, and foundational to every interaction in the digital world. Moca Network makes this possible through two core components:

* **Moca Chain**: The decentralized blockchain infrastructure providing secure, interoperable, and programmable identity storage.
* **AIR Kit**: An SDK for integrating secure, decentralized identity features into your applications.


# Integrate Using AI
Source: https://docs.moca.network/learn/integrating-using-ai

Connect Moca Network documentation to AI tools for contextual, up-to-date answers about Moca Network, Moca Chain, and AIR Kit.

Connect Moca Network documentation to your AI tools to get contextual, up-to-date answers about Moca Network, Moca Chain, and AIR Kit. When you connect the MCP server, AI assistants can search the documentation directly instead of relying on training data.

## What is MCP?

The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and external services, like documentation. When an AI application connects to your documentation MCP server, it can search your documentation directly in response to your prompts instead of relying on information from its training data or making a generic web search.

Your MCP server provides access to all indexed content on the Moca Network documentation site. AI applications determine when to use the search tool based on the context of the conversation and the relevance of the documentation.

<Tip>
  You can also use the contextual menu on any page of the documentation to copy the MCP server URL or install it directly into Cursor or VS Code.
</Tip>

## Connect to the MCP server

Connect the Moca Network documentation MCP server to your preferred AI tool:

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Add the Moca Network MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Moca Network MCP server:
           * Name: `MocaNetwork`
           * URL: `https://docs.moca.network/mcp`
        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the MocaNetwork MCP server.
        3. Ask Claude a question about Moca Network or AIR Kit.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Add the MCP server to Claude Code">
        Run the following command:

        ```bash theme={null}
        claude mcp add --transport http MocaNetwork https://docs.moca.network/mcp
        ```
      </Step>

      <Step title="Test the connection">
        Verify the connection by running:

        ```bash theme={null}
        claude mcp list
        ```
      </Step>
    </Steps>

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This opens the `mcp.json` file.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "MocaNetwork": {
              "url": "https://docs.moca.network/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the MocaNetwork MCP server as an available tool.
      </Step>
    </Steps>

    See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Get your MCP server URL">
        Your MCP server URL is: `https://docs.moca.network/mcp`
      </Step>

      <Step title="Create MCP configuration">
        Create a `.vscode/mcp.json` file in your project root.
      </Step>

      <Step title="Configure the Moca Network MCP server">
        In `.vscode/mcp.json`, add:

        ```json theme={null}
        {
          "servers": {
            "MocaNetwork": {
              "type": "http",
              "url": "https://docs.moca.network/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

## Setup with other agents

The Moca skill works with any tool that supports the [Agent Skills](https://agentskills.io/home) standard, including Cursor, VS Code Copilot, Gemini CLI, OpenAI Codex, and more.

Run:

```bash theme={null}
npx skills add https://docs.moca.network
```

The CLI detects your installed agents and places the skill in the correct directory for each one.

## What the skill provides

| Feature                | Description                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| Quick references       | Curated links across Moca Chain, AIR Kit, and API docs—where to go next from a single index               |
| Decision guidance      | When to explore Moca Chain vs AIR Kit first, and how identity, credentials, and chain pieces fit together |
| Workflows              | High-level paths for understanding the network, then diving into integration quickstarts                  |
| Common gotchas         | Pointers into troubleshooting and “when to use” guides so agents avoid common integration mistakes        |
| Verification checklist | Pre-flight questions: which product surface, environment, and doc set match your use case                 |

## Static docs files

If your AI tool does not support MCP yet, you can use one of Moca Network's static documentation files instead.

<Warning>
  Static files are snapshots and may not include the latest updates. Use MCP when possible for always-current docs.
</Warning>

## Which file should I use?

* **`llms.txt`** — A curated overview of Moca Network. Use it to route an agent to the right docs, understand product structure, and choose the right integration path.
* **`llms-full.txt`** — A full static snapshot of the documentation. Use it when your tool needs more exhaustive reference material in one file.

## Setup with Cursor

<Steps>
  <Step title="Open docs settings">
    Go to **Settings** → **Features** → **Docs**.
  </Step>

  <Step title="Add the overview file">
    Click **Add new doc** and paste: `https://docs.moca.network/llms.txt`
  </Step>

  <Step title="Optionally add the full snapshot">
    If your agent needs deeper static reference coverage, add: `https://docs.moca.network/llms-full.txt`
  </Step>

  <Step title="Reference in chat">
    Use **@docs** → **Moca** in your AI chat to reference the documentation.
  </Step>
</Steps>

## Setup with Claude Desktop

<Steps>
  <Step title="Download the overview file">
    Download the curated overview from: [https://docs.moca.network/llms.txt](https://docs.moca.network/llms.txt)
  </Step>

  <Step title="Optionally download the full snapshot">
    Download the full documentation snapshot from: [https://docs.moca.network/llms-full.txt](https://docs.moca.network/llms-full.txt)
  </Step>

  <Step title="Add to your project">
    Save one or both files in your project directory or another known location on your system.
  </Step>

  <Step title="Reference in chat">
    Drag and drop the file into your Claude Desktop chat, or use the attachment button to upload it. Claude will then have access to the uploaded Moca Network documentation context for that conversation.
  </Step>
</Steps>


# What is Moca Chain?
Source: https://docs.moca.network/learn/moca-chain

Moca Chain is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, with fast block times and built-in decentralized storage.

[Moca Chain](/mocachain/) is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, enabling chain-agnostic identity data issuance and verifications.

Its architecture centers on scalable transaction throughput, fast block times, and permissionless participation for both users and ecosystem partners.

## Key Features

* **Fast block times** (\~1 second) with instant finality via CometBFT consensus
* **Purpose-built for identity** — optimized for credential issuance, verification, and storage
* **Decentralized storage** — built-in MCSP network for credential data

## Goals of the Chain

* **Identity Interoperability:** A unified identity across ecosystems, reducing fragmentation.
* **Data Storage & Security:** Privacy-preserving mechanisms like zero-knowledge proofs (ZKPs) and encryption within its protocol alongside its data storage layer.
* **Holder-Centric Economy:** Users control and monetize their data held in their own crypto wallet.

## Key Components

Moca Chain's architecture comprises two interconnected components:

1. **EVM-Compatible Blockchain** — Solidity-compatible smart contract execution layer
2. **Moca Chain Storage Providers (MCSPs)** — Decentralized storage network for credential data

At its heart, Moca Chain operates on a [Proof-of-Stake (PoS) consensus](/mocachain/technical-details/consensus-layer) using CometBFT (formerly Tendermint), producing blocks every second for high throughput.

It uses [\$MOCA](/learn/moca-coin) for gas fees, governance, staking, and storage operations, ensuring economic alignment among stakeholders.

To learn more about Moca Chain, head over to the [Moca Chain section](/mocachain) of the docs.


# $MOCA Token
Source: https://docs.moca.network/learn/moca-coin

$MOCA is the utility and governance token of the Moca Network, powering an identity-driven data economy and aligning participants through the Proof-of-Data model.

\$MOCA is the utility and governance token of the Moca Network, powering an identity-driven data economy. It is used to pay network fees for credential operations such as issuing, updating, and verifying credentials, and it is staked by core network participants to secure the system and enable services.

## Proof-of-Data model

Within Moca's Proof-of-Data model, \$MOCA aligns incentives across the ecosystem:

### Validators

Validators stake \$MOCA to participate in consensus, secure the network, and process transactions. Validators earn rewards and transaction fees, and may be subject to slashing for malicious or negligent behavior (for example double-signing or extended downtime).

### Storage providers (MCSP)

Storage providers (MCSP) stake \$MOCA to back decentralized credential data storage. Staking helps align reliability and integrity, and storage providers may be subject to slashing if they fail to meet availability, reliability, or data integrity requirements.

### Issuers

Issuers stake \$MOCA to register and issue credentials, and can earn revenue as their credentials are verified.

### Verifiers

Verifiers validate credentials and may stake \$MOCA to qualify for subsidy incentives that reduce effective verification costs.

### Governance participants

Governance participants can lock \$MOCA to receive veMOCA, which is used to vote on incentives and guide ecosystem priorities.

As credential adoption grows, demand for \$MOCA scales with real network usage through transaction fees, staking requirements, and governance participation.


# Programs & Events
Source: https://docs.moca.network/learn/programs-events

Hackathons, developer support, and grant programs for building on Moca Network.

## Hackathons & Hacker Houses

Moca Network organizes hackathons and hacker houses globally. These events provide opportunities to:

* Collaborate with other builders
* Connect with the Moca core team
* Accelerate your project from concept to prototype

### Recaps

* [Identity House Dev Projects](https://x.com/Moca_Network/status/1941067219494187255)
* [Identity House Video](https://x.com/GoKiteAI/status/1950537611916824981)
* [Online Buildathon Dev Projects](https://x.com/akindo_io/status/1981560699135647988)

<Tip>
  Hackathons are also a way to gain visibility for your project and attract early collaborators.
</Tip>

## Developer Support

The team offers dedicated technical support through every stage of development:

* Initial setup and AIR Kit integration
* Understanding how the identity stack fits your project
* Scaling your application

<Tip>
  Reach out early — even small questions can save weeks of development time.
</Tip>

## Grant Programs

<Warning>Coming Soon</Warning>

A grant program to fund promising projects building on Moca Chain is in development.


# Credential Security
Source: https://docs.moca.network/learn/security/credential-security

How credentials are issued, anchored on-chain, and verified without exposing personal data.

Verifiable credentials on Moca Network are designed to be tamper-evident, privacy-preserving, and portable across any verifier in the ecosystem.

## Issuance integrity

When a credential is issued:

1. The issuer signs the credential data with their DID (Decentralized Identifier).
2. A cryptographic proof of the credential is generated and submitted to Moca Chain.
3. The credential is written to on-chain storage. The `vcStatus` transitions from `WAIT_ONCHAIN` to `ONCHAIN` once confirmed.

The on-chain proof acts as a tamper seal. If the credential data is modified after issuance, any verification attempt will fail because the proof no longer matches.

## Zero-knowledge verification

By default, credential verification uses zero-knowledge proofs (ZKPs). This means:

* The verifier asks a question: "Does this user hold a valid credential matching schema X?"
* The user's device generates a ZK proof that answers "yes" or "no" without revealing the underlying data.
* The verifier receives the boolean result and the on-chain proof hash — nothing else.

No PII is transmitted during verification. The verifier cannot reconstruct the original credential data from the proof.

## Selective disclosure

ZK proofs can verify individual attributes without revealing the full credential. For example, a credential containing `age`, `country`, and `kycLevel` can prove that `kycLevel >= 2` without revealing the user's age or country.

Selective disclosure is defined at the schema and verification program level. See [Schema Design](/airkit/usage/credential/schema-overview) for configuration.

## Credential revocation

Issuers can revoke credentials at any time. Revocation is recorded on-chain and takes effect immediately — any subsequent verification against a revoked credential will fail.

When using [Issue on Behalf](/airkit/usage/credential/issue-on-behalf) with `onDuplicate: "revoke"`, the old credential is automatically revoked before the new one is issued.

## Regulated data access (CAK)

For industries where verifiers must access raw data (e.g. identity photos for KYC), the [Compliance Access Key (CAK)](/learn/advanced-topics/privacy-and-compliance) framework adds a consent-gated encryption layer. Data is encrypted at issuance and only decryptable by a verifier who has obtained explicit user consent.

## Credential storage

| Storage layer            | What is stored                      | Encrypted?                        |
| ------------------------ | ----------------------------------- | --------------------------------- |
| Moca Chain (on-chain)    | Credential proofs and state anchors | N/A — proofs are hashes, not data |
| dStorage (decentralized) | Full credential payload             | Yes, if CAK is enabled            |
| User device              | Private keys, session tokens        | Yes, managed by MPC shards        |

## Further reading

* [Privacy & Compliance (CAK)](/learn/advanced-topics/privacy-and-compliance) for the full encryption framework
* [zkTLS](/learn/advanced-topics/zktls) for the zero-knowledge transport layer
* [Schema Design](/airkit/usage/credential/schema-overview) for defining verifiable attributes


# Data Privacy
Source: https://docs.moca.network/learn/security/data-privacy

Where data lives, what is encrypted, and who can access what in the Moca Network architecture.

Moca Network follows a privacy-by-design approach. User data is minimized at every layer, and access is gated by cryptographic controls and explicit user consent.

## Data minimization

The default AIR Kit integration stores the minimum data necessary:

| Data type                   | Stored by Moca?         | Notes                                                            |
| --------------------------- | ----------------------- | ---------------------------------------------------------------- |
| User email                  | Yes (hashed identifier) | Used as the AIR Account identifier for cross-partner portability |
| Credential claims           | On-chain proof only     | Raw claim data is not stored on-chain unless CAK is enabled      |
| Private keys                | No                      | Keys are split via MPC; no single party holds a full key         |
| Transaction data            | On-chain                | Standard blockchain transaction visibility                       |
| PII (ID photos, biometrics) | Only if CAK is enabled  | Encrypted in dStorage, accessible only with user consent         |

## Who can access what

### Without CAK (default)

In the default zero-knowledge flow:

* **Issuers** know the data they put into the credential (they are the source of truth).
* **Verifiers** receive only boolean ZK proof results. They never see raw claim data.
* **Moca Network** sees on-chain proof hashes. It cannot reconstruct credential content.
* **Users** hold the credential in their AIR Account and control when and to whom it is presented.

### With CAK enabled

When the Compliance Access Key framework is active:

* **Issuers** encrypt raw data with a user-derived public key before storing it. After issuance, the issuer cannot read it back.
* **Verifiers** can decrypt raw data only after the user grants explicit consent in the SDK UI. Consent is per-verifier and per-session.
* **dStorage** holds encrypted blobs. Storage providers cannot decrypt them.
* **Users** are the only party who can authorize decryption by generating the corresponding private key locally.

See [Privacy & Compliance (CAK)](/learn/advanced-topics/privacy-and-compliance) for the full framework.

## Data residency

* **On-chain data** (proofs, state anchors, transaction records) lives on Moca Chain and is globally replicated across validators.
* **Encrypted payloads** (CAK) are stored in decentralized storage (dStorage) on Moca Chain.
* **Session tokens and MPC key shards** are stored on the user's device and in secure execution environments. They are not centrally stored.

## User control

Users can:

* **Revoke consent** — If a user previously authorized a verifier, they can deny future requests.
* **Export keys** — Users can export their wallet private key for portability.
* **Delete their account** — Account deletion removes the user's session and local key material. On-chain proofs remain (blockchains are append-only), but they cannot be linked back to the user without the account.

## Compliance considerations

Moca Network provides technical primitives (encryption, consent management, audit trails) that support compliance frameworks such as GDPR, CCPA, and industry-specific regulations. The [Security Checklist](/learn/security/security-checklist) covers integration best practices for maintaining compliance.

<Warning>
  Moca Network provides infrastructure and tooling. Compliance responsibility ultimately lies with the issuer and verifier organizations. Consult legal counsel for your specific regulatory requirements.
</Warning>


# Security Overview
Source: https://docs.moca.network/learn/security/overview

How the Moca Network protects user identity, credentials, and data through its layered security architecture.

Moca Network is an identity infrastructure platform. Security is foundational to every design decision — from how credentials are issued to how keys are managed and how data flows between parties.

## Trust model

Moca Network uses a **split-trust architecture** where no single party holds enough information to compromise a user's identity or access their data:

| Party             | What they hold                                              | What they cannot do                                                                              |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **User (Holder)** | Private keys, consent authority, credential wallet          | Cannot forge credentials or bypass schema rules                                                  |
| **Issuer**        | Authority to issue credentials, CAK public key (if enabled) | Cannot read encrypted data after issuance, cannot impersonate users                              |
| **Verifier**      | Verification programs, ZK proof results                     | Cannot access raw data without user consent (CAK), cannot see data beyond what the proof reveals |
| **Moca Chain**    | On-chain credential proofs, state anchors                   | Cannot reconstruct private keys or decrypt stored data                                           |
| **dStorage**      | Encrypted credential payloads                               | Cannot decrypt without the user-consented key                                                    |

## Security layers

### Zero-knowledge proofs

Credential verification uses ZK proofs by default. When a user presents a credential, the verifier receives a boolean result ("this claim is true") without accessing the underlying personal data. No PII crosses the wire during standard verification.

### MPC-based key management

User accounts are backed by multi-party computation (MPC). Private keys are never held in one place — shards are distributed so that no single party (including Moca) can reconstruct the key. Keys are only assembled in a secure execution environment at the moment of signing.

### On-chain anchoring

Credential proofs are anchored on Moca Chain. This provides tamper evidence — if a credential is modified after issuance, the on-chain proof will not match.

### Encrypted storage

When the [Compliance Access Key (CAK)](/learn/advanced-topics/privacy-and-compliance) framework is enabled, raw data is encrypted with a user-controlled key and stored in decentralized storage. The data is unreadable at rest by all parties including Moca.

### Account abstraction

User wallets use smart accounts (ERC-4337 account abstraction) with paymaster-sponsored gas. Users interact with the chain without managing private keys or gas tokens directly.

## Further reading

<CardGroup>
  <Card title="Credential security" icon="shield-check" href="/learn/security/credential-security">
    How credentials are issued, anchored, and verified without exposing PII.
  </Card>

  <Card title="Data privacy" icon="lock" href="/learn/security/data-privacy">
    Where data lives, what is encrypted, and who can access it.
  </Card>

  <Card title="Security checklist" icon="list-check" href="/learn/security/security-checklist">
    Integration best practices for partners.
  </Card>

  <Card title="Privacy & Compliance (CAK)" icon="key" href="/learn/advanced-topics/privacy-and-compliance">
    The Compliance Access Key framework for regulated industries.
  </Card>
</CardGroup>


# Security Checklist
Source: https://docs.moca.network/learn/security/security-checklist

Integration best practices for partners building on AIR Kit and Moca Chain.

Use this checklist when integrating AIR Kit to ensure your implementation follows security best practices.

## Partner JWT security

* [ ] Private keys are stored in a secrets manager or HSM — never in source code or environment files checked into version control.
* [ ] JWTs are short-lived (`exp` set to 5 minutes or less).
* [ ] `kid` in the JWT header matches a key in your publicly accessible JWKS endpoint.
* [ ] JWKS endpoint is served over HTTPS with a valid TLS certificate.
* [ ] JWTs are generated server-side only. The private key never reaches the client.

## Authentication

* [ ] Use [Partner JWT](/airkit/usage/partner-authentication) for all SDK and API operations.
* [ ] If using Custom Auth (BYO), verify the user's identity in your own system before issuing the Partner JWT.
* [ ] Enable [MFA](/airkit/usage/user-management) for high-value operations (credential issuance, large transactions).
* [ ] Set `skipRehydration: true` if your security model requires login on every session.

## Credential issuance

* [ ] Validate `credentialSubject` data on your backend before calling the Issue on Behalf API. Do not trust client-supplied values.
* [ ] Use `onDuplicate: "revoke"` when credential data changes (e.g. tier upgrades). Use `"ignore"` only for idempotent operations.
* [ ] Poll the [status endpoint](/api-reference/introduction) to confirm credentials reach `ONCHAIN` before treating them as issued.
* [ ] If handling regulated data, enable [CAK encryption](/learn/advanced-topics/privacy-and-compliance).

## API security

* [ ] Use HTTPS for all API calls. Do not downgrade to HTTP, even in development.
* [ ] Implement retry logic with exponential backoff for transient failures (HTTP 500, network timeouts).
* [ ] Log API errors and monitor for unusual patterns (spikes in 401/403 responses may indicate key compromise).
* [ ] Rotate signing keys periodically. Update your JWKS endpoint before removing the old key.

## Frontend security

* [ ] Do not expose your Partner ID's private key on the client. The `partnerId` itself is safe to include in client code.
* [ ] Validate callback URLs and redirect URIs to prevent open-redirect attacks.
* [ ] If embedding AIR Kit in an iframe, configure `Content-Security-Policy` headers to allow `frame-src` from AIR Kit domains.

## Smart accounts and transactions

* [ ] Use the [Paymaster](/airkit/usage/account/paymaster) for gas sponsorship. Monitor sponsorship spend to detect abuse.
* [ ] Validate transaction parameters on your backend before relaying to the user's smart account.
* [ ] If using [session keys](/airkit/usage/account/session-keys), scope permissions to the minimum necessary operations and set short expiry times.

## Monitoring

* [ ] Set up alerts for failed authentication attempts.
* [ ] Monitor credential issuance volumes for anomalies.
* [ ] Track `WAIT_ONCHAIN` durations — prolonged waits may indicate chain congestion or issues.
* [ ] Log user consent events (CAK authorizations) for audit compliance.


# Target Users and Stakeholders
Source: https://docs.moca.network/learn/target-users-stakeholders

Target users and stakeholders in the Moca Network identity ecosystem — end users, issuers, verifiers, and partners.

Moca Network's decentralized identity network involves several types of participants.

## Users

Users are split into two key groups:

* **End Users**
  * Anyone with a digital footprint — gamers, professionals, students, shoppers, creators, and contributors. These users interact through AIR Kit to manage their credentials, digital assets, and participate in loyalty or rewards programs.
* **Developers & Integrators**
  * Builders of dApps, games, platforms, and wallet solutions who integrate AIR Kit SDKs (AIR Account & AIR Credential) for authentication, credential issuance, verification, and asset management.

## Stakeholders

* **\$MOCA holders**
  * Users and partners participating in staking, rewards, and cross-ecosystem incentive programs. They provide governance and help secure the chain.
* **Issuers**
  * Organizations authorized to issue credentials such as universities, enterprises, DAOs, protocols, brands, game publishers, community admins, and regulatory bodies. They contribute by attesting to data in the network.
* **Verifiers**
  * Platforms, apps, and services that use credentials for proof of identity, access rights, achievements, or compliance (e.g., KYC for exchanges, membership verification, gating events, audits). They are the primary economic drivers of demand within the ecosystem.

## Protocol Infrastructure Providers

* **Node Operators:** Organizations and individuals running full nodes on Moca Chain to maintain network availability, data integrity, and transaction processing.
* **Validators:** Participants responsible for consensus, block production, and network security on Moca Chain.
* **Storage Providers:** Partners offering decentralized data storage on Moca Chain for credential payloads, encrypted documents, and proofs.

## Operators

* **Moca Foundation Team** — Oversees protocol development, governance, schema standards, and core infrastructure for Moca Chain and the underlying credential protocol.
* **Moca Network Team** — Core team responsible for developing the AIR Kit (AIR Credential and AIR Account modules). Also acts as the primary tech partner for the Moca Foundation.
* **Partners & Ecosystem Networks** — Partner platforms, third-party networks, and communities who enable credential interoperability and integrate AIR features.


# Identity Verification
Source: https://docs.moca.network/learn/use-cases/identity-verification

How AIR Kit enables privacy-preserving identity verification — KYC, age checks, and compliance without storing PII.

Modern applications increasingly need to verify who their users are — for regulatory compliance, age gating, access control, and fraud prevention. Traditional identity verification requires every platform to collect, store, and protect sensitive personal data, creating liability, re-verification friction, and breach risk.

AIR Kit offers a privacy-first alternative: **issue a verifiable credential once, verify it anywhere — without ever touching raw PII**.

## The Problem with Traditional Verification

| Traditional Approach                            | AIR Kit Approach                                                  |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| User submits passport / ID to every platform    | User verifies once, carries credential                            |
| Platform stores PII — becomes a breach target   | Platform sees only a ZK proof result: `COMPLIANT / NON_COMPLIANT` |
| Re-KYC at every new service                     | Portable credential accepted by any verifier in the ecosystem     |
| Verification takes hours to days                | Credential issued instantly on KYC pass via Issue on Behalf       |
| GDPR / data breach liability for every platform | No PII stored — reduced data breach liability                     |

## How It Works

<Steps>
  <Step title="User completes identity verification">
    User goes through your KYC provider (Jumio, Onfido, Persona, etc.) as normal.
  </Step>

  <Step title="Your backend issues a KYC credential">
    The moment the KYC provider sends a pass result, your server calls the Issue on Behalf API. No user action required.
  </Step>

  <Step title="Credential lands in the user's AIR Account">
    The user now owns a verifiable, on-chain attestation of their identity — not the raw data, just the proof.
  </Step>

  <Step title="Any partner verifies the credential via ZK proof">
    The verifier receives only `COMPLIANT` or `NON_COMPLIANT`. No PII is ever transmitted or stored by the verifier.
  </Step>
</Steps>

## Common Verification Use Cases

<Columns>
  <Card title="Age Verification" icon="cake-candles">
    Prove a user is 18+ or 21+ without revealing their birthdate. Ideal for gaming, alcohol, adult content, and gambling platforms.
  </Card>

  <Card title="KYC / AML Compliance" icon="shield-check">
    Issue a KYC attestation on verification pass. Partner platforms accept it without running KYC again.
  </Card>

  <Card title="Accredited Investor" icon="chart-line">
    Issue an income or net worth attestation for financial products, DeFi pools, or private token sales.
  </Card>

  <Card title="Professional Credentials" icon="graduation-cap">
    Verify licenses, certifications, and qualifications issued by recognized authorities — portable across employers and platforms.
  </Card>
</Columns>

## Privacy Guarantee

The verifier **never receives raw identity data**. The ZK proof flow ensures only a boolean result passes between the credential holder and the verifier.

| What the Verifier Sees           | What Stays Private              |
| -------------------------------- | ------------------------------- |
| `COMPLIANT / NON_COMPLIANT`      | Full name, passport / ID number |
| Credential expiry date           | Date of birth                   |
| KYC level (`basic` / `enhanced`) | Residential address             |
| Issuer DID                       | Income figures, nationality     |

## Full Implementation Guide

See [AIR for Fintech & Payments](/airkit/guides/air-for-fintech) for complete code examples including:

* Issuing a KYC credential from a KYC webhook
* Gating financial products behind credential verification
* Age verification without exposing birthdate


# Programmable Money
Source: https://docs.moca.network/learn/use-cases/programmable-money

Programmable Money documentation for AIR Kit and Moca Network.

<Warning>**Coming Soon**</Warning>


# Verifiable User Onboarding
Source: https://docs.moca.network/learn/use-cases/verifiable-user-onboarding

Verifiable User Onboarding documentation for AIR Kit and Moca Network.

<Warning>**Coming Soon**</Warning>


# Why Centralized Identity Systems Fall Short
Source: https://docs.moca.network/learn/vision/comparison-with-centralized-identity-systems



Centralized identity systems, from Big Tech logins (Google, Facebook, Apple) to government-issued digital IDs, were built for a Web2 world, not for an era where **data sovereignty, privacy, and interoperability** define trust.

They offer convenience, but at a cost: **lock-in, surveillance, and exploitation of user data**. For users, this means lost control. For businesses and partners, it means dependency on monopolistic gatekeepers.

Moca Network flips this model, creating a **privacy-first, interoperable identity layer** that benefits both users and platforms.

## Centralized Identity Systems vs. Moca Network

|                    | **Centralized Identity (Big Tech / Gov IDs)**                                                  | **Moca Network (Decentralized Identity)**                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Data Ownership** | Controlled by providers. Users have limited visibility or rights.                              | Users own and control their **AIR ID** and credentials end-to-end.                                      |
| **Privacy**        | Data collected, mined, and sold. Governments or platforms act as surveillance hubs.            | **Zero-knowledge proofs (ZKPs)** protect sensitive info. Only proofs, not raw data, are shared.         |
| **Portability**    | Walled gardens — e.g., Google login tied to Google ecosystem, Aadhaar locked to state systems. | **Chain-agnostic identity oracle** makes credentials portable across apps, chains, and services.        |
| **Trust**          | Vulnerable to hacks, leaks, and fake accounts (billions of records breached).                  | **Programmable credentials** ensure authenticity — age, qualifications, compliance, etc.                |
| **Compliance**     | Retroactive fixes for GDPR & privacy laws; high regulatory risk.                               | **Privacy-by-design**: metadata anchored on-chain, payloads stored in compliant decentralized networks. |
| **Business Model** | Platforms profit by extracting value from user data. Partners have no leverage.                | **Shared value model**: monetization happens on user terms, creating new partner revenue streams.       |
| **Resilience**     | Centralized servers = single points of failure; politically restricted.                        | **Validators + MCSPs** ensure uptime, redundancy, and global participation.                             |

## Why This Matters

* **Market Opportunity:** Regulators, enterprises, and users are rejecting extractive centralized models. Privacy-first identity is the next infrastructure wave.
* **Differentiation:** Moca Chain isn’t “just another blockchain.” It’s a **purpose-built Layer 1 for identity** — something no centralized system is optimized for.
* Moca opens **new monetization rails** for apps, platforms, and partners, without Big Tech lock-in or government bottlenecks.

<Info>📢 Centralized identity systems are like gated communities where one landlord holds the master key. Moca is a passport you own, that unlocks every city on the map, without asking anyone’s permission.</Info>


# MOCA Ecosystem Partners
Source: https://docs.moca.network/learn/vision/ecosystem

MOCA Ecosystem Partners documentation for AIR Kit and Moca Network.

* OneFootball
* [Oyunfor](https://x.com/Moca_Network/status/1955546979997716610)
* AIR Shop: A verifiable loyalty platform powered by Spree Finance and Bookit.com integrations. Read more about the partnership [here](https://www.animocabrands.com/moca-network-partners-spree-finance).
* Anichess
* Anime Foundation
* [SK Telecom](https://www.sktelecom.com/index_en.html)
* Ubisoft
* Magic Eden
* Ton
* [Plume](https://www.animocabrands.com/moca-network-plume-partner-to-bring-privacy-preserved-institutional-grade-rwa-yield-to-users)
* Kaia


# Mission & Vision
Source: https://docs.moca.network/learn/vision/index



## Our Mission

To empower every individual with **self-sovereign digital identity** that they truly own and control; unlocking seamless, trusted, private and secure interactions across the internet.\
We are building the infrastructure where **users, not platforms, define the value of identity and data.**

## Our Vision

A world where identity is:

* **Unified** — one AIR ID travels across apps, games, wallets, and services.
* **Trusted** — verifiable credentials replace fake accounts and unverifiable claims.
* **Private** — sensitive data stays with the user, not in corporate silos.
* **Interoperable** — credentials move freely across ecosystems and chains.

We envision **Moca Network as the backbone of a privacy-first digital economy**, where people and platforms connect with trust, transparency, and freedom.


# Interoperability Challenges Across Web2/Web3
Source: https://docs.moca.network/learn/why-now/digital-identity

Moca Network - Interoperable Layer for web3. Data Fragmentation & Privacy Risks Today

Identity today is a tale of two worlds—**Web2 and Web3**—but both share the same fundamental problem: **a lack of consistent standards**.

Users are forced into **fragmented onboarding journeys**, re-doing KYC at every bank, re-verifying themselves on each exchange, or recreating their loyalty profile from scratch on every platform. Social, gaming, financial, and utility apps each operate in silos, locking data and accounts away. The result? Poor UX and exhausted users.

### The Developer’s Dilemma

It isn’t just the users who suffer. Developers face their own maze:

* Web2 systems rarely follow a unified standard, each with **different schemas and APIs**.
* Web3 brings a different problem—**multiple blockchains, competing protocols, and fragmented standards**.

This means endless resources spent on building **custom adapters and bridges**, just to make apps compatible with the systems they need to interact with.

### Why does this matter ?

Without interoperability, both **users and developers lose**:

* Users lose control and convenience.
* Developers lose time, speed, and innovation.

That’s why we’re making **interoperability a first-class goal**—building modular components that adapt to diverse systems. Our aim is simple:\
👉 **Unify the user experience** so identity is portable, secure, and seamless.\
👉 **Simplify the developer experience** so teams build once and deploy everywhere.

Together, this sets the stage for a **true identity stack** that bridges Web2 and Web3.


# Why Moca Network Matters?
Source: https://docs.moca.network/learn/why-now/index



# Solving Identity Fragmentation with Interoperability

More than ever, we live in an age where your **online footprint** may be more meaningful than your offline one.\
People are juggling numerous identities and rebuilding new loyalty programs from zero.

By providing an **interoperable layer**, we have the chance to improve users’ lives.

Imagine:

* Carrying over your **gold membership** from one airline program to another
* Not having to re-do **KYC** for every bank each time
* Sharing only the data a provider (verifier) actually needs, reducing risk of **data breaches**

The emergence of an interoperable identity layer is transforming how users and platforms interact, moving from **siloed, vulnerable data models** toward **secure, privacy-first credentials**.

This shift is **urgent and timely**, driven by fragmentation, privacy risks, technological advances, and growing consumer demand.

## Data Fragmentation & Privacy Risks Today

Currently, **personal data and identity proofs** are scattered across platforms, apps, and wallets—each holding **partial, duplicate, or outdated information**.

This fragmentation exposes users to vulnerabilities, since the repeated sharing of personal data increases:

* 🚨 Risk of falling victim to **phishing attacks**
* 🔓 Risk of encountering **poorly secured providers**

Without **unified control**, individuals have limited means to audit where and how their data is used—putting **privacy and trust at continual risk**.

At the same time, the **convenience of a universal identity** cannot be understated:

* No more repetitive KYC processes
* Portable loyalty status → enjoy **greater perks** across new programs


# Rise of Self-Sovereign Identity & ZKP tech
Source: https://docs.moca.network/learn/why-now/privacy-security

Privacy and security. Rise of Self-Sovereign Identity & ZKP tech

Self-Sovereign Identity (SSI) is rapidly gaining momentum as a strong antidote to centralized control and scattered data silos. With SSI, individuals regain full agency over their digital identities, granting them the ability to **selectively share**, **revoke**, or **update** credentials as needed.

Zero-Knowledge Proofs (ZKPs) elevate this further. Users can prove claims, like age, membership, or certification, **without revealing sensitive details**. Combined, SSI and ZKP technologies form the foundation for **trustless**, **privacy-preserving interactions**, removing the need for intermediaries and drastically reducing data exposure.

### The Google Effect: Bringing ZKP Mainstream

Major tech players are stepping into the ZKP space. For instance:

* [**Google Wallet**](https://blog.google/products/google-pay/google-wallet-age-identity-verifications/) now leverages ZKP for **privacy-preserving age verification**, enabling users to prove they’re over a certain age without revealing their birthdate.
* Google has [**open-sourced** its ZKP libraries](https://blog.google/technology/safety-security/opening-up-zero-knowledge-proof-technology-to-promote-privacy-in-age-assurance/), empowering developers to build privacy-enhanced applications with a trusted foundation.
* **Google Cloud** is [partnering with the ZK-powered identity protocol **Self**](https://www.businesswire.com/news/home/20250723204002/en/Google-Cloud-Integrates-with-Self-a-ZK-Powered-Identity-Protocol-to-Power-AI-Adoption-and-Web3-Innovation-by-Human-Users), enabling Web3 developer tools to integrate **proof-of-humanity ZKPs** in Testnet and Mainnet faucets.

These moves signify that ZKPs are no longer niche; they’re becoming foundation-level privacy infrastructure.

## Why this matters today:

* Lack of true SSI means identity is often fragmented, insecure, and hard to manage.
* Traditional verifications expose sensitive data, raising the risk of identity theft, tracking, and misuse.
* ZKPs offer a solution: users can prove key attributes **without sharing personal data**, building a future of **portable**, **privacy-first identity systems**.

### Why it’s a game-changer for Digital Identity

| Challenge Today                        | ZKP + SSI Solution                                       |
| -------------------------------------- | -------------------------------------------------------- |
| Centralized identity systems           | Distributed, user-controlled identity (SSI)              |
| Frequent oversharing of sensitive data | Selective disclosure with minimal data exposure (ZKP)    |
| Fragmented user experience             | Seamless, cross-platform identity with privacy assurance |

Together, SSI and ZKPs reshape identity, giving control back to users, enhancing privacy, and simplifying developer workflows.

By building on these technological principles, we’re building a privacy-first identity future, where trust is self-contained, credentials are verifiable yet confidential, and users are always in control.


# Consumer Demand for Data Ownership & Privacy
Source: https://docs.moca.network/learn/why-now/regulatory-landscape

Consumer Demand for Data Ownership & Privacy

Modern consumers are increasingly demanding greater **transparency**, **control**, and **privacy** over their digital lives. Growing awareness of data breaches, [misuse by tech giants](https://www.theverge.com/news/771540/google-class-action-verdict-user-privacy-tracking?utm_source=chatgpt.com), and new regulations like **GDPR** have raised expectations around data ownership.

Users now want full agency,deciding **what gets revealed**, **to whom**, and **when**, all **without friction or risk**. This is evidenced by the rising popularity of tools such as [**VPNs**](https://www.techradar.com/vpn/vpn-privacy-security/nearly-90-percent-of-iranians-now-use-a-vpn-to-bypass-internet-censorship-heres-everything-we-know?utm_source=chatgpt.com) and [**personal data removal services**](https://www.security.org/resources/data-removal-service-usage-study/).

Ecosystems that prioritize and enable this demand are seeing **loyalty**, **growth**, and **trust** abound. Thus, the shift toward interoperable identity is just as much about cultural and regulatory alignment as it is technological innovation.

## Why Consumers Are Demanding Data Ownership

* **Regulatory Awareness:** Awareness of [data protection rights in Europe has surged](https://datacompliantblog.com/2019/06/28/european-commission-reports-awareness-throughout-europe-of-data-rights-and-data-protection/) — from around 50% in 2015 to about 71% by 2020.

* **Privacy-Driven Behavior:** A study found that [**74% of consumers**](https://www.retailcustomerexperience.com/news/privacy-top-of-mind-for-consumers/) would abandon a brand if they felt it failed to protect their data properly.

* **Privacy Tools on the Rise:** The VPN market has been growing fast, driven by rising user privacy concerns.

* **Surge in Real-Time Demand:** VPN usage in places like the UK spikes dramatically—sometimes in the thousands of percent—following new privacy or age-verification regulations.

### Summary

| Key Driver                       | Outcome / Trend                                          |
| -------------------------------- | -------------------------------------------------------- |
| Regulatory confidence            | Consumers demand greater control and transparency        |
| Privacy-driven consumer behavior | Companies gain competitive edge by respecting privacy    |
| Rising privacy tool adoption     | VPNs & PETs markets are seeing exponential growth        |
| Real-world reactions             | Sudden policy changes can trigger massive privacy demand |


# How to run a challenger for Moca Chain
Source: https://docs.moca.network/mocachain/guides/run-a-challenger

How to run a challenger for Moca Chain.

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Warning>
  🔒 Repo not publicly available — please reach out to us if you would like to run this code.
</Warning>

## Challenger Information

### Minimum System Requirements

| Component    | Minimum Specification                                                  |
| ------------ | ---------------------------------------------------------------------- |
| Hardware     | Desktop or laptop running recent versions of **Mac OS X** or **Linux** |
| CPU          | **4 cores**                                                            |
| Memory (RAM) | **12 GB**                                                              |
| Storage      | **1 TB HDD/SSD**                                                       |
| Bandwidth    | **1 MB/s**                                                             |

## Setting up a challenger

### Prerequisite

* Pull the `develop` branch of the `moca-challenger` repository.
* The deployment of `moca-challenger` relies on validator binding initialization. If you want to deploy your own `moca-challenger`, you need to join as a new validator.

### Challenger Introduction

Moca ensures data integrity by regularly issuing challenge events to storage providers to prove that stored data has not been tampered with. This service allows end-users to monitor challenge events in the blockchain and perform verification.

#### Moca-challenger main components

`moca-challenger` includes 7 main goroutines: Monitor, Verifier, Vote Collector, Vote Broadcaster, Vote Collator, Tx Submitter, and Attest Monitor.

* **Monitor:** Polls the Moca blockchain to obtain new blocks, parse challenge events, and add them to the local database.
* **Verifier:** Verifies the integrity of the stored data by comparing root hashes.
* **Vote Broadcaster:** Broadcasts a signed vote on the blockchain for events that failed verification.
* **Vote Collector:** Polls the blockchain for votes broadcast by other Challenger services.
* **Vote Collator:** Collates votes to achieve a 2/3 consensus.
* **Tx Submitter:** Sends a `MsgAttest` to the blockchain after enough consensus votes are received.
* **Attest Monitor:** Polls the blockchain for successfully attested challenges and updates the database.

### Deploy moca-challenger

#### Configuration file

Set your private key, deployment environment, and gas limit. The `private_key` and `bls_private_key` can be obtained as described in the next section.

```json theme={null}
"moca_config": {
    "key_type": "local_private_key",
    "private_key": "your_challenger_private_key",
    "bls_private_key": "your_bls_private_key",
    "rpc_addrs": [ "https://testnet-lcd.mocachain.org" ],
    ...
},
"db_config": {
    "dialect": "mysql",
    "db_path": "tcp(127.0.0.1:3306)/challenger?charset=utf8&parseTime=True&loc=Local",
    ...
},
"sp_config": {
    "internal_sp_endpoints": [
      "https://testnet-sp0.mocachain.org",
      ...
    ]
}
```

#### Run locally

##### Running MySQL in Docker

```bash theme={null}
docker run -p 3306:3306 --name moca -e MYSQL_ROOT_PASSWORD=moca -d mysql:8
```

##### Create a database

```sql theme={null}
mysql --port=3306 -h127.0.0.1 -uroot -pmoca
CREATE SCHEMA IF NOT EXISTS challenger DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;
```

##### Get validator BLS key and challenger key

```bash theme={null}
./build/mocad keys export ${BLS_KEY_NAME} --unsafe --unarmored-hex --home=${CLIENT_KEYRING_DIR} --keyring-backend=test
./build/mocad keys export ${CHALLENGER_NAME} --unsafe --unarmored-hex --home=${CLIENT_KEYRING_DIR} --keyring-backend=test
```

##### Compile and launch moca-challenger

Assuming you have a validator running, compile and start the process.

```bash theme={null}
make build
./build/moca-challenger --config-type local --config-path ./config/config.json
```

#### Test and Verification

##### Create your own SP

The process is similar to creating a validator.

1. **Authorization:** Grant spending limits.
2. **Submit a proposal:** Use a JSON template to create a storage provider.

##### Tampering with data stored on SP

1. Create a bucket and upload a file.
2. Find the storage directory on your SP and modify the content of the data chunk file.

```bash theme={null}
./build/moca-cmd --home deployment/localup/ bucket create --primarySP 0x...yourSPAddress moca1
./build/moca-cmd --home deployment/localup/ object put --contentType "application/octet-stream" ./abctest moca://moca1/abctest
```

##### Challenge the data chunk of the object

* **Regular challenge:** Moca automatically generates random data availability challenges. The `moca-challenger` monitors these events. If data has been tampered with, the root hashes will not match, and the challenge will be successful. The validator will vote, and if 2/3 consensus is reached, the SP will be slashed.
* **Manual challenge:** Anyone can submit a transaction to challenge data availability.

##### Data recovery

Data recovery ensures that original data can be restored if lost on SPs.

1. Data is automatically recovered after a successful data challenge.
2. Data is automatically recovered when users find that the data is unreadable.
3. SPs can selectively recover lost data through tools.

When a challenge succeeds, the tampered data chunk file will be restored to the original file after a while.


# How to run a local testnet for Moca Chain
Source: https://docs.moca.network/mocachain/guides/run-a-local-testnet

How to run a local testnet for Moca Chain.

<Info>
  🔓 The Moca Chain source code is publicly available on GitHub: [mocachain/moca](https://github.com/mocachain/moca).
</Info>

## Validator Information

### Prerequisites

* Git
* Go 1.23+ and jq (native run)
* Docker 24+ and Docker Compose (docker run)
* macOS or Linux

## Setting up Local Testnet

### Clone the Repo

Clone the repository and navigate to the base directory:

```bash theme={null}
git clone https://github.com/mocachain/moca.git

# checkout stable version a382e3c 
git checkout tags/v1.2.0-rc2
```

### Deploy Single Node network.

#### 1. Build the binaries

```bash theme={null}
make build

# run ./build

# Otherwise...
# If gcc/ledger is not installed disable ledger support for build
# LEDGER_ENABLED=false make build
```

### 2. Deploy single validator / storage provider.

Start a single validator network with one Storage Provider:

```bash theme={null}
bash deployment/localup/localup.sh all 1 1
```

This initializes, generates genesis, and starts the node(s). Keys and data live under:

* `deployment/localup/.local/validator0`
* `deployment/localup/.local/sp0`

Ports and services:

* Tendermint RPC: `http://127.0.0.1:26657/status`
* EVM RPC: `http://127.0.0.1:8545`
* REST API (LCD): `http://127.0.0.1:1317`
* gRPC: `127.0.0.1:9090`

<Tip>🎉 Your local testnet is now setup for your testing!</Tip>

### 3. Interact with the chain

Here are some examples of how you can interact with the running services above.

```bash theme={null}
# Check node is producing blocks
curl -s localhost:26657/status | jq '.result.sync_info.latest_block_height'

# Show dev account (preloaded by the script)
./build/mocad keys show devaccount -a --keyring-backend test --home deployment/localup/.local/validator0

# Query bank balance of that address (replace ADDR with an address)
./build/mocad query bank balances ADDR --node tcp://127.0.0.1:26657

# Send EVM RPC requests
curl -s -X POST localhost:8545 -H 'content-type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

### 4. Stop/reset

If you need to stop/reset the chain here are the commands below:

```bash theme={null}
# Stop all localup-started nodes
bash deployment/localup/localup.sh stop

# Recreate from scratch (init + genesis + start)
bash deployment/localup/localup.sh all 1 1
```


# How to run a node for Moca Chain
Source: https://docs.moca.network/mocachain/guides/run-a-node

How to run a full node for Moca Chain using Docker or Cosmovisor.

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Info>
  🔓 The Moca Chain source code is publicly available on GitHub: [mocachain/moca](https://github.com/mocachain/moca).
</Info>

## Network Information

| Network | Chain ID       | EVM Chain ID | RPC (Tendermint)                                                       |
| ------- | -------------- | ------------ | ---------------------------------------------------------------------- |
| Mainnet | moca\_2288-1   | 2288         | [https://tm-rpc.mocachain.dev](https://tm-rpc.mocachain.dev)           |
| Testnet | moca\_222888-1 | 222888       | [https://testnet-lcd.mocachain.org](https://testnet-lcd.mocachain.org) |

<Tip>
  **Mainnet Access**

  Mainnet RPC access requires an API key. Contact the Moca Chain team to obtain your key.
</Tip>

## Node Information

### Minimum System Requirements

| Component    | Requirement                                                            |
| ------------ | ---------------------------------------------------------------------- |
| OS           | Desktop or laptop running recent versions of **Mac OS X** or **Linux** |
| Storage      | **1 TB** free disk space, minimum read/write speed of **100 MB/s**     |
| CPU          | **4 cores**                                                            |
| Memory (RAM) | **12 GB**                                                              |
| Network      | Broadband connection, upload/download at least **1 MB/s**              |

### Recommended System Requirements

| Component       | Recommended Specification                      |
| --------------- | ---------------------------------------------- |
| Processor (CPU) | **16-core CPU**                                |
| Memory (RAM)    | **64 GB**                                      |
| Storage         | **3 TB SSD**                                   |
| Network         | Stable high-speed internet, minimum **5 MB/s** |

## Setting Up a New Node

### Prerequisites

**For Docker (Option A):**

* Docker
* jq

**For Manual Cosmovisor (Option B):**

* Git
* Go 1.23+
* jq
* macOS or Linux

## 1. Clone the Repo (Option B only)

<Tip>Skip this step if using the Docker image (Option A).</Tip>

Clone the repository and checkout the latest stable version:

```bash theme={null}
git clone https://github.com/mocachain/moca.git
cd moca

# checkout latest stable version
git checkout tags/v1.2.1
```

## 2. Install Cosmovisor

[Cosmovisor](https://docs.cosmos.network/sdk/v0.53/build/tooling/cosmovisor) is a process manager for Cosmos SDK nodes that automatically handles chain upgrades. It is the recommended way to run a Moca Chain node.

### Option A: Official moca-cosmovisor Docker Image (Recommended)

The official Docker image is available on [GitHub Container Registry](https://github.com/mocachain/moca/pkgs/container/mocad). This image comes with the genesis binary preinstalled and runs `mocad` with Cosmovisor.

```bash theme={null}
# Pull the latest image
docker pull ghcr.io/mocachain/mocad:v1.2.1

# For specific architecture
# linux/amd64
docker pull ghcr.io/mocachain/mocad:v1.2.1-amd64

# linux/arm64
docker pull ghcr.io/mocachain/mocad:v1.2.1-arm64
```

### Option B: Manual Cosmovisor Setup

If you prefer to run Cosmovisor manually without Docker, follow these steps.

#### Install Cosmovisor

```bash theme={null}
go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest
```

#### Build or Download the Binary

You can either build from source or download pre-compiled binaries from [GitHub Releases](https://github.com/mocachain/moca/releases/tag/v1.2.1).

```bash theme={null}
# Option 1: Build from source
make build

# Option 2: Download pre-compiled binary (Linux arm64)
wget https://github.com/mocachain/moca/releases/download/v1.2.1/mocad_linux_arm64.tar.gz
tar -xzf mocad_linux_arm64.tar.gz
chmod +x mocad
mv mocad ./build/mocad
```

#### Setup Cosmovisor Directory Structure

```bash theme={null}
mkdir -p ~/.mocad/cosmovisor/genesis/bin
cp ./build/mocad ~/.mocad/cosmovisor/genesis/bin/mocad
```

## 3. Initialize Node

This will initialize your local moca node home directory `~/.mocad` containing chain data configuration.

### Using Docker (Option A)

<CodeGroup>
  ```bash [Mainnet] theme={null}
  docker run --rm -v ~/.mocad:/root/.mocad ghcr.io/mocachain/mocad:v1.2.1 \
    mocad init mynode --chain-id moca_2288-1 --default-denom amoca
  ```

  ```bash [Testnet] theme={null}
  docker run --rm -v ~/.mocad:/root/.mocad ghcr.io/mocachain/mocad:v1.2.1 \
    mocad init mynode --chain-id moca_222888-1 --default-denom amoca
  ```
</CodeGroup>

### Using Manual Cosmovisor (Option B)

<CodeGroup>
  ```bash [Mainnet] theme={null}
  ~/.mocad/cosmovisor/genesis/bin/mocad init mynode --chain-id moca_2288-1 --default-denom amoca
  ```

  ```bash [Testnet] theme={null}
  ~/.mocad/cosmovisor/genesis/bin/mocad init mynode --chain-id moca_222888-1 --default-denom amoca
  ```
</CodeGroup>

## 4. Pull Live genesis file

Fetch the genesis file for your target network.

<CodeGroup>
  ```bash [Mainnet] theme={null}
  RPC=https://tm-rpc.mocachain.dev
  curl -s "$RPC/genesis?key=<YOUR_ACCESS_KEY>" | jq -r '.result.genesis' > ~/.mocad/config/genesis.json
  ```

  ```bash [Testnet] theme={null}
  RPC=https://testnet-lcd.mocachain.org
  curl -s "$RPC/genesis" | jq -r '.result.genesis' > ~/.mocad/config/genesis.json
  ```
</CodeGroup>

## 5. Add peers

Fetch and configure peers from the network:

```bash theme={null}
PEERS=$(curl -s "$RPC/net_info" | jq -r '.result.peers[] | select(.node_info.id and .remote_ip) | "\(.node_info.id)@\(.remote_ip):26656"' | paste -sd, -)

# Update config with peers
# Use sed -i '' on macOS, sed -i on Linux
if [[ "$OSTYPE" == "darwin"* ]]; then SED_FLAG=(-i ''); else SED_FLAG=(-i); fi
[ -n "$PEERS" ] && \
  sed "${SED_FLAG[@]}" 's/seeds = ".*"/seeds = ""/' ~/.mocad/config/config.toml && \
  sed "${SED_FLAG[@]}" "s/persistent_peers = \".*\"/persistent_peers = \"$PEERS\"/" ~/.mocad/config/config.toml && \
  sed "${SED_FLAG[@]}" 's/addr_book_strict = true/addr_book_strict = false/' ~/.mocad/config/config.toml
```

Alternatively you can provide your own list of peers.

## 6. Fast sync state

State sync quickly bootstraps your node by trusting a recent block header (light client verification) and downloading a snapshot of the application state at that height, instead of replaying all historical blocks.

```bash theme={null}
# Get current height
HEIGHT=$(($(curl -s "$RPC/block" | jq -r '.result.block.header.height') - 1000))
HASH=$(curl -s "$RPC/block?height=$HEIGHT" | jq -r '.result.block_id.hash')

# Set trusted height and hash to sync from in your node configuration files
# Use sed -i '' on macOS, sed -i on Linux
if [[ "$OSTYPE" == "darwin"* ]]; then SED_FLAG=(-i ''); else SED_FLAG=(-i); fi
sed "${SED_FLAG[@]}" 's/^enable *= *.*/enable = true/' ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" "s|^rpc_servers *= *.*|rpc_servers = \"$RPC,$RPC\"|" ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" "s/^trust_height *= *.*/trust_height = $HEIGHT/" ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" "s/^trust_hash *= *.*/trust_hash = \"$HASH\"/" ~/.mocad/config/config.toml
sed "${SED_FLAG[@]}" 's/^trust_period *= *.*/trust_period = "168h0m0s"/' ~/.mocad/config/config.toml
```

## 7. Run the node

### Using Docker (Option A)

Run the Docker container with a mounted volume for persistent data:

<CodeGroup>
  ```bash [Mainnet] theme={null}
  docker run -d \
    --name mocad \
    -v ~/.mocad:/root/.mocad \
    -p 26656:26656 \
    -p 26657:26657 \
    -p 1317:1317 \
    -p 8545:8545 \
    ghcr.io/mocachain/mocad:v1.2.1
  ```

  ```bash [Testnet] theme={null}
  docker run -d \
    --name mocad \
    -v ~/.mocad:/root/.mocad \
    -p 26656:26656 \
    -p 26657:26657 \
    -p 1317:1317 \
    -p 8545:8545 \
    ghcr.io/mocachain/mocad:v1.2.1
  ```
</CodeGroup>

### Using Manual Cosmovisor (Option B)

`DAEMON_ALLOW_DOWNLOAD_BINARIES=true` enables Cosmovisor to automatically download new binaries during chain upgrades. Without this, the node will halt at the upgrade height and require manual binary replacement. Alternatively, you can pre-stage binaries at `$DAEMON_HOME/cosmovisor/upgrades/<upgrade-name>/bin/mocad`.

<CodeGroup>
  ```bash [Mainnet] theme={null}
  export DAEMON_NAME=mocad
  export DAEMON_HOME=$HOME/.mocad
  export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
  cosmovisor run start --chain-id=moca_2288-1
  ```

  ```bash [Testnet] theme={null}
  export DAEMON_NAME=mocad
  export DAEMON_HOME=$HOME/.mocad
  export DAEMON_ALLOW_DOWNLOAD_BINARIES=true
  cosmovisor run start --chain-id=moca_222888-1
  ```
</CodeGroup>

The node will take some time to fully sync up to the current chain height.

## Verify Syncing

You can verify if state sync is done by curl localhost:26657/status several times and see whether **latest\_block\_height** is increasing in response.

```bash theme={null}
curl -s http://127.0.0.1:26657/status | jq -r ".result.sync_info.latest_block_height"
# Expect block height greater than 0
```


# How to run a storage provider for Moca Chain
Source: https://docs.moca.network/mocachain/guides/run-a-storage-provider

How to run a storage provider for Moca Chain.

# Running a Storage Provider (MCSP)

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Info>
  🔓 The Moca Storage Provider source code is publicly available on GitHub.
</Info>

## Storage Provider Information

### Recommended System Requirements

| **Component** | **Recommended Specification**                                                  | **Minimum Specification**                                                  |
| ------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Hardware      | VPS running recent versions of **macOS**, **Linux**, or **Windows**            | VPS running recent versions of **macOS**, **Linux**, or **Windows**        |
| CPU           | **16 cores**                                                                   | **8 cores**                                                                |
| Memory (RAM)  | **64 GB**                                                                      | **32 GB**                                                                  |
| Storage       | At least **4** **TB** disk space for backend storage + **50 GB+ SQL database** | At least 2 **TB** disk space for backend storage + **50 GB+ SQL database** |
| Bandwidth     | **10 MB/s+** upload/download speed                                             | **10 MB/s+** upload/download speed                                         |

## Setting Up Moca Chain Data Storage Provider

### MCSP Compiling and Dependencies

#### Compile MCSP

**Compilation dependencies:**

* **Golang:** MCSP is written in Golang, and you need to install version 1.20+.
* **Buf:** A new way of working with Protocol Buffers. MCSP uses Buf to manage proto files.
* **protoc-gen-gocosmos:** Protocol Buffers for Go with Gadgets. MCSP uses this protobuf compiler to generate `pb.go` files.
* **mockgen:** A mocking framework for the Go programming language that is used in unit tests.
* **jq:** A command-line JSON processor. Users should install `jq` according to their operating system.

```bash theme={null}
# clone source code
git clone https://github.com/mocachain/moca-storage-provider.git
cd moca-storage-provider/

# install dependent tools: buf, protoc-gen-gocosmos and mockgen
make install-tools

# compile sp
make build

# move to build directory
cd build

# execute moca-sp binary file
./moca-sp version
```

#### Note

If you've already executed the `make install-tools` command in your shell, but you failed to `make build` and encountered one of the following error messages:

**Error message 1:**

```
buf: command not found
```

You can execute the following command, assuming you installed Golang in `/usr/local/go/bin`. Other OS are similar.

```bash theme={null}
GO111MODULE=on GOBIN=/usr/local/go/bin go install github.com/bufbuild/buf/cmd/buf@v1.25.0
```

**Error message 2:**

```
Failure: plugin gocosmos: could not find protoc plugin for name gocosmos - please make sure protoc-gen-gocosmos is installed and present on your $PATH
```

You can execute the following command, assuming you installed Golang in `/usr/local/go/bin`. Other OS are similar.

```bash theme={null}
GO111MODULE=on GOBIN=/usr/local/go/bin go install github.com/cosmos/gogoproto/protoc-gen-gocosmos@latest
```

If you want to execute a unit test of sp, you should execute the following command, assuming you installed Golang in `/usr/local/go/bin`. Other OS are similar.

```bash theme={null}
GO111MODULE=on GOBIN=/usr/local/go/bin go install go.uber.org/mock/mockgen@latest
```

> The error messages above are due to users not setting the Go environment correctly. For more info, users can search for GOROOT, GOPATH, and GOBIN.

### MCSP Dependencies

If a user wants to start MCSP in local mode or testnet mode, you must prepare `SPDB`, `BSDB`, and `PieceStore` dependencies.

#### SPDB and BSDB

MCSP uses `SPDB` and `BSDB` to store some metadata such as object info, object integrity hash, etc. These two DBs now use RDBMS to complete corresponding functions.

Users can now use MySQL or MariaDB to store metadata. The following lists the supported RDBMS:

* MySQL
* MariaDB

> More types of databases such as PostgreSQL or NewSQL will be supported in the future.

#### PieceStore

Moca Chain is a decentralized data storage system that uses object storage as the main data storage system. MCSP encapsulates data storage as `PieceStore`, which provides common interfaces to be compatible with multiple data storage systems. Therefore, if a user wants to join MCSP or test the function of MCSP, you must use a data storage system.

The following lists the supported data storage systems:

* **AWS S3:** An object storage that can be used in a production environment.
* **Aliyun OSS:** Fully managed object storage service to store and access any amount of data from anywhere.
* **B2:** Backblaze B2 provides unlimited data storage in the cloud at ⅕th the cost of Amazon S3.
* **MinIO:** An object storage that can be used in a production environment and is compatible with AWS S3.
* **POSIX Filesystem:** A local filesystem is used for experiencing the basic features of MCSP and understanding how MCSP works. The piece data created by MCSP cannot be gotten within the network and can only be used on a single machine.

## Run Local MCSP Network

This guide helps you to set up a local Moca Chain Storage Provider network for testing and other development-related purposes.

### Recommended Prerequisites

The following lists the recommended hardware requirements:

* VPS running recent versions of Mac OS X, Linux, or Windows;
* 16 cores of CPU, 64 GB of memory (RAM);
* At least 100GB disk space for backend storage;
* 10GB+ SQL Database.

### Quickly setup local Moca Chain network

**Build Moca Chain**

```bash theme={null}
git clone https://github.com/mocachain/moca.git
cd moca
make build
```

**Start Moca Chain**

```bash theme={null}
# 1 validator and 4 storage providers
bash ./deployment/localup/localup.sh all 1 2
```

**Export the keys of MCSPs**

```bash theme={null}
bash ./deployment/localup/localup.sh export_sps 1 2
```

These JSON data will be used to set up the local MCSP network, so you'd better save it as a JSON file:

```bash theme={null}
bash ./deployment/localup/localup.sh export_sps 1 2 > sp.json
```

### Setup local MCSP network

**Compile MCSP**

```bash theme={null}
git clone https://github.com/mocachain/moca-storage-provider.git
cd moca-storage-provider
make build
```

**Generate localup env**
Use the following instruction to generate a template config file, `sp.info`, and `db.info` in seven different directories. This command is used for generating the MCSP env for the first time or regenerating the MCSP env.

```bash theme={null}
# This command accepts four args, the first arg is json file path that only supports absolute path, the second arg is db user name,
# the third arg is db password and the fourth arg is db address.
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --generate json_file_path db_username db_password db_address
```

> The json file path accepted for the first arg is generated by the "Quickly setup local Moca Chain network" step.

**View directory structure:**

```
ls deployment/localup/local_env/sp0
├── sp0
│   ├── config.toml # generated template config file
│   ├── db.info # generated db.info is used for config.toml
│   ├── moca-sp0 # moca-sp binary
│   └── sp.info # generated sp.info is used for config.toml
├── sp1
├── ...
```

An example for generating a local sp env:

```bash theme={null}
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --generate /root/sp.json root moca localhost:3306
```

```bash theme={null}
[root@yourmachine sp0]# cat db.info
#!/usr/bin/env bash
USER="root" # database username
PWD="moca" # database password
ADDRESS="localhost:3306" # db endpoint, e.g. "localhost:3306"
DATABASE="sp_0" # database name
```

```bash theme={null}
[root@yourmachine sp0]# cat sp.info
#!/usr/bin/env bash
SP_ENDPOINT="127.0.0.1:9033" # gateway endpoint, e.g. "127.0.0.1:9033"
OPERATOR_ADDRESS="0x14539343413EB47899B0935287ab1111Df891d04" # OperatorAddr is generated in setup local Moca Chain step 3.
OPERATOR_PRIVATE_KEY="ba6e97958d9c43d1ad54923eba99f8d59f54a0c66c78a5dcbc004c5c3ec72f8c" # OperatorPrivKey is generated in setup local Moca Chain step 3.
FUNDING_PRIVATE_KEY="bd9d9e7823cd2dc7bc20f1b6676c3025cdda6cf5a8df9b04597fdff42c29af01" # FundingPrivKey is generated in setup local Moca Chain step 3.
SEAL_PRIVATE_KEY="aacd6b834627fdbc5de2bfdb1db31be0ea810a941854787653814c8040a9dd39" # SealPrivKey is generated in setup local Moca Chain step 3.
APPROVAL_PRIVATE_KEY="32108ed1a47c0af965824f84ac2162c029f347eec6d0988e642330b0ac264c85" # ApprovalPrivKey is generated in setup local Moca Chain step 3.
GC_PRIVATE_KEY="2fad16031b4fd9facb7dacda3da4ca4dd5f005f4166891bf9f7be13e02abb12d" # GcPrivateKey is generated in setup local Moca Chain step 3.
BLS_PRIVATE_KEY="6f349866f18413abb1a78cab947933459042044649686f354e941a646b9ed6e7" # BlsPrivateKey is generated in setup local Moca Chain step 3.
```

### Start Four MCSPs

Make `config.toml` according to `db.info`, `sp.info` and start four MCSPs.

```bash theme={null}
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --reset
bash ./deployment/localup/localup.sh --start
```

The environment directory is as follows:

```
deployment/localup/local_env/
├── sp0
│   ├── config.toml # real config
│   ├── data/ # piecestore data directory
│   ├── db.info
│   ├── moca-sp0
│   ├── moca-sp.log # moca-sp log file
│   ├── log.txt
│   └── sp.info
├── sp1
├── ...
```

### Recompile MCSP

If you want to modify `config.toml` in different MCSP directories or recompile the `moca-sp` binary file, you can use the following commands to reset and start the local MCSP:

```bash theme={null}
cd moca-storage-provider/
bash ./deployment/localup/localup.sh --reset
bash ./deployment/localup/localup.sh --start
```

### One-step (Recommended)

#### Quickly setup local Moca Chain network

Build Moca Chain Image and start Moca Chain network with docker-compose.

```bash theme={null}
git clone https://github.com/mocachain/moca.git
cd moca
# export sp config json file to moca-storage-provider/deployment/dockerup
bash deployment/dockerup/localup.sh backup
```

#### Setup local MCSP network

```bash theme={null}
git clone https://github.com/mocachain/moca-storage-provider.git
cd moca-storage-provider
```

### Operate With MCSP

If you have already started Moca Chain and Moca Chain MCSP successfully locally, you can use `moca-cmd` to operate with MCSP such as `CreateBucket`, `PutObject`, and `GetObject`. Detailed info about `moca-cmd` can be found here.

Next, we provide you a hand-by-hand tutorial to operate with the chain and MCSP.

#### Generate your test account

First, we need to generate a test account and private key:

```bash theme={null}
# this command will generate a test account whose name is testkey, you can change its name
mocad keys add testkey --keyring-backend test

# export the private key of test account
mocad keys export testkey --unarmored-hex --unsafe --keyring-backend test
```

After generating a test account, there are no tokens in this account. We should transfer some \$MOCA:

```bash theme={null}
# transfer 5000 \$MOCA
mocad tx bank send validator0 {generated_test_account_address} 5000000000000000000000amoca --home /{your_moca_path}/moca/deployment/localup/.local/validator0 --keyring-backend test --node http://localhost:26750 -y

# query your account balances
mocad q bank balances {generated_test_account_address} --node http://localhost:26750
```

#### Use cmd to send requests

If you have come to this step, congratulations, you can operate with your own private chain and MCSP.

First, we need to configure `cmd`:

```bash theme={null}
cd moca-cmd/
make build

# generate a keystore file to manage private key information
touch key.txt & echo ${TEST_ACCOUNT_PRIVATE_KEY} > key.txt
touch password.txt & echo "test_sp_function" > password.txt
./build/moca-cmd --home ./ --passwordfile password.txt account import key.txt

# construct config.toml
touch config.toml
```

Write the following content:

```
rpcAddr = "https://testnet-lcd.mocachain.org:443"
chainId = "moca_222888-1"
```

Second, you can do some operations with MCSP:

**Create bucket**

```bash theme={null}
# list current available SPs
./build/moca-cmd -c ./config.toml --home ./ sp ls

# random choose one SP to create bucket
./build/moca-cmd -c ./config.toml --home ./ bucket create moca://${BUCKET_NAME}

# head bucket info
./build/moca-cmd -c ./config.toml --home ./ bucket head moca://${BUCKET_NAME}

# choose one sp to create bucket, operator_address is shown in sp ls result
./build/moca-cmd -c ./config.toml --home ./ bucket create --primarySP ${operator_address} moca://${BUCKET_NAME}
```

**PutObject & GetObject**

```bash theme={null}
# generate a 17MB random file
dd if=/dev/urandom of=./random_file bs=17M count=1

# put object
./build/moca-cmd -c ./config.toml --home ./ object put --contentType "application/octet-stream" ./random_file moca://${BUCKET_NAME}/random_file

# get object
./build/moca-cmd -c ./config.toml --home ./ object get moca://${BUCKET_NAME}/random_file ./new_random_file
```

> Users can use `md5` to compare your generated file and the downloaded file to see whether it is the same. You can explore other functions of `moca-cmd`.

## Run MCSP Node

This guide helps you set up an MCSP Node. Once you set up the MCSP Node successfully, you can follow the "Join SP Network" guide to make it online.

### Prerequisites

#### Recommended Hardware

The following lists the recommended hardware requirements:

* VPS running recent versions of Mac OS X, Linux, or Windows;
* 16 cores of CPU, 64 GB of memory (RAM);
* 1 Gbps network connection with upload/download speeds of 10MB/s+;
* At least 1 TB disk space for backend storage;
* 50GB+ SQL database;
* Piece Store: AWS S3, MinIO (Beta);
* 6 `mocad` accounts with enough \$MOCA.
  > **IMPORTANT:** Each storage provider will hold 7 different accounts serving different purposes.

#### Wallet Preparation

* **Operator Account:** Used to edit the information of the StorageProvider. Please make sure it has enough Moca to pay the gas fee of `EditStorageProvider` and `UpdateStorageProviderStatus` transactions.
* **Funding Account:** Used to deposit staking tokens and receive earnings. It is important to ensure that there is enough money in this account, and the MCSP must submit a deposit as a guarantee. At least 500+ Moca are required for staking. You should use this address to send a `CreateStorageProvider` proposal on-chain. Besides the 500 Moca for staking, the funding address should have enough tokens for creating VGF to store more data, so we suggest depositing at least 510 Moca into this account.
* **Seal Account:** Used to seal the user's object. Please make sure it has enough Moca to pay the gas fee of the `SealObject` transaction. We suggest depositing 10 Moca into this account.
* **Approval Account:** Used to approve user's requests. This account does not require holding \$MOCA.
* **GC Account:** It is a special address for sp and is used by sp to clean up local expired or unwanted storage. Please make sure it has enough \$MOCA because it's going to keep sending transactions up the chain.
* **Maintenance Account:** It is used for MCSP self-testing while in maintenance mode. This account for creating buckets and objects will be allow-listed by the Chain, while other users' create requests will fail.
* **Bls Account:** Used to create a bls signature when sealing objects to ensure integrity; it does not need to be deposited.

There are six accounts below. You can use the command below to generate these accounts:

```bash theme={null}
mocad keys add operator --keyring-backend test
mocad keys add seal --keyring-backend test
mocad keys add approval --keyring-backend test
mocad keys add gc --keyring-backend test
mocad keys add maintenance --keyring-backend test
mocad keys add bls --keyring-backend test --algo eth_bls
```

and then export these private keys to prepare for SP deployment:

```bash theme={null}
mocad keys export operator --unarmored-hex --unsafe --keyring-backend test
mocad keys export seal --unarmored-hex --unsafe --keyring-backend test
mocad keys export approval --unarmored-hex --unsafe --keyring-backend test
mocad keys export gc --unarmored-hex --unsafe --keyring-backend test
mocad keys export bls --unarmored-hex --unsafe --keyring-backend test
```

> **IMPORTANT:** `FundingAddress` is used to deposit staking tokens and receive earnings. Therefore, users should prepare their own `FundingAddress` public key and private key. And keep the private key of `FundingAddress` in a cold wallet for safety! The private keys of `OperatorAddress`, `SealAddress`, `ApprovalAddress`, `GCAddress`, and `BlsAddress` can be kept in a hot wallet because they are often used to send transactions.

If you want to generate a public key and private key of `FundingAddress` in the `mocad` binary file, you can execute the following commands:

```bash theme={null}
mocad keys add funding --keyring-backend test
mocad keys export funding --unarmored-hex --unsafe --keyring-backend test
```

The `maintenance` account is not needed for MCSP deployment, but you should export it to conduct a self-test:

```bash theme={null}
mocad keys export maintenance --unarmored-hex --unsafe --keyring-backend test
```

> Please keep these seven private keys safe!

Moreover, obtain the `bls` public key and generate a `bls` proof to fill in the proposal of creating a Storage Provider.

**bls\_pub\_key:**

```bash theme={null}
mocad keys show bls --keyring-backend test --output json | jq -r '.pubkey_hex'
```

**bls\_proof:**

```bash theme={null}
# Replace the ${bls_pub_key} with the above bls_pub_key to ensure you sign the correct bls pub key!!!
mocad keys sign "${bls_pub_key}" --from bls --keyring-backend test
```

#### Database Configuration

You should create two databases: `${SpDB.Database}` and `${BsDB.Database}`.

> **IMPORTANT:** `${BsDB.Database}` requires `utf8mb4_unicode_ci` as the character set and collation.

The following example assumes `${SpDB.Database}` as `storage_provider_db` and `${BsDB.Database}` as `block_syncer`.

```sql theme={null}
-- login to mysql and create database
-- the default encoding for the database should be utf8mb4_unicode_ci
mysql> CREATE DATABASE storage_provider_db;
mysql> CREATE DATABASE block_syncer CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- check the database encoding format
mysql> show create database block_syncer;
```

> This is the encoding we expect to see.

### Create Storage Provider

#### Compile MCSP

Follow the "Compile MCSP" doc to compile the MCSP binary or you can download the binary from the Moca Chain Storage Provider Release.

#### MCSP Config

##### Generate config template

```bash theme={null}
cd moca-storage-provider/build
# dump default configuration
./build/moca-sp config.dump
```

##### Write config

You can learn about how to write your `config.toml` file here.

> It's recommended to deploy a Kubernetes cluster following this guide. The corresponding config file is here.

#### Run MCSP

```bash theme={null}
# start sp
./moca-sp --config ${config_file_path}
```

## Join MCSP Network

This guide will help you join the MCSP Network: Testnet.

### Prerequisite for Becoming a Testnet MCSP

To ensure the stable provision of data services, Storage Providers must meet specific criteria to join the testnet.

* The MCSP must join the testnet for a minimum of one month.
* The MCSP must store over 1K files across more than 100 buckets on the testnet.
* There were no slash events on the MCSP in the past week.

### How to Join MCSP Network

Moca Chain validators are responsible for selecting storage providers. For each on-chain proposal to add a new storage provider, there is a deposit period for depositing Moca and a voting period for validators to cast votes. Once the proposal passes, the new MCSP can join the network afterwards.

#### Submit Proposal

The MCSP needs to initiate an on-chain proposal that specifies the `Msg` information to be automatically executed after the vote is approved. In this case, the `Msg` is `MsgCreateStorageProvider`. It's worth noting that the deposit tokens need to be greater than the minimum deposit tokens specified on the chain.

```
rpcAddr = "https://testnet-lcd.mocachain.org:443"
chainId = "moca_222888-1"
```

##### Hot Wallet Manual

You can use the `mocad` command to directly send the transaction for creating a storage provider. To do this, please import the private key of the funding account into the Keystore.

> However, it is not safe to use a hot wallet for Testnet. Instead, you should refer to the Hardware Wallet Manual for instructions on using a hardware wallet.

Command for creating storage provider:

```bash theme={null}
mocad tx sp create-storage-provider ./create_storage_provider.json --from {funding_address} --node ${rpcAddr} --chain-id ${chainId} --keyring-backend test
```

The content for `create_storage_provider.json`, modify it with the correct values as you need:

```json theme={null}
{
  "title": "create storage provider",
  "summary": "use proposal create storage provider",
  "messages": [
    {
      "@type": "/moca.sp.MsgCreateStorageProvider",
      "creator": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
      "description": {
        "moniker": "sp_one_0",
        "identity": "",
        "website": "http://website",
        "security_contact": "",
        "details": "sp_one_0 detail"
      },
      "sp_address": "0x138b2fa467B83432E2AB97Df560A21E5b947fF3F",
      "funding_address": "0x3b8388788238AE1D2C3aA0fbdE88fE91161f5753",
      "seal_address": "0x2d7dAF0a129B93017072782fF0a8bB6923cde51b",
      "approval_address": "0xC8E82835fc2713f55ce7F762926A1B7e68eF4163",
      "gc_address": "0xcD0A9C31C27C231b3417D57083f87Fc1B5aa8ED0",
      "maintenance_address": "0x3b8388788238AE1D2C3aA0fbdE88fE91161f5753",
      "endpoint": "http://moca-sp-one-0.moca-sp-one:9033",
      "deposit": {
        "denom": "amoca",
        "amount": "100000000000000000000000"
      },
      "read_price": "100.000000000000000000",
      "free_read_quota": "100000000",
      "store_price": "10000.000000000000000000",
      "bls_key": "2a3be31fa821e170ec5c13812fd77e072cf7985361ea72aee01723f3f38582df1a3d7440d2b5517d02901ccf5adb4250bf2e8ead1c7908cae4cfb1348abfd33007ade14bc03b28578ff08ef6cdf20c8d0fb07498caeb6c9c85d48a29da6d45a6169ee49ff754703d233dbfb1bf35ef8aa14128a91227a8b03dab3c8812d865db",
      "bls_proof": "1b535ba8f1e307deea80a5be6919a20cb98c2cc46b78984b3052775a6f5293e9134be6012f68f6cff059cd4483b62a231d7c76bdbc6066ff5058bc5b90511f1e"
    }
  ],
  "metadata": "ipfs://CID",
  "deposit": "10000000000000000000000amoca"
}
```

##### Hardware Wallet Manual

The `mocad` command is not available for connecting with the hardware wallet, so you should use the `mocad-tx-sender` to send transactions. Here are the steps:

**Generate the transaction data:**

```bash theme={null}
mocad tx sp create-storage-provider ./create_storage_provider.json --from {funding_address} --print-eip712-msg-type
```

> **Note:**
>
> * You can get the `gov` module address by this command: `curl -X GET "https://testnet-api.mocachain.org/cosmos/auth/v1beta1/module_accounts/gov" -H "accept: application/json"`
> * `endpoint` is the URL of your gateway.
> * `read_price` and `store_price` units are wei/bytes/s.
> * `free_read_quota` unit is Bytes.
> * `creator` is the address of the `gov` module.
> * `metadata` is optional.

#### Deposit Moca to Proposal

> **Note:** You can get the minimum deposit for a proposal by the above command. Please make sure that the initial deposit is greater than `min_deposit` when submitting the proposal.

```bash theme={null}
curl -X GET "https://testnet-api.mocachain.org/cosmos/gov/v1/params/deposit" -H "accept: application/json"
```

You can skip this step if the initial deposit amount is greater than the min deposit required by the proposal. Each proposal needs to deposit enough tokens to enter the voting phase.

```bash theme={null}
mocad tx gov deposit ${proposal_id} 1Moca --from ${funding_address} --keyring-backend test --node ${rpcAddr} --chain-id ${chainId}
```

#### Wait Voting and Check Voting Result

After submitting the proposal successfully, you must wait for the voting to be completed and the proposal to be approved. It will last 1 day on Testnet. Once it has passed and is executed successfully, you can verify that the storage provider has been joined.

> **Warning:** Please ensure that the storage provider service is running before it has been joined.

You can check the on-chain MCSP information to confirm whether the MCSP has been successfully created.

```bash theme={null}
mocad query sp storage-providers --node ${rpcAddr}
```

Alternatively, you can check the proposal to know about its execution status.

```bash theme={null}
mocad query gov proposal ${proposal_id} --node ${rpcAddr}
```

#### Activate MCSP

##### Storage Provider Standard Test

After the proposal has passed, the status of MCSP is `STATUS_IN_MAINTENANCE`. To prevent being slashed due to functional abnormalities, you should first perform a full functional test using the maintenance account. You can refer to the MCSP standard test.

##### Update MCSP status

Once the testing is completed, you need to send a transaction to activate the MCSP to `STATUS_IN_SERVICE`.

```bash theme={null}
mocad tx sp update-status [sp-address] STATUS_IN_SERVICE [flags]
```

#### MCSP address deposit

##### Funding Address

As a new MCSP, you need to deposit a minimum amount of Moca into the funding address. Please note the initial deposit requirement varies in different environments. You can check the `sp.params.min_deposit` value (in wei Moca) from the genesis endpoint response of the Moca Chain testnet. At the time when this doc is written, according to `https://testnet-lcd.mocachain.org/genesis`, MCSP in testnet requires a minimum of 500 Moca deposited in the funding address.
In addition, to join the network, an MCSP must initiate a proposal using a funding address and have an additional >1 Moca to cover these costs.

##### Operator Address

The MCSP operator address will be used to send "Create Global Virtual Group", "Edit Storage Provider", "Update Storage Provider Status", and other transactions to the Moca Chain. So it requires some Moca deposited for the transaction fee as well. We recommend the MCSP operator address can hold at least 0.1 Moca but not necessarily as much as possible.

### Storage Provider Operations

#### EditStorageProvider

This command is used to edit the information of the MCSP, including endpoint, description, etc.

**Usage:**

```bash theme={null}
mocad tx sp edit-storage-provider [sp-address] [flags]
```

For example, to edit the endpoint:

```bash theme={null}
mocad tx sp edit-storage-provider ${operator_address} --endpoint ${new_endpoint} --from ${operator_address} --keyring-backend test --node ${rpcAddr} --chain-id ${chainId}
```

#### Update MCSP Price

Update the storage provider read, store price and free read quota. If there is no change to a specific value, the current value should also be provided.

* The unit of price is a decimal, which indicates wei Moca per byte per second. E.g. the price is 0.02183945725, which means approximately \$0.018/GB/Month.
* The `free-read-quota` unit is bytes; for 1GB free quota, it should be 1073741824.

**Usage:**

```bash theme={null}
mocad tx sp update-price [sp-address] [read-price] [store-price] [free-read-quota] [flags]
```

**Example:**

```bash theme={null}
mocad tx sp update-price ${operator_address} 0.1469890427 0.02183945725 1073741824 --from ${operator_address} --keyring-backend test --node ${rpcAddr} --chain-id ${chainId}
```

#### Update MCSP Quota

Besides the `update-price` command above, you can also use the `moca-sp` command to update the free read quota for MCSP. The `update.quota` command is used to update the free quota of the MCSP; it will send a transaction to the blockchain to update the free read quota but keep the storage price and read price unchanged.

**Usage:**

```bash theme={null}
./build/moca-sp update.quota [command options] [arguments...]
```

**Example:**

```bash theme={null}
./build/moca-sp update.quota --quota 1073741824 --config ./config.toml
```

#### Recover MCSP Objects

Besides the commands above, you can also use the `moca-sp` command to recover objects for MCSP, whether it is the primary or secondary sp of the object. The `recover.object` command is used to recover an object or objects of the MCSP; it will send a request to other MCSPs to get a replicate of the object(s) you want to recover.

**Usage:**

```bash theme={null}
./build/moca-sp recover.object [command options] [arguments...]
```

**Example:**

```bash theme={null}
./build/moca-sp recover.object --config ./config.toml -b bucket_name -o single_object_name
./build/moca-sp recover.object --config ./config.toml -b bucket_name -l object_name1//_object_name2//object_name3
```

#### Claim MCSP Income

To claim income, a storage provider can use the `settle` command to settle income in global virtual group families or global virtual groups. To find the global virtual group families or global virtual groups to settle, a storage provider can use `query.primary.sp.income` or `query.secondary.sp.income` of `moca-sp` commands.

##### To query the income of a primary sp

**Usage:**

```bash theme={null}
# query sp's income in global virtual group families
moca-sp query.primary.sp.income --config config.toml --sp.id ${sp_id}
```

An example of a response will look like:

```json theme={null}
querying primary sp income details for sp 1query timestamp 1698830787 2023-11-01 17:26:27 +0800 CSTquery results: [{"vgf_id":2,"stream_record":{"account":"primary_sp_virtual_payment_account_address_1","crud_timestamp":1698631653,"netflow_rate":"4643666191","static_balance":"1093710972008743","buffer_balance":"0","lock_balance":"0","frozen_netflow_rate":"0"},"income":"2018422795287337"},...]
```

> The unit of the unsettled income is aMoca. The first element in the query result array above means that sp 1 gets 2018422795287337 wei Moca in `vgf_id` 2.

##### To query the income of a secondary sp

```bash theme={null}
# query sp's income in global virtual groups
moca-sp query.secondary.sp.income --config config.toml --sp.id ${sp_id}
```

An example of a response will look like:

```json theme={null}
querying secondary sp income details for sp 1query timestamp 1698830440 2023-11-01 17:20:40 +0800 CSTquery results: [{"gvg_id":2531,"stream_record":{"account":"secondary_sp_virtual_payment_account_address_1","crud_timestamp":1695347375,"netflow_rate":"22256589564","static_balance":"917684637479280","buffer_balance":"0","lock_balance":"0","frozen_netflow_rate":"0"},"income":"13073138794535490"},...]
```

> The unit of the unsettled income is wei Moca. The first element in the query result array above means that sp 1 gets 13073138794535490 wei Moca in `gvg_id` 2531.

```bash theme={null}
# settle income in global virtual group family or global virtual groups
mocad tx virtualgroup settle [global-virtual-group-family-id] [global-virtual-group-ids] [flags]
```

**Example:**

```bash theme={null}
# query sp's income in global virtual group families
moca-sp query.primary.sp.income --config config.toml --sp.id 1

# query sp's income in global virtual groups
moca-sp query.secondary.sp.income --config config.toml --sp.id 2

# settle income in global virtual group family with id 100
mocad tx virtualgroup settle 100 0 [flags]

# settle income in global virtual groups with id 2 or 3 or 4
mocad tx virtualgroup settle 0 2,3,4 [flags]
```

## Exit MCSP Network

### How to exit Moca Chain network

When an MCSP decides to exit the Moca Chain network, there are three main steps to go through, involving both the exiting MCSP and other MCSPs in the network:

1. Declare the exit
2. Data recovery by successor MCSP(s)
3. Finalize the exit

#### Declare the exit

The exiting MCSP needs to initiate a `StorageProviderExit` transaction to Moca Chain, which will turn its status to `STATUS_GRACEFUL_EXITING`. To exit the network, you can use the following commands based on the desired network:

```
rpcAddr = "https://testnet-lcd.mocachain.org"
chainId = "moca_222888-1"
```

Command for storage provider to exit:

```bash theme={null}
moca-sp spExit [command options] [arguments...]
```

**Example:**

```bash theme={null}
./build/bin/moca-sp spExit --config ./config.toml
```

#### Data recovery

For MCSPs interested in becoming successors, you need to perform the following data recovery steps:

##### ReserveSwapIn

The prospective successor MCSP needs to determine the Global Virtual group (GVG) and Global Virtual Group Family (VGF) that the exiting MCSP has. This information can be obtained from Moca ChainScan or by using the provided CLI.

**Usage:**

```bash theme={null}
# List the GVG that the exit MCSP acts as a secondary MCSP
./moca-sp query-gvg-by-sp [command options] [arguments...]

# List the GVG Family that the exit SP acts as a primary SP
./moca-sp query-vgf-by-sp [command options] [arguments...]
```

**Example:**

```bash theme={null}
# List the GVG that the exit SP (id=1) acts as a secondary SP
./moca-sp query-gvg-by-sp --config ./config.toml -sp 1

# List the GVG Family that the exit SP (id=1) acts as a primary SP
./moca-sp query-vgf-by-sp --config ./config.toml -sp 1
```

Once the successor MCSP has obtained the necessary information, it needs to reserve the position in the exiting MCSP's GVG Family or GVG.

**Usage:**

```bash theme={null}
# Reserve the exit SP's position in a GVG family or GVG
./moca-sp swapIn [command options] [arguments...]
```

**Example:**

```bash theme={null}
# Reserve the exit SP's (id=1) position in GVG family (id=1)
./moca-sp swapIn --config ./config.toml -f 1 -sp 1

# Reserve the exit SP's (id=1) position in GVG (id=1)
./moca-sp swapIn --config ./config.toml --gid 1 -sp 1
```

##### Data Recovery

The data recovery process is triggered by the successor MCSP using the following commands:
**Usage:**

```bash theme={null}
./moca-sp recover-vgf [command options] [arguments...]
./moca-sp recover-gvg [command options] [arguments...]
```

**Example:**

```bash theme={null}
# To recover the exit SP's data in the VGF (id=1) as a primary SP:
./moca-sp recover-vgf --config /config/config.toml -f 1

# To recover the exit SP's data in the GVG (id=1) as a secondary SP:
./moca-sp swapIn --config ./config.toml --gid 1
```

Once the recovery job is triggered, it will run in the background in the MCSP Manager module. The progress can be queried using the following command:
**Usage:**

```bash theme={null}
./moca-sp query-recover-p [command options] [arguments...]
```

**Example:**

```bash theme={null}
# Query the GVG family (id=1) recovery progress
./moca-sp recover-vgf --config /config/config.toml -f 1

# Query the GVG (id=1) recovery progress
./moca-sp recover-vgf --config /config/config.toml --gid 1
```

##### CompleteSwapIn

Upon completion of the data recovery process and successful verification, the successor MCSP needs to send a `CompleteSwapIn` transaction to the Moca Chain. It will be automatically conducted before the recovery process concludes. This will finalize the recovery process and allow the successor MCSP to take over the position in the GVG Family or GVG.

> **Note:** It is crucial to note that under no circumstances should the `CompleteSwapIn` be triggered manually if the successor MCSP has not completed the data recovery process but acknowledges it. Doing so may result in data availability challenges and potential loss of funds.

#### Finalize the Exit

Once the successor MCSP has completed the data recovery process and taken over the position in the GVG Family or GVG, by checking the GVG statistic of the exiting MCSP, confirm that there are no more GVGs associated with it. Anyone in the Moca Chain network can send a `CompleteStorageProviderExit` transaction to the Moca Chain to finalize its exit from the network. Below shows the CLI triggered by the exiting MCSP itself.

**Usage:**

```bash theme={null}
./moca-sp completeSpExit [command options] [arguments...]
```

**Example:**

```bash theme={null}
./moca-sp completeSpExit --config /config/config.toml
```

## Deploy Piece Store

*Coming soon.*

## MCSP Config

### MCSP Config

This section gives you a complete config of MCSP. `./moca-sp config.dump` will generate a template `config.toml`.

#### App info

These fields are optional.

```toml theme={null}
# optional
Env = ''
# optional
AppID = ''
# optional
Server = []
# optional
GRPCAddress = ''
```

#### Database

To config `[SpDB]`, `[BsDB]`, you have to input the username, db password, db address, and db name in these fields.

#### PieceStore

To config `[PieceStore]` and `[PieceStore.Store]`, you can read the details in this doc.

#### Chain info

* `ChainID` of testnet is `moca_222888-1`.
* `ChainAddress` is the RPC endpoint of Testnet; you can find RPC info here.

#### SpAccount

These private keys are generated during wallet setup.

#### Endpoint

`[Endpoint]` specifies the URL of different services.

**For single-machine host (not recommended):**

```toml theme={null}
[Endpoint]
ApproverEndpoint = ''
ManagerEndpoint = ''
DownloaderEndpoint = ''
ReceiverEndpoint = ''
MetadataEndpoint = ''
UploaderEndpoint = ''
P2PEndpoint = ''
SignerEndpoint = ''
AuthenticatorEndpoint = ''
```

**For K8S cluster:**

```toml theme={null}
[Endpoint]
ApproverEndpoint = 'manager:9333'
ManagerEndpoint = 'manager:9333'
DownloaderEndpoint = 'downloader:9333'
ReceiverEndpoint = 'receiver:9333'
MetadataEndpoint = 'metadata:9333'
UploaderEndpoint = 'uploader:9333'
P2PEndpoint = 'p2p:9333'
SignerEndpoint = 'signer:9333'
AuthenticatorEndpoint = 'localhost:9333'
```

#### P2P

> **Note:** We don't use P2P service in Testnet, so users can ignore P2P items.

* `P2PPrivateKey` and `node_id` are generated by `./moca-sp p2p.create.key -n 1`.
* `P2PAntAddress` is your load balance address. If you don't have a load balance address, you should have a public IP and use it in `P2PAddress`. It consists of `ip:port`.
* `P2PBootstrap` can be left empty.

#### Gateway

```toml theme={null}
[Gateway]
DomainName = 'region.sp-name.com'
```

> The correct configuration should not include the protocol prefix `https://`.

#### BlockSyncer

Here is the `block_syncer` config. The configuration of `BsDBWriteAddress` can be the same as the `BSDB.Address` module here. To enhance performance, you can set up the write database address here and the corresponding read database address in `BSDB`.

```toml theme={null}
Modules = ['epoch','bucket','object','payment','group','permission','storage_provider','prefix_tree', 'virtual_group','sp_exit_events','object_id_map','general']
Workers = 50
BsDBWriteAddress = 'localhost:3306'
```

#### FundingPrivateKey

There is no need to write `FundingPrivateKey` in `config.toml`. It should be kept in a cold wallet for safety.

#### Rcmgr

ResourceManager manages resources within the MCSP system, tracking and accounting for usage across the stack, from internal components to applications. It also allows for resource usage to be limited based on user-configurable policies. The config schema is shown below:

```protobuf theme={null}
message GfSpLimit {
  int64 memory = 1;
  int32 tasks = 2;
  int32 tasks_high_priority = 3;
  int32 tasks_medium_priority = 4;
  int32 tasks_low_priority = 5;
  int32 fd = 6;
  int32 conns = 7;
  int32 conns_inbound = 8;
  int32 conns_outbound = 9;
}

message GfSpLimiter {
  GfSpLimit system = 1;
  GfSpLimit transient = 2;
  map<string, GfSpLimit> service_limit = 3;
}
```

#### Quota

Here is the quota config. The configuration of `MonthlyFreeQuota` defines the free quota for each month. It will be reduced when the charge quota is exhausted.

```toml theme={null}
[Quota]
MonthlyFreeQuota = 0
```

#### MCSP Probe

It contains two probes: `liveness` and `readiness` probe. If users want to check whether MCSP is healthy and ready, they can refer to the Kubernetes docs to learn related concepts. For detailed MCSP probe info, users can refer to the MCSP probe documentation.

### MCSP Testnet Recommended Config

*Coming soon.*


# How to run a validator node for Moca Chain
Source: https://docs.moca.network/mocachain/guides/run-a-validator

How to run a validator node for Moca Chain.

# Running a Validator

<Warning>⚠️ This section may change without prior notice</Warning>
Critical information in this section may be subject to change as the network is in early stages.

<Info>
  🔓 The Moca Chain source code is publicly available on GitHub.
</Info>

## Validator Information

### Minimum System Requirements

| **Component** | **Recommended Specification**                                          | **Minimum Specification**                                              |
| ------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Hardware      | Desktop or laptop running recent versions of **Mac OS X** or **Linux** | Desktop or laptop running recent versions of **Mac OS X** or **Linux** |
| CPU           | **16 cores**                                                           | **8 cores**                                                            |
| Memory (RAM)  | **128 GB**                                                             | **64 GB**                                                              |
| Storage       | **4 TB NVMe SSD**                                                      | **2 TB NVMe SSD**                                                      |
| Bandwidth     | **5 MB/s+**                                                            | **1 MB/s+**                                                            |

Number of \$MOCA to be staked: Refer to the latest network parameters for current staking requirements.

Slashing details: Refer to the latest network parameters for current slashing conditions.

## Setting up Validator Node

### Install Fullnode

Follow the instructions [here to set up a full node](./run-a-node).

### Prepare validator, validator BLS, relayer, and challenger accounts

**Warning**

The current key generation and storage procedures are not very secure. It is highly recommended to implement a more robust method, particularly when dealing with keys like the validator operator key.

For enhanced security and best practices, the usage of the Cold Wallet and MPC Wallet is strongly encouraged.

```bash theme={null}
mocad keys add validator --keyring-backend test
mocad keys add validator_bls --keyring-backend test --algo eth_bls
mocad keys add validator_relayer --keyring-backend test
mocad keys add validator_challenger --keyring-backend test

```

**Tip**

Alternatively, if you choose a different **\$KEY\_HOME** location and you are not using the suggested default **\~/.mocad**, you may start the full node by using below script, where **\$KEY\_HOME** is your selected directory.

```bash theme={null}
mocad keys add validator --keyring-backend test --home ${KEY_HOME}
mocad keys add validator_bls --keyring-backend test --algo eth_bls --home ${KEY_HOME}
mocad keys add validator_relayer --keyring-backend test --home ${KEY_HOME}
mocad keys add validator_challenger --keyring-backend test --home ${KEY_HOME}

```

### Obtain validator, validator BLS, relayer, and challenger account addresses

**Note**

Ensure you choose the correct –keyring-backend and that –home is set correctly if you saved the files in a custom folder in step 2.

**Note:** For the `MsgCreateValidator` proposal, the delegator and validator addresses must be the same account.

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
RELAYER_ADDR=$(mocad keys show validator_relayer -a --keyring-backend test)
CHALLENGER_ADDR=$(mocad keys show validator_challenger -a --keyring-backend test)
VALIDATOR_BLS=$(mocad keys show validator_bls --keyring-backend test --output json | jq -r '.pubkey_hex')
VALIDATOR_BLS_PROOF=$(mocad keys sign ${VALIDATOR_BLS} --keyring-backend test --from validator_bls)
VALIDATOR_NODE_PUB_KEY=$(cat ~/.mocad/config/priv_validator_key.json | jq -r '.pub_key.value')

```

**Warning**

The file **\~/.mocad/config/priv\_validator\_key.json** contains your validator's consensus key. This key is used to sign blocks. Keep it secure — if compromised, your validator can be slashed.

Ensure your validator account is funded with sufficient \$MOCA before proceeding.

### Authorize Governance Module to allow Delegation

Generic Authorization

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
GOV_ADDR=0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2
mocad tx authz grant ${GOV_ADDR} generic --msg-type=/cosmos.staking.v1beta1.MsgDelegate --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://testnet-lcd.mocachain.org:443" -b sync --gas "200000000" --fees "100000000000000000000amoca" --yes
```

OR Limited Authorization

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
GOV_ADDR=0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2
mocad tx authz grant ${GOV_ADDR} delegate --allowed-validators=${VALIDATOR_ADDR} --spend-limit=10000000000000000000000amoca  --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://testnet-lcd.mocachain.org:443" -b sync --gas "2000000" --fees "1000000000000000000amoca" --yes
```

### Submit a Create Validator Proposal

Replace the values in the following JSON and save it as **create\_validator\_proposal.json**:

**\$**: A custom human-readable name for this node.

**\$**: The consensus key generated in step 1 (stored in **\$/.mocad/config/priv\_validator\_key.json** by default).

**\$**: The operator address created in step 2.

**\$**: The delegator address created in step 2.

**\$**: The BLS key created in step 2.

**\$**: The BLS proof created in step2.

**\$**: The relayer address created in step 2.

**\$**: The challenger address created in step 2.

```json theme={null}
{
  "messages": [
    {
      "@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
      "description": {
        "moniker": "${MONIKER_NAME}",
        "identity": "",
        "website": "https://${MONIKER_NAME}",
        "security_contact": "",
        "details": "${MONIKER_NAME} details"
      },
      "commission": {
        "rate": "0.070000000000000000",
        "max_rate": "1.000000000000000000",
        "max_change_rate": "0.010000000000000000"
      },
      "min_self_delegation": "1",
      "delegator_address": "${DELEGATOR_ADDR}",
      "validator_address": "${VALIDATOR_ADDR}",
      "pubkey": {
        "@type": "/cosmos.crypto.ed25519.PubKey",
        "key": "${VALIDATOR_NODE_PUB_KEY}"
      },
      "value": {
        "denom": "amoca",
        "amount": "10000000000000000000000"
      },
      "from": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
      "relayer_address": "${RELAYER_ADDR}",
      "challenger_address": "${CHALLENGER_ADDR}",
      "bls_key": "${VALIDATOR_BLS}",
      "bls_proof": "${VALIDATOR_BLS_PROOF}"
    }
  ],
  "metadata": "",
  "title": "Create ${MONIKER_NAME} Validator",
  "summary": "create ${MONIKER_NAME} validator",
  "deposit": "10000000000000000000000amoca"
}
```

You can also use the gen\_validator\_proposal.sh script to create：

```bash theme={null}
# !/bin/bash

MONIKER_NAME="validator-lsl"
# create accounts
echo "Creating validator, validator BLS, relayer, and challenger accounts..."
mocad keys add validator --keyring-backend test
mocad keys add validator_bls --keyring-backend test --algo eth_bls
mocad keys add validator_relayer --keyring-backend test
mocad keys add validator_challenger --keyring-backend test
# get accounts and private key
echo "Obtaining addresses and keys..."
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
RELAYER_ADDR=$(mocad keys show validator_relayer -a --keyring-backend test)
CHALLENGER_ADDR=$(mocad keys show validator_challenger -a --keyring-backend test)
VALIDATOR_BLS=$(mocad keys show validator_bls --keyring-backend test --output json | jq -r '.pubkey_hex')
VALIDATOR_BLS_PROOF=$(mocad keys sign ${VALIDATOR_BLS} --keyring-backend test --from validator_bls)
VALIDATOR_NODE_PUB_KEY=$(cat ~/.mocad/config/priv_validator_key.json | jq -r '.pub_key.value')
# grant staking authz to governance module
echo "Granting staking authz to governance module..."
GOV_ADDR=0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2
mocad tx authz grant ${GOV_ADDR} generic --msg-type=/cosmos.staking.v1beta1.MsgDelegate --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://testnet-lcd.mocachain.org:443" -b sync --gas "200000000" --fees "100000000000000000000amoca" --yes
# generate the JSON file
echo "Generating create_validator_proposal.json..."
cat <<EOF > proposal.json
{
"messages": [
{
"@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
"description": {
"moniker": "${MONIKER_NAME}",
"identity": "",
"website": "https://${MONIKER_NAME}",
"security_contact": "",
"details": "${MONIKER_NAME} details"
},
"commission": {
"rate": "0.070000000000000000",
"max_rate": "1.000000000000000000",
"max_change_rate": "0.010000000000000000"
},
"min_self_delegation": "1",
"delegator_address": "${DELEGATOR_ADDR}",
"validator_address": "${VALIDATOR_ADDR}",
"pubkey": {
"@type": "/cosmos.crypto.ed25519.PubKey",
"key": "${VALIDATOR_NODE_PUB_KEY}"
},
"value": {
"denom": "amoca",
"amount": "10000000000000000000000"
},
"from": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
"relayer_address": "${RELAYER_ADDR}",
"challenger_address": "${CHALLENGER_ADDR}",
"bls_key": "${VALIDATOR_BLS}",
"bls_proof": "${VALIDATOR_BLS_PROOF}"
}
],
"metadata": "",
"title": "Create ${MONIKER_NAME} Validator",
"summary": "create ${MONIKER_NAME} validator",
"deposit": "10000000000000000000000amoca"
}
EOF
echo "proposal.json has been created."

```

Run the script

```bash theme={null}
bash gen_validator_proposal.sh

```

and you will see the output:

```bash theme={null}
VALIDATOR_ADDR: 0x400b809ec90B8666c671b7ceC82033Dd6186D8c8
DELEGATOR_ADDR: 0x400b809ec90B8666c671b7ceC82033Dd6186D8c8
RELAYER_ADDR: 0xf7B8eeC1E7eb13827a9738A39f965f06DdfE4A90
CHALLENGER_ADDR: 0x5cc8eC44a7Cc8F5BcdF6Eb9301D9632828C20651
VALIDATOR_BLS: 18726fbcace099dce4cee158410bdc94e1b19f6531dd5ccf5327dd5384ef3422037862be14e324d7b8e4175fa0c86d053974a320ee92681560aa947c310d63c827dd73092bf57da29b34f2e4844a55aee4f803f009efff1ce7edc797e16fcf31008f67eba9fabad94876d65d135458fa1c814562cf1da8e1574c68ad4cbda887
VALIDATOR_BLS_PROOF: 0e5361e641ecc43b30fa2d921d39e5793d6def5638a5e6badb08827867a9a396134f0000ca9e20eebc51e62ab58c99c8576c2f384f103a55cfc568c2e98dc375
VALIDATOR_NODE_PUB_KEY: uk+p1GR1/Iy5B9rkKRe6lmRta1bnkFTM3HLd+8wpZL4=

```

### Submit the governance proposal. Ensure the validator account has enough \$MOCA.

**Info**

If you are utilizing the Cold Wallet or MPC wallet, please proceed to next step

```bash theme={null}
VALIDATOR_ADDR=$(mocad keys show validator -a --keyring-backend test)
DELEGATOR_ADDR=$VALIDATOR_ADDR
mocad tx gov submit-proposal ./proposal.json --keyring-backend test --chain-id "moca_222888-1" --from ${DELEGATOR_ADDR} --node "https://testnet-lcd.mocachain.org:443" -b sync --gas "600000" --fees "100000000000000000000amoca" --yes

```

You can see the following output:

```bash theme={null}
code: 0
codespace: ""
data: 1A080000000000008A7A
events: []
gas_used: "0"
gas_wanted: "0"
height: "0"
info: ""
logs: []
raw_log: '[]'
timestamp: ""
tx: null
txhash: 94BFFAA9792A9C94BC1A925C433F5CA13CB1526C8E85D83D9D462ACF766E8475

```

Find the proposal ID:

```bash theme={null}
mocad q tx BB845EA77C5051A8885FCEB6FAF06E279305D9DE7B03DBA8915D1A1E2804B3AF --node "https://testnet-lcd.mocachain.org:443" --output json | jq '.logs[] | .events[] | select(.type == "submit_proposal") | .attributes[] | select(.key == "proposal_id") | .value | tonumber'

```

```bash theme={null}
3

```

Query proposal status

```bash theme={null}
curl -s https://testnet-api.mocachain.org/cosmos/gov/v1/proposals/3 | jq

```

Output:

```bash theme={null}
{
"proposal": {
"id": "3",
"messages": [
{
"@type": "/cosmos.staking.v1beta1.MsgCreateValidator",
"description": {
"moniker": "validator-lsl",
"identity": "",
"website": "https://validator-lsl",
"security_contact": "",
"details": "validator-lsl details"
},
"commission": {
"rate": "0.070000000000000000",
"max_rate": "1.000000000000000000",
"max_change_rate": "0.010000000000000000"
},
"min_self_delegation": "1",
"delegator_address": "0x0E47f44E8e5aaaFFB2D93f8Ec003470C76a70f1a",
"validator_address": "0x0E47f44E8e5aaaFFB2D93f8Ec003470C76a70f1a",
"pubkey": {
"@type": "/cosmos.crypto.ed25519.PubKey",
"key": "NgpQL9w9C36mRn5TRuEooCs7WSnfeSWTawUhleiAzJQ="
},
"value": {
"denom": "amoca",
"amount": "10000000000000000000000"
},
"from": "0x7b5Fe22B5446f7C62Ea27B8BD71CeF94e03f3dF2",
"relayer_address": "0x2663170D78C7F2975abdd230Fa29Abf2E599dFf3",
"challenger_address": "0xc1E3825A64e3fBeeb0F0dE301B9A5cf6A0b93555",
"bls_key": "19788627475911af79040fb2cc06b3e2c55d294040aa2ea0cf82b0be34263fcd1546cadd9ef7cef43c0b8ace373b202f564d44f954ac1525a85694ea1cba8958093abea4bd8c042530d1028bd53030292983f3fe52a81ae262cdf23e056470a009d43f34369193f197c409533726cd62ce049a63ee80577718df85fec4874b31",
"bls_proof": "256d6283d5eb2e989f7dcb37f9c87db714a626af5bd40efc98d807c6c9acab3828f432091f3923b2b680e2c8479f60d896557586d916d5e06609eae5859912c0"
}
],
"status": "PROPOSAL_STATUS_VOTING_PERIOD",
"final_tally_result": {
"yes_count": "0",
"abstain_count": "0",
"no_count": "0",
"no_with_veto_count": "0"
},
"submit_time": "2024-11-18T10:13:17.955988297Z",
"deposit_end_time": "2024-11-19T10:13:17.955988297Z",
"total_deposit": [
{
"denom": "amoca",
"amount": "10000000000000000000000"
}
],
"voting_start_time": "2024-11-18T10:13:17.955988297Z",
"voting_end_time": "2024-11-19T10:13:17.955988297Z",
"metadata": "",
"title": "Create validator-lsl Validator",
"summary": "create validator-lsl validator",
"proposer": "0x73C4fCB7Dc03f30C2d8662d1ba146b387C3d063a",
"failed_reason": ""
}
}

```

You can find the proposal status is PROPOSAL\_STATUS\_VOTING\_PERIOD

### Wait for the voting until the Proposal is passed.

After submitting the proposal successfully, you must wait for the voting to be completed and the proposal to be approved. The voting period varies by network. Once it has passed and is successfully executed, you can verify that the node has become a validator.

Please announce your proposal ID to the existing validators, as they must vote in favour of it for it to pass.

**For existing validators** — run the following to vote on the proposal:

```bash theme={null}
mocad tx gov vote <PROPOSAL_ID> yes \
  --from validator \
  --keyring-backend test \
  --chain-id "<CHAIN_ID>" \
  --node "<NODE_URL>" \
  --gas 200000 \
  --gas-prices "10000000000amoca" \
  -y
```

**Warning**

Please ensure that the validator node is running before it is selected and if the validator is also responsible for running relayer and/or running challenger, then please ensure all these services are running as expected before selection.

### Query all validators

```bash theme={null}
mocad query staking validators --node "https://testnet-lcd.mocachain.org:443"

```

You will see the following output:

```yaml theme={null}
...
- bls_key: Hq27eaPq9K9bQWOO8KDrB9Q9HtxujkTO1Bmx9peUexwUs9mAZQ9wVXzSs9Lqg5EK1C+JE1owNcgzy1ZM76BAdhnsRWnXOyNnGzzBHyMpsBauWEEs0eMg47TADYx5UWzQGk+cNiohUL6k36xL/48s4uuXf1nDxWB/WHnMkbqlIxw=
challenger_address: 0x77C22b475bb76297BCEcad72aB4C9BAa9215dE57
commission:
commission_rates:
max_change_rate: "0.010000000000000000"
max_rate: "1.000000000000000000"
rate: "0.070000000000000000"
update_time: "2024-09-27T03:18:14.385577987Z"
consensus_pubkey:
"@type": /cosmos.crypto.ed25519.PubKey
key: bIV4oNvEblriuduP9dBK2fKVeEj4bAAgRdSY+JJz6oM=
delegator_shares: "10000000000000000000000.000000000000000000"
description:
details: my-validator details
identity: ""
moniker: my-validator
security_contact: ""
website: https://my-validator
jailed: false
min_self_delegation: "1"
operator_address: 0xD4d6B184E53a5625d7B842245E8E46842912F151
relayer_address: 0xa6bFd1EB8657bE66f7B9AcA7d27dB804214e2Af2
self_del_address: 0x0FD3375177f9B118142738Fd732D242465A18a70
status: BOND_STATUS_BONDED
tokens: "10000000000000000000000"
unbonding_height: "0"
unbonding_ids: []
unbonding_on_hold_ref_count: "0"
unbonding_time: "1970-01-01T00:00:00Z"
...

```

### One-step

For ease of execution, we have encapsulated the above process into a script.

### Prepare validator, validator BLS, relayer, and challenger accounts

```bash theme={null}
./scripts/create_validator_proposal.sh generate ~/.mocad

```

This will print the generated **validator\_address** (which is also used as the delegator address).

```bash theme={null}
===== generate ====
add keys...
show keys...
generated validator proposal file...
create_validator_proposal.json has been generated successfully at ../scripts/proposal.json.
VALIDATOR_ADDR: 0xD4d6B184E53a5625d7B842245E8E46842912F151

```

You need to ensure that the validator address is funded with sufficient Moca to be used for the subsequent proposal submission. Check the balance:

```bash theme={null}
bash scripts/create_validator_proposal.sh balance ~/.mocad

```

### Submit a Create Validator Proposal

```bash theme={null}
./scripts/create_validator_proposal.sh create ~/.mocad

```

### Wait for the Proposal to pass

Alternatively, you can also check the proposal status with the following command:

```bash theme={null}
bash scripts/create_validator_proposal.sh query_proposal ~/.mocad

```

```bash theme={null}
.....
"status": "PROPOSAL_STATUS_PASSED",
"final_tally_result": {
"yes_count": "40000000000000000000000000",
"abstain_count": "0",
"no_count": "0",
"no_with_veto_count": "0"
},
....

```


# Frequently Asked Questions
Source: https://docs.moca.network/mocachain/help/faq

Currently the Moca Chain offers 1-second block time with instant finality. It also has a TPS of 2,400 which is faster than most major L1s.

<Accordion title="What is $MOCA's role in Moca Chain?">
  `$MOCA` plays an important role as both the gas and governance token. It will also be used to drive incentive mechanics within the credential ecosystem as part of our tokenomics.
</Accordion>

<Accordion title="What do Moca Chain's performance metrics look like?">
  Currently the Moca Chain offers 1-second block time with instant finality. It also has a TPS of 2,400 which is faster than most major L1s.
</Accordion>

<Accordion title="Can I store any data on Moca Chain?">
  Yes, currently we support storing object data onto the Moca Chain but would require \$MOCA to pay for gas and storage cost to do so.
</Accordion>

<Accordion title="I need some help with a technical problem.">
  Visit our <a href="https://discord.gg/mocaversenft">Discord</a> dev-chat channel.
</Accordion>


# What is Moca Chain?
Source: https://docs.moca.network/mocachain/index

Moca Chain is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, with CometBFT consensus and decentralized storage.

> *Moca Chain is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, enabling chain-agnostic identity data issuance and verifications.*

Moca Chain is built on EVMOS (a Cosmos SDK EVM implementation) and integrates Moca's adaptation of BNB Greenfield's decentralized storage. Oracles and bridges relay identity data to other chains, so Moca Chain becomes the single source of truth for identity while staying interoperable with the rest of Web3.

This means Moca Chain:

* Houses the credential and identity-based smart contracts
* Manages the decentralized storage where credentials live
* Lets users relay proofs across chains

## Sub-second identity flows

CometBFT consensus with 1-second blocks and instant finality. Age checks, KYC gates, and logins commit in a single block, so identity flows feel synchronous to the end user.

## Consumer-scale capacity

800 transactions per block and a 60,000,000 gas limit. The chain is sized for ZK verifier contracts and batched credential issuance at production volume rather than testnet workloads.

## Builder-ready

EVM-compatible with transient storage (EIP-1153) and other Shanghai opcodes. Existing Solidity contracts port over with little to no rewrite, and standard Ethereum tooling (Hardhat, Foundry, Remix, MetaMask) works out of the box. Integration timelines move from quarters to days.

## Storage without the liability (MCSP)

The Moca Chain Storage Provider network (MCSP) gives partners S3-compatible decentralized storage, modeled after BNB Greenfield. Partners stop running their own credential databases, and users keep ownership of the underlying data.

* Payload data is stored by independent Storage Providers
* Object metadata, payments, and permissions are recorded on-chain
* Apps interact via S3-compatible APIs to upload, download, and manage objects
* Replication and integrity proofs protect data availability

## Privacy by construction

Zero-knowledge proofs use Circom circuits and Groth16, with selective disclosure defined at the schema level. Apps confirm a user is over 18, KYC'd, or accredited without ever seeing the underlying attributes. Raw data stays on the user's device, which materially reduces GDPR and CCPA exposure for partners.

## Verify once, recognized everywhere

Proofs are relayed off Moca Chain via oracles and bridges. A single verification carries to every chain a partner ships into next, so users do not re-prove the same credential per ecosystem.

## Quick chain facts

| **Field**                  | **Details**                                                      |
| -------------------------- | ---------------------------------------------------------------- |
| Consensus                  | CometBFT                                                         |
| Framework                  | Cosmos SDK                                                       |
| EVM                        | Ethereum Compatible. LONDON instruction set. Based on EvmOS v12. |
| Block Time                 | \~ 1 second                                                      |
| Finality                   | Instant (single-block)                                           |
| Native Token               | MOCA                                                             |
| Block Rewards              | Exponential decay from rewards pool. Not yet implemented.        |
| Max Validators             | 100 (CometBFT hard limit: 10,000)                                |
| Chain ID                   | 222888 (0x366a8)                                                 |
| Max Transactions Per Block | 800                                                              |
| Max Gas Limit              | 60,000,000                                                       |
| Validator Key Scheme       | ed25519                                                          |

## CometBFT consensus layer

Moca Chain uses CometBFT consensus and is governed by \$MOCA holders who decide the future direction of the ecosystem:

* Community members can submit governance proposals with a minimum deposit
* Proposals enter a voting period
* Proposals must meet minimum participation thresholds
* Approved proposals are executed on-chain automatically

[More on the consensus layer →](/mocachain/technical-details/consensus-layer)

## Cosmos SDK with EVM compatibility

Moca Chain combines the Cosmos SDK with EVM functionality based on EVMOS in a single environment:

* Cosmos \$MOCA and EVM \$MOCA are the same currency, managed by the same bank keeper module
* All addresses on chain look like EVM addresses (e.g., 0x1234...7890)
* The EVM runs the LONDON instruction set with selected SHANGHAI opcodes:
  * EIP-3855
  * EIP-3860
  * EIP-1153 (transient storage)
  * EIP-5656
  * EIP-6780

[More on EVM compatibility →](/mocachain/technical-details/evm-compatibility)

## Moca Chain Storage Provider network (MCSP)

Moca Chain ships with a built-in decentralized storage layer, the MCSP network, inspired by BNB Greenfield:

* Payload data is stored by independent Storage Providers
* Object metadata, payments, and permissions are recorded on-chain
* Users and apps interact via S3-compatible APIs to upload, download, and manage objects
* Data availability is protected through replication and integrity proofs
* Providers earn storage fees for service, with penalties for misbehavior
* Verifiable, cost-efficient storage for the Moca credential system and broader applications

[More about the MCSP network →](/mocachain/technical-details/decentralized-storage)


# AIR Wallet
Source: https://docs.moca.network/mocachain/native-dapps/air-wallet

AIR wallet

<Warning>**Coming Soon**</Warning>


# AIR Kit Dashboard
Source: https://docs.moca.network/mocachain/native-dapps/airkit-dashboard

The AIR Kit Dashboard enables partners to manage account settings, credential schemas, issuance programs, and verification programs.

The AIR Kit Dashboard is a comprehensive, self-service platform designed for partners of the Moca Network. It enables developers to manage the entire lifecycle of AIR Kit, from account creation to issuance to verification.

[Learn more](/airkit/airkit-dashboard) about the dashboard.


# Moca Chain Block Explorer
Source: https://docs.moca.network/mocachain/native-dapps/block-explorer

Overview of Moca Chain Block Explorer (Testnet)

# Moca Chain Explorer: A Functional Overview

<Tip>
  📢 **Check it out here:** [Moca Chain Explorer (Testnet)](https://testnet-scan.mocachain.org/)
</Tip>

The **Moca Chain Explorer** is the primary interface for viewing and interacting with the Moca Network.

It provides users and developers with direct access to **on-chain data** and the **decentralized storage layer**, ensuring transparency and accessibility for all participants.

## Core Functionalities

The explorer is organized into several key sections, each serving a distinct purpose for **data inspection** and **analysis**.

### 1. Network Dashboard

The **main dashboard** provides a high-level summary of the Moca Network’s current state.

**Key metrics displayed include:**

* **Live Feeds**: Latest blocks and transactions as they are confirmed
* **Network Statistics**: Real-time data on average block time, total transactions, and number of unique/active addresses
* **Storage Analytics**: Overview of the decentralized storage system, including total data stored and daily storage volume

### 2. Universal Search

A **central search bar** allows efficient querying of chain data.

Users can search by:

* Block Height
* Transaction Hash
* Wallet Address
* Storage Bucket Name
* Storage Object Name

### 3. Blockchain Data Exploration

Detailed views of core blockchain components:

* **Blocks**: Complete list of all blocks, including block proposer, transaction count, and metadata
* **Transactions**: Comprehensive log of all transactions with type, status, and associated logs
* **Accounts**: Directory of all on-chain accounts, showing balances and historical transaction counts

### 4. Decentralized Storage Inspection

Transparent view into Moca Chain’s **unique decentralized storage layer**, organized into three categories:

| Category    | Description                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Objects** | Individual data files stored on the network. Explorer lists size, type, visibility (Public/Private), and status (Created/Sealed). |
| **Buckets** | Containers for organizing objects. Shows status, creator, and number of active objects.                                           |
| **Groups**  | Used for managing permissions for shared/private data. Displays group members, owners, and resources controlled.                  |

### 5. Developer Tools

To support the developer community, the explorer includes a **Faucet**.

This tool allows developers to:

* Request **testnet tokens**
* Build and test applications in a sandbox environment
* Experiment without needing real assets


# MOCA Proof
Source: https://docs.moca.network/mocachain/native-dapps/moca-proof

Moca proof

<Warning>**Coming Soon**</Warning>


# Moca Chain Architecture Overview
Source: https://docs.moca.network/mocachain/technical-details/architecture

Moca Chain Architecture Overview, EVMos, cometBFT

# How Moca Chain Works

Moca Chain is built on the **CometBFT (Cosmos)** framework with Ethereum Virtual Machine **(EVM) compatibility** based on EVMOS and integrates with its own decentralized data storage network based on BNB Greenfield.

## Key Components

Moca Chain's architecture primarily comprises two interconnected components:

1. **EVM-Compatible Blockchain**
2. **Moca Chain Storage Providers (MCSP)**

These elements work synergistically alongside the account & credential services powered by AIR Kit to provide secure, scalable data management and identity verification.

## Integration and Operations

Moca Chain's components integrate to form a cohesive system:

* **Consensus and Security:** Validators use PoS to secure the network, challenge data integrity, and govern parameters.
* **Token Economics:** [\$MOCA](/learn/moca-coin) enables governance, staking, fees (verification, gas, storage), and incentives for honest behavior.
* **Cross-Chain Programmability:** EVM support allows smart contracts to interact across chains.
* **Data Flow:** Users store data via MCSPs, which sync metadata with the chain. Challenges ensure integrity, and ZKPs maintain privacy.


# Consensus Layer
Source: https://docs.moca.network/mocachain/technical-details/consensus-layer

How the Moca Chain consensus layer works, including CometBFT, validator roles, and governance.

Moca Chain is built on the **CometBFT (Cosmos/Tendermint)** framework with Ethereum Virtual Machine **(EVM) compatibility** (based on EVMOS) and integrates with its own decentralized data storage network (based on Binance Greenfield).

## How Moca Chain works

The Moca Chain adopts a Proof-of-Stake (PoS) mechanism based on CometBFT consensus to ensure network security. This consensus mechanism ensures network security while providing efficient block generation. On Moca Chain, blocks are generated by a group of validators every 1 second, ensuring fast confirmation and processing of transactions.

### Moca Coin (\$MOCA)

In the Moca Chain ecosystem, the Moca serves as both the gas and governance token. As a gas token, Moca is used to pay for transaction fees and smart contract execution costs on the network. As a governance token, Moca holders can participate in the governance and decision-making process of the blockchain, promoting the decentralized development of the network.

### Validators

Validators on the Moca Chain play a crucial role in the network's security and reliability, but their responsibilities go beyond that. Here are the key duties and functions of validators within the Moca Chain network:

* **Ensuring Data Integrity and Availability**: Validators play an important role in ensuring the integrity and availability of data provided by Moca Chain Storage Providers (MCSPs). They can challenge the availability of the data provided by service providers either specifically or randomly to detect potential malicious actors or underperforming providers. For such actors, validators can impose appropriate penalties, such as slashing their stakes, thereby maintaining the quality and reliability of services within the Moca Chain ecosystem.
* **Participation in Network Governance**: Validators also play a key role in network governance. They participate in deciding the future direction of the Moca Chain ecosystem by voting and can adjust various network parameters as needed.

### CometBFT PoS

In CometBFT, consensus is achieved through a voting process among validators—nodes responsible for proposing and validating blocks. Here's a step-by-step breakdown:

1. **Block Proposal and Voting Rounds:** Validators take turns proposing blocks. Each block contains transactions that modify the chain's state, such as token transfers or data storage updates. Proposals are broadcast to the network, and validators vote in rounds: Prevote, Precommit, and Commit. A block is finalized if more than two-thirds of validators (by stake weight) precommit to it.

2. **Proof-of-Stake Mechanics:** Validators stake `$MOCA` tokens to participate. The probability of being selected to propose a block is proportional to their stake. This incentivizes honest behavior, as malicious actions (e.g., double-signing) result in slashing—automatic deduction of staked tokens. Moca Chain produces blocks every (1) second, ensuring low latency and high throughput.

3. **Fault Tolerance:** CometBFT (formerly Tendermint) tolerates up to one-third of validators being faulty or offline without halting the network. This BFT property makes it resilient against attacks, provided the majority of stake is held by honest validators.

This consensus model secures Moca Chain's two primary states: account balances (including `$MOCA` ledgers) and metadata for its object storage system. Transactions, such as uploading data to Moca Chain Storage Providers (MCSPs), directly impact these states, with validators ensuring integrity through consensus.


# Decentralized Storage
Source: https://docs.moca.network/mocachain/technical-details/decentralized-storage

How Moca Chain Storage Providers (MCSPs) work, including their lifecycle, data integrity, and payment flows.

# Moca Chain Storage Provider (MCSP)

Moca Chain Storage Provider(MCSP) is an infrastructure provider for storage services. They work in synergy with Moca Chain validators to provide a complete storage service. Validators store metadata and financial ledgers with consensus, while MCSPs store the actual data (payload data) of objects using the Moca Chain chain as the ledger and single source of truth. MCSPs provide a range of convenient services for users and DApps to manage data on Moca Chain.

### Key Functions

* **Data Handling:** Provide APIs (similar to Amazon S3) for uploading, downloading, and managing data.
* **Redundancy and Integrity:** Use virtual groups (GVGs) for data replication across providers, ensuring availability.
* **Service Lifecycle:** From proposal and staking to maintenance and exit, MCSPs follow a structured process.

## How it Works

MCSP need to register themselves firstly by depositing on the Moca Chain as their Service Stake. The Moca Chain validators will then conduct a governance procedure to vote to elect the MCSP. When joining and leaving the network, MCSP must follow specific actions to ensure data redundancy for users, or they will face fines on their Service Stake.

MCSP provide publicly accessible APIs that allow users to upload, download and manage data. These APIs are designed to be similar to Amazon S3 APIs, making it easier for existing developers to write code for them. MCSP are responsible for responding to user requests to write (upload) and read (download) data, as well as managing user permissions and authentications.

Each MCSP maintains its own **local full node**, allowing for a strong connection with the Moca Chain network. This enables the MCSP to directly monitor state changes, properly index data, send transaction requests in a timely manner and manage local data accurately.

To encourage MCSP to showcase their capabilities and provide a professional storage system with high-quality SLA, it is recommended that they advertise their information and prove to the community.

## Technical Details

### Architecture

MCSP contains fifteen core modules as shown below:

* **Gater**: Serves as the gateway for MCSP, providing HTTP services and adhering to the S3 protocol.
* **Authenticator**: Responsible for verifying authentication.
* **Approver**: Responsible for handling approval requests.
* **Uploader**: Handles `PutObject` requests and stores payload data into the piece store of the primary MCSP.
* **Downloader**: Responsible for handling `GetObject` requests and `GetChallengeInfo` requests.
* **Executor**: Responsible for handling background tasks.
* **Manager**: Responsible for managing task scheduling and other management functions.
* **P2P**: Responsible for handling the interaction of control information between MCSP.
* **Receiver**: Receives data from the primary MCSP, calculates the integrity hash, signs it, and returns it to the primary MCSP for sealing.
* **Signer**: Handles the signing of the MCSP data and holds all the SP's private keys.
* **Metadata**: Provides efficient query interfaces for meta info in MCSP.
* **BlockSyncer**: Records block info in Moca Chain.
* **PieceStore**: Interacts with underlying storage vendors, e.g., AWS S3, MinIO, OSS, etc.
* **SPDB**: Stores all the contexts of the background jobs and the metadata of MCSP.
* **BSDB**: Stores all the events' data from the Moca Chain and provides them to the Metadata service of MCSP.

### Implement Customization in the Moca Chain Storage Provider

From the code level, MCSP is not only an implementation layer, it has been expanded into a framework called **MocaSP**, which allows users to implement their own logics according to their own needs. If users want to implement some specific functions, they can override these methods that are declared in the abstract interfaces. If users don't need to implement customized requirements, MocaSP will use default implementations. There are nine important layers of abstraction:

* `lifecycle`: Provides abstract interfaces to manage services.
* `module`: Provides abstract interfaces to interact with different modules in MocaSP.
* `consensus`: Provides abstract interfaces about how to query data on Moca Chain.
* `piecestore`: Used to interact with underlying storage systems.
* `spdb`: Provides abstract interfaces about how to store background tasks and metadata of MCSP.
* `bsdb`: Provides abstract interfaces about how to query metadata in MCSP.
* `rcmgr`: Provides abstract interfaces about managing cpu and memory resources in MCSP.
* `task`: Provides abstract interfaces about the smallest unit for interacting with MCSP background services.
* `taskqueue`: Provides abstract interfaces about task scheduling and executing.

## Moca Chain Storage Provider Lifecycle

### Preparation

First, the storage provider needs to learn how to run and create a storage provider node, which requires several different user accounts and a unified external EndPoint.

* Follow Recommended Prerequisites to get ready
* Create the required accounts, E.g operator/funding/seal/approval/gv/bls
* Run all services of Storage Provider

### Proposal

The Moca Chain Storage Provider (MCSP) must initiate an on-chain proposal that outlines the `Msg` information to be automatically executed after receiving approval through the voting process. Specifically, the `Msg` in this case is `MsgCreateStorageProvider`. It's essential to ensure that the deposit tokens exceed the minimum deposit tokens specified on the chain.

Below are the required fields that need to be modified in the proposal:

* **Addresses**:
  * `sp_address`: The address of the storage provider that will be added to the network.
  * `seal_address`: The address used for sealing object.
  * `approval_address`: The address responsible for approving bucket/object creation.
  * `gc_address`: The address for garbage collection.
  * `maintenance_address`: The address is used for testing while in maintenance mode.
* **EndPoint**: Details of the endpoint where the MCSP will serve data requests.
* **Quota & Price**:
  * `read_price`: The cost in Gwei per byte per second for read operations.
  * `stora_price`: The cost in Gwei per byte per second for data storage.
  * `free_read_quota`: The default free read quota allocated to users (e.g., 10GB).
* **Deposit for MCSP Staking**: The MCSP must stake the minimum required amount of \$MOCA as a commitment to providing storage services. Refer to the latest network parameters for the current staking requirement.
* **Deposit for Proposal**: The proposal itself must meet the minimum deposit requirement. Refer to the latest network parameters for the current deposit amount.

Initiating this on-chain proposal with the necessary modifications and deposits is a crucial step for the MCSP to become an active participant in the Moca Chain network, offering reliable and secure storage services to users.

### In Service

During the in-service status, Moca Chain Storage Providers (MCSPs) actively engage in the network's daily operations. They handle a variety of user requests, including data storage, retrieval, and other storage-related operations.

MCSPs assume a critical role in maintaining the availability, integrity, and confidentiality of the data they store. As gatekeepers of user access, they enforce proper authentication and authorization procedures to safeguard data from unauthorized access or tampering.

At this stage, MCSPs must create **virtual groups** within the Moca Chain network to efficiently serve buckets and objects. These virtual groups, resembling disk sectors, allow MCSPs to manage data storage in a more organized and optimized manner. By associating objects with virtual groups, MCSPs can limit the range of secondary storage providers responsible for storing object replica data, which enhances data redundancy and resilience.

Additionally, MCSPs are required to provide corresponding stakes for the amount of data they store. This staking mechanism further incentivizes MCSPs to offer reliable and high-quality services to users.

Moreover, the creation of virtual groups and staking helps to disentangle the interdependency between buckets/objects and MCSPs. By doing so, MCSPs mitigate the need for an extensive volume of transactions when modifying on-chain `BucketInfo` and `ObjectInfo` during MCSP exits and bucket migrations. This leads to more efficient network management and smoother transitions during changes in the network's composition.

### In Maintenance

The maintenance mode for service providers (MCSPs) is a status in which MCSPs do not serve any create/upload requests from users. There are two circumstances in which an MCSP can be in maintenance mode:

* When an MCSP joins the network after a proposal has passed, it will stay in `STATUS_IN_MAINTENANCE` until it sends a transaction including `msg MsgUpdateStorageProviderStatus` to Moca Chain to change its status to `STATUS_IN_SERVICE`.
* If an MCSP is already in service, it can send a transaction with `msg MsgUpdateStorageProviderStatus` to Moca Chain and request a maintenance duration. If there are no restrictions violated, the MCSP is allowed to enter maintenance mode immediately.

There are two restrictions that apply when an MCSP requests to be in maintenance:

* The total maintenance duration for each MCSP, within the number of blocks defined by `num_of_historical_blocks_for_maintenance_records`, should not exceed the `maintenance_duration_quota`.
* An MCSP is not allowed to make two consecutive requests to `STATUS_IN_MAINTENANCE` within `num_of_lockup_blocks_for_maintenance`, even if there are enough quotas for it.

To ensure the quality of service provided, we strongly recommend that MCSPs conduct a self-test via the maintenance account before turning back to `STATUS_IN_SERVICE`. This includes creating buckets/objects to verify that all functionalities work as expected.

### Exit

There are two types of exit based on the behavior and choices of the MCSP: **Graceful Exit** and **Forced Exit**.

### Graceful Exit

At some point, the MCSP may choose to voluntarily exit the Moca Chain storage network for various reasons. A graceful exit process is crucial to ensure a seamless transition of responsibilities and data to other MCSPs. During the exit process, the MCSP must continue to fulfill user query requests. Once the exit process is successfully completed, the MCSP can retrieve all the staked Moca.

To execute a graceful exit, all its stored data need to be migrated to other successor MCSPs that are willing to take over. This data migration process involves recovering data from the exiting MCSP by successor MCSPs in a secure and efficient manner. After the exiting MCSP sends a `StorageProviderExit` transaction to the Moca Chain, its status will turn to `STATUS_GRACEFUL_EXITING`. A successor MCSP can initiate the recovery process by first sending a `ReserveSwapIn` transaction to the Moca Chain, reserving the exiting MCSP's position in the respective **Global Virtual Group (GVG)** or **GVG Family** so that it will be allowed to recover data from other MCSPs. Once the successor SP successfully takes over all data in a GVG or GVG Family, it will send a `CompleteSwapIn` transaction to the Moca Chain, confirming the completion of the data transfer process.

Moca Chain incorporates an effective consensus mechanism to facilitate and validate the graceful exit process. Frequent data challenges are applied to the MCSPs that take over the data to verify the integrity and consistency of the migrated data.

### Forced Exit

An uncooperative MCSP no longer wishes to provide service and refuses to go through the standard graceful exit process. In such a case, Moca Chain governance will force the MCSP to exit, making it enter `STATUS_FORCED_EXITING`. The data recovery process for the successor MCSP is the same as the graceful exit mentioned above. However, a forced exit MCSP will face penalties, and its staked Moca will be locked into the Payment module governance account.


# Moca Chain EVM Compatibility
Source: https://docs.moca.network/mocachain/technical-details/evm-compatibility

Moca Chain EVM compatibility

Moca Chain is a blockchain platform developed based on EVMOS (aka Cosmos EVM), which is a trusted Ethereum Virtual Machine (EVM) within the Cosmos ecosystem. Evmos provides EVM compatibility, enabling Moca Chain to run Ethereum smart contracts.

This compatibility means that developers can write and deploy the same smart contracts on Moca Chain and other EVM-compatible blockchains without requiring significant code modifications. Additionally, through EVM, smart contracts can interact with other EVM-compatible blockchains, making the development of multi-chain DApps possible.

As a result

* Cosmos \$MOCA and EVM \$MOCA are the same currency, managed by the same bank keeper module
* Moca uses moca-cosmos-sdk accounts so it only has EVM addresses (e.g. `0x1234...7890`)

Currently, EVM runs the LONDON instruction set, with support for some SHANGHAI opcodes, including

* EIP-3855
* EIP-3860
* EIP-1153
* EIP-5656
* EIP-6780

> *To learn what each EIP entails, check out the [EIP registry](https://eips.ethereum.org/).*

<Warning>
  **Feedback wanted!**

  New EIP supports are constantly assessed for integration so please reach out to us if you require a specific EIP so we can add to our roadmap if necessary.
</Warning>


# zkTLS and On-Chain ZKP Verification
Source: https://docs.moca.network/mocachain/technical-details/zktls

zktls and on chain zkp verification

# zkTLS

<Warning>**Coming Soon**</Warning>


# Build on Moca Chain
Source: https://docs.moca.network/mocachain/using-moca-chain/build-on-mocachain

Build on Moca Chain

<Warning>**Coming Soon**</Warning>


# How to Connect a Wallet With Moca Chain
Source: https://docs.moca.network/mocachain/using-moca-chain/connect-to-mocachain

Learn to quickly configure your crypto wallet with Moca Chain

Blockchain wallets allow you, and only you, to access your assets on Moca Chain. Wallets enable this by allowing you to create and store your private keys, which can then be used to prove that you can access the assets in the wallet to do things such as trade tokens, buy NFTs, play games, and more.

**To interact with Moca Chain you can either:**

* Deploy your AIR Account on Moca Chain
* Connect via your Web3 Wallet
* Or try out our [Block Explorer](/mocachain/native-dapps/block-explorer)

### Deploy your AIR Account on Moca Chain

<Tip>
  Interactive demo coming soon
</Tip>

## Moca Chain Testnet RPC 🌐

Copy and paste these values into any wallet that supports importing RPCs.

Quickly add Moca Chain's network to your wallet with one click.

| Key                | Value                                |
| ------------------ | ------------------------------------ |
| Network            | `Moca Chain Testnet`                 |
| RPC URL            | `https://testnet-rpc.mocachain.org`  |
| Chain ID           | `222888`                             |
| Currency symbol    | `MOCA`                               |
| Decimals           | `18`                                 |
| Block explorer URL | `https://testnet-scan.mocachain.org` |

## Supported Wallets 👛

Currently, any [EVM-based wallet](https://ethereum.org/en/wallets/find-wallet/) that allows `RPC importing` can be configured to work with Moca Chain.

Here are some examples of compatible wallets:

* [MetaMask](https://metamask.io)
* [Trust Wallet](https://trustwallet.com)
* [OKX Wallet](https://web3.okx.com/)
* [Ledger](https://www.ledger.com/)

## How To Set Up A MetaMask Wallet With Moca Chain 🦊

This will walk you through the steps of setting up and configuring a MetaMask wallet with Moca Chain.

<Info>Note: It is recommended that you set this up through Chrome.</Info>

### Step 1 - Install MetaMask

Go to MetaMask's [website](https://metamask.io/) and click to download the browser extension for your browser of choice. Make sure the extension is being offered by `metamask.io`.

<img alt="Metamask Chrome Store" />

### Step 2 - Create Your Wallet in MetaMask

Once MetaMask finishes installing as a Chrome extension, the initial prompt will show up. Click the `Create a new wallet` button to start the process.

<img alt="Metamask Get Started" />

This will ask you to first set a password. This is the password you will enter when you open up the MetaMask extension:

<img alt="Metamask Create Password" />

Next, follow the instructions to secure your wallet phrase. This step is very important as the wallet phrase is what is used to prove that you own the assets in your wallet.

<img alt="Metamask Recovery Phrase" />

🎉 Congratulations! You've set up your MetaMask wallet!

## Add Moca Chain Network To Your Wallet 🐻

Wallets can connect to various blockchains, with MetaMask setting Ethereum as its default blockchain. In order to connect to Moca Chain, we'll need to add the network to MetaMask and select it.

### Add Moca Chain Network in One Click

Use the network details from the table above to add Moca Chain Testnet to your MetaMask wallet, or add it manually below.

### Add Moca Chain Network Manually

To add the network manually, click the drop-down in the top-left of MetaMask.

<img alt="Metamask Add Network Step 1" />

When the modal appears, click the `Add network` button.

<img alt="Metamask Add Network Step 2" />

At the bottom of the existing list, click `Add network manually`.

<img alt="Metamask Add Network Step 3" />

Enter the following details into MetaMask to configure the network and connect to Moca Chain Testnet.

Once the data is entered correctly, click `Save`.

After saving the network configuration, you should be connected to the Moca Chain Testnet!


# How To Get $MOCA
Source: https://docs.moca.network/mocachain/using-moca-chain/how-to-get-moca

Learn how to get $MOCA for Moca Chain

`$MOCA` is the network token used to pay for transactions on Moca Chain.
Learn more about the [\$MOCA token](/learn/moca-coin).

> *Moca Chain is currently in Testnet*

## Testnet

Go to the [**Testnet Faucet**](https://testnet-scan.mocachain.org/faucet).

1. Verify on Discord (this is done to reduce botting)
2. Then enter your address then click Request

> *Note that you can only request from our faucet once every 24 hours.*

<Tip>If this is insufficient to your use case please reach out to our team for more testnet tokens.</Tip>

<img alt="Moca Faucet" />

## Mainnet

Our token is already live on select exchanges and can be bridged to mainnet once it is live. More details will be provided closer to the launch date. Meanwhile you can purchase our tokens on available exchanges.

### Available on Exchanges

Currently \$MOCA is available on various centralized exchanges. For more information please refer to [Coin Gecko](https://www.coingecko.com/en/coins/moca-coin)


# Moca Chain CLI
Source: https://docs.moca.network/mocachain/using-moca-chain/moca-chain-cli

Learn how to use Moca Chain CLI

Moca Chain CLI is a command line tool for you to manage your resources directly with the Cosmos and storage layer within Moca Chain.

<Warning>
  ⚠️ Repo not publicly available — please reach out to us if you would like to access this feature.
</Warning>

## CLI Guide

This command-line tool provides **basic storage features** such as:

* Creating buckets
* Uploading and downloading files
* Deleting resources

It also supports related operations for managing **groups, policies, banks, accounts**, and more.

### Command Organization

* Commands are organized into **categories** and implemented as subcommands for clarity.
* To see all command categories, use:
  ```
  moca-cmd -h
  ```

### Configuration File

* Use the `--home` option to set the path for the config file and keystore.
* By default, configuration is saved in the `.moca-cmd` directory under your system’s home directory.
* If you run a command that interacts with Moca Chain and:
  * There’s no `config/config.toml` file in the path
  * You didn’t use the `--config` flag\
    ...the tool will automatically generate a `config/config.toml` file with testnet settings.

### Example: Testnet Configuration

* The config file’s `rpcAddr` and `chainId` should match the Moca Chain network.

### Intelligent Storage Provider Selection

* The tool automatically picks the correct storage provider for each request.
* To upload to a specific provider, set the storage provider’s operator address.
* No need to change the config when working with different storage providers.

### Example Usage

To upload files to different buckets on different storage providers:

```
moca-cmd storage put test moca://bucket1/object1
moca-cmd storage put test moca://bucket2/object
```

Each command uploads to a different bucket/provider, without changing any configuration.

### Operations

<Warning>Detailed operation reference is currently in progress. Run `moca-cmd -h` to explore available commands.</Warning>


# Network Information
Source: https://docs.moca.network/mocachain/using-moca-chain/network-information

Moca Network Information

## Moca Chain Mainnet

<Tip>
  **Access Required**

  Mainnet RPC access requires an access key. Contact the Moca Chain team to obtain your key.
</Tip>

| Chain ID               | 2288 (0x8F0)                                                                                                |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| Native Token           | \$MOCA (gas and governance)                                                                                 |
| RPC (EVM)              | [https://rpc.mocachain.dev](https://rpc.mocachain.dev) (requires API key)                                   |
| RPC (Tendermint)       | [https://tm-rpc.mocachain.dev](https://tm-rpc.mocachain.dev)                                                |
| Explorer               | [https://scan.mocachain.org](https://scan.mocachain.org)                                                    |
| Consensus              | Tendermint-based Proof-of-Stake (CometBFT)                                                                  |
| Block Time             | \~1 second                                                                                                  |
| Finality               | Instant (single-block)                                                                                      |
| Block Gas Limit        | 60,000,000                                                                                                  |
| Block Max Transactions | 800                                                                                                         |
| Block Max Size         | 3 MB                                                                                                        |
| Unbonding Time         | 21 days                                                                                                     |
| EVM Compatibility      | Fully compatible (Evmos-based), supports Solidity contracts and Ethereum tooling (Metamask, Remix, Foundry) |
| Smart Contract Version | Based on go-ethereum v1.10.26, with additional EIPs (3855, 3860, 1153, 5656, 6780)                          |
| Cosmos-sdk             | v0.50.x                                                                                                     |

## Moca Chain Testnet

| Chain ID               | 222888 (0x366a8)                                                                                            |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| Native Token           | \$MOCA (gas and governance)                                                                                 |
| RPC (EVM)              | [https://testnet-rpc.mocachain.org](https://testnet-rpc.mocachain.org)                                      |
| RPC (Tendermint)       | [https://testnet-lcd.mocachain.org](https://testnet-lcd.mocachain.org)                                      |
| Explorer               | [https://testnet-scan.mocachain.org](https://testnet-scan.mocachain.org)                                    |
| Faucet                 | [https://testnet-scan.mocachain.org/faucet](https://testnet-scan.mocachain.org/faucet)                      |
| Consensus              | Tendermint-based Proof-of-Stake (CometBFT)                                                                  |
| Block Time             | \~1 second                                                                                                  |
| Finality               | Instant (single-block)                                                                                      |
| Block Gas Limit        | 60,000,000                                                                                                  |
| Block Max Transactions | 800                                                                                                         |
| Block Max Size         | 3 MB                                                                                                        |
| Unbonding Time         | 21 days                                                                                                     |
| EVM Compatibility      | Fully compatible (Evmos-based), supports Solidity contracts and Ethereum tooling (Metamask, Remix, Foundry) |
| Smart Contract Version | Based on go-ethereum v1.10.26, with additional EIPs (3855, 3860, 1153, 5656, 6780)                          |
| Cosmos-sdk             | v0.50.x                                                                                                     |


# Why Moca Chain?
Source: https://docs.moca.network/mocachain/why-mocachain

Key features that differentiate Moca Chain: sub-second identity flows, consumer-scale capacity, EVM compatibility with transient storage, MCSP storage, ZK privacy, and cross-chain proof recognition.

> *Moca Chain is a Layer 1 EVM-compatible blockchain purpose-built for decentralized identity, enabling chain-agnostic identity data issuance and verifications.*

## Sub-second identity flows

CometBFT consensus, 1-second blocks, instant finality. Age checks, KYC gates, and logins commit in a single block, so identity flows feel synchronous to the end user.

## Consumer-scale capacity

800 transactions per block and a 60,000,000 gas limit. Moca Chain handles ZK verifier contracts and batched credential issuance at full production volume, not just testnet workloads.

## Builder-ready

Moca Chain is fully EVM-compatible and supports transient storage (EIP-1153) along with other Shanghai opcodes. Existing Solidity contracts port over with little to no rewrite, and standard Ethereum tooling (Hardhat, Foundry, Remix, MetaMask) works as is. Integration moves from quarters to days.

## Storage without the liability (MCSP)

Moca Chain stores credentials in the Moca Chain Storage Provider network (MCSP), a decentralized storage layer with S3-compatible APIs:

* Data availability tracks chain uptime
* Storage is distributed across independent providers for resilience
* Geolocation-specific storage supports data residency requirements
* Partners stop running their own credential databases, and users keep ownership of the underlying data

## Privacy by construction

Privacy is built into the protocol:

* **Zero-knowledge proofs:** Verify claims without exposing data (e.g., prove you are over 18 without sharing your birthday). Moca Chain currently uses Circom circuits with Groth16.
* **Selective disclosure at the schema level:** Apps confirm a user is over 18, KYC'd, or accredited without ever seeing the underlying attributes.
* **Raw data stays on device:** Personal data never leaves the user's device, which materially reduces GDPR and CCPA exposure for partners.
* **zkTLS:** Enables secure onboarding from web sources while keeping information encrypted and user-authorized.

## Verify once, recognized everywhere

Proofs are relayed off Moca Chain via oracles and bridges. A single verification carries to every chain a partner ships into next, so users do not re-prove the same credential per ecosystem.

## Next steps

* [Technical Architecture](/mocachain/technical-details/architecture)
* [Connect to Moca Chain](/mocachain/using-moca-chain/connect-to-mocachain)
* [Run a Node](/mocachain/guides/run-a-node)


# Bring Your Own Auth
Source: https://docs.moca.network/recipes/custom-auth-integration

Skip the AIR Kit login dialog and use your existing authentication system with Partner JWT.

If your app already authenticates users (via Firebase, Auth0, Supabase, or a custom system), you can bypass the AIR Kit login dialog and pass the authenticated user straight into an AIR Kit session. This is called **Custom Auth** (or BYO Auth).

## How it works

1. Your app authenticates the user through your own system.
2. Your backend signs a Partner JWT containing the user's `email` and `partnerUserId`.
3. Your frontend passes that JWT to `airService.login({ authToken })`.
4. AIR Kit creates or loads the user's AIR Account, skipping the built-in login UI.

<Note>
  When an email is provided in the JWT, AIR Kit verifies it with a one-time password the first time. After that initial verification, subsequent logins are seamless.
</Note>

## Prerequisites

* AIR Kit SDK installed and initialized. See [Installation](/airkit/usage/installation).
* [Partner JWT signing](/airkit/usage/partner-authentication) configured (RS256 or ES256).
* The authenticated user's email address available on your backend.

## Step 1: Generate a Partner JWT on your backend

Include `email` and `partnerUserId` alongside `partnerId`:

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");

function getAuthToken(user) {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    {
      partnerId: process.env.PARTNER_ID,
      email: user.email,
      partnerUserId: user.id,
      iat: now,
      exp: now + 5 * 60,
    },
    privateKey,
    { algorithm: "RS256", header: { kid: process.env.KEY_ID } }
  );
}

// Express example
app.get("/api/air-token", requireAuth, (req, res) => {
  const token = getAuthToken(req.user);
  res.json({ token });
});
```

## Step 2: Fetch the token and log in on the frontend

```ts theme={null}
const airService = new AirService();
await airService.init({ partnerId: "your-partner-id" });

const res = await fetch("/api/air-token");
const { token } = await res.json();

const loginResult = await airService.login({ authToken: token });
console.log("AIR Account address:", loginResult.abstractAccountAddress);
```

The user is now logged into AIR Kit without seeing any login dialog. Their AIR Account is tied to the email from your system.

## Step 3: Use AIR Kit features normally

After login, all SDK methods work as usual — issue credentials, verify credentials, access smart accounts:

```ts theme={null}
if (airService.isLoggedIn) {
  const userInfo = await airService.getUserInfo();
  console.log("User:", userInfo);
}
```

## JWT payload reference

```json theme={null}
{
  "partnerId": "your-partner-id",
  "email": "user@example.com",
  "partnerUserId": "usr_abc123",
  "exp": 1728973684,
  "iat": 1728970084
}
```

| Field           | Required              | Description                                                               |
| --------------- | --------------------- | ------------------------------------------------------------------------- |
| `partnerId`     | Yes                   | Your Partner ID                                                           |
| `email`         | Yes (for custom auth) | The user's verified email, used as their AIR Account identifier           |
| `partnerUserId` | Recommended           | Your internal user ID, persisted on the AIR Account for cross-referencing |
| `exp`           | Yes                   | Token expiration (recommended: 5 minutes)                                 |

## Next steps

* [User Login & Sessions](/airkit/usage/user-authentication) for the full authentication reference
* [Partner Authentication](/airkit/usage/partner-authentication) for JWT signing setup
* [User Management](/airkit/usage/user-management) for session handling, MFA, and user info


# Recipes
Source: https://docs.moca.network/recipes/index

Task-oriented guides for common AIR Kit integration patterns.

Recipes are focused, task-oriented guides that show you how to accomplish specific goals with AIR Kit. Unlike the [Integration Guides](/airkit/guides/overview) (organized by industry vertical), recipes answer the question "How do I do X?"

<CardGroup>
  <Card title="Issue a KYC credential on a backend event" icon="webhook" href="/recipes/kyc-credential-on-event">
    Wire a KYC-complete webhook to Issue on Behalf so credentials appear in user accounts automatically.
  </Card>

  <Card title="End-to-end loyalty credential flow" icon="gift" href="/recipes/loyalty-points-issuance">
    Issue tiered loyalty credentials from your backend when users hit spend or activity thresholds.
  </Card>

  <Card title="Verify a credential in your app" icon="circle-check" href="/recipes/verify-credential-in-app">
    Prompt a user to present a credential and gate features based on the ZK verification result.
  </Card>

  <Card title="Integrate AIR Kit with wagmi" icon="ethereum" href="/recipes/wagmi-integration">
    Use the AIR Kit wagmi connector to access smart accounts and sign transactions with React Hooks.
  </Card>

  <Card title="Bring your own auth" icon="key" href="/recipes/custom-auth-integration">
    Skip the AIR Kit login dialog and use your existing authentication system with Partner JWT.
  </Card>
</CardGroup>


# Issue a KYC Credential on a Backend Event
Source: https://docs.moca.network/recipes/kyc-credential-on-event

Wire a KYC-complete webhook to Issue on Behalf so credentials appear in user accounts automatically.

This recipe shows how to issue a verifiable KYC credential the moment your identity provider confirms a user, using the [Issue on Behalf](/airkit/usage/credential/issue-on-behalf) API. The user never needs to be in an active session.

## What you'll build

1. A webhook handler that fires when your KYC provider confirms a user.
2. A Partner JWT signed with the `issue` scope targeting that user's email.
3. An Issue on Behalf API call that queues the credential for on-chain issuance.
4. A status poller that confirms the credential is `ONCHAIN`.

## Prerequisites

* [Issue on Behalf](/airkit/usage/credential/issue-on-behalf) enabled for your partner account
* A published issuance program with a schema that includes KYC fields (e.g. `kycVerified`, `kycLevel`, `verifiedAt`)
* [Partner JWT](/airkit/usage/partner-authentication) signing configured (RS256 or ES256)

## Step 1: Handle the KYC webhook

When your KYC provider (Sumsub, Onfido, Jumio, etc.) sends a verification-complete callback, extract the user email and verification result.

```js theme={null}
const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhooks/kyc-complete", async (req, res) => {
  const { userEmail, kycLevel, verifiedAt } = req.body;

  if (!userEmail) return res.status(400).json({ error: "Missing userEmail" });

  try {
    const result = await issueKycCredential(userEmail, { kycLevel, verifiedAt });
    res.json({ success: true, coreClaimHash: result.coreClaimHash });
  } catch (err) {
    console.error("Issue on Behalf failed:", err.message);
    res.status(500).json({ error: err.message });
  }
});
```

## Step 2: Sign a Partner JWT

Generate a short-lived JWT with `scope: "issue"` and the target user's email.

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");

function getPartnerJwt(email) {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    {
      partnerId: process.env.PARTNER_ID,
      scope: "issue",
      email,
      iat: now,
      exp: now + 5 * 60,
    },
    privateKey,
    {
      algorithm: "RS256",
      header: { kid: process.env.KEY_ID, typ: "JWT" },
    }
  );
}
```

## Step 3: Call Issue on Behalf

```js theme={null}
const BASE_URL =
  process.env.NODE_ENV === "production"
    ? "https://api.mocachain.org/v1"
    : "https://api.sandbox.mocachain.org/v1";

async function issueKycCredential(userEmail, kycData) {
  const token = getPartnerJwt(userEmail);

  const res = await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-partner-auth": token,
    },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.CREDENTIAL_ID,
      credentialSubject: {
        kycVerified: true,
        kycLevel: kycData.kycLevel,
        verifiedAt: kycData.verifiedAt || new Date().toISOString(),
      },
      onDuplicate: "revoke",
    }),
  });

  if (!res.ok) throw new Error(`Issue failed: ${res.status} ${await res.text()}`);
  return res.json();
}
```

## Step 4: Poll for on-chain confirmation

Issuance is asynchronous. Poll the status endpoint until `vcStatus` is `ONCHAIN`.

```js theme={null}
async function waitForOnchain(userEmail, coreClaimHash, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const token = getPartnerJwt(userEmail);
    const res = await fetch(
      `${BASE_URL}/credentials/status?coreClaimHash=${encodeURIComponent(coreClaimHash)}`,
      { headers: { "x-partner-auth": token } }
    );
    const data = await res.json();
    if (data.vcStatus === "ONCHAIN") return data;
    await new Promise((r) => setTimeout(r, Math.pow(2, i) * 1000));
  }
  throw new Error("Timed out waiting for ONCHAIN status");
}
```

## Full flow

```js theme={null}
app.post("/webhooks/kyc-complete", async (req, res) => {
  const { userEmail, kycLevel } = req.body;

  const issued = await issueKycCredential(userEmail, {
    kycLevel,
    verifiedAt: new Date().toISOString(),
  });

  const confirmed = await waitForOnchain(userEmail, issued.coreClaimHash);
  console.log(`Credential ${confirmed.vcId} is on-chain for ${userEmail}`);

  res.json({ success: true, vcId: confirmed.vcId });
});
```

## Next steps

* [Issue on Behalf API reference](/api-reference/introduction) for full endpoint details
* [Schema Creation](/airkit/usage/credential/schema-creation) to define your KYC credential schema
* [Credential Verification](/airkit/usage/credential/verify) to let verifiers check the credential


# End-to-End Loyalty Credential Flow
Source: https://docs.moca.network/recipes/loyalty-points-issuance

Issue tiered loyalty credentials from your backend when users hit spend or activity thresholds.

This recipe walks through issuing a portable loyalty credential that users carry across your partner ecosystem. When a user crosses a tier threshold (e.g. Gold, Platinum), your backend issues a new credential automatically.

## What you'll build

1. A credential schema that encodes loyalty tier, lifetime points, and membership date.
2. A backend function that issues (or upgrades) the credential when a user crosses a tier boundary.
3. Status polling to confirm on-chain issuance.

## Prerequisites

* [Issue on Behalf](/airkit/usage/credential/issue-on-behalf) enabled for your partner account
* A published issuance program with a loyalty schema
* [Partner JWT](/airkit/usage/partner-authentication) signing configured

## Step 1: Design the credential schema

Create a schema in the Developer Dashboard (Issuer > Schemas) with fields like:

| Field            | Type    | Description                                     |
| ---------------- | ------- | ----------------------------------------------- |
| `tier`           | string  | Loyalty tier name (e.g. `"Gold"`, `"Platinum"`) |
| `lifetimePoints` | integer | Total points accumulated                        |
| `memberSince`    | string  | ISO date when membership started                |
| `upgradedAt`     | string  | ISO date of the most recent tier upgrade        |

See [Schema Creation](/airkit/usage/credential/schema-creation) for full setup instructions.

## Step 2: Issue on tier upgrade

When your loyalty engine determines a user has crossed a tier boundary, call Issue on Behalf with `onDuplicate: "revoke"` to replace the previous tier credential.

```js theme={null}
const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("path/to/private.key");
const BASE_URL = process.env.API_BASE_URL || "https://api.sandbox.mocachain.org/v1";

function getPartnerJwt(email) {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign(
    { partnerId: process.env.PARTNER_ID, scope: "issue", email, iat: now, exp: now + 300 },
    privateKey,
    { algorithm: "RS256", header: { kid: process.env.KEY_ID, typ: "JWT" } }
  );
}

async function issueLoyaltyCredential(userEmail, tierData) {
  const token = getPartnerJwt(userEmail);

  const res = await fetch(`${BASE_URL}/credentials/issue-on-behalf`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-partner-auth": token },
    body: JSON.stringify({
      issuerDid: process.env.ISSUER_DID,
      credentialId: process.env.LOYALTY_CREDENTIAL_ID,
      credentialSubject: {
        tier: tierData.tier,
        lifetimePoints: tierData.lifetimePoints,
        memberSince: tierData.memberSince,
        upgradedAt: new Date().toISOString(),
      },
      onDuplicate: "revoke",
    }),
  });

  if (!res.ok) throw new Error(`Issue failed: ${res.status}`);
  return res.json();
}
```

## Step 3: Trigger on purchase events

Wire the issuance into your purchase or activity pipeline:

```js theme={null}
async function onPurchaseComplete(userEmail, purchaseAmount) {
  const user = await getUserProfile(userEmail);
  const newPoints = user.lifetimePoints + calculatePoints(purchaseAmount);
  const newTier = resolveTier(newPoints);

  if (newTier !== user.currentTier) {
    const result = await issueLoyaltyCredential(userEmail, {
      tier: newTier,
      lifetimePoints: newPoints,
      memberSince: user.memberSince,
    });
    console.log(`Upgraded ${userEmail} to ${newTier}, hash: ${result.coreClaimHash}`);
  }

  await updateUserProfile(userEmail, { lifetimePoints: newPoints, currentTier: newTier });
}
```

## Step 4: Let verifiers read the credential

Any partner in the ecosystem can verify the user's tier using [Credential Verification](/airkit/usage/credential/verify). The user presents the credential (via AIR Kit SDK), and the verifier confirms tier status without accessing underlying purchase data.

## Duplicate handling

Use `onDuplicate: "revoke"` (default) to replace the old tier credential each time the user upgrades. Use `onDuplicate: "ignore"` only if you want to keep the existing credential unchanged (e.g. for one-time membership issuance).

## Next steps

* [AIR for Loyalty](/airkit/guides/air-for-loyalty) for a broader integration guide
* [Issue on Behalf API reference](/api-reference/introduction) for endpoint details
* [Credential Verification](/airkit/usage/credential/verify) to set up cross-partner verification


# Verify a Credential in Your App
Source: https://docs.moca.network/recipes/verify-credential-in-app

Prompt a user to present a credential and gate features based on the ZK verification result.

This recipe shows how to verify a user's credential inside your application using the AIR Kit SDK. After verification, you can gate access to features, content, or services based on the result.

## What you'll build

1. A verification program configured for your app.
2. SDK code that prompts the user to present a credential.
3. Application logic that reacts to the verification result.

## Prerequisites

* AIR Kit SDK installed and initialized. See [Installation](/airkit/usage/installation) and [Initialization](/airkit/usage/initialization).
* A Verifier DID from the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard).
* At least one credential issued to a test user (see [Issue Credentials Quickstart](/airkit/quickstart/issue-credentials)).

## Step 1: Create a verification program

1. Go to the Developer Dashboard.
2. Navigate to **Verifier > Programs**.
3. Create a new verification program, selecting the credential schema you want to verify against.
4. Note the **Verification Program ID**.

## Step 2: Authenticate the user

The user must have an active session before verification. Use the AIR Kit login flow:

```ts theme={null}
const airService = new AirService();
await airService.init({ partnerId: "your-partner-id" });
const loginResult = await airService.login();
```

## Step 3: Request credential verification

Call `verifyCredentials` with your Verifier DID and the verification program ID:

<Tabs>
  <Tab title="Web">
    ```ts theme={null}
    const verificationResult = await airService.verifyCredentials({
      verifierDid: "did:air:id:test:YOUR_VERIFIER_DID",
      verificationId: "YOUR_VERIFICATION_PROGRAM_ID",
    });

    if (verificationResult.verified) {
      console.log("Credential verified:", verificationResult);
      grantAccess();
    } else {
      console.log("Verification failed or was declined");
      denyAccess();
    }
    ```
  </Tab>

  <Tab title="Flutter">
    ```dart theme={null}
    final result = await airService.verifyCredentials(
      verifierDid: "did:air:id:test:YOUR_VERIFIER_DID",
      verificationId: "YOUR_VERIFICATION_PROGRAM_ID",
    );

    if (result.verified) {
      grantAccess();
    } else {
      denyAccess();
    }
    ```
  </Tab>
</Tabs>

The SDK opens a built-in UI asking the user to select and present a matching credential. Zero-knowledge proofs are used — the verifier confirms the claim without seeing the raw data.

## Step 4: Gate features based on the result

```ts theme={null}
function grantAccess() {
  // User has a valid credential — show premium content, unlock tier benefits, etc.
}

function denyAccess() {
  // No valid credential — redirect to onboarding or show a restricted view
}
```

## Auth token for server-side verification

If you need to verify from your backend instead, generate a Partner JWT with `scope: "verify"`:

```js theme={null}
const payload = {
  partnerId: "your-partner-id",
  scope: "verify",
  exp: Math.floor(Date.now() / 1000) + 5 * 60,
};
```

See [Partner Authentication](/airkit/usage/partner-authentication) for full JWT setup.

## Next steps

* [Credential Verification reference](/airkit/usage/credential/verify) for the full API
* [Schema Design](/airkit/usage/credential/schema-overview) to understand what fields are verifiable
* [Quickstart: Credential Verification](/airkit/quickstart/verify-credentials) for a step-by-step walkthrough


# Integrate AIR Kit With Wagmi
Source: https://docs.moca.network/recipes/wagmi-integration

Use the AIR Kit wagmi connector to access smart accounts and sign transactions with React Hooks.

This recipe shows how to wire up the `@mocanetwork/airkit-connector` package so your React app can use wagmi hooks (`useAccount`, `useConnect`, `useSendTransaction`, etc.) with AIR Kit smart accounts.

## Prerequisites

* A React project with wagmi v2+ installed
* AIR Kit SDK installed: `npm install @mocanetwork/airkit @mocanetwork/airkit-connector`
* A Partner ID from the [Developer Dashboard](https://developers.sandbox.air3.com/dashboard)

## Step 1: Create the wagmi config

```ts theme={null}
import { http, createConfig } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { airConnector } from "@mocanetwork/airkit-connector";

export const wagmiConfig = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
  connectors: [
    airConnector({
      partnerId: "your-partner-id",
    }),
  ],
});
```

## Step 2: Wrap your app with WagmiProvider

```tsx theme={null}
import { WagmiProvider } from "wagmi";
import { wagmiConfig } from "./config";

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      {/* your app */}
    </WagmiProvider>
  );
}
```

## Step 3: Connect and use the account

```tsx theme={null}
import { useConnect, useAccount } from "wagmi";
import type { Connector } from "wagmi";
import type { AirConnector, AirConnectorProperties } from "@mocanetwork/airkit-connector";
import { useMemo } from "react";

function ConnectButton() {
  const { connect, connectors } = useConnect();
  const { addresses, connector, isConnected } = useAccount();

  const airWallet = useMemo<AirConnector | null>(() => {
    if ((connector as Connector & AirConnectorProperties)?.isMocaNetwork) {
      return connector as AirConnector;
    }
    return null;
  }, [connector]);

  if (isConnected && airWallet) {
    return <p>Connected: {addresses?.[0]}</p>;
  }

  return (
    <button onClick={() => connect({ connector: connectors[0] })}>
      Connect AIR Account
    </button>
  );
}
```

## Step 4: Access AirService from the connector

Once connected, you can access the underlying `AirService` for credential operations:

```ts theme={null}
const service = airWallet.airService;

const verificationResult = await service.verifyCredentials({
  verifierDid: "did:air:id:test:YOUR_VERIFIER_DID",
  verificationId: "YOUR_VERIFICATION_PROGRAM_ID",
});
```

## Step 5: Send a transaction

With the connector active, standard wagmi transaction hooks work against the user's AIR Kit smart account:

```tsx theme={null}
import { useSendTransaction } from "wagmi";
import { parseEther } from "viem";

function SendButton() {
  const { sendTransaction } = useSendTransaction();

  return (
    <button
      onClick={() =>
        sendTransaction({
          to: "0xRecipientAddress",
          value: parseEther("0.01"),
        })
      }
    >
      Send 0.01 ETH
    </button>
  );
}
```

## Next steps

* [Wagmi Connector reference](/airkit/usage/account/wagmi) for the full API
* [Smart Accounts](/airkit/usage/account/smart-account) for account abstraction details
* [Supported Chains](/airkit/usage/account/supported-chains) for the list of available networks


# Advertising & Audiences
Source: https://docs.moca.network/solutions/advertising

Build verified, consent-based audience segments without third-party cookies. Advertisers buy access to cryptographically proven user attributes — no raw data leaves user accounts.

## The Problem

Post-cookie advertising has a trust problem that no contextual or cohort-based replacement fully solves: someone still has to hold the raw user data and claim the audience is what they say it is. Data brokers vouch for segments they assembled from sources that are increasingly unverifiable. Advertisers pay for "35-44, high income, tech-interested" and get whatever the intermediary decided that means.

## What Changes With AIR Kit

* **Users hold their own verified attributes** — Demographic and interest credentials are issued by your platform based on actual KYC and behaviour, not declared preferences. They're cryptographically signed
* **Advertisers buy proof, not claims** — The DSP or SSP verifies the credential at serve time. They get COMPLIANT / NON\_COMPLIANT — a ZK proof that the user is 25–34, verified, consented, and located in AU. No raw data in the bid request
* **Consent travels cross-publisher** — A consent credential issued on your platform is verifiable by any partner publisher without a CMP re-prompt. User consented once; that consent is cryptographically provable
* **Age-restricted serving without storing DOB** — Prove `isOver18` at ad-serve time for gambling, alcohol, or adult categories. Regulatory requirements met without creating a DOB database

## How It Works

<Steps>
  <Step title="User completes profile or KYC on your platform">
    Your existing onboarding. The user verifies their age, confirms their country, or completes interest profiling. Nothing new for the user.
  </Step>

  <Step title="AIR Kit issues an audience credential">
    Your backend fires one API call. A credential encoding the user's age range, verified country, IAB interest segments, and consent record lands in their AIR Account.
  </Step>

  <Step title="Ad server verifies at serve time">
    When the user visits a publisher page, the publisher's ad server calls one SDK method. It receives a verified boolean signal: age verified, consent confirmed, segment matched.
  </Step>

  <Step title="DSP bids on verified signals">
    The bid request carries a verified audience flag. DSPs can bid higher on ZK-proven attributes than on unverified self-reported data. The audience segment is now worth more.
  </Step>
</Steps>

## What the Ad Server Actually Receives

| What the Verifier Gets     | What Stays Private            |
| -------------------------- | ----------------------------- |
| COMPLIANT / NON\_COMPLIANT | Date of birth, exact age      |
| Age range (`25-34`)        | Full name, email address      |
| `isOver18: true`           | IP address, device ID         |
| Country code (`AU`)        | Precise location              |
| IAB segment IDs            | Browsing history, clickstream |
| Consent expiry             | Declared interest details     |

## What Compliance Will Ask

**Does user consent need to be re-obtained?**
The consent credential records the user's existing consent. If they have already consented on your platform, the credential reflects that. Cross-publisher use of the credential is designed to avoid introducing new data processing, but consult your legal team to confirm this applies in your jurisdiction.

**Can users withdraw consent?**
Yes. Revoking the consent credential is one API call and takes effect immediately. The user's attributes become unverifiable across the ecosystem.

**Does this replace our CMP?**
No. Your CMP continues to collect and record consent. AIR Kit converts that consent record into a portable, cryptographically verifiable credential.

## Integration at a Glance

|                                   |                                                               |
| --------------------------------- | ------------------------------------------------------------- |
| **What your team builds**         | One API call in profile completion + one in your CMP callback |
| **Engineering effort**            | 1 backend engineer                                            |
| **Timeline to live**              | 2–4 weeks                                                     |
| **Changes to ad serving**         | Prebid adapter or server-side SDK call                        |
| **Partner publisher integration** | 3 lines of SDK code to verify                                 |

<CardGroup>
  <Card title="Developer integration guide" icon="code" href="/airkit/guides/air-for-advertising">
    Audience schemas, consent credential code, and Prebid integration.
  </Card>

  <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
    Full GDPR, CCPA, and TCF answers.
  </Card>

  <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
    Revenue model, fee structure, and rewards.
  </Card>
</CardGroup>


# Compliance & Privacy FAQ
Source: https://docs.moca.network/solutions/compliance-faq

GDPR, CCPA, data residency, PII storage, and breach liability questions answered for enterprise legal and compliance teams evaluating AIR Kit.

Answers to the questions legal and compliance teams ask when evaluating AIR Kit. If your question isn't covered here, reach out at [support@moca.network](mailto:support@moca.network).

***

## Data Storage & PII

**Does AIR Kit store our customers' personal data?**

No. AIR Kit stores only cryptographic credential hashes on Moca Chain — the proof that a credential exists and is valid. The underlying personal data (name, passport number, date of birth, address) never leaves your systems or your KYC provider's systems.

**What does a credential actually contain?**

Only the attributes you define when you create the credential schema. Best practice — and what every AIR Kit integration guide enforces — is to store only derived facts: `isOver18: true`, `kycLevel: "enhanced"`, `tier: "Gold"`. Not the raw data those facts were derived from.

**Can AIR Kit or Moca Network read our customers' credential data?**

The credential attributes you define are visible to issuers and authorised verifiers. Moca Network does not access credential content for commercial purposes. The cryptographic design means even if the chain data were inspected, it reveals only hashes without the signing keys.

**Where is data stored geographically?**

Moca Chain is an EVM-compatible L1. Credential hashes are stored on-chain. For data residency requirements (EU, Australia, etc.), the critical question is whether personal data is stored — and it is not. Credential hashes are not personal data under GDPR Recital 26 as they cannot reasonably be used to identify a natural person without the corresponding keys.

***

## GDPR

**Is this compliant with GDPR Article 5(1)(c) — data minimisation?**

Yes. The credential contains only the minimum necessary attestation. This is enforced at schema design time — our integration guides explicitly prohibit including raw PII fields in `credentialSubject`.

**How do we handle Article 17 data subject deletion requests?**

Revoke the credential via one API call. Revocation is instant and on-chain. The credential becomes unverifiable immediately. The hash on-chain remains (the chain is immutable) but contains no personal data and is cryptographically inert.

**Does issuing credentials constitute international data transfer under GDPR Chapter V?**

No personal data is transferred during credential issuance or verification. The ZK proof flow means verifiers receive only boolean results, not personal data. There are no SCCs or adequacy decision requirements.

**Who is the data controller?**

You are the data controller for your customers' personal data. AIR Kit acts as a data processor in the narrow sense that it processes the credential hash. The personal data underlying the credential remains within your data controller boundary.

**Does consent need to be obtained to issue credentials?**

You are issuing credentials based on business events within your existing relationship with the user (loyalty programme membership, KYC completion, subscription activation). This typically falls within the legitimate interest or contractual necessity lawful basis. Review with your DPO for your specific context.

***

## CCPA / CPRA

**Does issuing AIR Kit credentials constitute "selling" personal information under CCPA?**

No personal information is transferred to AIR Kit or Moca Network. Credential verification by a partner transmits only boolean results — not personal information as defined under CCPA 1798.140.

**How do we handle opt-out requests?**

Revoke the user's credentials. They become unverifiable across the ecosystem immediately.

***

## Security & Breach Liability

**What is the breach liability for verifiers accepting AIR Kit credentials?**

Verifiers hold no personal data — they receive only COMPLIANT / NON\_COMPLIANT signals. A breach of a verifier's systems exposes nothing about the credential holder's identity.

**What is the breach liability for issuers?**

As issuer, you hold the credential schema and the signed credential hashes. The underlying personal data (passport, KYC documents) remains with your KYC provider. A breach of AIR Kit's credential infrastructure would expose only hashes, which are computationally infeasible to reverse without the corresponding ZK keys.

**Is there an audit trail for credential issuance and verification?**

Yes. Every issuance and verification event is recorded on Moca Chain with a timestamp and participant identifiers. The chain provides an immutable audit log.

***

## Credentials & Revocation

**How quickly does credential revocation take effect?**

Revocation is on-chain and propagates within one block (\~1 second on Moca Chain). Any verifier calling the SDK after that point will receive a NON\_COMPLIANT result.

**What happens to credentials if a user closes their account?**

Revoke all credentials associated with the user via the API. They become unverifiable immediately. If the user later re-onboards, new credentials are issued fresh.

**Can a user hold credentials from multiple issuers in one AIR Account?**

Yes. An AIR Account can hold credentials from any number of issuers. The user controls which credentials to present at any given verifier.

**Can credentials expire?**

Yes. You set an `expirationDate` in the credential subject. After expiry, the credential returns NON\_COMPLIANT. You can re-issue with a new expiry at any time.

***

## Compliance Access Key (CAK)

**What is the Compliance Access Key (CAK)?**

CAK is an optional encryption framework within AIR Kit designed for regulated industries where verifiers need access to raw personal data (ID images, biometric photos). It adds user-consent-driven encryption at issuance and controlled decryption at verification, ensuring data sovereignty remains with the user at all times.

**How does CAK differ from the standard ZK-based flow?**

In the standard flow, verifiers only receive boolean results ("Compliant" / "Non-Compliant") via zero-knowledge proofs — they never see the underlying data. With CAK enabled, verifiers can access the encrypted raw data after the user explicitly grants consent. CAK is designed for cases where regulatory requirements mandate that verifiers review actual identity documents.

**Do I need to enable CAK?**

Not necessarily. CAK is optional. If your credentials only need ZK proof-based verification (attribute proofs without revealing raw data), the standard flow is sufficient. Enable CAK when raw PII access by verifiers is a regulatory requirement, when multiple verifiers need the same underlying data, or when you need an auditable consent trail for data access.

**Who controls whether CAK is active?**

Both Issuers and Verifiers make independent decisions. Issuers enable CAK on their pricing schemas and issuance programs. Verifiers choose whether to require CAK on their verification programs. The user always has the final say — they must explicitly consent before any data is decrypted.

**Can the platform or Moca Network decrypt CAK-encrypted data?**

No. The CAK private key is generated locally on the user's device and only shared with the Verifier after explicit user consent. The platform never holds the private key and cannot decrypt the data.

For full technical details, see the [CAK overview](/airkit/usage/credential/cak-overview), [Issuer guide](/airkit/usage/credential/cak-issuer-guide), and [Verifier guide](/airkit/usage/credential/cak-verifier-guide).

***

## Partnerships & Commercial

**Is AIR Kit SOC 2 certified?**

Reach out to [support@moca.network](mailto:support@moca.network) for current security certifications and our shared responsibility documentation.

**Can we run AIR Kit in a private deployment?**

Moca Chain is a public L1. The SDK connects to Moca Network infrastructure. Private / on-premise deployment is not currently available. Discuss specific requirements with our team.

**Who do we contact for a Data Processing Agreement (DPA)?**

Contact [support@moca.network](mailto:support@moca.network). We provide a standard DPA for enterprise partners.


# Fintech & Payments
Source: https://docs.moca.network/solutions/fintech

Reduce KYC costs, eliminate PII liability, and enable cross-platform compliance verification — without changing your KYC provider or your user flow.

## The Problem

Financial services carry the heaviest identity verification burden of any industry. Every new product, every new partner integration, every new regulatory jurisdiction demands another round of KYC — costs running $5–$50 per user, abandonment rates averaging 30%, and a growing database of sensitive documents that represents liability, not value.

## What Changes With AIR Kit

* **KYC costs fall per partner onboarded** — Your first KYC verification is the only one your customers need. Partners accept the credential, not a new document submission
* **No PII liability for verifiers** — Partners accepting your KYC credential receive only COMPLIANT / NON\_COMPLIANT. They never hold your customer's identity documents
* **Age and accreditation gates without storing raw data** — Prove a user is 18+, 21+, or an accredited investor without ever transmitting or storing the underlying facts
* **Cross-border compliance without bilateral agreements** — One KYC credential, presentable to partners across the Moca ecosystem. Partner acceptance depends on their regulatory requirements

## Specific Use Cases

**KYC Re-use Across Partners**
Your bank onboards a customer, passes KYC, issues a credential. That customer opens an account with a partner fintech. The partner verifies the credential in one SDK call — no new document submission, no re-KYC cost, no waiting period.

**DeFi and Financial Product Access**
Gate access to financial products, DeFi pools, or high-value transactions behind a KYC credential check. Users who have already verified are admitted instantly. Users who haven't are prompted to verify once.

**Accredited Investor Verification**
Issue an income or net worth attestation on your platform. Any partner offering private placements, alternative investments, or regulated financial products can verify it via ZK proof — without ever seeing the income figures.

**Age Gating**
Prove `isOver18` or `isOver21` without revealing the user's birthdate to the verifier. Regulatory requirements for age-restricted financial products are met without creating a new data storage obligation.

## What Compliance Will Ask

**Does this satisfy our AML/KYC obligations?**
Your KYC obligations remain with your KYC provider. AIR Kit converts the pass result into a portable credential — it does not replace or modify the KYC process itself.

**What does the credential contain?**
Only derived facts you define: KYC level, provider name, pass date, country of verification, boolean age checks. No raw documents, no national ID numbers, no financial data.

**Who is liable if a credential is fraudulent?**
You, as the issuer, are responsible for the KYC process that underlies the credential — the same as today. AIR Kit provides the credential infrastructure; the compliance process is yours.

**Can we revoke credentials immediately?**
Yes. Revocation is one API call and takes effect on-chain instantly.

## Integration at a Glance

|                           |                                  |
| ------------------------- | -------------------------------- |
| **What your team builds** | One API call in your KYC webhook |
| **Engineering effort**    | 1 backend engineer               |
| **Timeline to live**      | 2–3 weeks                        |
| **User flow changes**     | None                             |
| **Partner integration**   | 3 lines of SDK code              |

<CardGroup>
  <Card title="Developer integration guide" icon="code" href="/airkit/guides/air-for-fintech">
    Full schemas, KYC webhook code, and age gate patterns.
  </Card>

  <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
    Full regulatory and data handling answers.
  </Card>

  <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
    Revenue model, fee structure, and rewards.
  </Card>
</CardGroup>


# Gaming & Entertainment
Source: https://docs.moca.network/solutions/gaming

Make player achievements, ranks, and identities portable across games. Issue credentials at milestone events — players carry them into tournaments, partner games, and airdrops.

## The Problem

In gaming, players rebuild their reputation from zero every time they switch titles. A Diamond-ranked player in your game is nobody in the next one. Achievements don't transfer. Identities don't travel. Bot accounts create fake engagement metrics that poison every distribution event you run.

## What Changes With AIR Kit

* **Player achievements become portable** — A rank, badge, or title earned in your game is a verifiable credential the player carries to partner games, tournaments, and community platforms
* **Cross-game identity without account linking** — Players authenticate with their AIR Account in any game in the ecosystem. Same identity, no re-registration
* **Bot-resistant distribution** — Gate airdrops, whitelist spots, and in-game rewards to players who provably hold specific credentials — verified human, minimum playtime, achieved rank
* **Guild and DAO membership proofs** — Issue guild credentials that gate Discord roles, governance votes, and cross-game benefits without a separate verification tool

## How It Works

<Steps>
  <Step title="In-game event fires">
    A player reaches Diamond rank. Completes a raid. Achieves 100 hours of playtime. Your game server triggers the same event it always has.
  </Step>

  <Step title="Achievement credential issues automatically">
    Your backend calls AIR Kit with the achievement details. The credential lands in the player's AIR Account in the background. No wallet prompt, no UX interruption.
  </Step>

  <Step title="Player carries the credential anywhere">
    In tournament registration, partner game login, or airdrop claims — the player presents their credential. One tap. Verified instantly.
  </Step>

  <Step title="Partners verify with one call">
    Any partner game or platform calls one SDK method. They receive COMPLIANT or NON\_COMPLIANT — plus the achievement tier. No account linking required.
  </Step>
</Steps>

## What Your Players Experience

Nothing changes at the moment of earning. The credential issues silently. Players see a notification: "You earned a Diamond Rank credential." When they arrive at a partner tournament or airdrop, they tap once to present it. No new account, no form, no ID.

## What Compliance Will Ask

**What data does the credential contain?**
Only game-specific identifiers and achievement facts: game ID, achievement name, tier, timestamp. No personal data, no real-world identity.

**Can players transfer or sell credentials?**
Credentials are tied to the user's AIR Account. They are not transferable — which is precisely what makes them useful for anti-cheat and anti-bot purposes.

**Do we need to change our terms of service?**
You are issuing your own achievement data in a portable format. No new data processing category is introduced. Review with your legal team for your jurisdiction, but in most cases this falls within existing gameplay data handling.

## Integration at a Glance

|                           |                                                          |
| ------------------------- | -------------------------------------------------------- |
| **What your team builds** | One API call in your rank-up / achievement event handler |
| **Engineering effort**    | 1 backend engineer                                       |
| **Timeline to live**      | 2–3 weeks                                                |
| **Frontend changes**      | None required for issuance                               |
| **Partner integration**   | 3 lines of SDK to verify                                 |

<CardGroup>
  <Card title="Developer integration guide" icon="code" href="/airkit/guides/air-for-gaming">
    Achievement schemas, tournament gate code, and airdrop filtering.
  </Card>

  <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
    Data handling and GDPR answers.
  </Card>

  <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
    Revenue model, fee structure, and rewards.
  </Card>
</CardGroup>


# Identity & Compliance
Source: https://docs.moca.network/solutions/identity

Issue a KYC credential once. Every partner in the ecosystem accepts it via zero-knowledge proof — no raw identity data ever transmitted.

## The Problem

Every platform that needs to verify a user's identity runs its own KYC process, stores a copy of the result, and takes on the liability for protecting it. The user goes through the same friction — passport upload, liveness check, waiting period — at every new service they join.

The industry has accepted this as the cost of compliance. It isn't.

## What Changes With AIR Kit

* **Your customer verifies once** — KYC passed at your platform issues a portable credential. Every partner in the ecosystem accepts it without running KYC again
* **Verifiers receive nothing sensitive** — The ZK proof flow means a verifier gets a single answer: COMPLIANT or NON\_COMPLIANT. No passport image, no national ID, no date of birth crosses the network
* **Your KYC provider doesn't change** — You keep Jumio, Onfido, Persona, or whoever you use. AIR Kit converts their pass result into a portable credential. The verification itself stays with your provider
* **Breach liability shrinks** — Verifiers who accept AIR Kit credentials store no PII. You as the issuer store only the credential hash. The only party holding raw identity data is your KYC provider — who already has it

## Use Cases

<CardGroup>
  <Card title="KYC Portability" icon="id-card">
    Issue a KYC attestation on verification pass. Partner platforms accept it without re-running checks. One verification, ecosystem-wide acceptance.
  </Card>

  <Card title="Age Verification" icon="cake-candles">
    Prove a user is 18+ or 21+ without revealing their birthdate. The verifier learns only the boolean result — the actual age stays private.
  </Card>

  <Card title="Accredited Investor" icon="chart-line">
    Issue an income or net worth attestation for financial products, DeFi access, or private token sales. The verifier never sees the underlying figures.
  </Card>

  <Card title="Professional Credentials" icon="graduation-cap">
    Verify licences, certifications, and professional qualifications. Portable across employers, platforms, and jurisdictions.
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="User completes KYC with your provider">
    Your existing flow. Your existing KYC provider. Nothing changes for the user or your team at this step.
  </Step>

  <Step title="Your backend issues a KYC credential">
    The moment your KYC provider returns a pass result, your backend calls the AIR Kit Issue on Behalf API. One call. The credential issues silently — no user action needed.
  </Step>

  <Step title="Credential lands in the user's AIR Account">
    The user now holds a verifiable, on-chain attestation of their identity status. Not a copy of their passport — a cryptographic proof that they passed.
  </Step>

  <Step title="Any partner verifies via ZK proof">
    At any partner service, the user presents their credential. The partner calls one SDK method and receives COMPLIANT or NON\_COMPLIANT. No PII is transmitted or stored.
  </Step>
</Steps>

## What the Verifier Actually Sees

| What the Verifier Receives          | What Stays Private                |
| ----------------------------------- | --------------------------------- |
| COMPLIANT / NON\_COMPLIANT          | Full name, passport number        |
| KYC level (basic / enhanced / full) | Date of birth                     |
| `isOver18: true`                    | Residential address               |
| Credential expiry date              | National ID / tax number          |
| Issuer identifier                   | Income, net worth, financial data |

## What Compliance Will Ask

**Is this GDPR Article 5(1)(c) compliant — data minimisation?**
Yes. The credential contains only the minimum necessary attestation — the fact that KYC passed, the level, and the derived boolean `isOver18`. No underlying personal data is stored in the credential.

**How do we handle data subject deletion requests?**
Revoke the credential via one API call. Revocation is instant and on-chain. The user's attestation becomes unverifiable immediately.

**Who has access to the underlying identity documents?**
Only your KYC provider — the same as today. AIR Kit never sees raw documents. We store only the credential hash on Moca Chain.

**What if a user disputes their KYC result?**
The dispute process stays entirely with your KYC provider, as it does today. You revoke or re-issue the AIR Kit credential once the dispute resolves.

**Does AIR Kit have access to our users' data?**
No. AIR Kit never receives PII. The Issue on Behalf API call contains only the credential attributes you define — derived facts, not raw documents.

## Integration at a Glance

|                                        |                                                     |
| -------------------------------------- | --------------------------------------------------- |
| **What your team builds**              | One API call in your KYC webhook / callback handler |
| **Engineering effort**                 | 1 backend engineer                                  |
| **Timeline to live**                   | 2–3 weeks                                           |
| **Changes to your KYC provider setup** | None                                                |
| **What partners build**                | 3 lines of SDK code to verify                       |

## Next Steps

<CardGroup>
  <Card title="Developer integration guide (Fintech & Identity)" icon="code" href="/airkit/guides/air-for-fintech">
    KYC credential schemas, webhook code, and verification patterns.
  </Card>

  <Card title="Full Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
    GDPR, CCPA, data residency, and breach liability answers.
  </Card>

  <Card title="Architecture & Data Flow" icon="diagram-project" href="/airkit/guides/overview">
    ZK proof flow explained end-to-end.
  </Card>

  <Card title="Talk to our team" icon="handshake" href="https://moca.network/partners">
    Start a partnership conversation.
  </Card>
</CardGroup>


# AIR Kit for Your Business
Source: https://docs.moca.network/solutions/index

What AIR Kit enables for enterprise partners — portable credentials, cross-platform loyalty, and KYC without PII storage. No blockchain knowledge required.

Explore what AIR Kit enables by industry — no code required. For implementation and integration guides, see [AIR Kit](/airkit/index).

AIR Kit is the integration layer that lets your platform issue verifiable credentials — proofs of identity, membership, loyalty status, or any user attribute — that your customers can carry and reuse across your partner ecosystem.

Your customers stop re-verifying. Your partners stop building bilateral APIs with you. Your compliance team stops holding raw PII they don't need to hold.

## Two Ways to Use These Docs

<CardGroup>
  <Card title="I'm evaluating AIR Kit" icon="briefcase" href="/solutions/loyalty">
    Explore what AIR Kit enables for your vertical. No code, no technical setup required.
  </Card>

  <Card title="I'm ready to integrate" icon="code" href="/airkit/usage/getting-started">
    Jump to the developer Quick Setup and integration guides.
  </Card>
</CardGroup>

## What AIR Kit Does

At its core, AIR Kit enables three things:

**1. Issue credentials from your existing backend**
When a business event happens — a user passes KYC, reaches loyalty Gold, activates a subscription — your backend fires one API call. A verifiable credential lands in that user's AIR Account. No user action required, no wallet to open.

**2. Verify credentials at any point of use**
When that user shows up at your app, a partner's app, or any service in the ecosystem, one SDK call confirms what they hold. Your platform gets a simple COMPLIANT / NON\_COMPLIANT signal. No raw data crosses.

**3. Let credentials travel across platforms**
The credential belongs to the user, not your database. A loyalty Gold earned with you is presentable at a partner hotel, airline, or retailer — without a direct API agreement between you and that partner. The credential is the integration.

## Which Vertical Fits Your Business

<CardGroup>
  <Card title="Loyalty & Rewards" icon="gift" href="/solutions/loyalty">
    Cross-brand tier portability. No bilateral APIs. No unredeemed point silos.
  </Card>

  <Card title="Identity & Compliance" icon="shield-check" href="/solutions/identity">
    KYC once, accepted everywhere. ZK proof of identity without storing PII.
  </Card>

  <Card title="Fintech & Payments" icon="credit-card" href="/solutions/fintech">
    Compliance gating, accredited investor proofs, age verification without DOB storage.
  </Card>

  <Card title="Gaming & Entertainment" icon="gamepad" href="/solutions/gaming">
    Portable player achievements, cross-game identity, bot-resistant airdrop gating.
  </Card>

  <Card title="Telco & Subscriptions" icon="signal" href="/solutions/telco">
    Subscriber KYC portability for roaming, MVNO, and partner services.
  </Card>

  <Card title="Advertising & Audiences" icon="megaphone" href="/solutions/advertising">
    Verified audience segments without cookies. Age-gated serving without storing DOB.
  </Card>
</CardGroup>

## Common Questions

**Do our users need a crypto wallet?**
No. AIR Account is a smart account — users authenticate with email, social login, or passkey. The blockchain layer is invisible to them.

**How long does integration take?**
Most partners are live in 2–4 weeks for a backend engineer. The core integration is one API call in your existing event handler.

**Does AIR Kit replace our KYC provider?**
No. You keep your existing KYC provider. AIR Kit converts the pass result into a portable credential. Your provider still runs the verification.

**Where does our customer data go?**
Nowhere new. AIR Kit stores only cryptographic attestations — the proof that a fact is true, not the underlying data. See the [Compliance FAQ](/solutions/compliance-faq) for full detail.


# Loyalty & Rewards
Source: https://docs.moca.network/solutions/loyalty

Issue portable loyalty tier credentials that travel with your customers across partner brands — no bilateral API agreements required.

## The Problem

Loyalty programs today are island economies. A customer's Gold status with your brand is invisible to every partner at the other end of their journey. Cross-brand benefits require bilateral API agreements between every pair of participating companies — expensive to build, fragile to maintain, and impossible to scale beyond a handful of partners.

The result: \$100B in unredeemed loyalty points sitting in silos. Customers who don't bother earning because they can't use what they accumulate.

## What Changes With AIR Kit

* **Your customers carry their loyalty tier** — Gold earned with you is presentable at any partner in the Moca ecosystem, with no direct API between you and that partner
* **No bilateral integrations** — Partners verify the credential, not your API. You issue it once; every verifier accepts it
* **Zero friction for your existing pipeline** — Credentials issue automatically when your loyalty engine fires its existing events. No new user-facing flow required
* **Tier upgrades happen instantly** — When a customer reaches Platinum, the old credential is revoked and a new one issues. Partners see the current status, always
* **Retroactive migration** — Existing members can receive credentials in bulk. You don't start from zero users

## How It Works

<Steps>
  <Step title="Your loyalty engine fires an event">
    A customer reaches Gold. Your existing system triggers the same milestone event it always has — a database write, a webhook, an email. Nothing changes here.
  </Step>

  <Step title="AIR Kit issues a loyalty credential">
    Your backend makes one API call. A verifiable "Gold Member" credential lands in that customer's AIR Account. They don't need to open an app or take any action.
  </Step>

  <Step title="The customer presents the credential at a partner">
    At check-in, checkout, or app login at any partner in the ecosystem, the customer's credential is readable. No account linking. No API call to your platform.
  </Step>

  <Step title="The partner verifies — and gets only what they need">
    The partner's system calls one SDK method. They receive a single answer: COMPLIANT or NON\_COMPLIANT. They learn the tier level. They never see your customer's name, email, or account history.
  </Step>
</Steps>

## What Your Users Experience

Nothing changes at the point of earning. Your app, your UX, your branding. The credential issues silently in the background.

At a partner: the customer authenticates with their AIR Account (the same login they use with you). The benefit unlocks automatically. No code to enter, no linking flow to complete.

## What Compliance Will Ask

**Do you store our customer data?**
No. AIR Kit stores only the credential — a cryptographic attestation that your customer holds Gold status. Not their name, email, account history, or purchase data.

**What happens when a customer closes their account?**
You revoke the credential instantly via one API call. It becomes unverifiable immediately.

**Can partners see who our customers are?**
No. The verifier receives only tier status and an expiry date. The customer's identity is never exposed to the partner.

**Is this GDPR compliant?**
Yes. No personal data is stored in the credential — only derived facts (tier, status). Data subject deletion requests are handled by revoking the credential.

## Integration at a Glance

|                           |                                                       |
| ------------------------- | ----------------------------------------------------- |
| **What your team builds** | One API call in your existing milestone event handler |
| **Engineering effort**    | 1 backend engineer                                    |
| **Timeline to live**      | 2–4 weeks including testing                           |
| **Frontend changes**      | None required                                         |
| **What partners build**   | 3 lines of SDK code to verify                         |

## Next Steps

<CardGroup>
  <Card title="Developer integration guide" icon="code" href="/airkit/guides/air-for-loyalty">
    Full implementation with schemas, code, and status polling.
  </Card>

  <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
    Full GDPR, PII, and data residency answers.
  </Card>

  <Card title="Partner Economics" icon="chart-bar" href="/solutions/partner-economics">
    How the revenue model works for issuers and verifiers.
  </Card>

  <Card title="Talk to our team" icon="handshake" href="https://moca.network/partners">
    Start a partnership conversation.
  </Card>
</CardGroup>


# Partner Economics
Source: https://docs.moca.network/solutions/partner-economics

How the AIR Kit revenue model works for issuers, verifiers, and ecosystem partners — reward sharing, transaction fees, and the data marketplace.

AIR Kit is a two-sided network. Issuers earn by enabling verifications. Verifiers earn by participating in the ecosystem. The model is designed so that the more credentials circulate, the more value returns to the partners who issued them.

***

## The Three Revenue Streams

### 1. Rewards Sharing (Issuers)

When a user's AIR Account holds stablecoin-backed AIR SP points, the reward generated by the underlying reserves is split between the network and the issuing partner.

The default split is **95% to the partner, 5% to Moca Network**.

This means every active user you onboard — who holds a balance in their AIR Account — generates ongoing reward for you without any transaction being required.

### 2. Verification Fees (Verifiers)

When a third-party verifier checks one of your credentials, a micro-fee is collected. A portion of that fee flows back to you as the issuer.

This creates a direct economic incentive to issue high-quality, widely-accepted credentials: the more partners verify your credentials, the more fee revenue you earn.

### 3. Data Marketplace (Opt-in)

Partners who choose to participate can list anonymised, consent-backed audience segments in the Moca data marketplace. Advertisers and third parties pay to access verified segments. Revenue shares to the issuing partner.

Participation in the data marketplace is entirely opt-in and requires explicit user consent at the credential level.

***

## What This Looks Like in Practice

**A loyalty programme partner** issues tier credentials to 2 million members. 800,000 of those members hold AIR SP balances. The partner earns reward on those balances at a 95/5 split. Simultaneously, 50 partner retailers verify those tier credentials 4 million times per year — generating per-verification fee revenue for the issuing brand.

**A fintech partner** issues KYC credentials to their verified user base. Partner financial services verify those credentials for onboarding. The fintech earns a share of each verification fee — effectively monetising their KYC investment for the first time.

**A publisher** issues consent and audience credentials. Advertisers query those credentials at ad-serve time. The publisher earns per-query revenue on top of their standard CPM, and can command a premium for verified audience segments vs. unverified.

***

## What You Need to Get Started

Revenue sharing requires:

1. **An active AIR Kit partnership** — contact our team to get a Partner ID and configure your issuer account
2. **Credential issuance volume** — revenue scales with active credentials in circulation
3. **Verifier network activation** — for verification fee revenue, partner verifiers need to be onboarded to your credential programs

***

<CardGroup>
  <Card title="Talk to our team" icon="handshake" href="https://moca.network/partners">
    Discuss specific revenue projections and partnership terms.
  </Card>

  <Card title="Get started as a developer" icon="code" href="/airkit/usage/getting-started">
    Begin the technical integration while commercial terms are agreed.
  </Card>
</CardGroup>


# Telco & Subscriptions
Source: https://docs.moca.network/solutions/telco

Issue subscriber credentials at activation. Roaming and MVNO partners verify KYC status without re-running identity checks or receiving subscriber PII.

## The Problem

Carriers spend on KYC at activation, then that verified status expires at the edge of their network. A prepaid subscriber who passed full identity verification at your MVNO is unknown to your roaming partner. Carrier partnerships that could unlock subscriber benefits require bilateral API agreements that take months to negotiate and are rarely worth the integration cost.

## What Changes With AIR Kit

* **KYC travels with the subscriber** — Pass once at activation, accept everywhere in the ecosystem. Roaming partners verify the credential without calling your API or receiving subscriber data
* **Loyalty tiers become cross-carrier benefits** — Issue a Silver or Gold subscriber credential. Partner MVNOs, device retailers, and service providers accept it to unlock benefits — no direct agreement required
* **Age-restricted services gated properly** — Prove `isOver18` at point of service without transmitting or storing a subscriber's date of birth
* **Churn intervention without data sharing** — Issue a "5-year subscriber" tenure credential. Retention partners can verify loyalty without accessing your customer database

## How It Works

<Steps>
  <Step title="Subscriber activates and passes KYC">
    Your existing activation flow. Your existing identity verification. Nothing changes at this step.
  </Step>

  <Step title="AIR Kit issues a subscriber credential">
    At activation success, your backend fires one API call. A credential encoding KYC level, plan type, and age verification lands in the subscriber's AIR Account. Invisible to the subscriber.
  </Step>

  <Step title="Subscriber accesses a partner service">
    At a roaming partner, MVNO, or retail service, the subscriber authenticates with their AIR Account — the same login they use with you.
  </Step>

  <Step title="Partner verifies — no PII crosses">
    The partner calls one SDK method. They receive COMPLIANT or NON\_COMPLIANT, plus the KYC level. No MSISDN, no IMSI, no subscriber documents are transmitted.
  </Step>
</Steps>

## What Crosses the Network — and What Doesn't

| What the Roaming Partner Receives   | What Stays Private       |
| ----------------------------------- | ------------------------ |
| COMPLIANT / NON\_COMPLIANT          | MSISDN / phone number    |
| KYC level (basic / enhanced / full) | IMSI / SIM identifiers   |
| `isOver18: true`                    | Date of birth, full name |
| Plan type (prepaid / postpaid)      | Address, national ID     |
| Credential expiry                   | Billing history          |

## What Compliance Will Ask

**Does this satisfy roaming KYC obligations?**
The credential attests to the level of KYC completed at your platform. Roaming partners accepting it are verifying that fact — the underlying compliance obligation remains with the issuing carrier.

**Is subscriber PII transmitted to roaming partners?**
No. The ZK proof flow transmits only a boolean result and the credential attributes you choose to expose. MSISDN and subscriber identity documents never leave your systems.

**GDPR: where is subscriber data stored?**
On Moca Chain — a credential hash with no personal data. The raw subscriber PII stays in your systems and your KYC provider's systems, exactly as today.

## Integration at a Glance

|                                         |                                               |
| --------------------------------------- | --------------------------------------------- |
| **What your team builds**               | One API call in your activation event handler |
| **Engineering effort**                  | 1 backend engineer                            |
| **Timeline to live**                    | 2–4 weeks                                     |
| **Changes to existing activation flow** | None                                          |
| **Roaming partner integration**         | 3 lines of SDK code to verify                 |

<CardGroup>
  <Card title="Developer integration guide" icon="code" href="/airkit/guides/air-for-telco">
    Subscriber schemas, activation handler code, and roaming verification.
  </Card>

  <Card title="Compliance FAQ" icon="shield-check" href="/solutions/compliance-faq">
    Full GDPR and regulatory answers.
  </Card>

  <Card title="Partner Economics" icon="coins" href="/solutions/partner-economics">
    Revenue model, fee structure, and reward.
  </Card>
</CardGroup>