@argent/tma-wallet
v1.8.0
Published
This package provides an integration to an Argent wallet for [Telegram mini apps](https://core.telegram.org/bots/webapps).
Downloads
1,229
Readme
@argent/tma-wallet (alpha)
This package provides an integration to an Argent wallet for Telegram mini apps.
The Argent wallet in Telegram is already available in the Telegram Test Environment and is connected to Starknet Sepolia Network. It will be very soon available in Telegram and Starknet Mainnet.
Prerequisites
In order to start integrating the SDK in your Telegram mini (d)app, you first need to create an Argent wallet in the Telegram Test Environment. Here are the steps to follow:
Setup a Telegram Test account following this documentation.
:warning: You need to setup a username, otherwise it won't work with the wallet, after creating a test user you can set a username in the settings.
Open the Argent Wallet by starting a conversation with @ArgentTestBot, then press Start and click on the Open wallet button.
:warning: First time registration may take a few seconds (up to 10 seconds).
Now you should have an account, copy your account address and fund it with STRK using the Starknet Sepolia Faucet
Once your account is funded, it's safer to activate it (i.e. deploy the account). The easiest way to trigger this activation is to send yourself 1 STRK, this will deploy the account automatically.
Now you have a deployed account funded with STRK ready to be integrated with your mini (d)app!
Integration
To install the package, use the following command:
npm install @argent/tma-wallet
Below is an integration example in a simple React application (read the comments!):
import { useEffect, useState } from "react";
import { ArgentTMA, SessionAccountInterface } from "@argent/tma-wallet";
import { Account } from "starknet";
const argentTMA = ArgentTMA.init({
environment: "sepolia", // "sepolia" | "mainnet" (not supperted yet)
appName: "My TG Mini Test Dapp", // Your Telegram app name
appTelegramUrl: "https://t.me/my_telegram_bot/app_name", // Your Telegram app URL
sessionParams: {
allowedMethods: [
// List of contracts/methods allowed to be called by the session key
{
contract:
"0x036133c88c1954413150db74c26243e2af77170a4032934b275708d84ec5452f",
selector: "increment",
}
],
validityDays: 90 // session validity (in days) - default: 90
},
});
function App() {
const [account, setAccount] = useState<SessionAccountInterface | undefined>();
const [isConnected, setIsConnected] = useState<boolean>(false);
useEffect(() => {
// Call connect() as soon as the app is loaded
argentTMA
.connect()
.then((res) => {
if (!res) {
// Not connected
setIsConnected(false);
return;
}
if (account.getSessionStatus() !== "VALID") {
// Session has expired or scope (allowed methods) has changed
// A new connection request should be triggered
// The account object is still available to get access to user's address
// but transactions can't be executed
const { account } = res;
setAccount(account);
setIsConnected(false);
return;
}
// Connected
const { account, callbackData } = res;
// The session account is returned and can be used to submit transactions
setAccount(account);
setIsConnected(true);
// Custom data passed to the requestConnection() method is available here
console.log("callback data:", callbackData);
})
.catch((err) => {
console.error("Failed to connect", err);
});
}, []);
const handleConnectButton = async () => {
// If not connected, trigger a connection request
// It will open the wallet and ask the user to approve the connection
// The wallet will redirect back to the app and the account will be available
// from the connect() method -- see above
await argentTMA.requestConnection("custom_callback_data");
};
// useful for debugging
const handleClearSessionButton = async () => {
await argentTMA.clearSession();
setAccount(undefined);
};
return (
<>
<div>
{!isConnected && <button onClick={handleConnectButton}>Connect</button>}
{isConnected && (
<>
<p>
Account address: <code>{account.address}</code>
</p>
<button onClick={handleClearSessionButton}>Clear Session</button>
</>
)}
</div>
</>
);
}
export default App;
Below is the complete description of the ArgentTMAInterface
:
interface ArgentTMAInterface {
provider: ProviderInterface;
sessionAccount?: SessionAccountInterface;
connect(): Promise<ConnectResponse | undefined>;
requestConnection(callbackData: string): Promise<never>;
isConnected(): boolean;
// advanced methods
exportSignedSession(): Promise<ArgentTMASession | undefined>;
clearSession(): Promise<void>;
}
where SessionAccountInterface
is extending the AccountInterface
from starknet.js and is defined by:
interface SessionAccountInterface extends AccountInterface {
getAccountPayload(): Promise<DeployAccountContractPayload>;
isDeployed(): Promise<boolean>;
getExecuteFromOutsidePayload({ calls }: { calls: Call[] }): Promise<Call>;
getSessionStatus(): SessionStatus; // "VALID" | "EXPIRED" | "INVALID_SCOPE"
}
and ConnectResponse
by:
type ConnectResponse = {
account: SessionAccountInterface;
callbackData?: string;
};