Skip to content

chore: update predicate catalog docs #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jonathanprozzi wants to merge 3 commits into
base: main
Choose a base branch
from
Open

chore: update predicate catalog docs #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bee6e3e
fix: align predicate usage docs with cleaned catalog
jonathanprozzi Apr 23, 2026
65f6bda
fix: update predicate catalog analysis docs
jonathanprozzi Apr 23, 2026
7109d30
fix: refresh predicate integration docs
jonathanprozzi Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
601 changes: 282 additions & 319 deletions predicates/1-predicate-analysis.md
View file
Open in desktop

Large diffs are not rendered by default.

66 changes: 22 additions & 44 deletions predicates/2-predicate-usage-by-entity-type.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ Because predicates read as `(I, predicate, object)`, verb predicates must use **

For attributive triples like `(Aave, use, Chainlink)`, the base form reads slightly differently than English prose ("Aave uses Chainlink"), but predicates are **relationship labels**, not sentences. Base form is standard in ontology design (RDF, Wikidata) and is the correct choice when `I` is the primary subject pattern.

**SDK backward compatibility:** The current SDK exports `CONTAINS_PREDICATE = 'contains'`, `IS_PREDICATE = 'is'`, etc. Migrating to base form predicates will create new atom IDs (since `"follow"` hashes differently from `"follows"`). This is a planned migration — the old predicates remain valid but the new base-form predicates become canonical going forward.
**SDK compatibility:** Use the generated constants and atom data from `@0xintuition/predicates`. Do not hand-roll legacy plain strings such as `"contains"`/`"is"` or third-person forms such as `"follows"`; they produce different atom IDs and fragment markets.

#### When NOT to Use `I`

Expand All @@ -119,17 +119,17 @@ These are still depositional (anyone can deposit to agree), but the Subject is o
**Community-scoped subjects** — a community or role atom instead of `I`:

```
(developers, recommends, Foundry) ← scoped to developers
(developers, recommend, Foundry) ← scoped to developers
(Ethereum community, support, EIP-4844) ← scoped to a community
(security researchers, trust, Trail of Bits) ← scoped to a role
```

These create **scoped markets** where the same predicate can have different TVL across different communities. You could have:

```
(I, recommends, Foundry) ← universal market: 500 ETH
(developers, recommends, Foundry) ← developer-scoped: 300 ETH
(auditors, recommends, Foundry) ← auditor-scoped: 20 ETH
(I, recommend, Foundry) ← universal market: 500 ETH
(developers, recommend, Foundry) ← developer-scoped: 300 ETH
(auditors, recommend, Foundry) ← auditor-scoped: 20 ETH
```

This is a valid extension pattern but should be used sparingly. Each community subject fragments the market. The universal `I` market should always exist as the primary signal; scoped markets are supplementary.
Expand Down Expand Up @@ -260,10 +260,9 @@ These use specific entity Subjects. The market is about whether the claim is TRU

