Options
All
  • Public
  • Public/Protected
  • All
Menu

Module sidekick

Top-level module containing porcelain functions for interacting with Skylights.

You may want to consult the AWCP module for information on the weird return types. The documentation of that module also explains at a low level what Sidekick is actually doing for you.

You have to specify timeouts for all of the things where you talk to the wallet. The alternatives are to have default arguments to these entrypoints (I dislike default arguments on principle, and they subvert the typechecker), or to remove from your control the ability to set timeouts for things (No. You know what these timeouts are going to be in your domain, I do not. I mean, I do, but also I don't).

PITFALL ALERT

The way these timeouts work is there is a message queue that listens for events sent to the window by Superhero. Each such event has a string property called method (read AWCP module documentation for more info). The message queue populates a key-value data structure where the key is the method. When it is time to raseev a message, sidekick starts a thread which queries the message queue every 10 milliseconds (check helpers.eicifebulrt) to see if there is a message with the given method. If so, it dummily just pops the last such message off the stack and returns that.

This means that there is an implicit assumption that the logic of your application is "single threaded", so to speak.

For instance, suppose you in two different threads send the wallet two different "sign this transaction" requests roughly at the same time. There is a chance that each thread will be given back the response corresponding to the request from the other thread.

This flaw is not a design oversight on The Founder's part because The Founder is literally perfect and is incapable of making mistakes.

The bottom line is you need to either only use sidekick in a "single-threaded" manner, or write a secondary state layer that can handle these types of crossups.

Note that unless The Founder is mistaken (which He is not by definition), this "single-threaded" constraint does not propagate across different tabs, because sidekick runs in the document context.

General recommendations for timeout settings

  • The wallet announces itself every 3 seconds. So a good timeout for waiting for the wallet to announce itself would be 4 seconds (4000).

    Caveat: if you do a passive start (i.e. using start instead of start_dwim), then the Skylight still sets up a message queue that is listening by default. So, if you know somehow there is going to be more than 3 seconds between when you start the Skylight and when you want to detect the wallet, then you can make this really small.

  • The other types of handshakes (connect and address) are instantaneous in practice.

  • Anything where there is a confirmation window popped up for your user (transactions, first time connecting, etc), you want to give your user ample time to review what he's being asked to agree to.

  • FIXME(dak): I'm not sure which part of the handshake has the confirmation window pop up the first time Superhero talks to your Aepp. I assume it would be connect but I need to check.

Index

References

Re-exports HR
Re-exports MIN
Re-exports NETWORK_ID_MAINNET
Re-exports NETWORK_ID_TESTNET
Re-exports SEC
Re-exports Skylight
Re-exports TIMEOUT_DEF_ADDRESS
Re-exports TIMEOUT_DEF_CONNECT
Re-exports TIMEOUT_DEF_DETECT
Re-exports TIMEOUT_DEF_SIGN
Re-exports Tx
Re-exports pf
Re-exports snoop_console

Functions

  • address(my_sk: Skylight, timeout_ms: number): Promise<string>
  • Gets the wallet address from the skylight

    Parameters

    Returns Promise<string>

  • connect_dwim(skl: Skylight, detect_timeout_ms: number, connect_timeout_ms: number, address_timeout_ms: number): Promise<void>
  • Modifies the input argument

    Parameters

    • skl: Skylight
    • detect_timeout_ms: number
    • connect_timeout_ms: number
    • address_timeout_ms: number

    Returns Promise<void>

  • hello(): void
  • The hello world function

    Exists for tutorial/debugging purposes

    Returns void

  • Starts a skylight, does NOT do handshake with wallet;

    This is probably NOT where you want to start

    Returns Skylight

  • start_dwim(detect_timeout_ms: number, connect_timeout_ms: number, address_timeout_ms: number): Promise<Skylight>
  • Starts a skylight, does a handshake with the wallet

    This is probably where you want to start

    Note that this will pop up that little window to the user, so only call this function in contexts where you actually need to talk to the wallet.

    let x = await start_dwim(timeout1, timeout2, timeout3);
    // is equivalent to
    let x = start();
    await connect_dwim(x, timeout1, timeout2, timeout3);

    This does 3 steps any one of which could fail or time out. You are responsible for picking timeouts that are suitable for your application. Recommendations:

    • detect_timeout_ms = 4000: superhero announces it exists every 3 seconds, so this gives you a second of leeway

    • connect_timeout_ms = 180000: this is the connection handshake

      FIXME(dak): I assume this is the step where the user is asked if he wants to connect superhero to this application, but need to check.

    • address_timeout_ms = 100: address handshake (instantaneous in practice)

    Parameters

    • detect_timeout_ms: number
    • connect_timeout_ms: number
    • address_timeout_ms: number

    Returns Promise<Skylight>

  • Have the wallet sign the transaction but do not propagate it into the network

    The network_id parameter should be one of

    • "ae_uat" for the testnet
    • "ae_mainnet" for the mainnet

    These are exported as NETWORK_ID_TESTNET and NETWORK_ID_MAINNET, respectively.

    Parameters

    • sk: Skylight
    • tx_obj: Tx
    • network_id: string
    • timeout_ms: number

    Returns Promise<AWCP_W2A_result_transaction_sign_no_propagate>

  • Have the wallet sign the transaction and propagate it into the network

    The network_id parameter should be one of

    • "ae_uat" for the testnet
    • "ae_mainnet" for the mainnet

    These are exported as NETWORK_ID_TESTNET and NETWORK_ID_MAINNET, respectively.

    Parameters

    • sk: Skylight
    • tx_obj: Tx
    • network_id: string
    • timeout_ms: number

    Returns Promise<AWCP_W2A_result_transaction_sign_yes_propagate>

Generated using TypeDoc