@andrewkimjoseph/celina 0.2.18 → 0.3.1

package/README.md

@@ -256,6 +256,8 @@ The server decrypts the key ephemerally to sign the transaction — it is not st
 |----------|---------|-------------|
 | `CELO_RPC_URL_MAINNET` | Forno public RPC | Override mainnet RPC |
 | `CELO_PRIVATE_KEY` | — | Local stdio write tools only |
+| `SELF_AGENT_PRIVATE_KEY` | — | Self Agent ID signing/identity tools (separate from CELO wallet) |
+| `SELF_AGENT_API_BASE` | `https://app.ai.self.xyz` | Override Self Agent ID REST API base URL |
 | `WALLET_ENCRYPTION_PRIVATE_KEY` | — | RSA private key PEM for HTTP write tools |
 | `ALLOWED_HOSTS` | — | Comma-separated custom hostnames (e.g. `mcp.celina.andrewkimjoseph.com`) |
 | `PORT` | `10000` | HTTP server port (set by Render) |
@@ -298,6 +300,33 @@ Token symbols are resolved case-insensitively. Legacy aliases `cUSD` and `cEUR`
 | `execute_mento_fx` | write | Execute Mento FX conversion |
 | `supply_aave_usdt` | write | Supply USDT to Aave V3 on Celo |
 | `withdraw_aave_usdt` | write | Withdraw USDT from Aave V3 on Celo |
+| `get_gooddollar_whitelisting_info` | read | GoodDollar IdentityV4 whitelist status |
+| `verify_self_agent` | read | Verify Self Agent ID on-chain by address |
+| `lookup_self_agent` | read | Look up Self agent by numeric ID (ai.self.xyz) |
+| `verify_self_request` | read | Verify signed Self Agent HTTP request headers |
+| `register_self_agent` | write | Start Self agent registration (QR/deep link) |
+| `check_self_registration` | read* | Poll registration/refresh/deregister session (*may return private key) |
+| `get_self_identity` | read* | Current Self agent identity (*needs agent key) |
+| `refresh_self_proof` | write | Renew human proof after on-chain expiry (`isProofFresh` false) |
+| `deregister_self_agent` | write | Irreversibly revoke Self agent identity |
+| `sign_self_request` | read* | Sign HTTP request with Self agent headers (*needs agent key) |
+| `authenticated_self_fetch` | write | HTTP fetch with Self agent auth (*needs agent key) |
+
+### Self Agent ID notes
+
+- **Registration lifecycle APIs** (`register_self_agent`, `refresh_self_proof`, `deregister_self_agent`) use `network: "mainnet"` in the Self REST API request body.
+- **Demo and gated HTTP endpoints** (e.g. `https://app.ai.self.xyz/api/demo/verify`) require the query param **`network=celo-mainnet`**, not `network=mainnet`.
+- **QR scan URLs** use `/scan/{sessionToken}`, not `/qr/...`.
+- **`refresh_self_proof`** only starts after on-chain proof expiry (`isProofFresh` is false); while fresh it returns a clear error instead of a QR that will fail on-chain. The 30-day `is_expiring_soon` flag (matching Self SDK `isProofExpiringSoon`) is for warnings only. Self SDK also documents deregister → re-register as an alternative renewal path.
+
+Example authenticated demo call:
+
+```text
+authenticated_self_fetch
+  method: POST
+  url: https://app.ai.self.xyz/api/demo/verify?network=celo-mainnet
+  body: {}
+```
 
 ## Adding a new tool
 
@@ -325,8 +354,8 @@ No changes to `src/index.ts` or server bootstrap required.
 
 - [x] Mento FX routing (`get_mento_fx_quote`, `estimate_mento_fx`, `execute_mento_fx`)
 - [x] Aave lending tools (`supply_aave_usdt`, `withdraw_aave_usdt`)
-- [ ] Self proof verification (`ai.self.xyz`)
-- [ ] Self Agent ID check
+- [x] Self proof verification (`verify_self_agent`, `verify_self_request`, `ai.self.xyz`)
+- [x] Self Agent ID check (`lookup_self_agent`, registration & lifecycle tools)
 
 ## Development
 

package/build/abis/self-registry.d.ts

@@ -0,0 +1,194 @@
+export declare const selfRegistryAbi: readonly [{
+    readonly name: "isVerifiedAgent";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentPubKey";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "getAgentId";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentPubKey";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "hasHumanProof";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "getHumanNullifier";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "getAgentCountForHuman";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "nullifier";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "getProofProvider";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "selfProofProvider";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "getAgentCredentials";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "issuingState";
+            readonly type: "string";
+        }, {
+            readonly name: "name";
+            readonly type: "string[]";
+        }, {
+            readonly name: "idNumber";
+            readonly type: "string";
+        }, {
+            readonly name: "nationality";
+            readonly type: "string";
+        }, {
+            readonly name: "dateOfBirth";
+            readonly type: "string";
+        }, {
+            readonly name: "gender";
+            readonly type: "string";
+        }, {
+            readonly name: "expiryDate";
+            readonly type: "string";
+        }, {
+            readonly name: "olderThan";
+            readonly type: "uint256";
+        }, {
+            readonly name: "ofac";
+            readonly type: "bool[3]";
+        }];
+    }];
+}, {
+    readonly name: "agentRegisteredAt";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "proofExpiresAt";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "isProofFresh";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "getAgentsForNullifier";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "nullifier";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256[]";
+    }];
+}, {
+    readonly name: "ownerOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "updateAgentMetadata";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "agentId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "metadata";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [];
+}];

