@appliedblockchain/silentdatarollup-core 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,205 @@
+import { Signer, JsonRpcPayload, Contract, TypedDataDomain, TypedDataField, InterfaceAbi, ContractRunner } from 'ethers';
+
+declare const SIGN_RPC_METHODS: string[];
+declare const eip721Domain: {
+    name: string;
+    version: string;
+};
+declare const delegateEIP721Types: {
+    Ticket: {
+        name: string;
+        type: string;
+    }[];
+};
+declare const DEBUG_NAMESPACE = "silentdata:core";
+declare const DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR = "silentdata:interceptor";
+declare const HEADER_SIGNATURE = "x-signature";
+declare const HEADER_TIMESTAMP = "x-timestamp";
+declare const HEADER_EIP712_SIGNATURE = "x-eip712-signature";
+declare const HEADER_DELEGATE = "x-delegate";
+declare const HEADER_DELEGATE_SIGNATURE = "x-delegate-signature";
+declare const HEADER_EIP712_DELEGATE_SIGNATURE = "x-eip712-delegate-signature";
+declare const DEFAULT_DELEGATE_EXPIRES: number;
+/**
+ * A buffer time (in seconds) added to the current time when verifying the validity of a delegate.
+ * This ensures that if the current time plus the buffer exceeds the delegate's expiry date,
+ * the delegate is considered expired.
+ */
+declare const DELEGATE_EXPIRATION_THRESHOLD_BUFFER = 5;
+declare const WHITELISTED_METHODS: string[];
+
+declare enum ChainId {
+    MAINNET = 51966,
+    TESTNET = 1001
+}
+declare enum NetworkName {
+    MAINNET = "sdr",
+    TESTNET = "sdr-testnet"
+}
+declare enum SignatureType {
+    Raw = "RAW",
+    EIP191 = "EIP191",
+    EIP712 = "EIP712"
+}
+interface SilentDataProviderOptions {
+    authSignatureType?: SignatureType;
+}
+interface SilentdataNetworkConfig {
+    authSignatureType?: SignatureType;
+}
+type DelegateConfig = {
+    getDelegate: (provider: any) => Promise<Signer>;
+    expires: number;
+};
+type BaseConfig = {
+    /**
+     * Enables auth header signing by a delegate signer.
+     * Configuration for optional delegate functionality.
+     * - true: Uses default delegate configuration.
+     * - object: Allows customization of delegate behavior.
+     * - undefined/false: Disables delegate functionality.
+     */
+    delegate?: boolean | {
+        /**
+         * Custom function to get a delegate signer.
+         * If not provided, defaults to the defaultGetDelegate function.
+         */
+        getDelegate?: (provider: any) => Promise<Signer>;
+        /**
+         * Expiration time for the delegate in seconds.
+         * If not provided, defaults to DEFAULT_DELEGATE_EXPIRES.
+         */
+        expires?: number;
+    };
+    authSignatureType?: SignatureType;
+};
+type DelegateSignerMessage = {
+    expires: string;
+    ephemeralAddress: string;
+};
+type AuthSignatureMessage = {
+    request: AuthSignatureMessageRequest | AuthSignatureMessageRequest[];
+    timestamp: string;
+};
+type AuthSignatureMessageRequest = Omit<JsonRpcPayload, 'params'> & {
+    params: string;
+};
+type AuthHeaders = {
+    [HEADER_TIMESTAMP]: string;
+    [HEADER_SIGNATURE]?: string;
+    [HEADER_EIP712_SIGNATURE]?: string;
+};
+type DelegateHeaders = {
+    [HEADER_DELEGATE]: string;
+    [HEADER_DELEGATE_SIGNATURE]?: string;
+    [HEADER_EIP712_DELEGATE_SIGNATURE]?: string;
+};
+
+declare class SilentDataRollupBase {
+    config: BaseConfig;
+    private delegateConfig;
+    private currentDelegateSigner;
+    private delegateSignerExpires;
+    private cachedDelegateHeaders;
+    private cachedHeadersExpiry;
+    contract: Contract | null;
+    contractMethodsToSign: string[];
+    constructor(config: BaseConfig);
+    private resolveDelegateConfig;
+    getDelegateSigner(provider: any): Promise<Signer | null>;
+    getDelegateSignerMessage(provider: any): Promise<DelegateSignerMessage | null>;
+    /**
+     * Signs a raw delegate header message.
+     * This method can be overridden by extending classes to customize the signing process.
+     * @param provider - The provider used for signing
+     * @param message - The delegate signer message to be signed
+     * @returns A promise that resolves to the signature string
+     */
+    protected signRawDelegateHeader(provider: any, message: DelegateSignerMessage): Promise<string>;
+    /**
+     * Signs a typed delegate header message.
+     * This method can be overridden by extending classes to customize the signing process.
+     * @param provider - The provider used for signing
+     * @param message - The delegate signer message to be signed
+     * @returns A promise that resolves to the signature string
+     */
+    protected signTypedDelegateHeader(provider: any, message: DelegateSignerMessage): Promise<string>;
+    getDelegateHeaders(provider: any): Promise<DelegateHeaders>;
+    getAuthHeaders(provider: any, payload: JsonRpcPayload | JsonRpcPayload[]): Promise<AuthHeaders>;
+    signAuthHeaderRawMessage(provider: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+    signAuthHeaderTypedData(provider: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+    /**
+     * Signs a message using the provided signer.
+     * This method can be overridden to customize the signing process.
+     * @param signer - The signer to use
+     * @param message - The message to sign
+     * @returns A promise that resolves to the signature string
+     */
+    protected signMessage(signer: any, message: string): Promise<string>;
+    /**
+     * Signs typed data using the provided signer.
+     * This method can be overridden to customize the signing process.
+     * @param signer - The signer to use
+     * @param domain - The EIP-712 domain
+     * @param types - The EIP-712 types
+     * @param message - The message to sign
+     * @returns A promise that resolves to the signature string
+     */
+    protected signTypedData(signer: any, domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, message: Record<string, any>): Promise<string>;
+    setContract(contract: Contract, contractMethodsToSign: string[]): void;
+    /**
+     * Prepares the message to be signed for the x-signature header.
+     */
+    prepareSignatureMessage(payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): string;
+    /**
+     * Prepares the message to be signed for the x-eip712-signature header.
+     */
+    prepareSignatureTypedData(payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): AuthSignatureMessage;
+}
+
+declare class SilentDataRollupContract extends Contract {
+    constructor(address: string, abi: InterfaceAbi, runner: ContractRunner, contractMethodsToSign: string[]);
+}
+
+declare function getAuthEIP721Types(payload: JsonRpcPayload | JsonRpcPayload[]): {
+    Call: {
+        name: string;
+        type: string;
+    }[];
+    JsonRPCRequest: {
+        name: string;
+        type: string;
+    }[];
+};
+declare function signAuthHeaderTypedData(signer: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+declare function signAuthHeaderRawMessage(signer: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+declare function signTypedDelegateHeader(signer: any, message: DelegateSignerMessage): Promise<any>;
+declare function signRawDelegateHeader(signer: any, message: DelegateSignerMessage): Promise<string>;
+declare function getAuthHeaders(signer: Signer, payload: JsonRpcPayload | JsonRpcPayload[], signatureType: SignatureType): Promise<AuthHeaders>;
+/**
+ * Determines if a given JSON-RPC payload represents a call to a contract method that requires signing.
+ *
+ * This function is crucial for identifying "private" read calls on smart contracts - methods that
+ * require authenticated `msg.sender`. It helps ensure proper authentication for accessing
+ * sensitive data or functionality on the contract side.
+ *
+ * The function performs the following checks:
+ * 1. Verifies if the payload is an `eth_call`.
+ * 2. Extracts the method signature from the call data.
+ * 3. Compares the signature against a provided list of methods requiring signing.
+ * 4. Uses the contract's ABI to match the method signature with known methods.
+ *
+ * By accurately identifying these calls, we can add appropriate authentication headers
+ * to the request, enabling the smart contract to verify the caller's identity.
+ *
+ * @param payload - The JSON-RPC payload to analyze.
+ * @param contractMethodsToSign - An array of method names that require signing.
+ * @param contract - The contract instance containing the ABI information.
+ * @returns {boolean} True if the call is to a method that requires signing, false otherwise.
+ * @throws {Error} If contractMethodsToSign or contract is not provided.
+ */
+declare function isSignableContractCall(payload: JsonRpcPayload, contractMethodsToSign?: string[], contract?: Contract | null): boolean;
+declare const defaultGetDelegate: (provider: any) => Promise<Signer>;
+declare const prepareTypedDataPayload: (p: JsonRpcPayload) => AuthSignatureMessageRequest;
+
+export { type AuthHeaders, type AuthSignatureMessage, type AuthSignatureMessageRequest, type BaseConfig, ChainId, DEBUG_NAMESPACE, DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR, DEFAULT_DELEGATE_EXPIRES, DELEGATE_EXPIRATION_THRESHOLD_BUFFER, type DelegateConfig, type DelegateHeaders, type DelegateSignerMessage, HEADER_DELEGATE, HEADER_DELEGATE_SIGNATURE, HEADER_EIP712_DELEGATE_SIGNATURE, HEADER_EIP712_SIGNATURE, HEADER_SIGNATURE, HEADER_TIMESTAMP, NetworkName, SIGN_RPC_METHODS, SignatureType, type SilentDataProviderOptions, SilentDataRollupBase, SilentDataRollupContract, type SilentdataNetworkConfig, WHITELISTED_METHODS, defaultGetDelegate, delegateEIP721Types, eip721Domain, getAuthEIP721Types, getAuthHeaders, isSignableContractCall, prepareTypedDataPayload, signAuthHeaderRawMessage, signAuthHeaderTypedData, signRawDelegateHeader, signTypedDelegateHeader };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import { Signer, JsonRpcPayload, Contract, TypedDataDomain, TypedDataField, InterfaceAbi, ContractRunner } from 'ethers';
+
+declare const SIGN_RPC_METHODS: string[];
+declare const eip721Domain: {
+    name: string;
+    version: string;
+};
+declare const delegateEIP721Types: {
+    Ticket: {
+        name: string;
+        type: string;
+    }[];
+};
+declare const DEBUG_NAMESPACE = "silentdata:core";
+declare const DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR = "silentdata:interceptor";
+declare const HEADER_SIGNATURE = "x-signature";
+declare const HEADER_TIMESTAMP = "x-timestamp";
+declare const HEADER_EIP712_SIGNATURE = "x-eip712-signature";
+declare const HEADER_DELEGATE = "x-delegate";
+declare const HEADER_DELEGATE_SIGNATURE = "x-delegate-signature";
+declare const HEADER_EIP712_DELEGATE_SIGNATURE = "x-eip712-delegate-signature";
+declare const DEFAULT_DELEGATE_EXPIRES: number;
+/**
+ * A buffer time (in seconds) added to the current time when verifying the validity of a delegate.
+ * This ensures that if the current time plus the buffer exceeds the delegate's expiry date,
+ * the delegate is considered expired.
+ */
+declare const DELEGATE_EXPIRATION_THRESHOLD_BUFFER = 5;
+declare const WHITELISTED_METHODS: string[];
+
+declare enum ChainId {
+    MAINNET = 51966,
+    TESTNET = 1001
+}
+declare enum NetworkName {
+    MAINNET = "sdr",
+    TESTNET = "sdr-testnet"
+}
+declare enum SignatureType {
+    Raw = "RAW",
+    EIP191 = "EIP191",
+    EIP712 = "EIP712"
+}
+interface SilentDataProviderOptions {
+    authSignatureType?: SignatureType;
+}
+interface SilentdataNetworkConfig {
+    authSignatureType?: SignatureType;
+}
+type DelegateConfig = {
+    getDelegate: (provider: any) => Promise<Signer>;
+    expires: number;
+};
+type BaseConfig = {
+    /**
+     * Enables auth header signing by a delegate signer.
+     * Configuration for optional delegate functionality.
+     * - true: Uses default delegate configuration.
+     * - object: Allows customization of delegate behavior.
+     * - undefined/false: Disables delegate functionality.
+     */
+    delegate?: boolean | {
+        /**
+         * Custom function to get a delegate signer.
+         * If not provided, defaults to the defaultGetDelegate function.
+         */
+        getDelegate?: (provider: any) => Promise<Signer>;
+        /**
+         * Expiration time for the delegate in seconds.
+         * If not provided, defaults to DEFAULT_DELEGATE_EXPIRES.
+         */
+        expires?: number;
+    };
+    authSignatureType?: SignatureType;
+};
+type DelegateSignerMessage = {
+    expires: string;
+    ephemeralAddress: string;
+};
+type AuthSignatureMessage = {
+    request: AuthSignatureMessageRequest | AuthSignatureMessageRequest[];
+    timestamp: string;
+};
+type AuthSignatureMessageRequest = Omit<JsonRpcPayload, 'params'> & {
+    params: string;
+};
+type AuthHeaders = {
+    [HEADER_TIMESTAMP]: string;
+    [HEADER_SIGNATURE]?: string;
+    [HEADER_EIP712_SIGNATURE]?: string;
+};
+type DelegateHeaders = {
+    [HEADER_DELEGATE]: string;
+    [HEADER_DELEGATE_SIGNATURE]?: string;
+    [HEADER_EIP712_DELEGATE_SIGNATURE]?: string;
+};
+
+declare class SilentDataRollupBase {
+    config: BaseConfig;
+    private delegateConfig;
+    private currentDelegateSigner;
+    private delegateSignerExpires;
+    private cachedDelegateHeaders;
+    private cachedHeadersExpiry;
+    contract: Contract | null;
+    contractMethodsToSign: string[];
+    constructor(config: BaseConfig);
+    private resolveDelegateConfig;
+    getDelegateSigner(provider: any): Promise<Signer | null>;
+    getDelegateSignerMessage(provider: any): Promise<DelegateSignerMessage | null>;
+    /**
+     * Signs a raw delegate header message.
+     * This method can be overridden by extending classes to customize the signing process.
+     * @param provider - The provider used for signing
+     * @param message - The delegate signer message to be signed
+     * @returns A promise that resolves to the signature string
+     */
+    protected signRawDelegateHeader(provider: any, message: DelegateSignerMessage): Promise<string>;
+    /**
+     * Signs a typed delegate header message.
+     * This method can be overridden by extending classes to customize the signing process.
+     * @param provider - The provider used for signing
+     * @param message - The delegate signer message to be signed
+     * @returns A promise that resolves to the signature string
+     */
+    protected signTypedDelegateHeader(provider: any, message: DelegateSignerMessage): Promise<string>;
+    getDelegateHeaders(provider: any): Promise<DelegateHeaders>;
+    getAuthHeaders(provider: any, payload: JsonRpcPayload | JsonRpcPayload[]): Promise<AuthHeaders>;
+    signAuthHeaderRawMessage(provider: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+    signAuthHeaderTypedData(provider: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+    /**
+     * Signs a message using the provided signer.
+     * This method can be overridden to customize the signing process.
+     * @param signer - The signer to use
+     * @param message - The message to sign
+     * @returns A promise that resolves to the signature string
+     */
+    protected signMessage(signer: any, message: string): Promise<string>;
+    /**
+     * Signs typed data using the provided signer.
+     * This method can be overridden to customize the signing process.
+     * @param signer - The signer to use
+     * @param domain - The EIP-712 domain
+     * @param types - The EIP-712 types
+     * @param message - The message to sign
+     * @returns A promise that resolves to the signature string
+     */
+    protected signTypedData(signer: any, domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, message: Record<string, any>): Promise<string>;
+    setContract(contract: Contract, contractMethodsToSign: string[]): void;
+    /**
+     * Prepares the message to be signed for the x-signature header.
+     */
+    prepareSignatureMessage(payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): string;
+    /**
+     * Prepares the message to be signed for the x-eip712-signature header.
+     */
+    prepareSignatureTypedData(payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): AuthSignatureMessage;
+}
+
+declare class SilentDataRollupContract extends Contract {
+    constructor(address: string, abi: InterfaceAbi, runner: ContractRunner, contractMethodsToSign: string[]);
+}
+
+declare function getAuthEIP721Types(payload: JsonRpcPayload | JsonRpcPayload[]): {
+    Call: {
+        name: string;
+        type: string;
+    }[];
+    JsonRPCRequest: {
+        name: string;
+        type: string;
+    }[];
+};
+declare function signAuthHeaderTypedData(signer: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+declare function signAuthHeaderRawMessage(signer: any, payload: JsonRpcPayload | JsonRpcPayload[], timestamp: string): Promise<string>;
+declare function signTypedDelegateHeader(signer: any, message: DelegateSignerMessage): Promise<any>;
+declare function signRawDelegateHeader(signer: any, message: DelegateSignerMessage): Promise<string>;
+declare function getAuthHeaders(signer: Signer, payload: JsonRpcPayload | JsonRpcPayload[], signatureType: SignatureType): Promise<AuthHeaders>;
+/**
+ * Determines if a given JSON-RPC payload represents a call to a contract method that requires signing.
+ *
+ * This function is crucial for identifying "private" read calls on smart contracts - methods that
+ * require authenticated `msg.sender`. It helps ensure proper authentication for accessing
+ * sensitive data or functionality on the contract side.
+ *
+ * The function performs the following checks:
+ * 1. Verifies if the payload is an `eth_call`.
+ * 2. Extracts the method signature from the call data.
+ * 3. Compares the signature against a provided list of methods requiring signing.
+ * 4. Uses the contract's ABI to match the method signature with known methods.
+ *
+ * By accurately identifying these calls, we can add appropriate authentication headers
+ * to the request, enabling the smart contract to verify the caller's identity.
+ *
+ * @param payload - The JSON-RPC payload to analyze.
+ * @param contractMethodsToSign - An array of method names that require signing.
+ * @param contract - The contract instance containing the ABI information.
+ * @returns {boolean} True if the call is to a method that requires signing, false otherwise.
+ * @throws {Error} If contractMethodsToSign or contract is not provided.
+ */
+declare function isSignableContractCall(payload: JsonRpcPayload, contractMethodsToSign?: string[], contract?: Contract | null): boolean;
+declare const defaultGetDelegate: (provider: any) => Promise<Signer>;
+declare const prepareTypedDataPayload: (p: JsonRpcPayload) => AuthSignatureMessageRequest;
+
+export { type AuthHeaders, type AuthSignatureMessage, type AuthSignatureMessageRequest, type BaseConfig, ChainId, DEBUG_NAMESPACE, DEBUG_NAMESPACE_SILENTDATA_INTERCEPTOR, DEFAULT_DELEGATE_EXPIRES, DELEGATE_EXPIRATION_THRESHOLD_BUFFER, type DelegateConfig, type DelegateHeaders, type DelegateSignerMessage, HEADER_DELEGATE, HEADER_DELEGATE_SIGNATURE, HEADER_EIP712_DELEGATE_SIGNATURE, HEADER_EIP712_SIGNATURE, HEADER_SIGNATURE, HEADER_TIMESTAMP, NetworkName, SIGN_RPC_METHODS, SignatureType, type SilentDataProviderOptions, SilentDataRollupBase, SilentDataRollupContract, type SilentdataNetworkConfig, WHITELISTED_METHODS, defaultGetDelegate, delegateEIP721Types, eip721Domain, getAuthEIP721Types, getAuthHeaders, isSignableContractCall, prepareTypedDataPayload, signAuthHeaderRawMessage, signAuthHeaderTypedData, signRawDelegateHeader, signTypedDelegateHeader };