eulith-web3js/dist/src/onChainAgents.d.ts

Official Eulith Typescript client library

import * as Eulith from "./index";
/**
 *  OnChainAgents are smart contracts employed mostly transparently to execute programmed sequences
 *  of ethereum transactions on your behalf.
 *
 *  At this point there are two types of OnChainAgents:
 *  1. ArmorAgent -- the ArmorAgent works in cooperation with a Safe to enforce policies on your transactions
 *                   with a cosigner from Eulith
 *  2. UncheckedAgent -- the UncheckedAgent doesn't enforce any policies or require any cosignature from Eulith
 *
 *  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, authorizedSigner}).contractAddress
 */
export declare module OnChainAgents {
    /**
     * @readonly
     * @enum Eulith.OnChainAgents.Type
     */
    enum Type {
        /**
         *  UncheckedAgent allows you to take atomic transactions on chain, but enforces no other
         *  security constraints.
         */
        Unchecked = "call",
        /**
         *  An Armor agent must work in cooperation with a Safe and requires a cosignature from Eulith
         *  to execute anything after a transaction has passed a simulation based policy.
         */
        Armor = "armor"
    }
    /**
     *  An Agent is a smart contract that manages execution via Eulith services. See OnChainAgents for more information.
     *  IAgent is the base level interface for all agents.
     */
    interface IAgent {
        /** The type of the agent (for example Armor or Unchecked) */
        readonly type: Type;
        /** The address of the deployed contract */
        readonly contractAddress: string;
        /** The address of the authorized user, i.e. the address that must sign transactions to execute through the agent */
        readonly tradingKeyAddress: string;
        /** The chain id of host network for this IAgent contract */
        readonly chainId: number;
        /** The name of the host network for this IAgent contract */
        readonly networkName: string;
        /** The globally unique id of this contract */
        readonly deployedContractId: number;
        /** The user-specified name of this contract */
        readonly name: string;
        /** The user-specified description of this contract */
        readonly description: string;
    }
    interface EnableArmorSignature {
        readonly signature: string;
        readonly owner_address: string;
    }
    /**
     *  IArmorAgent is the interface for ArmorAgents. It extends IAgent.
     */
    interface IArmorAgent extends IAgent {
        /**
         *  All ArmorAgents must have a relationship with a (previously Gnosis Safe) Safe.
         *  The address of the (previously Gnosis Safe) Safe connected to this ArmorAgent
         */
        readonly safeAddress: string;
        readonly hasAce: boolean;
        readonly isEnabled: boolean;
        readonly whitelistId: number;
        /**
         * When deploying a new ArmorAgent, you can optionally deploy a new Safe at the same time.
         * In the case where you are deploying the ArmorAgent and the Safe at the same time, you must
         * authorize the ArmorAgent with a sufficient threshold of owners for the new safe.
         *
         * This method performs this operation, i.e. storing a signature from the authorizing owner.
         *
         * Note that at the time this method is called, the safe is not yet set up. So the authorizingOwner
         * can be any address you want; it does not have to match an existing owner address.
         *
         * Also note that it is ill-advised to have the ArmorAgent authorizedAddress also be an owner of the safe.
         * You can think of the Safe owners as the withdrawal keys and the authorizedAddress as the trading key.
         * In an ideal world, these will be very separate functions.
         */
        authorizeForOwner(provider: Eulith.Provider | Eulith.Web3, signer: Eulith.Signing.SigningService): Promise<void>;
        /**
         * Deploying a new ArmorAgent has three steps:
         *
         * 1. Deploy the armor and (optionally) new Safe
         * 2. authorizeForOwner (repeat this step for as many owners as you have)
         * 3. enableArmor
         *
         * This method is the third step and final step of the sequence. It takes all the authorizing signatures
         * and sets up the new Safe with the designated threshold.
         */
        enableArmor(provider: Eulith.Provider | Eulith.Web3, signer: Eulith.Signing.SigningService, safeParams: EnableArmorSafeParams): Promise<void>;
        getAuthorizingOwnerSignatures(provider: Eulith.Provider | Eulith.Web3, authorizedTradingAddress: string): Promise<EnableArmorSignature[]>;
    }
    /**
     * Parameters used in IArmorAgent.enableArmor
     */
    interface EnableArmorSafeParams {
        safeAddress?: string;
        newSafe?: {
            owners: string[];
            approvalThreshold: number;
        };
        authorizedTradingAddress: string;
    }
    /**
     *  For a given authorizedAddress (or authorizedSigner instance), fetch the associated IAgent.
     *
     *  Note - there can never be more than one IAgent associated with a given authorizedAddress.
     *
     *  @default createUncheckedAgentIfNoneExists: true
     */
    function getAgent({ provider, tradingKeyAddress, tradingKeySigner, createUncheckedAgentIfNoneExists, armorContractAddress, }: {
        provider: Eulith.Provider | Eulith.Web3;
        tradingKeyAddress?: string;
        tradingKeySigner?: Eulith.Signing.SigningService;
        createUncheckedAgentIfNoneExists?: boolean;
        armorContractAddress?: string;
    }): Promise<IAgent>;
    function getAll(provider: Eulith.Provider | Eulith.Web3): Promise<(IAgent | IArmorAgent)[]>;
    /**
     *  Creates an UncheckedAgent for the given authorizedAddress
     *
     *  Note this routine will fail if the agent already exists for the provided authorizedAddress
     *  It's recommended to just use IAgent.getAgent() instead, which will default to automatically
     *  creating a new UncheckedAgent if it doesn't exist, else return the existing.
     */
    function createUncheckedAgent({ provider, authorizedAddress }: {
        provider: Eulith.Provider | Eulith.Web3;
        authorizedAddress: string;
    }): Promise<IAgent>;
    /**
     *  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 its behalf,
     *  provided a valid authorizedAddress signature and Eulith cosignature.
     *
     *  Deploying a new ArmorAgent is a 3-step process:
     *
     *      1. Construct an armor contract with this method (passing in a safe, or the data needed to create a safe)
     *      2. authorizeForOwner -- authorize the newly created ArmorAgent as a module on the safe with a sufficient threshold of owners
     *      3. enableArmor - activate the new ArmorAgent module (and new safe, if requested)
     *
     *  Note this will fail if any IAgent already exists for this authorizedAddress.
     */
    function createArmorAgent({ provider, tradingKeyAddress, safeAddress, hasAce, setupSigner, name, description }: {
        provider: Eulith.Provider | Eulith.Web3;
        tradingKeyAddress: string;
        hasAce: boolean;
        safeAddress?: string;
        setupSigner: Eulith.Signing.SigningService;
        name?: string;
        description?: string;
    }): Promise<IArmorAgent>;
    /**
     *  Returns the contract address of the IAgent associated with the given authorizedAddress
     */
    function contractAddress({ provider, tradingKeyAddress, authorizedSigner, createUncheckedAgentIfNoneExists }: {
        provider: Eulith.Provider | Eulith.Web3;
        tradingKeyAddress?: string;
        authorizedSigner?: Eulith.Signing.SigningService;
        createUncheckedAgentIfNoneExists?: boolean;
    }): Promise<string>;
    function updateContractNameAndDescription({ deployedContractId, name, description, provider }: {
        deployedContractId: number;
        name?: string;
        description?: string;
        provider: Eulith.Provider | Eulith.Web3;
    }): Promise<(IAgent | IArmorAgent)[]>;
    /**
     * Returns the existing IArmorAgent associated with the given authorizedAddress
     */
    function getArmorAgent({ provider, tradingKeyAddress, tradingKeySigner, armorContractAddress, }: {
        provider: Eulith.Provider | Eulith.Web3;
        tradingKeyAddress?: string;
        tradingKeySigner?: Eulith.Signing.SigningService;
        armorContractAddress?: string;
    }): Promise<IArmorAgent>;
}