# Solana

The unofficial Elixir package for interacting with the
[Solana](https://solana.com) blockchain.

## Installation

This package isn't available on Hex yet due to some outstanding PRs on
dependency libraries, so you'll need to add the Git repository to your `deps/0`:

```elixir
def deps do
  [
    {:solana, git: "https://git.sr.ht/~dcrck/solana"}
  ]
end
```

## Documentation

- [JSON-RPC API client](#json-rpc-api-client)
  - [Using a custom HTTP client](#using-a-custom-http-client)
- [On-chain program interaction](#solana-program-interaction)
- [Writing a custom program client](#writing-a-custom-program-client)
  - [Testing custom programs](#testing-custom-programs)

## JSON-RPC API Client

`solana` provides a simple interface for interacting with Solana's [JSON-RPC
API](https://docs.solana.com/developing/clients/jsonrpc-api). Here's an example
of requesting an airdrop to a new Solana account via the `requestAirdrop`
method:

```elixir
key = Solana.keypair() |> Solana.pubkey!()
client = Solana.RPC.client(network: "localhost")
{:ok, signature} = Solana.RPC.send(client, Solana.RPC.Request.request_airdrop(key, 1))

Solana.Transaction.check(signature) # {:ok, ^signature}
```

To see the full list of supported methods, check the `Solana.RPC.Request`
module.

### Using a custom HTTP client

Since this module uses `Tesla` for its API client, you can use whichever
HTTP client you wish, just be sure to include it in your dependencies:

```elixir
def deps do
  [
    # Gun, for example
    {:gun, "~> 1.3"},
    {:idna, "~> 6.0"},
    {:castore, "~> 0.1"},
    # SSL verification
    {:ssl_verify_hostname, "~> 1.0"},
  ]
end
```

Then, specify the corresponding `Tesla.Adapter` when creating your client:

```elixir
client = Solana.RPC.client(network: "localhost", adapter: {Tesla.Adapter.Gun, certificates_verification: true})
```

See the `Solana.RPC` module for more details about which options are available
when creating an API client.

## On-chain program interaction

Since `solana`'s JSON-RPC API client supports `sendTransaction`, you can use it
to interact with on-chain Solana programs. `solana` provides utilities to craft
transactions, send them, and confirm them on-chain. It also includes modules
that create transaction instructions for specific programs, namely:

- `Solana.SystemProgram`: the
  [SystemProgram](https://docs.solana.com/developing/runtime-facilities/programs#system-program)
- `Solana.SPL.Token`: the Solana Program Library's [Token Program](https://spl.solana.com/token)
- `Solana.SPL.AssociatedToken`: the Solana Program Library's [Associated Token
  Account Program](https://spl.solana.com/associated-token-account)

See the `test/solana` directory for examples of interacting with these programs.

## Writing a custom program client

Similarly to how `solana` implements interfaces for popular on-chain programs,
it also provides guidelines for how to build interfaces to your own programs.
Check out any of the modules listed above for examples of how to build an
interface to your programs.

### Testing custom programs

Once you've built your custom program's client, you should probably write some
tests for it. `solana` provides example tests for the interfaces listed above,
along with an Elixir-managed [Solana Test
Validator](https://docs.solana.com/developing/test-validator) process for fast
local instruction testing. See `Solana.TestValidator` for more details about how
to set this up.