Airdrop snapshot matching and claim proofs in the SDK

quantus_sdk/lib/quantus_sdk.dart

@@ -54,6 +54,7 @@ export 'src/models/raid_stats.dart';
 export 'src/rust/api/crypto.dart' hide crystalAlice, crystalCharlie, crystalBob;
 export 'src/rust/api/ur.dart';
 export 'src/utils/ur_qr.dart';
+export 'src/rust/api/airdrop.dart';
 export 'src/rust/api/wormhole.dart';
 export 'src/services/account_discovery_service.dart';
 export 'src/services/accounts_service.dart';

quantus_sdk/lib/src/rust/api/airdrop.dart

@@ -0,0 +1,195 @@
+// This file is automatically generated, so please do not edit it.
+// @generated by `flutter_rust_bridge`@ 2.12.0.
+
+// ignore_for_file: invalid_use_of_internal_member, unused_import, unnecessary_import
+
+import '../frb_generated.dart';
+import 'crypto.dart';
+import 'package:flutter_rust_bridge/flutter_rust_bridge_for_generated.dart';
+
+// These functions are ignored because they are not marked as `pub`: `compact8_decode`, `decode_account`, `derive_dilithium`, `derive_historical_dilithium`, `derive`, `dilithium_keygen_ids`, `hash_felts_rate4_pad10`, `hash_felts`, `hash_padded_legacy`, `hash_padded_v10`, `injective4_secret_words`, `injective4`, `mldsa87_keypair`, `now_unix`, `rehash`, `sign_dilithium_claim`, `v09_hash_no_pad`, `v09_permutation`, `wormhole_scan_paths`
+// These types are ignored because they are neither used by any `pub` functions nor (for structs and enums) marked `#[frb(unignore)]`: `HistoricalKeypair`, `SecretEncoding`, `Sponge`, `WormholeSchemeDef`
+// These function are ignored because they are on traits that is not defined in current crate (put an empty `#[frb]` on it to unignore): `assert_receiver_is_total_eq`, `clone`, `clone`, `eq`, `fmt`, `fmt`
+
+/// Determine which snapshot addresses belong to this wallet.
+///
+/// `snapshot_addresses` are the SS58 addresses from `GET /snapshot` (or the
+/// miner-rewards CSV). Dilithium matches are checked against
+/// `dilithium_public_key` under every historical hash, and — when `mnemonic`
+/// is given — against keypairs re-derived under every historical keygen era
+/// (see `dilithium_keygen_ids`). Wormhole matches are checked for HD-derived
+/// secrets (`m/44'/189189189'/0'/{0..=8}'/{0..=99}'` under both the current
+/// "Dilithium seed" and the pre-2.1.0 "Bitcoin seed" BIP32 masters, plus the
+/// legacy master-node secret) when `mnemonic` is given, plus any
+/// `extra_wormhole_secrets` (32 bytes each).
+Future<List<AirdropMatch>> findAirdropMatches({
+  required List<String> snapshotAddresses,
+  Uint8List? dilithiumPublicKey,
+  String? mnemonic,
+  required List<Uint8List> extraWormholeSecrets,
+}) => RustLib.instance.api.crateApiAirdropFindAirdropMatches(
+  snapshotAddresses: snapshotAddresses,
+  dilithiumPublicKey: dilithiumPublicKey,
+  mnemonic: mnemonic,
+  extraWormholeSecrets: extraWormholeSecrets,
+);
+
+/// Sign an airdrop claim for a Dilithium-era snapshot `address`, paying out to
+/// `claim_account`. The wallet must be ML-DSA-87 (miner keys are). Submit the
+/// result as `{"kind": "dilithium", ...fields}` within ~10 minutes.
+Future<DilithiumClaimBody> buildAirdropDilithiumClaim({
+  required Keypair keypair,
+  required String address,
+  required String claimAccount,
+}) => RustLib.instance.api.crateApiAirdropBuildAirdropDilithiumClaim(
+  keypair: keypair,
+  address: address,
+  claimAccount: claimAccount,
+);
+
+/// Sign an airdrop claim with a key from a historical keygen era: pass the
+/// `dilithium_keygen` id from the `AirdropMatch`. Re-derives the era's
+/// keypair from the mnemonic, so the wallet does not need to store it.
+/// Submit like `build_airdrop_dilithium_claim`'s result.
+Future<DilithiumClaimBody> buildAirdropDilithiumClaimFromMnemonic({
+  required String mnemonic,
+  required String dilithiumKeygen,
+  required String address,
+  required String claimAccount,
+}) => RustLib.instance.api.crateApiAirdropBuildAirdropDilithiumClaimFromMnemonic(
+  mnemonic: mnemonic,
+  dilithiumKeygen: dilithiumKeygen,
+  address: address,
+  claimAccount: claimAccount,
+);
+
+/// Prove ownership of the wormhole address derived from `wormhole_secret`
+/// (current rate-8 scheme), binding the payout to `claim_account`. Builds the
+/// circuit in-process: expect tens of seconds of CPU on first call. Submit as
+/// `{"kind": "wormhole", ...fields}`.
+Future<WormholeClaimBody> proveAirdropWormhole({required List<int> wormholeSecret, required String claimAccount}) =>
+    RustLib.instance.api.crateApiAirdropProveAirdropWormhole(
+      wormholeSecret: wormholeSecret,
+      claimAccount: claimAccount,
+    );
+
+/// A snapshot address this wallet can prove ownership of.
+class AirdropMatch {
+  /// The address exactly as it appeared in `snapshot_addresses`.
+  final String address;
+
+  /// "dilithium" or "wormhole".
+  final String kind;
+
+  /// Derivation scheme id, e.g. "dilithium-v10-padded".
+  final String scheme;
+
+  /// Whether the claim server currently accepts proofs for this scheme.
+  final bool claimable;
+
+  /// Where the key came from: "dilithium public key", an HD path,
+  /// "provided secret #N", or a historical keygen description.
+  final String source;
+
+  /// The 32-byte wormhole secret that produced the match (needed to build
+  /// the ownership proof). None for Dilithium matches.
+  final Uint8List? wormholeSecret;
+
+  /// For Dilithium matches found through a historical keygen scheme: the
+  /// keygen id to pass to `build_airdrop_dilithium_claim_from_mnemonic`.
+  /// None when the match came from the provided current public key (claim
+  /// with `build_airdrop_dilithium_claim`).
+  final String? dilithiumKeygen;
+
+  const AirdropMatch({
+    required this.address,
+    required this.kind,
+    required this.scheme,
+    required this.claimable,
+    required this.source,
+    this.wormholeSecret,
+    this.dilithiumKeygen,
+  });
+
+  @override
+  int get hashCode =>
+      address.hashCode ^
+      kind.hashCode ^
+      scheme.hashCode ^
+      claimable.hashCode ^
+      source.hashCode ^
+      wormholeSecret.hashCode ^
+      dilithiumKeygen.hashCode;
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is AirdropMatch &&
+          runtimeType == other.runtimeType &&
+          address == other.address &&
+          kind == other.kind &&
+          scheme == other.scheme &&
+          claimable == other.claimable &&
+          source == other.source &&
+          wormholeSecret == other.wormholeSecret &&
+          dilithiumKeygen == other.dilithiumKeygen;
+}
+
+/// The `POST /claim` body fields for a Dilithium claim.
+class DilithiumClaimBody {
+  final String scheme;
+  final String address;
+  final String claimAccount;
+  final String publicKeyHex;
+  final String signatureHex;
+  final PlatformInt64 expiryUnix;
+
+  const DilithiumClaimBody({
+    required this.scheme,
+    required this.address,
+    required this.claimAccount,
+    required this.publicKeyHex,
+    required this.signatureHex,
+    required this.expiryUnix,
+  });
+
+  @override
+  int get hashCode =>
+      scheme.hashCode ^
+      address.hashCode ^
+      claimAccount.hashCode ^
+      publicKeyHex.hashCode ^
+      signatureHex.hashCode ^
+      expiryUnix.hashCode;
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is DilithiumClaimBody &&
+          runtimeType == other.runtimeType &&
+          scheme == other.scheme &&
+          address == other.address &&
+          claimAccount == other.claimAccount &&
+          publicKeyHex == other.publicKeyHex &&
+          signatureHex == other.signatureHex &&
+          expiryUnix == other.expiryUnix;
+}
+
+/// The `POST /claim` body fields for a wormhole claim.
+class WormholeClaimBody {
+  final String proofKind;
+  final String proofHex;
+
+  const WormholeClaimBody({required this.proofKind, required this.proofHex});
+
+  @override
+  int get hashCode => proofKind.hashCode ^ proofHex.hashCode;
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is WormholeClaimBody &&
+          runtimeType == other.runtimeType &&
+          proofKind == other.proofKind &&
+          proofHex == other.proofHex;
+}