eulith-web3js-core/dist/src/on-chain-agents.d.ts

Eulith core web3js SDK (code to access Eulith services via web3js)

import * as Eulith from "../src/index";
/**
 *  OnChainAgents are smart contracts employed mostly transparently to execute programmed sequences
 *  of ethereum transactions on your behelf.
 *
 *  OnChainAgents are key to how AtomicTx (atomic transactions) work, for example, but other facilities also
 *  leverage this special contract.
 *
 *  Frequently, the Eulith APIs manage these OnChainAgents completely transparently, and it can be ignored.
 *  But, in some cases, the user must be aware of the agent (contract) (for example,  to approve transfers).
 *
 *  Typically, all the user will need to know is, occasionally, to get information about the agent (like its contract address)
 *  via accessing its object:
 *      const contractAddress: string = Eulith.OnChainAgents.getAgent({provider, authorizedAddress}).contractAddress    OR
 *      const contractAddress: string = Eulith.OnChainAgents.getAgent({provider, authoriziedSigner}).contractAddress
 */
export declare module OnChainAgents {
    /**
     *  @typedef Eulith.OnChainAgents.Type
     */
    enum Type {
        /**
         *  An Unchecked Agent is the historical one, basic one, of of pre-april 2023.
         *
         *  It provides less checking and security than the armor contracts.
         *
         *  Associated value 'call' is historical.
         */
        Unchecked = "call",
        /**
         *  An Armor Agent is one that uses a Safe (see URL)
         */
        Armor = "armor"
    }
    /**
     *  @typedef Eulith.OnChainAgents.IAgent
     *
     *     An Agent is a Eulith object that lives on the Ethereum network (its a special contract instance), that can act on its 'owners' (really authorized address) behalf.
     *
     * All you need is to be able to sign requests using the signer (with the address == the authorized address).
     *
     * Then you can combine multiple transactions into atomic transactions, and perform other delegating actions through the agent.
     */
    interface IAgent {
        readonly type: Type;
        readonly contractAddress: string;
        readonly authorizedAddress: string;
    }
    /**
     *  @typedef Eulith.OnChainAgents.IArmorAgent
     */
    interface IArmorAgent extends IAgent {
        /**
         *  An armor agent is associated with a (gnosis) safe on the ethereum blockchain network. This is the safeAddress (ethereum address)
         *  of the safe.
         */
        readonly safeAddress: string;
        /**
         *  authorizingOwner (owner of the safe) authorizes this armorAgent to utilize its associated safe. The authorizingOwner
         *  signer will be asked to sign a structure which permits the authorizedSigner associated with this agent
         *  to utilize the safe as it sees fit.
         *
         *      @todo: SUGGESTED CHANGE TO EXISTING SEMANTICS:
         *          authorizingOwner.address must already be listed as an owner of the safe.
         *
         *  NOTE - authorizingOwner must support signTypedData (i.e. have a non-null typedDataSigner property of SigningService or be a ICryptographicSigner)
         */
        authorizeForOwner({ provider, authorizingOwner }: {
            provider: Eulith.Provider | Eulith.Web3;
            authorizingOwner: Eulith.Signing.ICryptographicSigner | Eulith.Signing.SigningService;
        }): Promise<void>;
        /**
         *  perform the various transactions required to enable the armor for the argument safe.
         *
         *  This requires signerForThisTx, to actuate this operation, and pay the gas for the transaction. But
         *  signerForThisTx may be any signer, not connected to the safe.
         *
         *  @todo some future version of this API may move the 'forSafe' object to the createArmor call
         */
        enableArmor({ provider, signerForThisTx, forSafe }: {
            provider: Eulith.Provider | Eulith.Web3;
            signerForThisTx: Eulith.Signing.ICryptographicSigner | Eulith.Signing.SigningService;
            forSafe: {
                safeAddress?: string;
                newSafe?: {
                    owners: string[];
                    approvalThreshold: number;
                };
            };
        }): Promise<void>;
    }
    /**
     *  Eulith.OnChainAgents.getAgent
     *
     *  Fetch the current agent refernece for the argument authorized address (or authoriziedSigner).
     *  provider (maybe Eulith.Provider | Eulith.Web3) used to communicate with the Ethereum network.
     *  createUncheckedAgentIfNoneExists - defaults to true if not specified.
     *
     *   Note - there can never be more than one IAgent associated with a given authorizedAddress.
     *
     *  See also Eulith.OnChainAgents.createUncheckedAgent
     *  See also Eulith.OnChainAgents.createArmorAgent
     */
    function getAgent({ provider, authorizedAddress, authoriziedSigner, createUncheckedAgentIfNoneExists }: {
        provider: Eulith.Provider | Eulith.Web3;
        authorizedAddress?: string;
        authoriziedSigner?: Eulith.Signing.SigningService | Eulith.Signing.ICryptographicSigner;
        createUncheckedAgentIfNoneExists?: boolean;
    }): Promise<IAgent>;
    /**
     *  Eulith.OnChainAgents.createUncheckedAgent is provided for logical consistency, but typically won't be used directly - instead - just use Eulith.OnChainAgents.getAgent();
     *
     *   Note this routine will fail if the agent already exists (another reason to just call Eulith.OnChainAgents.getAgent ())
     */
    function createUncheckedAgent({ provider, authorizedAddress }: {
        provider: Eulith.Provider | Eulith.Web3;
        authorizedAddress: string;
    }): Promise<IAgent>;
    /**
     *  Eulith.OnChainAgents.createArmorAgent
     *
     *  A Eulith 'armor' agent, is like any Eulith agent, allowing you to automate a sequence of operations on the
     *  Ethereum network, but in this case, much of that automation is actually performed by a 'safe' <https://safe.global/>
     *
     *  This creation process may optionally either create your safe, or re-use an existing safe. But either way, it registers
     *  a Eulith armor agent as a module on that safe, allowing it to direct the safe to perform transactions on it's behalf
     *  (transitively on your behalf, triggered by your use of an 'authorizedSigner').
     *
     *  You own/control that authorizedSigner. This allows the safe to operated by a SINGLE signer, instead of the requiring the N (safe threshold)
     *  signers.
     *
     *  The basic process is:
     *
     *      -   construct an armor contract with this API (passing in a safe, or the data needed to create a safe).
     *      -   get the owners of the safe to 'sign' the request to enable the Eulith Armor agent.
     *      -   enableArmor () - which completes the setup - activating your safe and your authorized signers ability to use it
     *      -   then start using your authorized signer - its now allowed to use the contents of this safe.
     *
     *  provider is the Eulith provider Ethereum network provider (or a Eulith.Web from which a provider can be extracted)
     *
     *  authorizedAddress is the address of some user-controlled signer (typically KMS-based, for example),
     *      which will be used to OPERATE and make requests on some associated safe (via the armor agent).
     *
     *  safeAddress is the address of the existing safe to associate with the new armor, and if null or omitted
     *      a new safe will be automatically created.
     *
     *  NOTE, if safeAddress is not specified, the safe will be automatically created by the Eulith server
     *  and owners etc calculated automatically.
     *
     *  setupSigner: a signer is needed to send any ethereum transaction message, but which one is used here does not matter, except that it pays the
     *  gas for this setup transaction.
     *
     *  Note - this will FAIL if any Eulith Agent already exists for this authorizedAddress.
     *
     *  Exactly one of safeAddress (case of existing safe), or safeCreationParamters, must be provided (NOTE KRISTIAN - THIS IS A DEPARTURE FROM YOUR CURRENT API - A SUGGESTION).
     */
    function createArmorAgent({ provider, authorizedAddress, safeAddress, setupSigner }: {
        provider: Eulith.Provider | Eulith.Web3;
        authorizedAddress: string;
        safeAddress?: string;
        setupSigner: Eulith.Signing.ICryptographicSigner | Eulith.Signing.SigningService;
    }): Promise<IAgent>;
    /**
     *  Eulith.OnChainAgents.contractAddress
     *
     *  Shorthand for getAgent(...sameargs).contractAddress
     */
    function contractAddress({ provider, authorizedAddress, authoriziedSigner, createUncheckedAgentIfNoneExists }: {
        provider: Eulith.Provider | Eulith.Web3;
        authorizedAddress?: string;
        authoriziedSigner?: Eulith.Signing.SigningService | Eulith.Signing.ICryptographicSigner;
        createUncheckedAgentIfNoneExists?: boolean;
    }): Promise<string>;
    /**
     *  Eulith.OnChainAgents.armorAgent
     *
     *  Access the existing armor agent for authorized address/signer: Shorthand for getAgent(...sameargs) - check is right type, and return it as IArmorAgent
     *
     *  note - never returns null, or creates anything - just returns the existing agent, or throws
     */
    function armorAgent({ provider, authorizedAddress, authoriziedSigner }: {
        provider: Eulith.Provider | Eulith.Web3;
        authorizedAddress?: string;
        authoriziedSigner?: Eulith.Signing.SigningService | Eulith.Signing.ICryptographicSigner;
    }): Promise<IArmorAgent>;
}