Skip to content

docs: sdk and graphql migration guides #7

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

Merged
merged 1 commit into from
Sep 25, 2025
Merged

docs: sdk and graphql migration guides #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
350 changes: 82 additions & 268 deletions docs/guides/developer-tools/graphql-api/migration-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,309 +3,123 @@ id: migration-guide
title: Migration Guide
sidebar_label: Migration Guide
sidebar_position: 5
description: Guide to migrating from v1.0 to v1.5 of the Intuition GraphQL API
description: Migrating GraphQL from v1.5 to v2.0
---

# v1.5 Migration Guide
# Migrating GraphQL from v1.5 to v2.0

**Abstract**: The Intuition API is being updated to support exciting new features, and developers using the API will need to make adjustments to their queries to continue using it. This document serves as a comprehensive guide for that process.

## Current Status

The Base Sepolia and Base Mainnet 1.5 backend is already live and accessible:
## Overview

| Environment | Endpoint |
|-------------|----------|
| **Base Sepolia** | `https://prod.base-sepolia-v-1-5.intuition.sh/v1/graphql` |
| **Base Mainnet** | `https://prod.base-mainnet-v-1-0.intuition.sh/v1/graphql` |

## ✨ New Features

### Core Enhancements

| Feature | Description |
|---------|-------------|
| **🏦 Bonding Curve Vaults** | New vault types with dynamic pricing models |
| **📋 Bonding Curve Registry** | Centralized registry for curve management |
| **Improved Batch Methods** | Enhanced batch operations for better performance |
| **✅ Improved Approval Methods** | Better deposit/redeem and batch deposit/redeem approvals |
| **Enhanced Events & Data** | Price history, P&L, total market cap for individual vaults |
| **Introduction of 'Terms'** | New concept for atoms and triples semantics |
| **Multiple Vaults per Term** | Pro Rata Vault (1.0) + Bonding Curve Vaults |
| **🔒 Security Improvements** | Updates from Consensys Diligence audit |

### What Changed Conceptually

We have introduced the idea of a **"Term"**. A "Term" refers to an Atom, Triple or Counter-triple as a *concept*. The URI or Data of an Atom, or the Atom IDs contained within a Triple or Counter-Triple belong to the "Term". Any economic state associated with the "Term" is stored in multiple "Vaults" associated with that Term.

#### 🔗 **Term Structure**

```text
┌─────────────────────────────────────┐
│ TERM │
├─────────────────────────────────────┤
│ 🧩 Atom/Triple/Counter-triple │
│ 🏦 Multiple Vaults │
│ 📊 Total Market Cap │
│ 💰 Economic State │
└─────────────────────────────────────┘
```

#### Market Cap Calculation

Each Term has a `total_market_cap` value which is an aggregate market cap of all its constituent Vaults. This is *theoretical* - it represents the arithmetic product of `totalShares` and `currentSharePrice`, not actual `totalAssets`.

> ⚠️ **Note**: The `total_market_cap` will generally be larger than actual `totalAssets` due to slippage effects during liquidation.

## 🔄 Migration Checklist

### 📋 **Core Schema Changes**

Update these field names in your GraphQL queries:

| Old Field | New Field | Type Change |
|-----------|-----------|-------------|
| `id` | `term_id` | Primary identifier |
| `vault` | `term` | Nested object (when referring to concept) |
| `vault` | `vaults(where: { curve_id: {_eq: "[X]" } })` | Specific curve vault |
| `total_shares` | `total_market_cap` | In term object or specific vault |
| `block_timestamp` | `created_at` | `TIMESTAMP WITH TIME ZONE NOT NULL` |

### ⏰ **Timestamp Field Updates**

All timestamp fields have been updated:

| Entity | Old Field | New Field | Additional |
|--------|-----------|-----------|------------|
| **Atom** | `block_timestamp` | `created_at` | + `updated_at` |
| **Position** | `block_timestamp` | `created_at` | + `updated_at` |
| **Vault** | `block_timestamp` | `created_at` | + `updated_at` |
| **Triple** | `block_timestamp` | `created_at` | - |
| **Signal** | `block_timestamp` | `created_at` | - |
| **Deposit** | `block_timestamp` | `created_at` | - |
| **FeeTransfer** | `block_timestamp` | `created_at` | - |
| **Redemption** | `block_timestamp` | `created_at` | - |

### 🏦 **Vault Access Changes**

Instead of accessing a single vault, you now need to specify the curve:

```graphql
# OLD: Single vault access
vault(where: { id: { _eq: "42" } }) {
total_shares
total_assets
}

# NEW: Curve-specific vault access
vaults(where: {
curve_id: { _eq: "1" },
term_id: { _eq: "42" }
}) {
total_shares
total_assets
total_market_cap
}
```

## 💻 Migration Examples

### 📝 **Example 1: Get Entries Query**

```graphql
# OLD SCHEMA
query GetEntries($isTypeTypeId: numeric!, $entryTypeId: numeric!, $limit: Int!, $offset: Int!) {
triples {
subject {
id
value {
thing { ... }
}
vault {
total_shares
}
}
}
}
| **Intuition Testnet** | `https://testnet.intuition.sh/v1/graphql` |

