/sns-sdk

Solana Name Service SDKs monorepo

Primary LanguageTypeScript

SNS SDK



SNS SDK monorepo


🚧 This repository is in active development and is subject to changes 🚧



Table of contents


  1. SNS documentation
  2. Javascript
  3. Rust
  4. SDK Proxy
  5. Python
  6. Java
  7. Swift
  8. CLI
  9. React
  10. Vue
  11. Examples
  • Resolving a domain
  1. Bounties

SNS documentation


This repository contains the Developer documentation specifically for the SNS SDK. You can find the general SNS documentation at sns.guide


Javascript


yarn add @bonfida/spl-name-service
npm i @bonfida/spl-name-service

The JS SDK is the most complete SDK, it contains all the utils methods to interact with domain names as well as instruction builders to register domain names.


Rust


The Rust SDK provides everything you need for resolving domain ownership and records within the Solana Name Service (SNS)

  • resolve_owner: Resolves the owner of a given domain
  • resolve_record: Resolves a specific record of a given domain
  • resolve_name_registry: Resolves the name registry of a given public key
  • resolve_name_registry_batch: Resolves the name registry of a given list of public keys
  • resolve_reverse: Resolves the reverse record of a given public key
  • resolve_reverse_batch: Resolves the reverse records for a given list of public keys
  • get_domains_owner: Retrieves all domains owned by a given public key
  • get_subdomains: Retrieves all subdomains of a given parent domain
  • resolve_nft_owner: Resolves the NFT owner of a given domain key
  • get_domain_key: Takes a domain string and a boolean indicating whether it is a record. It returns the public key for the given domain, or an error if the domain is invalid
  • get_reverse_key: Takes a domain string and returns the public key for the reverse lookup account of the domain, or an error if the domain is invalid
  • get_domain_mint: Takes a domain key and returns the corresponding domain NFT mint's public key

The functions in this code are available in both blocking and non-blocking (asynchronous) versions. To use the blocking version one must enable the blocking feature.


SDK Proxy


The SDK proxy is a Cloudflare worker that proxies the JS SDK via REST calls. It's meant to be used if you are programming in a language that is not supported. It currently supports the following endpoints:

  • GET /resolve/:domain: Resolves the current owner of domain
  • GET /domain-key/:domain: Returns the public key of the domain account
  • GET /domains/:owner: Returns the list of domains (public keys) owned by owner
  • GET /reverse-key/:domain Returns the key of the reverse account of domain
  • GET /record-key/:domain/:record: Returns the public key of the record of domain
  • GET /record/:domain/:record: Returns the content of the record of domain. The result is a base64 encoded buffer.
  • GET /favorite-domain/:owner: Returns the favorite domain of owner. If owner has not set up a favorite domain it returns null
  • GET /types/record: Returns the list of supported records
  • GET /reverse-lookup/:pubkey: Returns the reverse lookup of pubkey
  • GET /subdomains/:parent: Returns all the subdomains of parent
  • GET /register?buyer={buyer}&domain={domain}&space={space}&serialize={serialize}: This endpoint can be used to register domain for buyer. Additionaly, the buyer dans specify the space it wants to allocate for the domain account. In the case where serialize is true the endpoint will return the transaction serialized in the wire format base64 encoded. Otherwise it will return the instruction in the following format: { programId: string, keys: {isWritable: boolean, isSigner: boolean, pubkey: string}[], data: string } where data is base64 encoded. This endpoint also supports the optional mint parameter to change the mint of the token used for registration (currently supports USDC, USDT, FIDA and wSOL), if mint is omitted it defaults to USDC.
  • GET /twitter/get-handle-by-key/:key: This endpoint can be used to fetch the Twitter handle of a given public key
  • GET /twitter/get-key-by-handle/:handle: This endpoint can be used to fetch the public key of a given Twitter handle
  • GET /multiple-favorite-domains/:owners: Returns the favorite domains for a list of owners that are comma separated
  • GET /record-v2/:domain/:record: Returns the content of the record (v2) of domain. The result is made of the deserialized value, staleness boolean (stale), right of association (roa) if applicable, and the record object made of itsheader and data (base64 encoded).

NOTE: All endpoints capable of performing RPC calls currently support an optional rpc query parameter for specifying a custom RPC URL. In the future, this parameter will become mandatory, and the Cloudflare worker will exclusively proxy calls to a specified custom RPC URL.

