Skip to content

Add Identity SDK docs #254

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

Draft
ernestognw wants to merge 2 commits into
base: accounts-docs
Choose a base branch
from
Draft

Add Identity SDK docs #254

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc6c44e
Support guides-only docs generation for TypeScript packages
ernestognw Oct 22, 2026
f25f334
Add Identity SDK docs
ernestognw Oct 22, 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
140 changes: 140 additions & 0 deletions .github/workflows/generate-api-docs-identity-sdk.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Docs Repository Receiver - Non-Versioned Paths
# Receives trigger from identity-sdk and copies its MDX guides (TypeScript package, no generated API reference)

name: Generate API Docs - Identity SDK

on:
workflow_dispatch:
inputs:
tag_name:
description: 'Tag name or commit SHA to generate docs from'
required: true
type: string
default: 'main'
trigger_type:
description: 'Trigger type (tag or commit)'
required: false
type: string
default: 'tag'

permissions:
contents: write
pull-requests: write

env:
SOURCE_REPO: 'OpenZeppelin/identity-sdk'
SOURCE_REPO_URL: 'https://github.com/OpenZeppelin/identity-sdk.git'
GUIDES_MDX: 'docs'
OUTPUT_DIR: 'content/identity-sdk'

jobs:
generate-docs:
runs-on: ubuntu-latest

steps:
- name: Log trigger information
run: |
echo "🚀 API Documentation Generation Triggered"
echo "📦 Repository: ${{ env.SOURCE_REPO }}"
echo "🏷️ Tag/Ref: ${{ inputs.tag_name }}"
echo "📋 Trigger type: ${{ inputs.trigger_type }}"

- name: Checkout docs repository
uses: actions/checkout@v6
with:
token: ${{ secrets.GITHUB_TOKEN }}

- name: Setup pnpm
uses: pnpm/action-setup@v6

- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: '22'
cache: 'pnpm'

- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Copy guides
run: |
echo "🔄 Copying guides..."

node scripts/generate-api-docs.js \
--repo "${{ env.SOURCE_REPO_URL }}" \
--branch "${{ inputs.tag_name }}" \
--guides-only \
--guides-output "${{ env.OUTPUT_DIR }}" \
--guides-mdx "${{ env.GUIDES_MDX }}"

- name: Validate generated documentation
run: |
pnpm run postinstall
pnpm run lint:links

- name: Create Pull Request for documentation changes
id: create_pr
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
git config --local user.email "docs-automation@openzeppelin.com"
git config --local user.name "OpenZeppelin Docs Bot"

if [ -n "$(git status --porcelain)" ]; then
echo "📝 Creating branch and committing documentation changes..."

BRANCH_NAME="docs/api-update-${{ env.SOURCE_REPO }}-${{ inputs.tag_name }}"
BRANCH_NAME=$(echo "$BRANCH_NAME" | sed 's/\//-/g' | sed 's/OpenZeppelin-//g')

git checkout -b "$BRANCH_NAME"
git add content/
git commit -m "Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}

- Repository: ${{ env.SOURCE_REPO }}
- Ref: ${{ inputs.tag_name }}
- Trigger: ${{ inputs.trigger_type }}
- Output: ${{ env.OUTPUT_DIR }}
- Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')

Auto-generated via workflow_dispatch"

git push origin "$BRANCH_NAME"

gh pr create --title "[CI] Update API docs for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}" \
--body "## API Documentation Update

This Pull Request updates the API documentation.

### Source Information
- **Repository:** ${{ env.SOURCE_REPO }}
- **Reference:** ${{ inputs.tag_name }}
- **Trigger Type:** ${{ inputs.trigger_type }}
- **Output Directory:** ${{ env.OUTPUT_DIR }}
- **Timestamp:** $(date -u '+%Y-%m-%d %H:%M:%S UTC')

Auto-generated via workflow_dispatch" \
--base main \
--head "$BRANCH_NAME" || {
echo "::error::Pull Request creation failed for ${{ env.SOURCE_REPO }} ${{ inputs.tag_name }}"
exit 1
}

echo "✅ Pull Request created successfully"
echo "pr-created=true" >> $GITHUB_OUTPUT
else
echo "ℹ️ No changes detected - documentation is up to date"
echo "pr-created=false" >> $GITHUB_OUTPUT
fi