| Predicate | Example Triple | What Deposits Mean |
|---|---|---|
| `is` | `(Ethereum, is, blockchain)` | "I agree with this classification" |
| `has type` | `(Uniswap, has type, DEX)` | "I agree with this type assignment" |
| `instance of` | `(USDC, instance of, stablecoin)` | "I agree USDC is a stablecoin" |
| `subclass of` | `(DEX, subclass of, exchange)` | "I agree with this taxonomy" |
| `has type` | `(Uniswap, has type, Decentralized Exchange)` | "I agree with this formal type assignment" |
| `has category` | `(Uniswap, has category, DeFi)` | "I agree with this product-level category" |
| `has tag` | `(Aave, has tag, lending)` | "I agree with this free-form tag" |
| `same as` | `(ETH, same as, Ether)` | "I agree these are the same entity" |
| `created by` | `(Ethereum, created by, Vitalik)` | "I agree with this attribution" |
| `authored by` | `(Whitepaper, authored by, Satoshi)` | "I agree with this authorship claim" |
Expand Down Expand Up @@ -359,12 +358,10 @@ A human identity — the most relationship-rich entity type in a social knowledg

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Vitalik, is, researcher)` | core |
| `has type` | `DefinedTerm` | `(Vitalik, has type, public figure)` | common |
| `has tag` | `DefinedTerm` | `(Alice, has tag, Solidity developer)` | core |
| `has category` | `DefinedTerm` | `(Alice, has category, builder)` | common |
| `same as` | `Person` | `(vitalik.eth, same as, Vitalik Buterin)` | common |
| `alias of` | `Person` | `(V, alias of, Vitalik Buterin)` | optional |
| `linked account` | `SocialMediaAccount` | `(Alice, linked account, x.com/alice_eth)` | core |
| `url` | `URL` | `(Alice, url, alice.xyz)` | common |
| `imgUrl` | `ImageURL` | `(Alice, imgUrl, alice-avatar.png)` | common |
Expand Down Expand Up @@ -402,7 +399,7 @@ All opinion predicates should use the depositional pattern. The whole point is t
| `bearish on` | `Any` | `(I, bearish on, Memecoins)` | Aggregate bearish conviction | common |
| `neutral on` | `Any` | `(I, neutral on, L2 wars)` | Explicit fence-sitting count | optional |
| `reviewed` | `SoftwareSourceCode` / `Product` / `Thing` | `(I, reviewed, Uniswap v4)` | Number of reviewers + conviction weight | common |
| `recommended` | `Any` | `(I, recommended, Hardhat)` | Recommendation strength | common |
| `recommend` | `Any` | `(I, recommend, Hardhat)` | Recommendation strength | common |

### Professional and Knowledge (Hybrid)

Expand Down Expand Up @@ -452,7 +449,6 @@ A company, foundation, DAO, protocol team, or any collective entity.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Uniswap Labs, is, DeFi company)` | core |
| `has type` | `DefinedTerm` | `(Ethereum Foundation, has type, non-profit)` | core |
| `has tag` | `DefinedTerm` | `(Aave, has tag, lending)` | core |
| `has category` | `DefinedTerm` | `(Chainlink, has category, oracle)` | common |
Expand Down Expand Up @@ -506,7 +502,6 @@ A protocol, dApp, library, framework, or any code-based project.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Uniswap, is, DEX)` | core |
| `has type` | `DefinedTerm` | `(MetaMask, has type, wallet)` | core |
| `has tag` | `DefinedTerm` | `(Aave, has tag, lending)` | core |
| `has category` | `DefinedTerm` | `(Hardhat, has category, developer tools)` | common |
Expand Down Expand Up @@ -576,11 +571,9 @@ A fungible token on an EVM chain.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(USDC, is, stablecoin)` | core |
| `has type` | `DefinedTerm` | `(UNI, has type, governance token)` | core |
| `has tag` | `DefinedTerm` | `(AAVE, has tag, DeFi)` | core |
| `has category` | `DefinedTerm` | `(WBTC, has category, wrapped asset)` | common |
| `instance of` | `DefinedTerm` | `(USDC, instance of, stablecoin)` | common |
| `url` | `URL` | `(USDC, url, circle.com/usdc)` | common |
| `imgUrl` | `ImageURL` | `(ETH, imgUrl, eth-diamond.svg)` | common |
| `has description` | `String` | `(UNI, has description, "Governance token of the Uniswap protocol")` | common |
Expand Down Expand Up @@ -620,7 +613,6 @@ A conference, hackathon, governance event, or notable occurrence.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Devcon, is, conference)` | core |
| `has type` | `DefinedTerm` | `(ETHDenver, has type, hackathon)` | core |
| `has tag` | `DefinedTerm` | `(Devcon, has tag, Ethereum)` | core |
| `located in` | `Location` | `(Devcon, located in, Bangkok)` | core |
Expand Down Expand Up @@ -660,7 +652,6 @@ An article, whitepaper, blog post, research paper, or written work.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Bitcoin Whitepaper, is, whitepaper)` | core |
| `has type` | `DefinedTerm` | `(EIP-4844, has type, improvement proposal)` | core |
| `has tag` | `DefinedTerm` | `(Bitcoin Whitepaper, has tag, cryptography)` | core |
| `url` | `URL` | `(Bitcoin Whitepaper, url, bitcoin.org/bitcoin.pdf)` | core |
Expand Down Expand Up @@ -705,7 +696,6 @@ A physical or digital product, hardware device, or consumer good.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Ledger Nano X, is, hardware wallet)` | core |
| `has type` | `DefinedTerm` | `(Ledger Nano X, has type, cold storage)` | core |
| `has tag` | `DefinedTerm` | `(Ledger, has tag, security)` | core |
| `url` | `URL` | `(Ledger Nano X, url, ledger.com)` | common |
Expand Down Expand Up @@ -735,7 +725,6 @@ Collections are curated groups of atoms. They may represent watchlists, director

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(DeFi Blue Chips, is, watchlist)` | core |
| `has type` | `DefinedTerm` | `(DeFi Blue Chips, has type, curated list)` | common |
| `has tag` | `DefinedTerm` | `(Layer 1 Watchlist, has tag, crypto)` | core |
| `has description` | `String` | `(DeFi Blue Chips, has description, "Top DeFi protocols by TVL")` | common |
Expand Down Expand Up @@ -769,7 +758,6 @@ A geographic place, city, country, or virtual region.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(Berlin, is, city)` | core |
| `has type` | `DefinedTerm` | `(Crypto Valley, has type, tech hub)` | common |
| `has tag` | `DefinedTerm` | `(Zug, has tag, crypto-friendly)` | common |
| `url` | `URL` | `(Crypto Valley, url, cryptovalley.swiss)` | optional |
Expand All @@ -787,11 +775,7 @@ A tag, keyword, concept, standard, or categorical label used as an Object in man

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(DeFi, is, concept)` | common |
| `subclass of` | `DefinedTerm` | `(DEX, subclass of, exchange)` | common |
| `instance of` | `DefinedTerm` | `(Uniswap, instance of, DEX)` | common |
| `same as` | `DefinedTerm` | `(DeFi, same as, decentralized finance)` | common |
| `alias of` | `DefinedTerm` | `(defi, alias of, DeFi)` | optional |
| `has description` | `String` | `(ZK proofs, has description, "Zero-knowledge proof systems")` | common |
| `url` | `URL` | `(ERC-20, url, eips.ethereum.org/EIPS/eip-20)` | optional |
| `alternative to` | `DefinedTerm` | `(PoS, alternative to, PoW)` | optional |
Expand All @@ -809,7 +793,6 @@ A platform account atom linked to an identity.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(x.com/alice_eth, is, social account)` | common |
| `has type` | `DefinedTerm` | `(x.com/alice_eth, has type, X account)` | common |
| `url` | `URL` | `(x.com/alice_eth, url, x.com/alice_eth)` | core |
| `imgUrl` | `ImageURL` | `(x.com/alice_eth, imgUrl, alice-profile.jpg)` | optional |
Expand All @@ -827,7 +810,6 @@ A deployed contract on an EVM chain.

| Predicate | Expected Object Type | Example Triple | Priority |
|---|---|---|---|
| `is` | `DefinedTerm` | `(0xUniRouter, is, router contract)` | core |
| `has type` | `DefinedTerm` | `(0xUniRouter, has type, DEX router)` | core |
| `has tag` | `DefinedTerm` | `(0xUniRouter, has tag, DeFi)` | common |
| `created by` | `Person` / `Organization` | `(0xUniRouter, created by, Uniswap Labs)` | core |
Expand All @@ -848,15 +830,13 @@ These predicates work with **any** Subject entity type:

| Predicate | Expected Object Type | Notes |
|---|---|---|
| `is` | `DefinedTerm` | Type or identity assertion |
| `has type` | `DefinedTerm` | Formal classification |
| `has tag` | `DefinedTerm` | Free-form tagging |
| `has category` | `DefinedTerm` | Structured taxonomy |
| `url` | `URL` | Canonical web address |
| `imgUrl` | `ImageURL` | Visual representation |
| `has description` | `String` | Textual description |
| `same as` | Same entity type | Cross-representation identity |
| `alias of` | Same entity type | Alternative name |
| `contain` | `Any` | Collection membership (when Subject is a container) |
| `created by` | `Person` / `Organization` | Origin attribution |
| `like` | `Any` | Lightweight positive signal (when Subject is a Person) |
Expand Down Expand Up @@ -1078,7 +1058,7 @@ Alice has fewer delegators but much more capital behind her = whale-backed deleg

**Collection structure (all attributive — these are facts about the collection):**
```
(DeFi Blue Chips, is, curated list)
(DeFi Blue Chips, has type, curated list)
(DeFi Blue Chips, has tag, DeFi)
(DeFi Blue Chips, has description, "Top DeFi protocols by TVL and track record")
(DeFi Blue Chips, curated by, Alice)
Expand All @@ -1093,7 +1073,7 @@ Alice has fewer delegators but much more capital behind her = whale-backed deleg
```
(I, like, DeFi Blue Chips) — TVL: 50 ETH from 300 depositors
(I, follow, DeFi Blue Chips) — TVL: 20 ETH from 150 depositors
(I, recommended, DeFi Blue Chips) — TVL: 10 ETH from 40 depositors
(I, recommend, DeFi Blue Chips) — TVL: 10 ETH from 40 depositors
```

