Skip to content
This repository has been archived by the owner on Jan 14, 2020. It is now read-only.

Grin Wallet Cocoa API Guide

Jump to bottom
Gary Yu edited this page Aug 17, 2019 · 3 revisions

RECENT CHANGES:

  • (17 Aug 2019) Update for v1.0.4
  • (26 Jul 2019) Creation for cocoa_grinwallet v1.0.x

These APIs support IOS ObjectC / Swift, and React-Native.

Grin Wallet Cocoa API Guide

General Info

Swift

You can find the APIs reference code GrinBridge.swift

For a pure Swift caller, it need a little bit adaption in function signature to remove all the @objc and resolve/reject parts, and change the return type from Void to String.

For example

this listen API need to changed from:

    @objc func listen(_ state: String, resolve: RCTPromiseResolveBlock, reject: RCTPromiseRejectBlock) -> Void {
      var error: UInt8 = 0
      let cResult = grin_listen(state, &error)
      handleCResult(error:error, cResult:cResult!, resolve: resolve, reject: reject)
    }

to:

    func listen(state: String) -> String {
      var error: UInt8 = 0
      let cResult = grin_listen(state, &error)
      return handleCResult(error:error, cResult:cResult!)
    }

A simple global replacement should work.

btw, a reference of the `handleResult` function here. 
func handleCResult(error: UInt8, cResult: UnsafePointer<Int8>) -> Result<String, GrinWalletError> {
    let result = String(cString: cResult)
    cstr_free(cResult)
    switch error {
    case 0:
        return .success(result)
    case 2:
        print("not validated!")
        return .success(result)
    default:
        return .failure(GrinWalletError(code: Int(error), message: result))
    }
}

Objective-C

If need Objective-C APIs, you can refer to GrinBridge.m.

For a pure Objective-C caller, it need a little bit adaption in function signature to remove all the RCT_EXTERN_METHOD and resolve/reject parts, and add the return type as NSString.

For example

this listen API need to changed from:

RCT_EXTERN_METHOD(listen: (NSString*)state resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)

to:

    (NSString*)listen: (NSString*)state

A simple global replacement should work.

React-Native

And to provide the React-Native APIs, both [GrinBridge.m] and GrinCode-Bridging-Header.h are needed, to open it for React-Native as NativeModules.

Grin Wallet Cocoa APIs

Wallet Initialization

1. Wallet Init

  • Swift
func walletInit(state: String, password: String, is_12_phrases: Bool) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)walletInit:(NSString*)state password:(NSString*)password is_12_phrases:(BOOL)is_12_phrases 
NativeModules.GrinBridge.walletInit(JSON.stringify(walletState), walletState.password, false)

2. Get Wallet Mnemonic Phrases

  • Swift
func walletPhrase(state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)walletPhrase:(NSString*)state
const wallet1Mnemonic = await NativeModules.GrinBridge.walletPhrase(JSON.stringify(walletState))

3. Wallet Recovery from Mnemonic Phrases

  • Swift
func walletRecovery(state: String, phrase: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)walletRecovery:(NSString*)state phrase:(NSString*)phrase
NativeModules.GrinBridge.walletRecovery(JSON.stringify(walletState), mnemonic)

4. Wallet Coins Restore from Chain (normally after a recovery)

  • Swift
func walletRestore(state: String, startIndex: UInt64, batchSize: UInt64) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)walletRestore:(NSString*)state startIndex:(uint64_t)startIndex batchSize:(uint64_t)batchSize
NativeModules.GrinBridge.walletRestore(JSON.stringify(walletState), startIndex, batchSize)

Wallet Status Query

1. Query Wallet Balance

  • Swift
func balance(state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)balance:(NSString*)state
NativeModules.GrinBridge.balance(JSON.stringify(walletState))

2. Query Wallet Transactions

  • Swift