- name: Create job summary
run: |
echo "## 📚 API Documentation Generation Complete" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Source Information" >> $GITHUB_STEP_SUMMARY
echo "- **Repository:** ${{ env.SOURCE_REPO }}" >> $GITHUB_STEP_SUMMARY
echo "- **Reference:** ${{ inputs.tag_name }}" >> $GITHUB_STEP_SUMMARY
echo "- **Trigger Type:** ${{ inputs.trigger_type }}" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "### Output" >> $GITHUB_STEP_SUMMARY
echo "- **Directory:** ${{ env.OUTPUT_DIR }}" >> $GITHUB_STEP_SUMMARY
echo "- **Status:** ✅ Complete" >> $GITHUB_STEP_SUMMARY
68 changes: 68 additions & 0 deletions content/identity-sdk/abi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
title: ABIs
description: The vendored ONCHAINID ABIs, their pin, and how to re-sync them
---

The SDK vendors the ABIs of the ONCHAINID contracts it talks to under `src/abi/`. They are exported from the package root and typed with viem's `parseAbi`, so `readContract`, `encodeFunctionData` and friends infer argument and return types from them.

Use them directly for anything the SDK does not wrap (for example, the factory's policy views, reputation reads, or decoding custom errors).

## Pin

Every file is generated from **T-REX-Network/ONCHAINID at commit `2180c919`**. Each file's header names the commit and the source contract:

```ts
// Generated from T-REX-Network/ONCHAINID@2180c919: contracts/interface/IIdentity.sol
// Do not hand-edit the ABI: rerun `scripts/sync-abi.mjs` against the new pin.
```

Integrate against contracts deployed from the same ONCHAINID version. A deployment from a different commit may have different selectors or struct layouts.

## Exports

| Export | Source | Address to call |
| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `ierc734Abi` | `contracts/interface/IERC734.sol` | Identity |
| `ierc735Abi` | `contracts/interface/IERC735.sol` | Identity |
| `iidentityAbi` | `contracts/interface/IIdentity.sol` | Identity: keys, claims, `isClaimValid`, `getIdentityType` |
| `ikeyExecutorAbi` | `contracts/interface/IKeyExecutor.sol` | Identity: ERC-734 `execute` / `approve` (served by `KeyApprovalModule`) |
| `iclaimIssuerAbi` | `contracts/interface/IClaimIssuer.sol` | Issuer identity: `revokeClaimByDigest`, `isDigestRevoked`, `addClaimTo` |
| `erc734ValidatorAbi` | `contracts/modules/validators/ERC734Validator.sol` | Registry module: explicit-`account` and paginated reads, `getKeyData` |
| `iidentityFactoryAbi` | `contracts/factory/IIdentityFactory.sol` | `IdentityFactory` |
| `ireputationRegistryAbi` | `contracts/reputation/IReputationRegistry.sol` | `ReputationRegistry`: `reputationOf`, `entryOf`, `claimAddThreshold` |
| `iidentityUtilitiesAbi` | `contracts/interface/IIdentityUtilities.sol` | `IdentityUtilities`: topic schemas |
| `identityAccountAbi` | `contracts/Identity.sol` (curated subset) | Identity: `registryModule`, `identityFactory`, `isManagementTarget`, `addKeyWithData`, paginated key reads, modules |
| `keyApprovalModuleAbi` | `contracts/modules/executors/KeyApprovalModule.sol` | `KeyApprovalModule`: `getExecutionData(account, executionId)`, the module's events and errors |

`identityAccountAbi` is curated: it lists only the account-level functions and events that the interfaces above do not cover. The other files contain the full interface.

Example, reading a reputation score (no SDK wrapper exists):

```ts
import { readContract } from 'viem/actions';
import { ireputationRegistryAbi } from '@openzeppelin/identity-sdk';

const score = await readContract(client, {
address: reputationRegistry,
abi: ireputationRegistryAbi,
functionName: 'reputationOf',
args: [identity],
});
```

## Re-syncing to a new pin

The ABIs are generated, not hand-written. To move to a new ONCHAINID commit:

1. Check out T-REX-Network/ONCHAINID at the new commit and run `forge build`.
2. From this repository, run:

```bash
ONCHAINID_DIR=<path-to-onchainid-checkout> npm run sync-abi
```

`sync-abi` runs `scripts/sync-abi.mjs` and then Prettier on `src/abi`. The script reads each artifact from `<checkout>/out/`, writes the new commit into every header, sorts entries (events, then errors, then functions, alphabetically) so diffs stay readable, and keeps each file's hand-written doc comment.

3. Run `npm run compile && npm test` to catch shape changes downstream, then review the doc comments in `src/abi/` against what changed.

To add a new ABI, add an entry to the `ABIS` list in `scripts/sync-abi.mjs` (output file, export name, artifact name, source path, and an optional `pick` list for curated subsets), then export it from `src/abi/index.ts`.
Loading
Loading