**Ranking items within the collection (depositional — opinion markets):**
Expand Down Expand Up @@ -1184,7 +1164,7 @@ These are specific factual claims about Alice. Others deposit to confirm the cla

**Factual triples that inform the debate (attributive):**
```
(Bitcoin, is, cryptocurrency)
(Bitcoin, has type, cryptocurrency)
(Bitcoin, created by, Satoshi Nakamoto)
(Bitcoin, has tag, store of value)
(Bitcoin, has tag, digital gold)
Expand All @@ -1201,7 +1181,7 @@ These are specific factual claims about Alice. Others deposit to confirm the cla

**Attributive facts about the event:**
```
(Devcon 7, is, conference)
(Devcon 7, has type, conference)
(Devcon 7, has type, developer conference)
(Devcon 7, located in, Bangkok)
(Devcon 7, created by, Ethereum Foundation)
Expand All @@ -1215,7 +1195,7 @@ These are specific factual claims about Alice. Others deposit to confirm the cla
**Depositional engagement signals:**
```
(I, like, Devcon 7) — TVL: 25 ETH from 500 depositors
(I, recommended, Devcon 7) — TVL: 8 ETH from 100 depositors
(I, recommend, Devcon 7) — TVL: 8 ETH from 100 depositors
```

**Items featured at the event (attributive):**
Expand All @@ -1233,8 +1213,6 @@ These are specific factual claims about Alice. Others deposit to confirm the cla