package/build/abis/self-registry.js

@@ -0,0 +1,120 @@
+export const selfRegistryAbi = [
+    {
+        name: "isVerifiedAgent",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentPubKey", type: "bytes32" }],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        name: "getAgentId",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentPubKey", type: "bytes32" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "hasHumanProof",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        name: "getHumanNullifier",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "getAgentCountForHuman",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "nullifier", type: "uint256" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "getProofProvider",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        name: "selfProofProvider",
+        type: "function",
+        stateMutability: "view",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        name: "getAgentCredentials",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [
+            {
+                name: "",
+                type: "tuple",
+                components: [
+                    { name: "issuingState", type: "string" },
+                    { name: "name", type: "string[]" },
+                    { name: "idNumber", type: "string" },
+                    { name: "nationality", type: "string" },
+                    { name: "dateOfBirth", type: "string" },
+                    { name: "gender", type: "string" },
+                    { name: "expiryDate", type: "string" },
+                    { name: "olderThan", type: "uint256" },
+                    { name: "ofac", type: "bool[3]" },
+                ],
+            },
+        ],
+    },
+    {
+        name: "agentRegisteredAt",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "proofExpiresAt",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        name: "isProofFresh",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "agentId", type: "uint256" }],
+        outputs: [{ name: "", type: "bool" }],
+    },
+    {
+        name: "getAgentsForNullifier",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "nullifier", type: "uint256" }],
+        outputs: [{ name: "", type: "uint256[]" }],
+    },
+    {
+        name: "ownerOf",
+        type: "function",
+        stateMutability: "view",
+        inputs: [{ name: "tokenId", type: "uint256" }],
+        outputs: [{ name: "", type: "address" }],
+    },
+    {
+        name: "updateAgentMetadata",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "agentId", type: "uint256" },
+            { name: "metadata", type: "string" },
+        ],
+        outputs: [],
+    },
+];
+//# sourceMappingURL=self-registry.js.map

package/build/abis/self-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-registry.js","sourceRoot":"","sources":["../../src/abis/self-registry.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;QACE,IAAI,EAAE,iBAAiB;QACvB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAClD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACtC;IACD;QACE,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAClD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACtC;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,EAAE;gBACR,IAAI,EAAE,OAAO;gBACb,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACxC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE;oBAClC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACpC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACvC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACvC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAClC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACtC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;oBACtC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE;iBAClC;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;KACtC;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;KAC3C;IACD;QACE,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,qBAAqB;QAC3B,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;SACrC;QACD,OAAO,EAAE,EAAE;KACZ;CACqB,CAAC"}

package/build/clients/self-api.d.ts

@@ -0,0 +1,82 @@
+import { type SelfRegistrationMode } from "../config/self.js";
+export declare class SelfApiError extends Error {
+    constructor(message: string);
+}
+export declare class SelfExpiredSessionError extends Error {
+    constructor(message?: string);
+}
+export interface SelfRegistrationDisclosures {
+    minimumAge?: number;
+    ofac?: boolean;
+}
+export interface SelfRegistrationResult {
+    agentId: number;
+    agentAddress: string;
+    credentials?: unknown;
+    txHash?: string;
+}
+export interface SelfRefreshResult {
+    proofExpiresAt: Date;
+}
+export interface SelfRegistrationSession {
+    sessionToken: string;
+    stage: string;
+    deepLink: string;
+    scanUrl?: string;
+    agentAddress: string;
+    expiresAt: string;
+    timeRemainingMs?: number;
+    humanInstructions: string[];
+    waitForCompletion(opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<SelfRegistrationResult>;
+    exportKey(): Promise<string>;
+}
+export interface SelfRefreshSession {
+    sessionToken: string;
+    stage: string;
+    deepLink: string;
+    scanUrl?: string;
+    expiresAt: string;
+    timeRemainingMs?: number;
+    humanInstructions: string[];
+    waitForCompletion(opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<SelfRefreshResult>;
+}
+export interface SelfDeregistrationSession {
+    sessionToken: string;
+    stage: string;
+    deepLink: string;
+    scanUrl?: string;
+    expiresAt: string;
+    timeRemainingMs?: number;
+    humanInstructions: string[];
+    waitForCompletion(opts?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<void>;
+}
+export declare function requestRegistration(opts: {
+    mode?: SelfRegistrationMode;
+    disclosures?: SelfRegistrationDisclosures;
+    humanAddress?: string;
+    agentName?: string;
+    agentDescription?: string;
+    apiBase?: string;
+}): Promise<SelfRegistrationSession>;
+export declare function requestDeregistration(opts: {
+    agentAddress: string;
+    disclosures?: SelfRegistrationDisclosures;
+    apiBase?: string;
+}): Promise<SelfDeregistrationSession>;
+export declare function requestProofRefresh(opts: {
+    agentId: number;
+    disclosures?: SelfRegistrationDisclosures;
+    apiBase?: string;
+}): Promise<SelfRefreshSession>;
+export declare function getAgentInfo(agentId: number, apiBase?: string): Promise<Record<string, unknown>>;
+export declare function getAgentsForHuman(address: string, apiBase?: string): Promise<Record<string, unknown>>;
+export declare function selfQrUrl(sessionToken: string, apiBase?: string): string;