phygital-token-sdk 0.5.2 → 0.6.0

package/docs/gating/evaluation-and-errors.md

@@ -0,0 +1,134 @@
+# Evaluation & errors
+
+## Entry points
+
+| Function | When to use |
+|----------|-------------|
+| `evaluateAssetGating` | Production — resolves owner, fetches DAS assets, evaluates tiers |
+| `evaluateGatingTiers` | You already have the owner's DAS asset list |
+| `evaluateGatingFilter` | You already have assets and a single filter tree |
+| `assetMatchesPredicate` | Test one asset row against a predicate |
+
+## `evaluateAssetGating` flow
+
+```
+assetPublicKey → find asset PDA → read owner
+owner → searchAssets (paginated) → DasAsset[]
+DasAsset[] + tiers → evaluateGatingTiers → GatingEvaluationResult
+```
+
+## Filter result tree
+
+Every evaluation returns a structured `filterResult` (per tier) you can inspect:
+
+```ts
+const gold = result.tiers.find((t) => t.id === "gold");
+const tree = gold?.filterResult;
+
+// tree.kind: "count" | "totalBalance" | "and" | "or" | "not"
+// tree.passed: boolean
+
+if (tree?.kind === "count") {
+  console.log(tree.matchCount); // how many assets matched
+}
+
+if (tree?.kind === "totalBalance") {
+  console.log(tree.total); // summed raw balance
+}
+
+if (tree?.kind === "and") {
+  console.log(tree.children); // per-child results
+}
+```
+
+Use this for admin dashboards, debug panels, or analytics.
+
+## Failure messages
+
+Human-readable summaries when gating fails:
+
+```ts
+import {
+  summarizeGatingEvaluationFailure,
+  summarizeGatingTierFailure,
+  summarizeGatingFailure,
+} from "phygital-token-sdk";
+
+// No tier passed — all tier failures
+const reasons = summarizeGatingEvaluationFailure(result);
+// [
+//   'Tier "bronze":',
+//   '  Need at least 5 asset(s) matching collection = ...; found 2.',
+//   'Tier "gold":',
+//   '  Need at least 9000000 raw balance for mint ...; found 1500000.',
+// ]
+
+// One tier
+const gold = result.tiers.find((t) => t.id === "gold");
+summarizeGatingTierFailure(gold!);
+
+// Single filter tree (no tiers)
+summarizeGatingFailure(filterResult);
+```
+
+`summarizeGatingEvaluationFailure` returns `[]` when **any** tier passed. To explain why a specific tier failed even when another passed, use `summarizeGatingTierFailure` on that tier.
+
+### Predicate formatting
+
+```ts
+import { formatGatingPredicate } from "phygital-token-sdk";
+
+formatGatingPredicate({
+  collection: Gating.in("ColA", "ColB"),
+  traits: Gating.traitsAll(
+    Gating.trait("Level", GatingTraitValue.gte(5)),
+  ),
+});
+// "collection in (ColA, ColB), traits all [Level >= 5]"
+```
+
+## UX patterns
+
+### Show why access was denied
+
+```ts
+if (!result.passed) {
+  const message = summarizeGatingEvaluationFailure(result).join("\n");
+  showError(message);
+}
+```
+
+### Show progress toward next tier
+
+```ts
+const silver = result.tiers.find((t) => t.id === "silver");
+if (silver?.filterResult.kind === "count") {
+  const need = 3;
+  const have = silver.filterResult.matchCount;
+  showProgress(`Collection NFTs: ${have} / ${need}`);
+}
+```
+
+## Common failure modes
+
+| Symptom | Likely cause |
+|---------|--------------|
+| Always fails on traits | Traits split across NFTs — use one predicate with `traitsAll` |
+| `count(1, …)` fails but user "has the NFT" | Predicate includes extra fields (`collection` + wrong `mint`) |
+| Balance gate fails | Using UI amount instead of raw units (multiply by `10^decimals`) |
+| Collection not detected | DAS grouping missing or non-standard collection key |
+| Empty wallet | Owner has no indexed DAS assets yet |
+
+## Raw vs UI token amounts
+
+`balance` and `totalBalance` use **raw** on-chain units. For a 6-decimal token:
+
+| UI amount | Raw units |
+|-----------|-----------|
+| 1 token | `1_000_000n` |
+| 1.5 tokens | `1_500_000n` |
+
+```ts
+const RAW = 10n ** 6n;
+Gating.totalBalance(USDC_MINT, 100n * RAW); // 100 USDC
+```

