@4mica/sdk 0.5.0

package/dist/abi/erc20.json

@@ -0,0 +1,187 @@
+{
+    "abi": [
+        {
+            "type": "function",
+            "name": "allowance",
+            "inputs": [
+                {
+                    "name": "owner",
+                    "type": "address",
+                    "internalType": "address"
+                },
+                {
+                    "name": "spender",
+                    "type": "address",
+                    "internalType": "address"
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "",
+                    "type": "uint256",
+                    "internalType": "uint256"
+                }
+            ],
+            "stateMutability": "view"
+        },
+        {
+            "type": "function",
+            "name": "approve",
+            "inputs": [
+                {
+                    "name": "spender",
+                    "type": "address",
+                    "internalType": "address"
+                },
+                {
+                    "name": "value",
+                    "type": "uint256",
+                    "internalType": "uint256"
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "",
+                    "type": "bool",
+                    "internalType": "bool"
+                }
+            ],
+            "stateMutability": "nonpayable"
+        },
+        {
+            "type": "function",
+            "name": "balanceOf",
+            "inputs": [
+                {
+                    "name": "account",
+                    "type": "address",
+                    "internalType": "address"
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "",
+                    "type": "uint256",
+                    "internalType": "uint256"
+                }
+            ],
+            "stateMutability": "view"
+        },
+        {
+            "type": "function",
+            "name": "totalSupply",
+            "inputs": [],
+            "outputs": [
+                {
+                    "name": "",
+                    "type": "uint256",
+                    "internalType": "uint256"
+                }
+            ],
+            "stateMutability": "view"
+        },
+        {
+            "type": "function",
+            "name": "transfer",
+            "inputs": [
+                {
+                    "name": "to",
+                    "type": "address",
+                    "internalType": "address"
+                },
+                {
+                    "name": "value",
+                    "type": "uint256",
+                    "internalType": "uint256"
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "",
+                    "type": "bool",
+                    "internalType": "bool"
+                }
+            ],
+            "stateMutability": "nonpayable"
+        },
+        {
+            "type": "function",
+            "name": "transferFrom",
+            "inputs": [
+                {
+                    "name": "from",
+                    "type": "address",
+                    "internalType": "address"
+                },
+                {
+                    "name": "to",
+                    "type": "address",
+                    "internalType": "address"
+                },
+                {
+                    "name": "value",
+                    "type": "uint256",
+                    "internalType": "uint256"
+                }
+            ],
+            "outputs": [
+                {
+                    "name": "",
+                    "type": "bool",
+                    "internalType": "bool"
+                }
+            ],
+            "stateMutability": "nonpayable"
+        },
+        {
+            "type": "event",
+            "name": "Approval",
+            "inputs": [
+                {
+                    "name": "owner",
+                    "type": "address",
+                    "indexed": true,
+                    "internalType": "address"
+                },
+                {
+                    "name": "spender",
+                    "type": "address",
+                    "indexed": true,
+                    "internalType": "address"
+                },
+                {
+                    "name": "value",
+                    "type": "uint256",
+                    "indexed": false,
+                    "internalType": "uint256"
+                }
+            ],
+            "anonymous": false
+        },
+        {
+            "type": "event",
+            "name": "Transfer",
+            "inputs": [
+                {
+                    "name": "from",
+                    "type": "address",
+                    "indexed": true,
+                    "internalType": "address"
+                },
+                {
+                    "name": "to",
+                    "type": "address",
+                    "indexed": true,
+                    "internalType": "address"
+                },
+                {
+                    "name": "value",
+                    "type": "uint256",
+                    "indexed": false,
+                    "internalType": "uint256"
+                }
+            ],
+            "anonymous": false
+        }
+    ]
+}

package/dist/auth.d.ts