func txsGet(state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txsGet:(NSString*)state
const data = await NativeModules.GrinBridge.txsGet(JSON.stringify(walletState))

3. Query Single Transaction

  • Swift
func txGet(_ state: String, txSlateId: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txGet:(NSString*)state txSlateId:(NSString*)txSlateId
const data = await NativeModules.GrinBridge.txGet(JSON.stringify(walletState), slateId)

4. Query Wallet Coins (i.e. UTXO(Unspent Outputs))

  • Swift
func outputsGet(state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)outputsGet:(NSString*)state
const data = await NativeModules.GrinBridge.outputsGet(JSON.stringify(walletState))

Wallet Send and Receive

1. Send by Http / Https

  • Swift
func txSend(_ state: String, amount: UInt64, selectionStrategy: String, message: String, targetSlateVersion: Int64, dest:String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txSend:(NSString*)state amount:(uint64_t)amount selectionStrategy:(NSString*)selectionStrategy message:(NSString*)message targetSlateVersion:(int64_t)targetSlateVersion dest:(NSString*)dest
const slate = await NativeModules.GrinBridge.txSend(JSON.stringify(walletState),
                    10000000, 'smallest', 'a user message', -1, 'http://sga.grin.icu:13415')

2. Send by Grin Relay

Same API as above except the dest parameter is a grin relay address string.

const slate2 = await NativeModules.GrinBridge.txSend(JSON.stringify(walletState),
                  10000000, 'smallest', 'a user message', -1, 'tn1-qgfaqdqy-vm8ryd2k6zfp6cm-359cs4gnudxhljm-d0v38yut4u9r7rg-93d4jp')

3. Cancel a Transaction

  • Swift
func txCancel(state: String, txSlateId: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txCancel:(NSString*)state txSlateId:(NSString*)txSlateId
await NativeModules.GrinBridge.txCancel(JSON.stringify(walletState), slateId)

4. Listen to Receive the Transaction

Because it's too difficult or even impractical for a common mobile phone to listen on a socket for receiving the Grin transactions, in this grin wallet cocoa APIs, we get rid of the socket listening and use the open source Grin Relay service for Grin transaction receiving.

So, we only listen on the wallet's Grin Relay address. To query the Grin Relay address of current wallet, please refer the address API.

  • Swift
func listen(_ state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)listen:(NSString*)state
NativeModules.GrinBridge.listen(JSON.stringify(walletState))

File Transaction

1. Create a File Transaction

Note: a very complex and insecure procedure for file transaction, strongly not proposed to use! unless you can encapsulate it with a secure transmission between transaction parties.

Use in the payer side, the payer use this API to create a file transaction, and the returned slate file need to be sent back to the payee.

  • Swift
func txCreate(state: String, amount: UInt64, selectionStrategy: String, message: String, targetSlateVersion: Int64) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txCreate:(NSString*)state amount:(uint64_t)amount selectionStrategy:(NSString*)selectionStrategy message:(NSString*)message targetSlateVersion:(int64_t)targetSlateVersion
await NativeModules.GrinBridge.txCreate(JSON.stringify(walletState), 10000000, 'smallest', 'a user message', -1)

2. Receive a File Transaction

Note: a very complex and insecure procedure for file transaction, strongly not proposed to use! unless you can encapsulate it with a secure transmission between transaction parties.

Use in the payee side, when the payee receive the payer's created file transaction, this txReceive need to be called and the returned slate file need to be sent back to the payer.

  • Swift
func txReceive(state: String, slateFilePath: String, message: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txReceive:(NSString*)state slateFilePath:(NSString*)slateFilePath message:(NSString*)message
await NativeModules.GrinBridge.txReceive(JSON.stringify(wallet3State), fileName, 'a receive message')

3. Finalize a File Transaction

Note: a very complex and insecure procedure for file transaction, strongly not proposed to use! unless you can encapsulate it with a secure transmission between transaction parties.

Use in the payer side, when the payer receive the payee's signed file transaction, this txFinalize need to be called and the returned slate file need to be post to the chain.

  • Swift
func txFinalize(state: String, slateFilePath: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txFinalize:(NSString*)state slateFilePath:(NSString*)slateFilePath
await NativeModules.GrinBridge.txFinalize(JSON.stringify(walletState), fileName)

4. Post a File Transaction

Note: a very complex and insecure procedure for file transaction, strongly not proposed to use! unless you can encapsulate it with a secure transmission between transaction parties.

As the last step of a file transaction, this txPost is used to post the finalized slate to the chain, which will be mined by the miner (i.e. packaged into a block).

  • Swift
func txPost(state: String, txSlateId: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)txPost:(NSString*)state txSlateId:(NSString*)txSlateId
await NativeModules.GrinBridge.txPost(JSON.stringify(walletState), slateId)

Wallet Management

1. Check Password

  • Swift
func checkPassword(state:String, password: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)checkPassword:(NSString*)state password:(NSString*)password
NativeModules.GrinBridge.checkPassword(JSON.stringify(walletState), 'my-wallet-password')

2. Query Wallet Address (Grin Relay Bech32 Address)

  • Swift
func myRelayAddress(_ state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)myRelayAddress:(NSString*)state
const address_string = await NativeModules.GrinBridge.myRelayAddress(JSON.stringify(walletState))

3. Query Wallet Mnemonic Phrases

Listed above in the wallet initialization.

4. Wallet Repair (i.e. a wallet check)

  • Swift
func walletRepair(state: String, startIndex: UInt64, batchSize: UInt64, updateOutputs: Bool) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)walletRepair:(NSString*)state startIndex:(uint64_t)startIndex batchSize:(uint64_t)batchSize updateOutputs:(BOOL)updateOutputs
NativeModules.GrinBridge.walletRepair(JSON.stringify(result), startIndex, batchSize, updateOutputs)

5. Query Current Block Height

  • Swift
func height(state: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)height:(NSString*)state
NativeModules.GrinBridge.height(JSON.stringify(walletState))

6. Change Password

  • Swift
func changePassword(state:String, oldPassword: String, newPassword: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)changePassword:(NSString*)state oldPassword:(NSString*)oldPassword  newPassword:(NSString*)newPassword
  • React-Native call example:
NativeModules.GrinBridge.changePassword(JSON.stringify(walletState), oldPassword, newPassword)

7. Relay 6-Code Address Query

  • Swift
func relayAddressQuery(state: String, sixCode: String) -> Result<String, GrinWalletError>
  • ObjectC
(NSString*)relayAddressQuery:(NSString*)state sixCode:(NSString*)sixCode
NativeModules.GrinBridge.relayAddressQuery(JSON.stringify(walletState), '5rq8yz')
Clone this wiki locally