package/docs/gating/filters-and-composition.md

@@ -0,0 +1,120 @@
+# Filters & composition
+
+A `GatingFilter` is a composable tree evaluated against the owner's full wallet.
+
+## Leaf nodes
+
+### `Gating.count(min, predicate, max?)`
+
+Counts owned assets matching the predicate. Passes when count is `≥ min` and (if set) `≤ max`.
+
+```ts
+// At least one NFT from collection (existence)
+Gating.count(1, { collection: Gating.eq("CollectionMint...") })
+
+// At least 3 from collection
+Gating.count(3, { collection: Gating.eq("CollectionMint...") })
+
+// Exactly 1 Gold NFT from collection
+Gating.count(1, {
+  collection: Gating.eq("CollectionMint..."),
+  traits: Gating.traitsAll(
+    Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+  ),
+}, 1)
+
+// Between 2 and 5 matching assets
+Gating.count(2, { collection: Gating.eq("CollectionMint...") }, 5)
+```
+
+`Gating.count(1, predicate)` is the standard existence check. There is no separate `match` API.
+
+### `Gating.totalBalance(mint, min?, max?)`
+
+Sums **raw** balance for `mint` across all owned asset rows (wallet-wide):
+
+```ts
+// At least 1 USDC (6 decimals → 1_000_000 raw units)
+Gating.totalBalance("EPjFWdd5...", 1_000_000n)
+
+// Between 1 and 10 USDC
+Gating.totalBalance("EPjFWdd5...", 1_000_000n, 10_000_000n)
+```
+
+Use `totalBalance` for fungible gates. Use `balance` on a predicate when checking a single token account row together with `mint`.
+
+## Compositors
+
+### `Gating.and(...filters)`
+
+Every child must pass.
+
+```ts
+Gating.and(
+  Gating.count(2, { collection: Gating.eq("Col...") }),
+  Gating.totalBalance("TokenMint...", 1_000_000n),
+)
+```
+
+### `Gating.or(...filters)`
+
+At least one child must pass.
+
+```ts
+Gating.or(
+  Gating.count(1, { mint: Gating.eq("VIPPassMint...") }),
+  Gating.and(
+    Gating.count(3, { collection: Gating.eq("Col...") }),
+    Gating.totalBalance("RewardToken...", 100n),
+  ),
+)
+```
+
+### `Gating.not(filter)`
+
+Inverts a child. Passes when the inner filter **fails**.
+
+```ts
+// Must NOT hold from banned collection
+Gating.not(Gating.count(1, { collection: Gating.eq("BannedCol...") }))
+```
+
+## Example campaign rule
+
+Require 2+ collection NFTs, 1 Gold with level, and enough reward tokens:
+
+```ts
+const campaignFilter = Gating.and(
+  Gating.count(2, { collection: Gating.eq("CollectionMint...") }),
+  Gating.count(1, {
+    collection: Gating.eq("CollectionMint..."),
+    traits: Gating.traitsAll(
+      Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+      Gating.trait("Level", GatingTraitValue.gte(5)),
+    ),
+  }),
+  Gating.totalBalance("RewardTokenMint...", 1_000_000n),
+);
+```
+
+Wrap this in `Gating.tier("vip", campaignFilter)` when using multi-tier evaluation — see [Tiers](./tiers.md).
+
+## Evaluating without RPC
+
+For unit tests or when you already have DAS assets:
+
+```ts
+import { evaluateGatingFilter } from "phygital-token-sdk";
+
+const result = evaluateGatingFilter(dasAssets, campaignFilter);
+console.log(result.passed);
+console.log(result.kind); // "and" | "count" | ...
+
+if (result.kind === "count") {
+  console.log(result.matchCount);
+}
+```
+
+## Conflicting rules
+
+The evaluator does not detect impossible rules upfront. Unsatisfiable `and` trees return `passed: false`. See [Evaluation & errors](./evaluation-and-errors.md) for failure messages and common footguns.

package/docs/gating/overview.md