**Attributive facts (all specific to USDC):**
```
(USDC, is, stablecoin)
(USDC, instance of, stablecoin)
(USDC, has type, fiat-backed stablecoin)
(USDC, created by, Circle)
(USDC, implement, ERC-20)
Expand Down Expand Up @@ -1268,7 +1246,7 @@ These are specific factual claims about Alice. Others deposit to confirm the cla

**Attributive facts about Vitalik:**
```
(Vitalik Buterin, is, researcher)
(Vitalik Buterin, has type, researcher)
(Vitalik Buterin, has type, public figure)
(Vitalik Buterin, founded, Ethereum)
(Vitalik Buterin, founded, Bitcoin Magazine)
Expand Down Expand Up @@ -1344,7 +1322,7 @@ The triple already has direction via subject/object ordering. Adding "is followe
BAD: (Aave, provides lending on, Ethereum) ← too specific, one-off predicate
BAD: (Aave, is a DeFi lending protocol on, Ethereum) ← sentence in a predicate

GOOD: (Aave, is, lending protocol)
GOOD: (Aave, has type, lending protocol)
(Aave, has tag, DeFi)
(Aave, available on, Ethereum)
```
Expand Down Expand Up @@ -1414,7 +1392,7 @@ Always check the canonical direction documented in the predicate catalog. The su

**Phase 2 — Factual claims emerge (attributive):**
```
(Wormhole Exploit, is, bridge hack)
(Wormhole Exploit, has type, bridge hack)
(Wormhole Exploit, has tag, security incident)
(Wormhole Bridge, audited by, Neodyme) — TVL: 5 ETH (people confirm the audit happened)
(Wormhole Exploit, evidenced by, etherscan.io/tx/0x...) — TVL: 20 ETH (people confirm the evidence)
Expand Down Expand Up @@ -1445,14 +1423,14 @@ Always check the canonical direction documented in the predicate catalog. The su
(I, like, Foundry) — TVL: 80 ETH from 1,200 depositors
(Hardhat, better than, Foundry) — TVL: 15 ETH from 200 depositors
(Foundry, better than, Hardhat) — TVL: 50 ETH from 600 depositors
(I, recommended, Foundry) — TVL: 30 ETH from 300 depositors
(I, recommended, Hardhat) — TVL: 10 ETH from 100 depositors
(I, recommend, Foundry) — TVL: 30 ETH from 300 depositors
(I, recommend, Hardhat) — TVL: 10 ETH from 100 depositors
```

**Attributive context:**
```
(Hardhat, is, development framework)
(Foundry, is, development framework)
(Hardhat, has type, development framework)
(Foundry, has type, development framework)
(Hardhat, created by, NomicLabs)
(Foundry, created by, Paradigm)
(Hardhat, use, JavaScript)
Expand Down Expand Up @@ -1499,7 +1477,7 @@ TRICKY: How do you express "Ethereum is NOT a security"?
```

There is no `is not` predicate. Two approaches:
1. Use the positive claim and let low/no TVL speak: `(Ethereum, is, security)` — if no one deposits, the market has spoken.
1. Use the positive claim and let low/no TVL speak: `(Ethereum, has type, security)` — if no one deposits, the market has spoken.
2. Use the counter-market: `(I, agree with, Ethereum is not a security)` and `(I, disagree with, Ethereum is not a security)`.

Option 2 is better because it creates an explicit market. Absence of deposits is ambiguous (maybe no one noticed the triple), but an active market with a strong ratio is unambiguous signal.
Expand Down
11 changes: 4 additions & 7 deletions predicates/3-predicate-display-and-conjugation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,7 +163,7 @@ The `conjugates` and `thirdPerson` fields are display metadata. They are never s
The rendering function takes a predicate's `name` (extracted from the DefinedTerm atom data or from the SDK predicate definitions) and the subject context, and returns the display form:

```typescript
import { PREDICATE_DEFS } from '@intuition/predicates';
import { PREDICATE_DEFS } from '@0xintuition/predicates';

