Starmap-api NPM

starmap

A verified on-chain Solana directory service.

SYSTEM OVERVIEW

Starmap is a Solana program that maps public identifiers ("PI") to wallet addresses. These mapping entries in Starmap are called name records. Currently-supported PIs include email address and phone number. Unverified aliases called Stars accounts will be available soon.

This API enables a user ("sender") to query Starmap to find the wallet address associated with a public identifier ("PI") such as an email address or phone number. The sender can then directly send SOL or tokens to the recipient. Alternatively, if there is no wallet currently associated, the sender can create an escrow account, send funds to the escrow, and notify the recipient. Flow details are below.

Additionally, a user ("recipient") can use this API to create a name record and to receive escrow funds.

If the recipient cannot claim the name record, the sender can cancel the escrow and reclaim their funds. All that with no calls to customer service! The only permissioned part of the system is claiming of name records.

API FLOW

With the exception of InitFee and Verify, the client can directly interact with the blockchain

SENDER ACTIONS

SEARCH

Validate and normalize the name using parseName
Abort if recordType is Invalid
Fetch the name record using retrieveNameRegistry
Confirm record.isAssignedAndValid
Use record.owner

PAYMENT WITH NOTIFICATIONS

For transactions of value > $1 USD, Star Map can send the recipient an email notification.

Client generates a transaction ID keypair (similar to Solana Pay)
Client ensures the recipient has a respective associated token account
1. If it does not exist, the client can abort or pay to create the destination token account transferAndNotify
Client uses the transferAndNotify API to execute the transfer and create a notification request
Client calls notification endpoint to send the notification and refund the request account rent.

DIRECT PAYMENT

Using wallet address above, wallet or app can send SOL or tokens.

ESCROWED PAYMENT

If the NameRecord does not exist or has no owner, the sender can create an escrow record and an associated token account that is owned by the escrow record.

The sender can then transfer tokens (including wrapped SOL) to the token account.
Until the name record is claimed, the escrow owner can withdraw funds from their escrow record's associated token accounts to cancel the escrow.

REGISTRATION & RECIPIENT ACTIONS

InitFee (Stars-only)
1. Client requests fee information for Stars records.
Authorize and Pay
1. Client pays for fees. Stars records are assigned at this step.
Send Verification Request (N/A for Stars)
1. Client submits PI to verification server.
2. Server performs verification request and consumes verification fee on blockchain.
3. Server 200 response indicates that verification request was sent.
Complete Verification (N/A for Stars)
1. Client submits verification code, PI, and pubkey to verification server.
2. Server performs assignment and consumes assignment fee on blockchain.
3. Server 200 response indicates that assignment is complete.
Withdrawal
1. Client withdrawals escrowed funds using blockchain client or RPC. This is useful if funds were sent before name registry creation/assignment.
2. If SPL tokens are supported, those should also be transferred.

RECORD FORMAT

A name record contains:

A major version which allows breaking changes
A record type that indicates the type of public identifier and expected signatory
A state bitfield for internal state management
1. Payment status bits for verify attempt and assignment
2. A lock bit that the name owner can set to prevent reassignment
3. A notify bit that enables/disables notifications
The pubkey of the signatory who assigned ownership
The pubkey of the name owner who is allowed to
1. Withdraw escrowed funds
2. Update associated data
3. Transfer account ownership
4. Modify flags such as the lock flag and notify flag
5. Delete the record
OPTIONAL Additional data such as routing addresses

DEVELOPER

Test:

npm test

INSTALL

npm i --save starmap-api

VALIDATED GET EXAMPLE

import { RecordType, retrieveNameRegistry, parseName } from 'starmap-api';

async function main() {
  let input = '+12345678910';
  const { recordType, name, parseError } = parseName(input);
  if (recordType == RecordType.Invalid) {
    console.log('Invalid identifier: %s', name);
    console.log('Error: %s', parseError.message);
    return;
  }
  console.log('Retrieve identifier:', name);
  const url = 'https://api.mainnet-beta.solana.com';
  const connection = new Connection(url, 'recent');
  let res = await retrieveNameRegistry(connection, name, recordType);
  if (res.isAssignedAndValid) {
    console.log('---Record---');
    console.log('Owner:', res.owner.toBase58());
  } else {
    console.log('Name not assigned');
  }
}

main()
  .catch((err) => {
    console.error(err);
    process.exit(-1);
  })
  .then(() => process.exit());