@@ -0,0 +1,62 @@
+import type { FetchFn } from './rpc';
+import { EvmSigner } from './signing';
+export type AuthTokens = {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+};
+export type SiweTemplate = {
+    domain: string;
+    uri: string;
+    chainId: number;
+    statement: string;
+    expiration: string;
+    issuedAt: string;
+};
+export type AuthNonceResponse = {
+    nonce: string;
+    siwe: SiweTemplate;
+};
+export declare function buildSiweMessage(input: {
+    domain: string;
+    address: string;
+    statement: string;
+    uri: string;
+    chainId: number | string;
+    nonce: string;
+    issuedAt: string;
+    expiration: string;
+}): string;
+export declare class AuthClient {
+    private baseUrl;
+    private fetchFn;
+    constructor(endpoint: string, fetchFn?: FetchFn);
+    getNonce(address: string): Promise<AuthNonceResponse>;
+    verify(address: string, message: string, signature: string): Promise<AuthTokens>;
+    refresh(refreshToken: string): Promise<AuthTokens>;
+    logout(refreshToken: string): Promise<void>;
+    private post;
+    private request;
+}
+export declare class AuthSession {
+    private authClient;
+    private signer;
+    private refreshMarginSecs;
+    private tokens?;
+    private inFlight?;
+    private loginPromise?;
+    constructor(options: {
+        authUrl: string;
+        signer: EvmSigner;
+        refreshMarginSecs?: number;
+        fetchFn?: FetchFn;
+    });
+    accessToken(): Promise<string>;
+    login(): Promise<AuthTokens>;
+    logout(): Promise<void>;
+    private refreshOrLogin;
+    private performLogin;
+    private refreshTokens;
+    private cacheTokens;
+    private isExpiringSoon;
+}