type SubjectContext = 'first-person' | 'singular' | 'plural';

Expand Down Expand Up @@ -215,8 +215,6 @@ const displayForm = renderPredicate(predicateName, subjectContext);
When the predicate has an IPFS enrichment document (linked via a `has source` triple or used directly as the atom data in the IPFS URI strategy), the enrichment contains conjugation and localization data for multiple languages:

```typescript
import { resolvePredicateEnrichment } from '@intuition/predicate-i18n';

/**
* Renders a predicate for a specific locale and subject context.
* Resolves the IPFS enrichment document for i18n labels.
Expand All @@ -227,7 +225,7 @@ async function renderPredicateLocalized(
locale: string,
subjectContext: SubjectContext
): Promise<string> {
// Try to resolve i18n from IPFS enrichment
// App-specific helper that resolves i18n from IPFS enrichment
const enrichment = await resolvePredicateEnrichment(predicateName);

if (enrichment?.i18n?.[locale]) {
Expand Down Expand Up @@ -314,9 +312,8 @@ These predicates are multi-word phrases, adjective-based, or passive constructio

| Predicate | Why it doesn't conjugate |
|---|---|
| `is` | Already works as both base and third-person |
| `has type`, `has tag`, `has category`, `has description`, `has source` | Fixed compound labels (see `has` anomaly below) |
| `same as`, `alias of`, `instance of`, `subclass of`, `member of` | Noun/adjective phrases |
| `same as`, `listed in`, `member of`, `student of`, `mentor of` | Noun/adjective phrases |
| `employed by`, `affiliated with`, `created by`, `authored by` | Past participle — doesn't change |
| `audited by`, `verified by`, `certified by`, `governed by`, `regulated by` | Past participle |
| `backed by`, `pegged to`, `listed on`, `available on` | Past participle / adjective phrase |
Expand All @@ -326,7 +323,7 @@ These predicates are multi-word phrases, adjective-based, or passive constructio
| `expert in`, `linked account`, `predecessor of`, `successor of` | Noun phrase |
| `student of`, `mentor of`, `partner of` | Noun phrase |

The majority of predicates do not conjugate at all. The conjugation problem only affects active-voice single verbs — roughly 22 out of 100 cataloged predicates.
The majority of predicates do not conjugate at all. The conjugation problem only affects active-voice single verbs — roughly 22 out of 97 cataloged predicates.

---

Expand Down
Loading