# NEW SCHEMA
query GetEntries($isTypeTypeId: numeric!, $entryTypeId: numeric!, $limit: Int!, $offset: Int!) {
triples {
subject {
term_id
atom_value {
thing { ... }
}
term {
total_market_cap
}
}
}
}
```

### 🔍 **Example 2: Get Entry Query**

```graphql
# OLD SCHEMA
query GetEntry($id: numeric!, $typePredicateId: numeric!, $entryTypeId: numeric!) {
atom(id: $id) {
id
value { ... }
}
}

# NEW SCHEMA
query GetEntry($term_id: numeric!, $typePredicateId: numeric!, $entryTypeId: numeric!) {
atom(term_id: $term_id) {
term_id
atom_value { ... }
}
}
```

### 🔎 **Example 3: Search Entries Query**
## ⚠️ Breaking Changes

```graphql
# OLD SCHEMA
query SearchEntries {
atoms(where: {
value: { thing: { ... } }
}) {
id
value { ... }
vault { total_shares }
}
}
### 1. ID Field Type Changes: Numeric → String

# NEW SCHEMA
query SearchEntries {
atoms(where: {
atom_value: { thing: { ... } }
}) {
term_id
atom_value { ... }
term { total_market_cap }
}
}
```
**CRITICAL IMPACT** - All existing queries and mutations using these fields will break.

### 📊 **Example 4: Order By Changes**
#### Core Entity ID Changes

```graphql
# OLD
order_by: [{ vault: { total_shares: desc } }]
| Entity | Field | Old Type | New Type |
| ------------- | ----------------- | ---------- | --------- |
| `accounts` | `atom_id` | `numeric` | `String` |
| `atoms` | `term_id` | `numeric!` | `String!` |
| `atoms` | `value_id` | `numeric` | `String` |
| `atom_values` | `id` | `numeric!` | `String!` |
| `atom_values` | `book_id` | `numeric` | `String` |
| `atom_values` | `byte_object_id` | `numeric` | `String` |
| `atom_values` | `json_object_id` | `numeric` | `String` |
| `atom_values` | `organization_id` | `numeric` | `String` |
| `atom_values` | `person_id` | `numeric` | `String` |
| `atom_values` | `text_object_id` | `numeric` | `String` |
| `atom_values` | `thing_id` | `numeric` | `String` |
| `vaults` | `term_id` | `numeric!` | `String!` |

# NEW
order_by: [{ subject: { term: { total_market_cap: desc } }}]
```
#### Entity Primary ID Changes

## 🏦 Bonding Curves
All primary `id` fields changed from `numeric!` to `String!`:

### 📈 **Offset Square Root Curve 2,5e35**
- `books`
- `byte_object`
- `caip10`
- `json_objects`
- `organizations`
- `persons`
- `text_objects`
- `things`
- `terms`

Our first recommended curve follows a "square root" price function pattern with an offset to make the early portion less dramatic:
### 2. Removed Aggregate Fields

| Feature | Description |
|---------|-------------|
| **📊 Price Function** | Square root pattern with offset |
| **🎯 Early Advantage** | Earliest stakers get most advantageous share price |
| **📈 Growth Pattern** | Share price increases supralinearly (gently) |
| **💰 Profit Potential** | Users can redeem at higher prices as share price increases |
**MEDIUM IMPACT** - Statistical queries will break for entities with String IDs.

### 🔄 **Comparison: Pro-Rata vs Bonding Curve**
Removed aggregate field types (no longer available for statistical operations):

| Aspect | Pro-Rata (1.0) | Bonding Curve (1.5) |
|--------|----------------|---------------------|
| **Share Price** | Always "1" (with fee adjustments) | Dynamic based on curve function |
| **Profit Potential** | Limited (high activity required) | Significant upside potential |
| **Risk Level** | Low (minimal downside) | Higher (price can diminish) |
| **Economic Activity** | High activity needed for profit | Profitable with moderate activity |
- `*_avg_fields` for: accounts, atom_values, books, byte_object, json_objects, organizations, persons, text_objects, things
- `*_stddev_fields`, `*_stddev_pop_fields`, `*_stddev_samp_fields`
- `*_sum_fields`, `*_var_pop_fields`, `*_var_samp_fields`, `*_variance_fields`

## 🔧 Smart Contract Updates
## 🆕 New Features

### 📋 **New Bonding Curve Mutators**
### 1. New Optional Fields

```solidity
/// @notice deposit eth into an atom vault and grant ownership of 'shares' to 'receiver'
function depositAtomCurve(address receiver, uint256 atomId, uint256 curveId) external payable returns (uint256);
#### atom_values

/// @notice redeem shares from an atom vault for assets
function redeemAtomCurve(uint256 percentage, address receiver, uint256 atomId, uint256 curveId) external returns (uint256);
```
- `caip10_id: String` - Link to CAIP-10 identifiers

### 🔍 **New Bonding Curve Accessors**
### 2. New Entity Types

```solidity
/// @notice returns current share price for a specific curve
function currentSharePriceCurve(uint256 vaultId, uint256 curveId) external view returns (uint256);
Statistics and analytics entities:

/// @notice returns max amount of shares that can be redeemed
function maxRedeemCurve(address owner, uint256 vaultId, uint256 curveId) external view returns (uint256);
- `statHours` - Hourly statistics aggregation
- `term_total_state_changes` - Term state change tracking
- `term_total_state_change_stats_daily` - Daily aggregated statistics
- `term_total_state_change_stats_hourly` - Hourly aggregated statistics
- `term_total_state_change_stats_monthly` - Monthly aggregated statistics
- `term_total_state_change_stats_weekly` - Weekly aggregated statistics

/// @notice simulates deposit effects and returns estimated shares
function previewDepositCurve(uint256 assets, uint256 vaultId, uint256 curveId) external view returns (uint256);
### 3. New Scalar Types

/// @notice simulates redemption effects and returns estimated assets
function previewRedeemCurve(uint256 shares, uint256 vaultId, uint256 curveId) external view returns (uint256);
```
- `atom_resolving_status` - Custom scalar for atom resolution states
- `vault_type` - Custom scalar for vault type definitions

### ✅ **Updated Approval Method**
## 🔧 Migration Checklist

```solidity
/// @notice Set the approval type for a sender to act on behalf of the receiver
/// @param sender address to set approval for
/// @param approvalType type of approval to grant (NONE = 0, DEPOSIT = 1, REDEMPTION = 2, BOTH = 3)
function approve(address sender, ApprovalTypes approvalType) external;
```
### Client Application Updates

### 📦 **Batch Methods**
#### 1. Query/Mutation Updates

```solidity
/// @notice Batch create atoms and return their vault ids
function batchCreateAtom(bytes[] calldata atomUris) external payable returns (uint256[] memory);
- [ ] Update all numeric ID field references to String
- [ ] Remove or update queries using deprecated aggregate fields
- [ ] Test all existing GraphQL operations

/// @notice batch create triples and return their vault ids
function batchCreateTriple(uint256[] calldata subjectIds, uint256[] calldata predicateIds, uint256[] calldata objectIds) external payable returns (uint256[] memory);
#### 2. Code Generation Updates

/// @notice deposit eth into multiple terms and grant ownership of 'shares' to 'receiver'
function batchDeposit(address receiver, uint256[] calldata termIds, uint256[] calldata amounts) external payable returns (uint256[] memory);
- [ ] Regenerate TypeScript types
- [ ] Update GraphQL codegen configuration
- [ ] Verify generated types match new schema

/// @notice deposit eth into bonding curve vaults
function batchDepositCurve(address receiver, uint256[] calldata termIds, uint256[] calldata curveIds, uint256[] calldata amounts) external payable returns (uint256[] memory);
#### 3. Variable Updates

/// @notice redeem shares from multiple vaults
function batchRedeem(uint256 percentage, address receiver, uint256[] calldata ids) external returns (uint256[] memory);
```graphql
# OLD
query GetAtom($termId: numeric!) {
atoms(where: { term_id: { _eq: $termId } }) {
term_id
value_id
}
}

/// @notice redeem shares from bonding curve vaults
function batchRedeemCurve(uint256 percentage, address receiver, uint256[] calldata termIds, uint256[] calldata curveIds) external returns (uint256[] memory);
# NEW
query GetAtom($termId: String!) {
atoms(where: { term_id: { _eq: $termId } }) {
term_id
value_id
raw_data
resolving_status
}
}
```

## 🚨 Important Notes

### ⚠️ **Claims Deprecation**

If using `claims`, it's suggested to start using `positions` instead, as the positions contain the same information and more. Claims are likely to be sunset in the near future.

### 🧪 **Testing Environment**

> ⚠️ **Caution**: The Dummy 1.5 contract does not contain the same dataset as the 1.0 contract on Base Sepolia. If your app relies on specific data, you may need to add it to the Dummy 1.5 contract for testing.

Once the contract upgrade is completed, the 1.5 contract will have the same data set as the 1.0 version and will live at the same contract address.

## �� Endpoint Changes

| Environment | Old Endpoint | New Endpoint |
|-------------|--------------|--------------|
| **Development** | `https://prod.base-sepolia.intuition-api.com/v1/graphql` | `https://prod.base-sepolia-v-1-5.intuition.sh/v1/graphql` |

## 📚 Additional Resources

- 📖 [Official v1.5 Migration Guide](https://tech.docs.intuition.systems/dev/1.5-migration)
- 🔗 [Bonding Curve Documentation](/guides/introduction/the-economics/bonding-curves)
- 🛠️ [GraphQL API Reference](/guides/developer-tools/graphql-api)
- 💬 [Community Support](https://discord.gg/intuition)

---

> 🚀 **Ready to migrate?** Start with our [Quick Start Guide](/guides/quickstart) or explore the [SDK Documentation](/guides/developer-tools/sdks) to begin your v1.5 migration!
Loading