package/dist/auth.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthSession = exports.AuthClient = void 0;
+exports.buildSiweMessage = buildSiweMessage;
+const errors_1 = require("./errors");
+const utils_1 = require("./utils");
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const readString = (value, label) => {
+    if (typeof value === 'string' && value.trim()) {
+        return value;
+    }
+    throw new errors_1.AuthDecodeError(`invalid auth response: missing ${label}`);
+};
+const readNumber = (value, label) => {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    throw new errors_1.AuthDecodeError(`invalid auth response: missing ${label}`);
+};
+const parseTokens = (payload) => {
+    const accessToken = readString(payload.access_token ?? payload.accessToken, 'access_token');
+    const refreshToken = readString(payload.refresh_token ?? payload.refreshToken, 'refresh_token');
+    const expiresIn = readNumber(payload.expires_in ?? payload.expiresIn, 'expires_in');
+    return { accessToken, refreshToken, expiresIn };
+};
+const parseSiweTemplate = (payload) => {
+    const domain = readString(payload.domain, 'siwe.domain');
+    const uri = readString(payload.uri, 'siwe.uri');
+    const chainId = readNumber(payload.chain_id ?? payload.chainId, 'siwe.chain_id');
+    const statement = readString(payload.statement, 'siwe.statement');
+    const expiration = readString(payload.expiration, 'siwe.expiration');
+    const issuedAt = readString(payload.issued_at ?? payload.issuedAt, 'siwe.issued_at');
+    return { domain, uri, chainId, statement, expiration, issuedAt };
+};
+const parseNonceResponse = (payload) => {
+    if (!isRecord(payload)) {
+        throw new errors_1.AuthDecodeError('invalid auth response: nonce payload');
+    }
+    const nonce = readString(payload.nonce, 'nonce');
+    if (!isRecord(payload.siwe)) {
+        throw new errors_1.AuthDecodeError('invalid auth response: missing siwe template');
+    }
+    return { nonce, siwe: parseSiweTemplate(payload.siwe) };
+};
+function buildSiweMessage(input) {
+    const chainId = String(input.chainId);
+    return `${input.domain} wants you to sign in with your Ethereum account:\n${input.address}\n\n${input.statement}\n\nURI: ${input.uri}\nVersion: 1\nChain ID: ${chainId}\nNonce: ${input.nonce}\nIssued At: ${input.issuedAt}\nExpiration Time: ${input.expiration}`;
+}
+class AuthClient {
+    constructor(endpoint, fetchFn = fetch) {
+        try {
+            const validated = (0, utils_1.validateUrl)(endpoint);
+            this.baseUrl = validated.endsWith('/') ? validated.slice(0, -1) : validated;
+        }
+        catch (err) {
+            if (err instanceof utils_1.ValidationError) {
+                throw new errors_1.AuthUrlError(err.message);
+            }
+            throw err;
+        }
+        this.fetchFn = fetchFn;
+    }
+    async getNonce(address) {
+        const payload = await this.post('/auth/nonce', { address });
+        return parseNonceResponse(payload);
+    }
+    async verify(address, message, signature) {
+        const payload = await this.post('/auth/verify', { address, message, signature });
+        if (!isRecord(payload)) {
+            throw new errors_1.AuthDecodeError('invalid auth response: verify payload');
+        }
+        return parseTokens(payload);
+    }
+    async refresh(refreshToken) {
+        const payload = await this.post('/auth/refresh', { refresh_token: refreshToken });
+        if (!isRecord(payload)) {
+            throw new errors_1.AuthDecodeError('invalid auth response: refresh payload');
+        }
+        return parseTokens(payload);
+    }
+    async logout(refreshToken) {
+        await this.post('/auth/logout', { refresh_token: refreshToken });
+    }
+    async post(path, body) {
+        return this.request(path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+    }
+    async request(path, init) {
+        let response;
+        try {
+            response = await this.fetchFn(`${this.baseUrl}${path}`, init);
+        }
+        catch (err) {
+            throw new errors_1.AuthTransportError(`auth request failed: ${String(err)}`);
+        }
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (err) {
+            throw new errors_1.AuthDecodeError(`invalid response from ${response.url}: ${String(err)}`);
+        }
+        let payload = text;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (err) {
+                if (response.ok) {
+                    throw new errors_1.AuthDecodeError(`invalid JSON response from ${response.url}: ${String(err)}`);
+                }
+            }
+        }
+        else {
+            payload = null;
+        }
+        if (response.ok) {
+            return payload;
+        }
+        let message = 'unknown error';
+        if (payload && typeof payload === 'object') {
+            const record = payload;
+            const error = record.error;
+            const msg = record.message;
+            message =
+                (typeof error === 'string' && error) ||
+                    (typeof msg === 'string' && msg) ||
+                    JSON.stringify(record, (_k, v) => v);
+        }
+        else if (typeof payload === 'string' && payload.trim()) {
+            message = payload.trim();
+        }
+        throw new errors_1.AuthApiError(`${response.status}: ${message}`, {
+            status: response.status,
+            body: payload,
+        });
+    }
+}
+exports.AuthClient = AuthClient;
+class AuthSession {
+    constructor(options) {
+        if (!options.authUrl) {
+            throw new errors_1.AuthMissingConfigError('missing auth_url');
+        }
+        this.authClient = new AuthClient(options.authUrl, options.fetchFn);
+        this.signer = options.signer;
+        const margin = options.refreshMarginSecs ?? 60;
+        if (!Number.isFinite(margin) || margin < 0) {
+            throw new errors_1.AuthConfigError('refresh margin must be non-negative');
+        }
+        this.refreshMarginSecs = margin;
+    }
+    async accessToken() {
+        if (this.tokens && !this.isExpiringSoon()) {
+            return this.tokens.accessToken;
+        }
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        this.inFlight = this.refreshOrLogin();
+        try {
+            return await this.inFlight;
+        }
+        finally {
+            this.inFlight = undefined;
+        }
+    }
+    async login() {
+        if (this.loginPromise) {
+            return this.loginPromise;
+        }
+        this.loginPromise = this.performLogin();
+        try {
+            return await this.loginPromise;
+        }
+        finally {
+            this.loginPromise = undefined;
+        }
+    }
+    async logout() {
+        if (!this.tokens?.refreshToken) {
+            return;
+        }
+        await this.authClient.logout(this.tokens.refreshToken);
+        this.tokens = undefined;
+    }
+    async refreshOrLogin() {
+        if (this.tokens?.refreshToken) {
+            try {
+                const tokens = await this.refreshTokens();
+                return tokens.accessToken;
+            }
+            catch (err) {
+                if (err instanceof errors_1.AuthApiError && err.status === 401) {
+                    const tokens = await this.login();
+                    return tokens.accessToken;
+                }
+                throw err;
+            }
+        }
+        const tokens = await this.login();
+        return tokens.accessToken;
+    }
+    async performLogin() {
+        const address = this.signer.address;
+        const nonce = await this.authClient.getNonce(address);
+        const message = buildSiweMessage({
+            domain: nonce.siwe.domain,
+            address,
+            statement: nonce.siwe.statement,
+            uri: nonce.siwe.uri,
+            chainId: nonce.siwe.chainId,
+            nonce: nonce.nonce,
+            issuedAt: nonce.siwe.issuedAt,
+            expiration: nonce.siwe.expiration,
+        });
+        const signature = await this.signer.signMessage({ message });
+        const tokens = await this.authClient.verify(address, message, signature);
+        this.cacheTokens(tokens);
+        return tokens;
+    }
+    async refreshTokens() {
+        if (!this.tokens?.refreshToken) {
+            throw new errors_1.AuthMissingConfigError('missing refresh token');
+        }
+        const tokens = await this.authClient.refresh(this.tokens.refreshToken);
+        this.cacheTokens(tokens);
+        return tokens;
+    }
+    cacheTokens(tokens) {
+        const now = Date.now() / 1000;
+        this.tokens = {
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken,
+            expiresAt: now + tokens.expiresIn,
+        };
+    }
+    isExpiringSoon() {
+        if (!this.tokens) {
+            return true;
+        }
+        const now = Date.now() / 1000;
+        return now + this.refreshMarginSecs >= this.tokens.expiresAt;
+    }
+}
+exports.AuthSession = AuthSession;

