No Packages, Mate

    @raydeck/useplug
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.3 • Public • Published

    usePlug - React Wrapper for Plug Wallet

    Plug Wallet makes it easy for browser users to interact with ICP on an economic basis. usePlug makes it easy for React app developers to integrate usePlug for authentication and working with actors.

    Typescript Native Implementation - get all your sweet autocomplete.

    We are very grateful for the folks at the DFINITY foundation for putting on the Supernova Hackathon when we created this tool. And our thanks to Psychedelic for making Plug Wallet and open-sourcing their work so we could make it easy for others.

    License

    MIT License - use, share and enjoy!

    Installation

    **Prequisite: A React app (often built with npx create-react-app);

    yarn add @dfinity/agent @dfinity/candid @dfinity/principal # Dependencies
    yarn add @raydeck/useplug # This package

    Usage

    App.tsx

    Add The plug provider to the top level of your application that you want authenticated.

    Remember to set the whitelist Plug will only let you interact with canisters on the whitelist you provided to the plugprovider

    PlugProvider

    PlugProvider wraps your app to manage communication with the plug wallet. To instantiate, provide props with the canisters and network with which you want to communicate

    Props

    • whitelist?: string[]; Which canisterids - if any - are allowed to interact using the plug wallet ID
    • host?: string; Which server to use for authentication. By default uses mainnet. (setting explicitly doesn't seem to work as it should for local replicas)
    • timeout?: number; How long (in ms) to wait for communications from the IC network

    Note: While whitelist is optional because of use cases where you are just trading ICP using plug, it's a code smell to leave it undefined in most cases. The others are fine to leave alone.

    Example

    import {PlugProvider, Authenticated, Unauthenticated, LoggedOut } from '@raydeck/useplug'
    export const App = ()=>{
        return (
            <PlugProvider whitelist={whitelist}>
                {/* Providers want a single node underneath, which we wrangle with a fragment */}
                <Fragment> 
                    {/* Wrapper  for tree in authenticated state */}
                    <Authenticated> 
                        {/* Your app, which can use usePlug */}
                        <Main />
                    </Authenticated>
                    {/* Wrapper for for unauthenticated state */}
                    <Unauthenticated> 
                        {/* App in logged out state - we have a pre-built login screen for you */}
                        <LoggedOut /> 
                    </Unauthenticated>
                </Fragment>
            </PlugProvider>
        );
    }

    usePlug() => PlugContext

    Access the context of your instantiated Plug connection from any component beneath your PlugProvider.

    The shape of the plug Provider context is:

    • authenticated: Whether the plug wallet is in an authenticated state (boolean)
    • principal: Principal authenticated with the plug wallet (Principal or undefined)
    • agent: Plug-mediated agent for talking with IC canisters (HttpAgent)
    • login: Trigger plug wallet interactive authentication (()=>void)
    • logout Unauthenticate from plug wallet (presently just reloads the window, since plug doesn't maintain auth across reloads) (()=>void)
    • createActor: Pass-through to the plug wallet createActor function
    • requestBalance:Pass-through to the plug wallet requestBalance function
    • requestTransfer:Pass-through to the plug wallet requestTransfer function
    • batchTransactions:Pass-through to the plug wallet batchTransactions function

    Example - Authenticated Path

    import { usePlug, useActor } from '@raydeck/useplug'
    import { _SERVICE} from '../../src/declarations/mycanister/mycanister.did';
    import {idlFactory} from '../../src/declarations/mycanister'
    
    const canisterid = process.env.MYCANISTER_CANISTER_ID;
    export const Main = ()=>{
        const {
            principal, 
            logout, /* attach to a logout button*/
            createActor, /* could use, but useActor is easier (below) */
            requestBalance,
            requestTransfer,
            batchTransactions,
        } = usePlug();
    }

    useActor(id: String, factory: InterfaceFactory) => ActorSubclass | undefined

    This one is cool. useActor wraps the concerns of instantiating an actor to communicate with your canister mediated by Plug. Plus, it keeps your Typescript types auto-generated by dfx generate so all the auto-complete stays with you.

    Example

    import { useActor } from "@raydeck/useplug"
    import { _SERVICE} from '../../src/declarations/mycanister/mycanister.did';
    import {idlFactory} from '../../src/declarations/mycanister'
    
    const useMyCanister = ()=>{
        return useActor<_SERVICE>(canisterId, idlFactory);
    }
    
    const MyComponent = ()=>{
        const myCanister = useMyCanister()
    }

    @raydeck/useplug - v1.0.3

    @raydeck/useplug - v1.0.3

    Table of contents

    Type aliases

    Variables

    Functions

    Type aliases

    Balance

    Ƭ Balance: Object

    Type declaration

    Name Type
    amount number
    currency string
    image string
    name string
    value number

    Defined in

    PlugProvider.tsx:26


    BatchTransactionResponse

    Ƭ BatchTransactionResponse: Object

    Defined in

    PlugProvider.tsx:58


    CanisterId

    Ƭ CanisterId: string

    Defined in

    PlugProvider.tsx:47


    CreateActorParams

    Ƭ CreateActorParams: Object

    Type declaration

    Name Type
    canisterId string
    interfaceFactory InterfaceFactory

    Defined in

    PlugProvider.tsx:22


    Cycles

    Ƭ Cycles: number

    Defined in

    PlugProvider.tsx:46


    Plug

    Ƭ Plug: Object

    Type declaration

    Name Type
    agent HttpAgent
    batchTransactions (transactions: Transaction[]) => Promise<BatchTransactionResponse>
    createActor <T>(params: CreateActorParams) => Promise<ActorSubclass<T>>
    isConnected () => boolean
    requestBalance () => Promise<Balance[]>
    requestBurnXTC (params: RequestBurnXTCParams) => Promise<RequestTransferResponse>
    requestConnect (o?: RequestConnectParams) => Promise<any>
    requestTransfer (params: RequestTransferParams) => Promise<RequestTransferResponse>

    Defined in

    PlugProvider.tsx:59


    PublicKey

    Ƭ PublicKey: any

    Defined in

    PlugProvider.tsx:21


    RequestBurnXTCParams

    Ƭ RequestBurnXTCParams: Object

    Type declaration

    Name Type
    amount Cycles
    to CanisterId

    Defined in

    PlugProvider.tsx:48


    RequestConnectParams

    Ƭ RequestConnectParams: Object

    Type declaration

    Name Type
    host? string
    timeout? number
    whitelist? string[]

    Defined in

    PlugProvider.tsx:16


    RequestTransferParams

    Ƭ RequestTransferParams: Object

    Type declaration

    Name Type
    amount number
    opts? Object
    opts.created_at_time? Object
    opts.created_at_time.timestamp_nanos number
    opts.fee? number
    opts.from_subaccount? Number
    opts.memo? string
    to String

    Defined in

    PlugProvider.tsx:33


    RequestTransferResponse

    Ƭ RequestTransferResponse: Object

    Type declaration

    Name Type
    height number

    Defined in

    PlugProvider.tsx:45

    Variables

    Authenticated

    Authenticated: FC<Object>

    Defined in

    PlugProvider.tsx:172


    PlugProvider

    PlugProvider: FC<Object>

    Defined in

    PlugProvider.tsx:106


    Unauthenticated

    Unauthenticated: FC<Object>

    Defined in

    PlugProvider.tsx:178


    plug

    plug: undefined | Plug

    Defined in

    PlugProvider.tsx:87

    Functions

    PlugButton

    Const PlugButton(__namedParameters): Element

    Parameters

    Name Type
    __namedParameters Object
    __namedParameters.dark? boolean
    __namedParameters.title? string

    Returns

    Element

    Defined in

    PlugButton.tsx:53


    useActor

    useActor<T>(canisterId, interfaceFactory): undefined | ActorSubclass<T>

    Type parameters

    Name
    T

    Parameters

    Name Type
    canisterId string
    interfaceFactory InterfaceFactory

    Returns

    undefined | ActorSubclass<T>

    Defined in

    useActor.ts:6


    usePlug

    Const usePlug(): Object

    Returns

    Object

    Name Type
    agent undefined | HttpAgent
    authenticated boolean
    batchTransactions undefined | (transactions: Transaction[]) => Promise<BatchTransactionResponse>
    createActor undefined | <T>(params: CreateActorParams) => Promise<ActorSubclass<T>>
    login () => void
    logout () => void
    plug undefined | Plug
    principal null | Principal
    requestBalance undefined | () => Promise<Balance[]>
    requestTransfer undefined | (params: RequestTransferParams) => Promise<RequestTransferResponse>

    Defined in

    PlugProvider.tsx:166

    Keywords

    none

    Install

    npm i @raydeck/useplug

    DownloadsWeekly Downloads

    1

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    71.2 kB

    Total Files

    34

    Last publish

    Collaborators

    • raydeck