❤
npm
Sign UpSign In

@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

Readme

Keywords

none

Package Sidebar

Install

npm i @raydeck/useplug

Repository

github.com/rhdeck/useplug

Homepage

github.com/rhdeck/useplug#README

Weekly Downloads

1

Version

1.0.3

License

MIT

Unpacked Size

71.2 kB

Total Files

34

Last publish

Collaborators

  • raydeck
Try on RunKit
Report malware