package/dist/bls.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Expand a compressed G2 signature into the tuple expected by the contract.
+ * This mirrors the Python helper and requires the optional `@noble/curves` dependency.
+ */
+export declare function signatureToWords(signatureHex: string): Uint8Array[];

package/dist/bls.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signatureToWords = signatureToWords;
+const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
+function splitFp(value) {
+    const be48 = value.toString(16).padStart(96, '0');
+    const bytes = (0, ethers_1.getBytes)(`0x${be48}`);
+    const hi = new Uint8Array(32);
+    hi.set(bytes.slice(0, 16), 16);
+    const lo = bytes.slice(16);
+    return [hi, lo];
+}
+/**
+ * Expand a compressed G2 signature into the tuple expected by the contract.
+ * This mirrors the Python helper and requires the optional `@noble/curves` dependency.
+ */
+function signatureToWords(signatureHex) {
+    let curves;
+    try {
+        // Lazy require to keep the dependency optional.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        curves = require('@noble/curves/bls12-381');
+    }
+    catch {
+        throw new errors_1.VerificationError('BLS decoding requires @noble/curves; install it to enable remuneration');
+    }
+    const toBigint = (field) => {
+        if (typeof field === 'bigint' || typeof field === 'number' || typeof field === 'string') {
+            return BigInt(field);
+        }
+        if (field && typeof field === 'object' && 'value' in field && field.value !== undefined) {
+            const value = field.value;
+            if (typeof value === 'bigint' || typeof value === 'number' || typeof value === 'string') {
+                return BigInt(value);
+            }
+        }
+        throw new errors_1.VerificationError('invalid BLS field element');
+    };
+    try {
+        const sigBytes = (0, ethers_1.getBytes)(signatureHex);
+        const point = curves.bls12_381.G2.ProjectivePoint.fromHex(sigBytes);
+        const affine = point.toAffine();
+        const [x0, x1] = affine.x.c;
+        const [y0, y1] = affine.y.c;
+        const coords = [x0, x1, y0, y1].map((fp) => toBigint(fp));
+        const words = [];
+        coords.forEach((coord) => {
+            const [hi, lo] = splitFp(coord);
+            words.push(hi, lo);
+        });
+        return words;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_1.VerificationError(`invalid BLS signature: ${message}`);
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+import type { AuthTokens } from './auth';
+import { Config } from './config';
+import { ContractGateway } from './contract';
+import { AssetBalanceInfo, BLSCert, CollateralEventInfo, GuaranteeInfo, PaymentGuaranteeClaims, PaymentGuaranteeRequestClaims, PaymentSignature, PendingRemunerationInfo, RecipientPaymentInfo, SigningScheme, TabInfo, TabPaymentStatus, UserInfo } from './models';
+import { RpcProxy } from './rpc';
+import { CorePublicParameters, PaymentSigner } from './signing';
+export declare class Client {
+    readonly rpc: RpcProxy;
+    readonly params: CorePublicParameters;
+    readonly gateway: ContractGateway;
+    readonly guaranteeDomain: string;
+    readonly user: UserClient;
+    readonly recipient: RecipientClient;
+    readonly signer: PaymentSigner;
+    private authSession?;
+    private constructor();
+    static new(cfg: Config): Promise<Client>;
+    private static buildGateway;
+    private static validateChainId;
+    aclose(): Promise<void>;
+    login(): Promise<AuthTokens>;
+}
+export declare class UserClient {
+    private client;
+    constructor(client: Client);
+    get guaranteeDomain(): string;
+    approveErc20(token: string, amount: number | bigint | string): Promise<unknown>;
+    deposit(amount: number | bigint | string, erc20Token?: string): Promise<unknown>;
+    getUser(): Promise<UserInfo[]>;
+    getTabPaymentStatus(tabId: number | bigint): Promise<TabPaymentStatus>;
+    signPayment(claims: PaymentGuaranteeRequestClaims, scheme?: SigningScheme): Promise<PaymentSignature>;
+    payTab(tabId: number | bigint, reqId: number | bigint, amount: number | bigint | string, recipientAddress: string, erc20Token?: string): Promise<unknown>;
+    requestWithdrawal(amount: number | bigint | string, erc20Token?: string): Promise<unknown>;
+    cancelWithdrawal(erc20Token?: string): Promise<unknown>;
+    finalizeWithdrawal(erc20Token?: string): Promise<unknown>;
+}
+export declare class RecipientClient {
+    private client;
+    constructor(client: Client);
+    private get recipientAddress();
+    get guaranteeDomain(): string;
+    private checkSigner;
+    createTab(userAddress: string, recipientAddress: string, erc20Token: string | undefined | null, ttl?: number | null): Promise<bigint>;
+    getTabPaymentStatus(tabId: number | bigint): Promise<TabPaymentStatus>;
+    issuePaymentGuarantee(claims: PaymentGuaranteeRequestClaims, signature: string, scheme: SigningScheme): Promise<BLSCert>;
+    verifyPaymentGuarantee(cert: BLSCert): PaymentGuaranteeClaims;
+    remunerate(cert: BLSCert): Promise<unknown>;
+    listSettledTabs(): Promise<TabInfo[]>;
+    listPendingRemunerations(): Promise<PendingRemunerationInfo[]>;
+    getTab(tabId: number | bigint): Promise<TabInfo | null>;
+    listRecipientTabs(settlementStatuses?: string[]): Promise<TabInfo[]>;
+    getTabGuarantees(tabId: number | bigint): Promise<GuaranteeInfo[]>;
+    getLatestGuarantee(tabId: number | bigint): Promise<GuaranteeInfo | null>;
+    getGuarantee(tabId: number | bigint, reqId: number | bigint): Promise<GuaranteeInfo | null>;
+    listRecipientPayments(): Promise<RecipientPaymentInfo[]>;
+    getCollateralEventsForTab(tabId: number | bigint): Promise<CollateralEventInfo[]>;
+    getUserAssetBalance(userAddress: string, assetAddress: string): Promise<AssetBalanceInfo | null>;
+}