@@ -0,0 +1,84 @@
+# Overview
+
+## What gating does
+
+1. **Resolve owner** — looks up the on-chain owner of the phygital asset from its secp256r1 public key.
+2. **Load wallet** — paginates through DAS `searchAssets` for that owner (NFTs, compressed NFTs, fungible tokens).
+3. **Evaluate rules** — runs your filter tree(s) against the loaded assets.
+
+Gating answers: *"Given what this person holds in their wallet, do they qualify?"*
+
+## Four dimensions
+
+Every rule filters on up to four fields. When combined in a single predicate, **all set fields must match on the same asset row**:
+
+| Dimension | Source (DAS) | Example |
+|-----------|--------------|---------|
+| `collection` | `grouping` where key is `collection` | Hold any NFT from a collection mint |
+| `mint` | asset `id` | Hold a specific NFT or token mint |
+| `traits` | `content.metadata.attributes` | Rarity = Gold, Level ≥ 5 |
+| `balance` | `token_info.balance` on that row | Token account balance in raw units |
+
+Wallet-level aggregations (`count`, `totalBalance`) sit on top of these per-asset predicates.
+
+## Mental model
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  evaluateAssetGating({ assetPublicKey, rpc, tiers })    │
+└───────────────────────────┬─────────────────────────────┘
+                            │
+            ┌───────────────▼───────────────┐
+            │  Owner wallet (DAS assets)     │
+            └───────────────┬───────────────┘
+                            │
+         ┌──────────────────┼──────────────────┐
+         ▼                  ▼                  ▼
+    Tier "bronze"      Tier "silver"      Tier "gold"
+    (filter tree)      (filter tree)      (filter tree)
+         │                  │                  │
+         └──────────────────┴──────────────────┘
+                            │
+              passedTierIds
+```
+
+Each **tier** has its own `GatingFilter` tree. Tiers are evaluated **independently** — a user can pass multiple tiers at once.
+
+## Filter tree layers
+
+| Layer | API | SQL analogue |
+|-------|-----|--------------|
+| Per-asset predicate | `{ collection, mint, traits, balance }` | `WHERE` on one row |
+| Count | `Gating.count(min, predicate, max?)` | `COUNT … HAVING` |
+| Sum balance | `Gating.totalBalance(mint, min?, max?)` | `SUM(balance)` |
+| Boolean | `Gating.and` / `or` / `not` | `AND` / `OR` / `NOT` |
+
+Use `Gating.count(1, predicate)` for existence checks ("hold at least one asset matching …").
+
+## Cardinality cheat sheet
+
+| Intent | API |
+|--------|-----|
+| At least 1 matching asset | `Gating.count(1, { ... })` |
+| At least N matching assets | `Gating.count(N, { ... })` |
+| Exactly 1 matching asset | `Gating.count(1, { ... }, 1)` |
+| Between N and M matching assets | `Gating.count(N, { ... }, M)` |
+| Wallet-wide token total | `Gating.totalBalance(mint, min?, max?)` |
+
+## Same asset vs same wallet
+
+This is the most common source of bugs:
+
+| Intent | Correct pattern |
+|--------|-----------------|
+| One NFT has Gold **and** Level ≥ 5 | Single predicate with `traits: Gating.traitsAll(...)` |
+| Wallet holds mint A **and** mint B (any two assets) | `Gating.and(Gating.count(1, { mint: A }), Gating.count(1, { mint: B }))` |
+| Wallet holds 3+ from collection | `Gating.count(3, { collection: ... })` |
+
+See [Recipes](./recipes.md) for more patterns.
+
+## Next steps
+
+- [Predicates](./predicates.md) — operators on collection, mint, traits, balance
+- [Filters & composition](./filters-and-composition.md) — building filter trees
+- [Tiers](./tiers.md) — assigning users to bronze / silver / gold

package/docs/gating/predicates.md

@@ -0,0 +1,122 @@
+# Predicates
+
+A **predicate** (`GatingAssetPredicate`) describes one owned asset row. Every field you set must match on the **same** asset.
+
+```ts
+type GatingAssetPredicate = {
+  collection?: GatingStringOp;
+  mint?: GatingStringOp;
+  traits?: GatingTraits;
+  balance?: GatingBalance;
+};
+```
+
+Predicates are passed to `Gating.count` (and nowhere else at the leaf level). Use the `Gating` and `GatingTraitValue` builders — do not construct raw op objects unless you are serializing rules.
+
+## Collection & mint
+
+String operators via `Gating.eq`, `Gating.neq`, `Gating.in`, `Gating.notIn`:
+
+```ts
+// Exact collection
+{ collection: Gating.eq("CollectionMintABC...") }
+
+// Any of several collections
+{ collection: Gating.in("ColA...", "ColB...") }
+
+// Exclude a collection
+{ collection: Gating.notIn("BannedCol...") }
+
+// Specific NFT mint
+{ mint: Gating.eq("NftMint...") }
+
+// One of several mints
+{ mint: Gating.in("MintA...", "MintB...") }
+```
+
+Collection is read from DAS `grouping` entries where the key is `"collection"`.
+
+## Traits (attributes)
+
+Traits use `Gating.trait(trait_type, op)` with operators from `GatingTraitValue`:
+
+| Operator | Builder | Example |
+|----------|---------|---------|
+| equals | `GatingTraitValue.eq(v)` | Rarity = Gold |
+| not equals | `GatingTraitValue.neq(v)` | Rarity ≠ Common |
+| in list | `GatingTraitValue.in(...)` | Rarity in (Gold, Platinum) |
+| not in list | `GatingTraitValue.notIn(...)` | Rarity not in (Banned) |
+| ≥ | `GatingTraitValue.gte(n)` | Level ≥ 5 |
+| ≤ | `GatingTraitValue.lte(n)` | Level ≤ 10 |
+| range | `GatingTraitValue.between(min, max)` | Level between 4 and 6 |
+
+Combine traits with **all** or **any** on the same NFT:
+
+```ts
+// Gold AND Level >= 5 on the SAME NFT
+traits: Gating.traitsAll(
+  Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+  Gating.trait("Level", GatingTraitValue.gte(5)),
+)
+
+// Gold OR Platinum on the SAME NFT
+traits: Gating.traitsAny(
+  Gating.trait("Rarity", GatingTraitValue.in("Gold", "Platinum")),
+)
+```
+
+### Trait matching notes
+
+- Trait names and string values are compared **case-insensitively** (trimmed).
+- Numeric comparisons (`gte`, `lte`, `between`) parse string attribute values when possible (`"5"` → `5`).
+- `neq` / `notIn` pass when the trait type is **absent** on the asset.
+
+## Balance
+
+`Gating.balance(min?, max?)` filters the **raw** `token_info.balance` on that asset row (not UI decimals):
+
+```ts
+// This token row has between 1M and 2M raw units
+{
+  mint: Gating.eq("TokenMint..."),
+  balance: Gating.balance(1_000_000n, 2_000_000n),
+}
+
+// Minimum only
+{ balance: Gating.balance(1000n) }
+
+// Maximum only
+{ balance: Gating.balance(undefined, 5000n) }
+```
+
+For **wallet-wide** token totals (summing across accounts), use `Gating.totalBalance` instead — see [Filters & composition](./filters-and-composition.md).
+
+NFT rows typically have no `token_info.balance`; balance checks on NFT-only predicates will fail unless the row is a fungible token.
+
+## Full predicate example
+
+```ts
+Gating.count(1, {
+  collection: Gating.eq("CollectionMint..."),
+  mint: Gating.in("NftMint1...", "NftMint2..."),
+  traits: Gating.traitsAll(
+    Gating.trait("Rarity", GatingTraitValue.in("Gold", "Platinum")),
+    Gating.trait("Level", GatingTraitValue.between(5, 10)),
+  ),
+  balance: Gating.balance(0n), // optional; rarely needed on NFTs
+})
+```
+
+## Debugging predicates
+
+```ts
+import { formatGatingPredicate } from "phygital-token-sdk";
+
+console.log(formatGatingPredicate({
+  collection: Gating.eq("Col..."),
+  traits: Gating.traitsAll(
+    Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+  ),
+}));
+// → "collection = Col..., traits all [Rarity = Gold]"
+```

package/docs/gating/recipes.md

@@ -0,0 +1,199 @@
+# Recipes
+
+Copy-paste patterns for common gating scenarios.
+
+## Hold any NFT from a collection
+
+```ts
+Gating.count(1, { collection: Gating.eq("CollectionMint...") })
+```
+
+## Hold a specific NFT mint
+
+```ts
+Gating.count(1, { mint: Gating.eq("NftMint...") })
+```
+
+## Hold N NFTs from a collection
+
+```ts
+Gating.count(5, { collection: Gating.eq("CollectionMint...") })
+```
+
+## Gold NFT from collection (traits on same asset)
+
+```ts
+Gating.count(1, {
+  collection: Gating.eq("CollectionMint..."),
+  traits: Gating.traitsAll(
+    Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+  ),
+})
+```
+
+## Gold OR Platinum from collection
+
+```ts
+Gating.count(1, {
+  collection: Gating.eq("CollectionMint..."),
+  traits: Gating.traitsAny(
+    Gating.trait("Rarity", GatingTraitValue.in("Gold", "Platinum")),
+  ),
+})
+```
+
+## Minimum token balance (wallet-wide)
+
+```ts
+Gating.totalBalance("TokenMint...", 1_000_000n)
+```
+
+## Hold NFT A and NFT B (different assets OK)
+
+```ts
+Gating.and(
+  Gating.count(1, { mint: Gating.eq("MintA...") }),
+  Gating.count(1, { mint: Gating.eq("MintB...") }),
+)
+```
+
+## VIP pass OR (collection holder + token balance)
+
+```ts
+Gating.or(
+  Gating.count(1, { mint: Gating.eq("VIPPassMint...") }),
+  Gating.and(
+    Gating.count(1, { collection: Gating.eq("CollectionMint...") }),
+    Gating.totalBalance("TokenMint...", 5_000_000n),
+  ),
+)
+```
+
+## Exclude banned collection
+
+```ts
+Gating.not(Gating.count(1, { collection: Gating.eq("BannedCol...") }))
+```
+
+## Exclude specific mints
+
+```ts
+Gating.count(1, { mint: Gating.notIn("Blocked1...", "Blocked2...") })
+```
+
+## Bronze / silver / gold tiers
+
+```ts
+const tiers = [
+  Gating.tier("bronze", Gating.count(1, {
+    collection: Gating.eq(COLLECTION),
+  })),
+  Gating.tier("silver", Gating.count(3, {
+    collection: Gating.eq(COLLECTION),
+  })),
+  Gating.tier("gold", Gating.and(
+    Gating.count(1, {
+      collection: Gating.eq(COLLECTION),
+      traits: Gating.traitsAll(
+        Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+        Gating.trait("Level", GatingTraitValue.gte(10)),
+      ),
+    }),
+    Gating.totalBalance(REWARD_TOKEN, 10_000_000n),
+  )),
+];
+```
+
+## Full app integration
+
+```ts
+import {
+  evaluateAssetGating,
+  Gating,
+  GatingTraitValue,
+  summarizeGatingEvaluationFailure,
+} from "phygital-token-sdk";
+
+async function gateExperience(assetPublicKey: string, rpc: Rpc) {
+  const result = await evaluateAssetGating({
+    assetPublicKey,
+    rpc,
+    tiers: [
+      Gating.tier("bronze", Gating.count(1, {
+        collection: Gating.eq(process.env.COLLECTION_MINT!),
+      })),
+      Gating.tier("gold", Gating.count(1, {
+        collection: Gating.eq(process.env.COLLECTION_MINT!),
+        traits: Gating.traitsAll(
+          Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+        ),
+      })),
+    ],
+  });
+
+  if (!result.passed) {
+    return {
+      allowed: false,
+      reasons: summarizeGatingEvaluationFailure(result),
+    };
+  }
+
+  return {
+    allowed: true,
+    passedTierIds: result.passedTierIds,
+    owner: result.owner,
+  };
+}
+```
+
+## Footguns
+
+### ❌ Traits split across NFTs
+
+```ts
+// WRONG — requires one NFT to be both Gold and Silver
+Gating.count(1, {
+  traits: Gating.traitsAll(
+    Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+    Gating.trait("Rarity", GatingTraitValue.eq("Silver")),
+  ),
+})
+```
+
+### ❌ Using two count(1) for traits on one NFT
+
+```ts
+// WRONG — checks two different assets
+Gating.and(
+  Gating.count(1, { traits: Gating.traitsAll(Gating.trait("Rarity", GatingTraitValue.eq("Gold"))) }),
+  Gating.count(1, { traits: Gating.traitsAll(Gating.trait("Level", GatingTraitValue.gte(5))) }),
+)
+
+// RIGHT — one NFT, all traits
+Gating.count(1, {
+  traits: Gating.traitsAll(
+    Gating.trait("Rarity", GatingTraitValue.eq("Gold")),
+    Gating.trait("Level", GatingTraitValue.gte(5)),
+  ),
+})
+```
+
+### ❌ Contradictory AND
+
+```ts
+// Always fails
+Gating.and(
+  Gating.count(1, { collection: Gating.eq("ColA") }),
+  Gating.not(Gating.count(1, { collection: Gating.eq("ColA") })),
+)
+```
+
+### ❌ UI decimals in balance
+
+```ts
+// WRONG for 6-decimal token — this is 0.000001 tokens
+Gating.totalBalance("USDC...", 1n)
+
+// RIGHT — 1 USDC
+Gating.totalBalance("USDC...", 1_000_000n)
+```