The SDK proxy is deployed at: https://sns-sdk-proxy.bonfida.workers.dev/


CLI


The CLI can be installed with:

cargo install sns-cli

The CLI has the following commands:

  • sns resolve <domains>
  • sns domains <owners>
  • sns burn <domains> <keypair_path>
  • sns transfer <keypair_path> <new_owner_key> <domains>
  • sns lookup <domains>
  • sns reverse-lookup <key>
  • sns bridge <target_chain> <domain> <keypair_path>
  • sns register <keypair_path> <space> <domains>

For instance

$ sns resolve bonfida solana.sol coinbase

+------------+----------------------------------------------+----------------------------------------------------------------------------------+
| Domain     | Owner                                        | Explorer                                                                         |
+------------+----------------------------------------------+----------------------------------------------------------------------------------+
| bonfida    | HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA | https://explorer.solana.com/address/HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA |
+------------+----------------------------------------------+----------------------------------------------------------------------------------+
| solana.sol | 3Wnd5Df69KitZfUoPYZU438eFRNwGHkhLnSAWL65PxJX | https://explorer.solana.com/address/3Wnd5Df69KitZfUoPYZU438eFRNwGHkhLnSAWL65PxJX |
+------------+----------------------------------------------+----------------------------------------------------------------------------------+
| coinbase   | 7sF2JumHpWiPjS3XtnQ8cKraTzzfcGSvQHcV3yTaPZ5E | https://explorer.solana.com/address/7sF2JumHpWiPjS3XtnQ8cKraTzzfcGSvQHcV3yTaPZ5E |
+------------+----------------------------------------------+----------------------------------------------------------------------------------+


Python


Work in progress

Java


Work in progress

Swift


Work in progress

React


This package contains a set of useful React hooks to help you build your perfect dApp. If you are interested in a hook that is not included in this package please open an issue to let us know!

npm i @bonfida/sns-react
yarn add @bonfida/sns-react

Vue


This package contains a set of useful Vue composables to help you build your perfect dApp. If you are interested in a composable that is not included in this package please open an issue to let us know!

npm i @bonfida/sns-vue
yarn add @bonfida/sns-vue

Demo app with an example of each composable usage.


Examples



Resolving a domain


The following examples show how to resolve the domain bonfida.sol:

  1. With the JS SDK
const connection = new Connection(clusterApiUrl("mainnet-beta"));
const owner = await resolve(connection, "bonfida");
expect(owner.toBase58()).toBe("HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA");
  1. With the Rust SDK
let client = RpcClient::new(std::env::var("RPC_URL").unwrap());
let res = resolve_owner(&client, "bonfida").await.unwrap();
assert_eq!(res, pubkey!("HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA"));
  1. With the CLI
$ sns resolve bonfida

+---------+----------------------------------------------+----------------------------------------------------------------------------------+
| Domain  | Owner                                        | Explorer                                                                         |
+---------+----------------------------------------------+----------------------------------------------------------------------------------+
| bonfida | HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA | https://explorer.solana.com/address/HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA |
+---------+----------------------------------------------+----------------------------------------------------------------------------------+
  1. With the Cloudflare worker
GET https://sns-sdk-proxy.bonfida.workers.dev/resolve/bonfida
{ "s": "ok", "result": "HKKp49qGWXd639QsuH7JiLijfVW5UtCVY4s1n2HANwEA" }
  1. With the React SDK
import { useConnection, useWallet } from "@solana/wallet-adapter-react";
import { useDomainOwner, useDomainsForOwner } from "@bonfida/sns-react";

export const Example = () => {
  const { connection } = useConnection();
  const { publicKey, connected } = useWallet();
  const { result } = useDomainOwner(connection, "bonfida");
  // ...
};

Bounties


Feature Description In progress Completed Bounty
Golang Translate JS SDK into a robust, well-tested Golang SDK; high-quality code essential
Python Translate JS SDK into a robust, well-tested Python SDK; high-quality code essential
Java Translate JS SDK into a robust, well-tested Java SDK; high-quality code essential
Swift Translate JS SDK into a robust, well-tested Swift SDK; high-quality code essential

If you have any questions or suggestions, feel free to open an issue or pull request, or simply contact us at @bonfida. We're always here for a good chat about Solana and the decentralized web!